From ef47a7ba17fb9220063aa899e92cf5dc6acf5997 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Mon, 19 Oct 2026 19:48:47 -0400 Subject: [PATCH 01/12] Add design spec: Retire trivial: every build-ready change has a spec --- ...ry-build-ready-change-has-a-spec-design.md | 183 ++++++++++++++++++ 1 file changed, 183 insertions(+) create mode 100644 docs/superpowers/specs/2026-10-19-retire-trivial-every-build-ready-change-has-a-spec-design.md diff --git a/docs/superpowers/specs/2026-10-19-retire-trivial-every-build-ready-change-has-a-spec-design.md b/docs/superpowers/specs/2026-10-19-retire-trivial-every-build-ready-change-has-a-spec-design.md new file mode 100644 index 000000000..0dec57ee9 --- /dev/null +++ b/docs/superpowers/specs/2026-10-19-retire-trivial-every-build-ready-change-has-a-spec-design.md @@ -0,0 +1,183 @@ +# Every build-ready change has a spec — retire `trivial` + +Change 0573 — Retire trivial: every build-ready change has a spec + +## Why + +Grooming can end in a *trivial verdict*: no spec file, `trivial: true` on the record, and the +change body's owned sections (`## Why`, `## What changes`, `## Out of scope`) carry whatever the +groom decided. In practice this exit loses work. Grooming only offers it after a design +conversation has already happened — research done, alternatives weighed, decisions made — and the +trivial exit then asks the agent to squeeze that into "the tightened body as the trivial +rationale." Nothing requires the decisions or the rejected alternatives to survive, there is no +heading for them, and the result never reaches the PR or `main` (a spec is committed as the +feature branch's first commit; a trivial body stays on the metadata branch only). + +The exit also saves almost nothing. The flag changes only build-readiness and whether a spec file +exists: implement-next still reconciles, writes a plan, builds, reviews, and writes a results file +for a trivial change. The one thing skipped is writing the design down. + +History matches: every trivial verdict since about #325 (14 changes) came out of a groom; the +capture-time trivial path in `docket-new-change` was last used around #358. The human always +declines the trivial suggestion now, because the research has nowhere reliable to go. + +The suggestion itself mostly comes from the brainstorm role: `superpowers:brainstorming` sizes +small work as "described in chat, no written design." Removing the exit without countering that +sizing would leave the agent still proposing to skip the spec, with no place to record the choice. + +## Goal + +One rule: **a change is build-ready only when it has a spec** (plus the unchanged conditions: +`proposed`, dependencies `done`, stack base resolved, and the hold rule). Every groom that makes a +change build-ready writes a spec, sized to the change — a rename gets a short one. + +## Non-goals + +- Rewriting archived records or other repositories' records. Docket is pre-1.0.0; an unbuilt + `trivial: true` change in another repository simply drops back to needs-grooming. +- The broader trimming of superpowers brainstorming steps docket does not use (builder check, + visual companion, spike offers, its own spec location) — that is #566. This change counters + only the "no written design" sizing outcome, because it is the trivial suggestion's source. +- Changing what a spec must contain, how the plan-writer reads it, or the reconcile pass. + +## Anti-goals + +- A groom that settles decisions but leaves no written place for them. +- A new check, finding, warning, or gate about legacy `trivial:` lines. They are inert data. +- Rewriting history: archived records keep their `trivial: true` lines byte-for-byte. + +## Decisions + +### 1. Readiness and the domain model + +`trivial` leaves the domain model entirely. Build-ready = `proposed` + non-empty `spec:` + the +existing dependency, stack-base, and hold conditions. Needs-grooming = `proposed` with no spec. +Auto-groomable = needs-grooming + `auto_groomable: true`. + +Remove `Trivial` from the change entity, the readiness evaluation, the claim/action facts that +copy it, and the decoder's wire struct. The decoder already treats unknown frontmatter keys as +compatibility data ("Unknown keys are compatibility data and stay in the document; they are not +decoded here and never fail the decode"), so a legacy `trivial: true` line stays in the file, +untouched by every writer, and means nothing. A legacy record with `trivial: true` and no spec +reads as needs-grooming. + +### 2. New records + +`change.create` stops writing a `trivial:` line into the frontmatter template. + +### 3. The groom operation + +`change.groom` drops the `trivial` outcome. Remaining outcomes: `spec`, `revise`, `abstain`, +`re-enable`. A request naming `outcome: trivial` refuses through the existing invalid-outcome +finding and writes nothing — no special "retired" message. Remove what only the trivial outcome +used: the missing-rationale finding code and its `hasAuthoredRationale` helper, the +`groomed (trivial)` receipt text, the `trivial` field edit, and the trivial checks in the +revise/stub-edit gates (a stub edit now refuses only when the change has a spec). The schema's +`groom_outcomes` vocabulary and the `change groom` CLI help drop `trivial`. + +### 4. The board + +Every build-ready or held proposed change now has a spec, so it renders in the Groomed section. +Drop the `build-ready (trivial)` cell and the comments and branches that existed only for +trivial-without-spec rows in the Proposed section. + +### 5. `docket open` + +The `trivial-no-spec` reason goes. Asking for the spec of a change with no spec — a stub, or a +legacy trivial record — gets the existing `artifact-unset` answer ("change N has no spec yet"). + +### 6. Spec always — the brainstorm direction + +`docket-groom-next` and `docket-new-change` tell the brainstorm role, at the point they invoke it, +that its artifact is always a written spec, sized to the change: a small change gets a short spec, +and the brainstorm never concludes that a change needs no written design. Phrase it by shape (what +outcome to avoid), never by citing a vendored superpowers heading. Keep it to the minimum prose that +does the job; these skills are read on every groom. + +`docket-groom-next`: delete the trivial exit (Step 4 becomes five exits) and every "or trivial" / +"not trivial" / "trivial rationale" clause in selection, the revise route, retitle, reprioritize, +deliverable, hold, and stacking paragraphs. + +`docket-new-change`: delete the *Trivial path* section and its *When to use* bullet. Small work is +captured through brainstorm mode (with a short spec) or as a stub groomed later. + +### 7. Auto-groom + +Autonomous grooming has two exits: **spec** and **abstain**. The designer pass drops the +"genuinely mechanical → trivial verdict" sentence; a mechanical stub gets a short spec with its +`## Assumptions` block like any other. The critic attacks a spec, never a verdict. Update the +drain summary (`groomed N, abstained K`), the termination paragraph, the hold paragraph, the skill +and agent descriptions, and the critic agent's description. + +### 8. ADR + +Record a new ADR that supersedes ADR-0006 (through `docket-adr` during the build): every +build-ready change carries a spec; autonomous grooming has two exits (spec, abstain); ADR-0006's two +bounds (an adversarial critic gates every build-ready exit; kill and defer are never autonomous) +carry forward unchanged. ADR-0153 (hold) already narrows ADR-0006's "build-ready means the +autonomous builder will build it" for held changes; the new ADR keeps that hold exception and +relates to ADR-0153, so the supersession does not silently restore the old rule (my call). The new +ADR's *Alternatives considered* records why the trivial exit was retired rather than repaired +(requiring decisions in the trivial body still keeps the design off the PR and saves nothing over a +short spec). ADR-0129 mentions `trivial` only inside a historical rename table and stays as it is. + +### 9. Skill, agent, and doc prose + +Docs describe only current behavior: delete `trivial` mentions outright, with no "formerly" notes. +The set below comes from a repo-wide grep. Watch the spelling "non-trivial": most uses are +ordinary English, but two refer to the flag and change too (implement-next's "(non-trivial +changes)" beside the spec copy, and new-change's "The default path for any non-trivial new +change"). Frozen point-in-time snapshots stay untouched: `docs/release/v1.0.0-alpha.2/*` and +`internal/install/legacydata/*`. + +- `skills/docket-convention/SKILL.md` — manifest's `trivial:` line, build-readiness, + needs-grooming, auto-groomable, the hold sentence, and "trivial included" in the results lines. +- `skills/docket-groom-next/SKILL.md`, `skills/docket-new-change/SKILL.md`, + `skills/docket-auto-groom/SKILL.md` — as in decisions 6 and 7. +- `skills/docket-implement-next/SKILL.md` — reconcile's "A trivial change has no spec — patch the + body only", commit-spec's "(a trivial change reports `no-spec`)", the "trivial included" + results line, and the `reconciled` paragraph's readiness restatement. +- `skills/docket-implement-next/references/results-artifact.md`, + `skills/docket-implement-next/results-template.md`, `skills/docket-review/SKILL.md`, + `skills/docket-status/SKILL.md` — "or a trivial change's body", "trivial included", and the + board-cell list. +- `agents/docket-auto-groom.md`, `agents/docket-auto-groom-critic.md` — descriptions; then + regenerate the harness goldens that embed them (`internal/harness/*/testdata/golden/docket-auto-groom*`). +- `cursor-rules/dispatch/docket-auto-groom-critic.md` — hand-maintained; "draft spec / trivial + verdict" appears twice. +- `README.md`, `docs/guide/capturing-work.md`, `docs/guide/designing-before-building.md`, + `docs/guide/building-without-supervision.md`, `docs/concepts/change-lifecycle.md`, + `docs/reference/glossary.md` (including the `### Trivial` entry and the "Capture modes" entry), + `docs/install/models-and-effort.md` ("a trivial verdict"), and + `docs/comparison/ai-native-sdlc-playbook.md` (the "Trivial path" row, "or `trivial: true`", and + the capture-modes list). + +"Required for every change, trivial included" becomes "required for every implemented change." +Regenerate embedded assets after skill edits (`go generate ./internal/assets/`). + +### 10. Tests + +- About 40 test setups use `trivial: true` as a cheap way to make a change build-ready. Give them + a spec instead (a minimal spec file plus `spec:`), through a shared fixture helper where one + fits. +- Delete tests that exist only for the trivial outcome, the trivial board cell, or the + `trivial-no-spec` open reason. +- Update pinned prose and budgets that move: `internal/repoguard/prose_contracts_test.go` (the + "trivial included" phrases) and `internal/repoguard/budgets_test.go` (skill line/byte budgets). +- New coverage: `outcome: trivial` refuses as an invalid outcome and writes nothing; a record + carrying `trivial: true` and no spec reads as needs-grooming, and a groom of it keeps the + `trivial: true` line byte-identical; a newly created record has no `trivial:` key. +- The status-corpus testdata records keep their `trivial: true` lines; they now double as proof + that the key is inert. + +### 11. `workspace.commit-spec` keeps `no-spec` (my call) + +Once readiness requires a spec, a change claimed after the upgrade always has one. A change claimed +*before* it with `trivial: true` and no spec could still be in progress when the binary is +swapped, so `no-spec` stays as the quiet no-op it is today and that build finishes. Only its +"trivial" comment and implement-next's "(a trivial change reports `no-spec`)" clause change. + +## Left to the builder + +- The fixture helper's shape and where it lives. +- Exact wording of the brainstorm direction, within decision 6's constraints. From 73a28c560ebc21f0dacb517f206dfb96a046da99 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Mon, 19 Oct 2026 20:18:51 -0400 Subject: [PATCH 02/12] test(app): build-ready fixtures link a spec instead of trivial: true --- internal/app/change_claim_test.go | 8 +-- .../change_implemented_integration_test.go | 6 +-- internal/app/change_implemented_test.go | 10 ++-- internal/app/change_integration_test.go | 11 +--- internal/app/claim_workflow_git_test.go | 11 ++-- .../app/finalize_cleanup_integration_test.go | 14 ++--- internal/app/implementation_context_test.go | 2 +- .../leak_check_private_integration_test.go | 47 +++++++++-------- internal/app/named_branch_facts_test.go | 18 +++++-- .../app/named_isolation_integration_test.go | 2 + internal/app/planning_git_test.go | 3 +- ...ository_set_visibility_integration_test.go | 1 + .../runtracker_verdict_integration_test.go | 4 +- internal/app/spec_fixture_test.go | 51 +++++++++++++++++++ internal/app/workflow_e2e_test.go | 10 ++-- internal/app/workflow_integration_test.go | 21 +++++--- 16 files changed, 135 insertions(+), 84 deletions(-) create mode 100644 internal/app/spec_fixture_test.go diff --git a/internal/app/change_claim_test.go b/internal/app/change_claim_test.go index 28da92017..5c6363e54 100644 --- a/internal/app/change_claim_test.go +++ b/internal/app/change_claim_test.go @@ -14,10 +14,10 @@ import ( ) // claimableChange renders a proposed, build-ready change: the canonical proposed -// record with trivial: true (so it carries a design outcome) and no claim -// fields yet. Claiming it must INSERT branch/claimed_at/reconciled. +// record linking a spec (so it carries a design) and no claim fields yet. +// Claiming it must INSERT branch/claimed_at/reconciled. func claimableChange(id int, slug string) string { - return strings.Replace(lifecycleChange(id, slug, "proposed"), "trivial: false\n", "trivial: true\n", 1) + return withLinkedSpec(lifecycleChange(id, slug, "proposed"), fixtureSpecPath(slug)) } // stackedOn rewrites a record's empty stacked_on edge to point at parent. @@ -527,7 +527,7 @@ func assertUnrelatedShapeIntact(t *testing.T, repo *gitRepo, branch string, shap // and the claimed record keeps the hold for the human to lift. func TestChangeClaimAcceptsHeldChangeAndKeepsField(t *testing.T) { recPath := groomPath(3, "widget") - src := strings.Replace(claimableChange(3, "widget"), "trivial: true\n", "trivial: true\nhold: true\n", 1) + src := strings.Replace(claimableChange(3, "widget"), "trivial: false\n", "trivial: false\nhold: true\n", 1) plan, opRes := claimPlanFor(t, map[string]string{recPath: src}, baseClaimOp([]string{"inline"}, 3, domain.NewBranchFacts(nil))) if opRes.Refused { t.Fatalf("claim of a held change refused: %v", opRes.Findings) diff --git a/internal/app/change_implemented_integration_test.go b/internal/app/change_implemented_integration_test.go index 6408f6292..705e09599 100644 --- a/internal/app/change_implemented_integration_test.go +++ b/internal/app/change_implemented_integration_test.go @@ -39,7 +39,7 @@ func TestIntegrationRecordOpsMarkImplementedAcceptsSkippedEvidence(t *testing.T) // Through the production engine, the committed record carries the skipped // evidence it verified as its "## Build evidence" section. recPath := groomPath(3, miSlug) - real := newWorkingRepo(t, map[string]string{recPath: miRecord(3, miSlug, miPlanPath(), miResultsPath, true, false)}) + real := newWorkingRepo(t, map[string]string{recPath: miRecord(3, miSlug, miPlanPath(), miResultsPath, true)}) realHead := miAdvanceHead(t, real) advanceDocketOrigin(t, real, miMetadataResults()) if res := miRealRunWith(t, real, recPath, realHead, prSkippedEvidenceBytes(t, realHead)); res.Result != ResultApplied { @@ -62,7 +62,7 @@ func TestIntegrationRecordOpsMarkImplementedUnrelatedInvalidRecordProgress(t *te requireRealGit(t) recPath := groomPath(3, miSlug) repo := newWorkingRepo(t, map[string]string{ - recPath: miRecord(3, miSlug, miPlanPath(), miResultsPath, true, false), + recPath: miRecord(3, miSlug, miPlanPath(), miResultsPath, true), unrelatedBrokenPath: unrelatedBrokenBytes, }) head := miAdvanceHead(t, repo) @@ -79,7 +79,7 @@ func TestIntegrationRecordOpsMarkImplementedUnrelatedInvalidRecordProgress(t *te func TestIntegrationRecordOpsMarkImplementedUnrelatedInvalidRecordRefusals(t *testing.T) { requireRealGit(t) recPath := groomPath(3, miSlug) - src := miRecord(3, miSlug, miPlanPath(), miResultsPath, true, false) + src := miRecord(3, miSlug, miPlanPath(), miResultsPath, true) for _, c := range unrelatedRefusalCases(t, 3, recPath, src, lifecycleChange(3, "dupe", "in-progress")) { t.Run(c.name, func(t *testing.T) { repo := newWorkingRepo(t, c.files) diff --git a/internal/app/change_implemented_test.go b/internal/app/change_implemented_test.go index fb61acf1e..c8b1ede31 100644 --- a/internal/app/change_implemented_test.go +++ b/internal/app/change_implemented_test.go @@ -20,14 +20,11 @@ const miRevision = "1234123412341234123412341234123412341234" // miRecord renders an in-progress change record with the given plan/results // linkage and reconciled flag — the shape mark-implemented reprobes. -func miRecord(id int, slug, plan, results string, reconciled, trivial bool) string { +func miRecord(id int, slug, plan, results string, reconciled bool) string { src := lifecycleChange(id, slug, "in-progress") if !reconciled { src = strings.Replace(src, "reconciled: true", "reconciled: false", 1) } - if trivial { - src = strings.Replace(src, "trivial: false", "trivial: true", 1) - } if plan != "" { src = strings.Replace(src, "plan:\n", "plan: '"+plan+"'\n", 1) } @@ -100,7 +97,7 @@ func TestMarkImplementedApplies(t *testing.T) { recPath := groomPath(3, "widget") planPath := "docs/superpowers/plans/2026-08-17-widget-plan.md" files := map[string]string{ - recPath: miRecord(3, "widget", planPath, "", true, false), + recPath: miRecord(3, "widget", planPath, "", true), "docs/changes/BOARD.md": "# Backlog\n\nold\n", } plan, opRes := implementedPlanFor(t, files, baseImplementedOp([]string{"inline"}, 3, "github.com/acme/widget#42")) @@ -216,7 +213,6 @@ func miAdvanceHead(t *testing.T, repo *gitRepo) string { // condition's stable reason, having never called the engine. type miKit struct { reconciled bool - trivial bool plan string results string revision string // corpus blob revision @@ -243,7 +239,7 @@ func buildMI(t *testing.T, client *gitcli.Client, invocation string, k miKit) ( Location: repository.LocationActive, Path: groomPath(3, miSlug), Revision: k.revision, - Data: []byte(miDeliverable(miRecord(3, miSlug, k.plan, k.results, k.reconciled, k.trivial), k.deliverable)), + Data: []byte(miDeliverable(miRecord(3, miSlug, k.plan, k.results, k.reconciled), k.deliverable)), } artifacts := map[string]StatusArtifact{} for p, content := range miMetadataResults() { diff --git a/internal/app/change_integration_test.go b/internal/app/change_integration_test.go index a203e39e7..9a8595ea7 100644 --- a/internal/app/change_integration_test.go +++ b/internal/app/change_integration_test.go @@ -1944,20 +1944,11 @@ func TestIntegrationChangeRuntimeMarkImplementedConditions(t *testing.T) { }, reason: ReasonImplementedPRReferenceMismatch, }, - { // condition 5 — required (change 0410): an empty results field refuses, - // trivial changes included (there is no trivial exemption to remove). + { // condition 5 — required (change 0410): an empty results field refuses. name: "no results artifact is attached", mutate: func(k *miKit) { k.results = "" }, reason: ReasonImplementedResultsMissing, }, - { // condition 5 — required for a trivial change too (pin, not a branch change). - name: "trivial change with no results artifact still refuses", - mutate: func(k *miKit) { - k.results = "" - k.trivial = true - }, - reason: ReasonImplementedResultsMissing, - }, { // condition 5 — the attached path is a metadata file with the correct // backlink, but its FINAL content is filler (## Findings and limitations → None.). name: "attached results fail the final content contract", diff --git a/internal/app/claim_workflow_git_test.go b/internal/app/claim_workflow_git_test.go index 29429d40c..aaae49d7c 100644 --- a/internal/app/claim_workflow_git_test.go +++ b/internal/app/claim_workflow_git_test.go @@ -2,7 +2,6 @@ package app import ( "github.com/danielhanold/docket/internal/repository/transaction" - "strings" "testing" ) @@ -25,12 +24,12 @@ import ( // origin, never the invocation clone's stale local tree. // buildReadyChange renders a proposed, unstacked, build-ready change record: the -// canonical groomable record with trivial flipped true, so EvaluateReadiness -// reports build-ready (design present) and ClaimEligibility passes without a -// separate spec artifact. It is the fixture the claim race/retry tests start -// from — a change a fresh context read reports claim-eligible. +// canonical groomable record linking a spec, so EvaluateReadiness reports +// build-ready (design present) and ClaimEligibility passes. It is the fixture +// the claim race/retry tests start from — a change a fresh context read reports +// claim-eligible. func buildReadyChange(id int, slug string) string { - return strings.Replace(groomableChange(id, slug), "trivial: false\n", "trivial: true\n", 1) + return withLinkedSpec(groomableChange(id, slug), fixtureSpecPath(slug)) } // --- claim race: two claimants, same context revision, one loses cleanly ----- diff --git a/internal/app/finalize_cleanup_integration_test.go b/internal/app/finalize_cleanup_integration_test.go index b88c2e70e..089cda88d 100644 --- a/internal/app/finalize_cleanup_integration_test.go +++ b/internal/app/finalize_cleanup_integration_test.go @@ -973,10 +973,10 @@ func TestIntegrationFinalizeCleanupResultsArtifactRealGit(t *testing.T) { slug = "research" ) recPath := groomPath(id, slug) - rec := strings.Replace(groomableChange(id, slug), "trivial: false\n", "trivial: true\n", 1) + rec := withLinkedSpec(groomableChange(id, slug), fixtureSpecPath(slug)) rec = strings.Replace(rec, "type: feat\n", "type: feat\ndeliverable: results-artifact\n", 1) m := planRepoModes()[0] - repo := buildConfiguredRepoWith(t, m, map[string]string{recPath: rec}) + repo := buildConfiguredRepoWith(t, m, map[string]string{recPath: rec, fixtureSpecPath(slug): fixtureSpecFile(id, slug)}) lw := prepareLeakWorkspace(t, repo, m.branch, id, recPath, false) runGit(t, lw.wp, "push", "-q", "origin", "HEAD:"+lw.featureRef) @@ -995,7 +995,7 @@ func TestIntegrationFinalizeCleanupResultsArtifactPrivate(t *testing.T) { requireRealGit(t) create := validChangeCreateRequest() create.Deliverable = string(domain.DeliverableResultsArtifact) - lw, lay := newPrivateLeakWorkspaceFor(t, create, false) + lw, lay := newPrivateLeakWorkspaceFor(t, create) meta := lay.DefaultBareRemote recPath := runGit(t, meta, "ls-tree", "-r", "--name-only", privateFixtureBranch, "docs/changes/active/") if strings.Contains(recPath, "\n") || recPath == "" { @@ -1085,10 +1085,10 @@ func TestIntegrationFinalizeCleanupResultsArtifactNeverPrepared(t *testing.T) { ) setup := func(t *testing.T) (*gitRepo, realNode, FinalizeDeps, *workspace.Service) { recPath := groomPath(id, slug) - rec := strings.Replace(groomableChange(id, slug), "trivial: false\n", "trivial: true\n", 1) + rec := withLinkedSpec(groomableChange(id, slug), fixtureSpecPath(slug)) rec = strings.Replace(rec, "type: feat\n", "type: feat\ndeliverable: results-artifact\n", 1) m := planRepoModes()[0] - repo := buildConfiguredRepoWith(t, m, map[string]string{recPath: rec}) + repo := buildConfiguredRepoWith(t, m, map[string]string{recPath: rec, fixtureSpecPath(slug): fixtureSpecFile(id, slug)}) node, deps, svc := completeNeverPrepared(t, repo, m.branch, id, recPath) return repo, node, deps, svc } @@ -1219,10 +1219,10 @@ func TestIntegrationFinalizeCleanupLeftoverBranchFullSweep(t *testing.T) { setup := func(t *testing.T) (*leakWorkspace, FinalizeDeps) { t.Helper() recPath := groomPath(id, slug) - rec := strings.Replace(groomableChange(id, slug), "trivial: false\n", "trivial: true\n", 1) + rec := withLinkedSpec(groomableChange(id, slug), fixtureSpecPath(slug)) rec = strings.Replace(rec, "type: feat\n", "type: feat\ndeliverable: results-artifact\n", 1) m := planRepoModes()[0] - repo := buildConfiguredRepoWith(t, m, map[string]string{recPath: rec}) + repo := buildConfiguredRepoWith(t, m, map[string]string{recPath: rec, fixtureSpecPath(slug): fixtureSpecFile(id, slug)}) lw := prepareLeakWorkspace(t, repo, m.branch, id, recPath, false) deps := completeLeakWorkspace(t, lw, repo.meta, m.branch, recPath) diff --git a/internal/app/implementation_context_test.go b/internal/app/implementation_context_test.go index 3484cf2a7..7512c17c6 100644 --- a/internal/app/implementation_context_test.go +++ b/internal/app/implementation_context_test.go @@ -573,7 +573,7 @@ func TestContextImplementationBranchFactsFailure(t *testing.T) { // change is selected. func TestImplementationContextAutoSelectionSurvivesMalformedStackBranch(t *testing.T) { pin := docketPin(t) - inner := &fakeReader{pin: pin, corpus: malformedStackCorpus(t), facts: domain.NewBranchFacts(map[string]bool{"feat/ok": true})} + inner := &fakeReader{pin: pin, corpus: malformedStackCorpus(t), facts: domain.NewBranchFacts(map[string]bool{"feat/ok": true}), artifactData: stackFixtureSpecArtifacts()} reader := poisoned(inner, "feat/a..parent", "feat/a:b", "feat/a:c") got := ContextImplementation(context.Background(), PlanningDeps{Reader: reader, Clock: testClock()}, "", ImplementationContextRequest{}) if got.Result == ResultExternalFailed { diff --git a/internal/app/leak_check_private_integration_test.go b/internal/app/leak_check_private_integration_test.go index c59a31fbe..9115a65f0 100644 --- a/internal/app/leak_check_private_integration_test.go +++ b/internal/app/leak_check_private_integration_test.go @@ -10,6 +10,7 @@ import ( "strings" "testing" + "github.com/danielhanold/docket/internal/domain" "github.com/danielhanold/docket/internal/githubcli" "github.com/danielhanold/docket/internal/layout" "github.com/danielhanold/docket/internal/workspace" @@ -39,9 +40,10 @@ type leakWorkspace struct { // prepareLeakWorkspace runs the opening steps of driveClaimToImplemented in // order — context, claim, reconcile, workspace prepare, and the spec-copy commit -// — and fails unless each applies. A change without a spec (spec false) must -// report no-spec instead, and its prepared head stands in for the spec commit. -func prepareLeakWorkspace(t *testing.T, repo *gitRepo, branch string, id int, recPath string, spec bool) *leakWorkspace { +// — and fails unless each applies. With commitSpec false the spec-copy step is +// skipped (as a results-artifact ending skips it), and the prepared head stands +// in for the spec commit. +func prepareLeakWorkspace(t *testing.T, repo *gitRepo, branch string, id int, recPath string, commitSpec bool) *leakWorkspace { t.Helper() ctx := context.Background() node := planningDepsFor(t, repo.invocation) @@ -70,11 +72,7 @@ func prepareLeakWorkspace(t *testing.T, repo *gitRepo, branch string, id int, re if prep.Result != ResultApplied { t.Fatalf("workspace prepare = %q (reason %q msg %q)", prep.Result, prep.Reason, prep.Message) } - cs := WorkspaceCommitSpec(ctx, node.deps, wdeps, node.dir, WorkspaceIDRequest{ID: id}) - if !spec { - if cs.Result != ResultNoOp || cs.Disposition != SpecCopyNoSpec { - t.Fatalf("workspace commit-spec = (%q, %q) (reason %q msg %q), want no-op/no-spec", cs.Result, cs.Disposition, cs.Reason, cs.Message) - } + if !commitSpec { return &leakWorkspace{ node: node, wdeps: wdeps, id: id, wp: prep.Path, specCommit: runGit(t, prep.Path, "rev-parse", "HEAD"), @@ -82,6 +80,7 @@ func prepareLeakWorkspace(t *testing.T, repo *gitRepo, branch string, id int, re origin: repo.origin, writer: repo.writer, invocation: repo.invocation, } } + cs := WorkspaceCommitSpec(ctx, node.deps, wdeps, node.dir, WorkspaceIDRequest{ID: id}) if cs.Result != ResultApplied || cs.Disposition != SpecCopyCommitted { t.Fatalf("workspace commit-spec = (%q, %q) (reason %q msg %q), want applied/committed", cs.Result, cs.Disposition, cs.Reason, cs.Message) } @@ -107,12 +106,13 @@ func prepareLeakWorkspace(t *testing.T, repo *gitRepo, branch string, id int, re // a spec — and prepares its workspace against the dckt store. func newPrivateLeakWorkspace(t *testing.T) (*leakWorkspace, layout.Layout) { t.Helper() - return newPrivateLeakWorkspaceFor(t, validChangeCreateRequest(), true) + return newPrivateLeakWorkspaceFor(t, validChangeCreateRequest()) } // newPrivateLeakWorkspaceFor is newPrivateLeakWorkspace for the given create -// request, groomed with a spec (spec true) or as trivial (no spec copy). -func newPrivateLeakWorkspaceFor(t *testing.T, create ChangeCreateRequest, spec bool) (*leakWorkspace, layout.Layout) { +// request. The change is always groomed with a spec; the spec copy is committed +// unless the change ends in a results artifact, whose ending skips that step. +func newPrivateLeakWorkspaceFor(t *testing.T, create ChangeCreateRequest) (*leakWorkspace, layout.Layout) { t.Helper() ctx := context.Background() r, _ := newPrivateInitRepo(t, nil) @@ -141,15 +141,12 @@ func newPrivateLeakWorkspaceFor(t *testing.T, create ChangeCreateRequest, spec b Outcome: GroomSpec, SpecMarkdown: "# Widget: design\n\nBuild the widget.\n", } - if !spec { - req.Outcome, req.SpecMarkdown = GroomTrivial, "" - req.Sections = []SectionEditRequest{{Heading: "## Why", Intent: "replace", Markdown: "Too small to design.\n"}} - } groom := ChangeGroom(ctx, node.deps, node.dir, req) - if groom.Result != ResultApplied || (spec && groom.SpecPath == "") { - t.Fatalf("change groom = %q (%s, findings %v), want applied (with a spec: %v)", groom.Result, groom.HumanText(), groom.Findings, spec) + if groom.Result != ResultApplied || groom.SpecPath == "" { + t.Fatalf("change groom = %q (%s, findings %v), want applied with a spec", groom.Result, groom.HumanText(), groom.Findings) } - return prepareLeakWorkspace(t, repo, privateFixtureBranch, created.ID, created.Path, spec), lay + commitSpec := create.Deliverable != string(domain.DeliverableResultsArtifact) + return prepareLeakWorkspace(t, repo, privateFixtureBranch, created.ID, created.Path, commitSpec), lay } // newSharedLeakWorkspace builds the shared (docket-branch) fixture @@ -439,14 +436,16 @@ func TestIntegrationPrivateModeLeakCheckUnverifiedPushesNothing(t *testing.T) { // TestIntegrationPrivateModeLeakCheckScansBranchName proves the // pushed feature branch name is scanned like any other published text: a -// trivial change titled "Fix the dckt alias" — no spec copy, clean commits — -// still refuses, because its slug puts dckt in the branch origin would show. +// change titled "Fix the alias table" with branch prefix dckt-fix — clean +// title, slug, spec copy, and commits — still refuses, because its prefix puts +// dckt in the branch origin would show. (A bare dckt prefix cannot be used: the +// private store's local dckt branch blocks a dckt/ ref.) func TestIntegrationPrivateModeLeakCheckScansBranchName(t *testing.T) { create := validChangeCreateRequest() - create.Title, create.Type = "Fix the dckt alias", "fix" - lw, _ := newPrivateLeakWorkspaceFor(t, create, false) - if lw.featureRef != "refs/heads/fix/fix-the-dckt-alias" { - t.Fatalf("feature ref = %q, want refs/heads/fix/fix-the-dckt-alias", lw.featureRef) + create.Title, create.Type, create.BranchPrefix = "Fix the alias table", "fix", "dckt-fix" + lw, _ := newPrivateLeakWorkspaceFor(t, create) + if lw.featureRef != "refs/heads/dckt-fix/fix-the-alias-table" { + t.Fatalf("feature ref = %q, want refs/heads/dckt-fix/fix-the-alias-table", lw.featureRef) } head := commitInWorkspace(t, lw.wp, "Tidy the alias table", map[string]string{"aliases.txt": "tidy\n"}) diff --git a/internal/app/named_branch_facts_test.go b/internal/app/named_branch_facts_test.go index 95d0e90be..429473323 100644 --- a/internal/app/named_branch_facts_test.go +++ b/internal/app/named_branch_facts_test.go @@ -49,14 +49,26 @@ func poisoned(inner StatusReader, branches ...string) *poisonBranchReader { return &poisonBranchReader{StatusReader: inner, poison: set} } +// stackFixtureSpecPath is the spec every stackFixtureBlob record links. +const stackFixtureSpecPath = "docs/superpowers/specs/x-design.md" + +// stackFixtureSpecArtifacts serves stackFixtureSpecPath from the metadata +// branch, for a fake reader whose operation reads the linked spec. +func stackFixtureSpecArtifacts() map[string]StatusArtifact { + return map[string]StatusArtifact{ + sourceMetadata + "|" + stackFixtureSpecPath: {Found: true, Revision: "specx", Data: []byte("# X: design\n")}, + } +} + // stackFixtureBlob renders a change record for the stackBranchesFor fixture. +// Every record links stackFixtureSpecPath, so a proposed one is build-ready. func stackFixtureBlob(id int, slug, status, branch, extra string) StatusBlob { branchField := "" if branch != "" { branchField = "branch: '" + branch + "'\nclaimed_at: '2026-01-03T00:00:00Z'\nreconciled: true\n" } - fm := fmt.Sprintf("---\nid: %d\nslug: %s\ntitle: Change %d\nstatus: '%s'\npriority: medium\ntype: feat\ncreated: 2026-01-02\ntrivial: true\n%s%s---\n\nBody of %d.\n", - id, slug, id, status, branchField, extra, id) + fm := fmt.Sprintf("---\nid: %d\nslug: %s\ntitle: Change %d\nstatus: '%s'\npriority: medium\ntype: feat\ncreated: 2026-01-02\nspec: '%s'\n%s%s---\n\nBody of %d.\n", + id, slug, id, status, stackFixtureSpecPath, branchField, extra, id) return StatusBlob{ Kind: repository.KindChange, Location: repository.LocationActive, @@ -122,7 +134,7 @@ func TestContextImplementationNamedIDProbesOnlyOwnStack(t *testing.T) { t.Run("unrelated-poison-does-not-block", func(t *testing.T) { corpus := append(append([]StatusBlob(nil), unrelated...), stackFixtureBlob(30, "b", "proposed", "", "")) - reader := poisoned(&fakeReader{pin: pin, corpus: corpus, facts: domain.NewBranchFacts(nil)}, "feat/a-parent") + reader := poisoned(&fakeReader{pin: pin, corpus: corpus, facts: domain.NewBranchFacts(nil), artifactData: stackFixtureSpecArtifacts()}, "feat/a-parent") got := ContextImplementation(context.Background(), PlanningDeps{Reader: reader, Clock: testClock()}, "", ImplementationContextRequest{ID: 30}) if got.Result != ResultApplied { t.Fatalf("named context beside an unprobeable unrelated stack = %q (%s: %s), want applied", got.Result, got.Reason, got.Message) diff --git a/internal/app/named_isolation_integration_test.go b/internal/app/named_isolation_integration_test.go index 5d368a190..2d4f7212a 100644 --- a/internal/app/named_isolation_integration_test.go +++ b/internal/app/named_isolation_integration_test.go @@ -185,6 +185,7 @@ func TestIntegrationNamedImplementationFlowIsolation(t *testing.T) { resultsPath := "docs/results/2026-08-17-widget-results.md" records := namedIsolationUnrelatedStack(t) records[recPath] = buildReadyChange(id, slug) + records[fixtureSpecPath(slug)] = fixtureSpecFile(id, slug) records[unrelatedBrokenPath] = unrelatedBrokenBytes repo := newDocketModeRepo(t, map[string]string{".docket.yml": "integration_branch: main\nbuild:\n test_command: 'go test ./...'\nfinalize:\n test_command: 'go test ./...'\n"}, @@ -309,6 +310,7 @@ func TestIntegrationNamedClaimRefusesDefectiveDependency(t *testing.T) { } records := namedIsolationUnrelatedStack(t) records[recPath] = b + records[fixtureSpecPath("widget")] = fixtureSpecFile(id, "widget") records[depPath] = dep records[unrelatedBrokenPath] = unrelatedBrokenBytes repo := newWorkingRepo(t, records) diff --git a/internal/app/planning_git_test.go b/internal/app/planning_git_test.go index c231cc44b..68141ea66 100644 --- a/internal/app/planning_git_test.go +++ b/internal/app/planning_git_test.go @@ -267,8 +267,7 @@ func assertIndexMatchesCommitted(t *testing.T, origin, branch, repoDir string) { // killableChangeWithSpec renders a proposed change record carrying a spec pointer // at specPath, so a kill exercises the metadata-resident-spec backlink retarget. func killableChangeWithSpec(id int, slug, specPath string) string { - src := groomableChange(id, slug) - return strings.Replace(src, "spec:\n", "spec: "+specPath+"\n", 1) + return withLinkedSpec(groomableChange(id, slug), specPath) } // specWithBacklink renders a minimal spec file: a docket:backlink managed block diff --git a/internal/app/repository_set_visibility_integration_test.go b/internal/app/repository_set_visibility_integration_test.go index faa34f8e2..a68b07fb9 100644 --- a/internal/app/repository_set_visibility_integration_test.go +++ b/internal/app/repository_set_visibility_integration_test.go @@ -1367,6 +1367,7 @@ func TestIntegrationRepoVisibilitySwitchRoundTripPreservesRecords(t *testing.T) dotDocket := filepath.Join(r.invocation, layout.SharedWorktreeDir) runGit(t, dotDocket, "fetch", "-q", "origin", layout.SharedName) runGit(t, dotDocket, "merge", "-q", "--ff-only", "FETCH_HEAD") + r.writeDocketFileAndPush(t, fixtureSpecPath("widget"), fixtureSpecFile(claimID, "widget"), "the spec the change links") r.writeDocketFileAndPush(t, recPath, buildReadyChange(claimID, "widget"), "a build-ready change to claim") node := planningDepsFor(t, r.invocation) bundle := ContextImplementation(ctx, node.deps, node.dir, ImplementationContextRequest{ID: claimID}) diff --git a/internal/app/runtracker_verdict_integration_test.go b/internal/app/runtracker_verdict_integration_test.go index 78c449f41..439daaf15 100644 --- a/internal/app/runtracker_verdict_integration_test.go +++ b/internal/app/runtracker_verdict_integration_test.go @@ -1706,10 +1706,10 @@ func TestIntegrationRunVerdictCompletedResultsArtifactReadsDone(t *testing.T) { slug = "research" ) recPath := groomPath(id, slug) - rec := strings.Replace(groomableChange(id, slug), "trivial: false\n", "trivial: true\n", 1) + rec := withLinkedSpec(groomableChange(id, slug), fixtureSpecPath(slug)) rec = strings.Replace(rec, "type: feat\n", "type: feat\ndeliverable: results-artifact\n", 1) m := planRepoModes()[0] - repo := buildConfiguredRepoWith(t, m, map[string]string{recPath: rec}) + repo := buildConfiguredRepoWith(t, m, map[string]string{recPath: rec, fixtureSpecPath(slug): fixtureSpecFile(id, slug)}) lw := prepareLeakWorkspace(t, repo, m.branch, id, recPath, false) completeLeakWorkspace(t, lw, repo.meta, m.branch, recPath) diff --git a/internal/app/spec_fixture_test.go b/internal/app/spec_fixture_test.go new file mode 100644 index 000000000..74d825aa1 --- /dev/null +++ b/internal/app/spec_fixture_test.go @@ -0,0 +1,51 @@ +package app + +import ( + "fmt" + "strings" + "testing" +) + +func TestWithLinkedSpecLinksAndRefusesMissingAnchor(t *testing.T) { + got := withLinkedSpec(lifecycleChange(3, "widget", "proposed"), fixtureSpecPath("widget")) + if !strings.Contains(got, "\nspec: 'docs/superpowers/specs/2026-08-01-widget-design.md'\n") { + t.Errorf("record does not link the fixture spec:\n%s", got) + } + if strings.Contains(got, "\nspec:\n") { + t.Errorf("record still carries an empty spec line:\n%s", got) + } + + panicked := func() (p bool) { + defer func() { p = recover() != nil }() + withLinkedSpec("---\nid: 3\n---\n", fixtureSpecPath("widget")) + return false + }() + if !panicked { + t.Errorf("withLinkedSpec on a record with no empty spec line did not panic") + } +} + +// fixtureSpecPath is the spec path a build-ready fixture change links. +func fixtureSpecPath(slug string) string { + return "docs/superpowers/specs/2026-08-01-" + slug + "-design.md" +} + +// withLinkedSpec links specPath on a record's empty spec line, so a proposed +// fixture carries the design every build-ready change needs. It panics when the +// record has no empty spec line, so a fixture can never silently stay spec-less. +func withLinkedSpec(src, specPath string) string { + const anchor = "\nspec:\n" + if !strings.Contains(src, anchor) { + panic("withLinkedSpec: record has no empty \"spec:\" line to link") + } + return strings.Replace(src, anchor, "\nspec: '"+specPath+"'\n", 1) +} + +// fixtureSpecFile is a spec as the metadata branch stores it: a +// docket:backlink block above the authored title. +func fixtureSpecFile(id int, slug string) string { + return "\n" + + "> ↩ **[Change " + fmt.Sprintf("%04d", id) + " — A change](../../changes/active/" + fmt.Sprintf("%04d", id) + "-" + slug + ".md)**\n" + + "\n\n" + + "# Widget: design\n\nBuild the widget.\n" +} diff --git a/internal/app/workflow_e2e_test.go b/internal/app/workflow_e2e_test.go index 76ec5b7c5..164bd9b55 100644 --- a/internal/app/workflow_e2e_test.go +++ b/internal/app/workflow_e2e_test.go @@ -2,7 +2,6 @@ package app import ( "context" - "fmt" "github.com/danielhanold/docket/internal/evidence" "github.com/danielhanold/docket/internal/githubcli" "github.com/danielhanold/docket/internal/testsupport" @@ -364,18 +363,15 @@ func buildConfiguredRepoWith(t *testing.T, m planRepoMode, metadata map[string]s } // specLinkedBuildReadyChange is a proposed, build-ready change record whose -// design is the spec at specPath (not a trivial verdict). +// design is the spec at specPath. func specLinkedBuildReadyChange(id int, slug, specPath string) string { - return strings.Replace(groomableChange(id, slug), "spec:\n", "spec: "+specPath+"\n", 1) + return withLinkedSpec(groomableChange(id, slug), specPath) } // workflowMetadataSpec is a spec as the metadata branch stores it: a // docket:backlink block above the authored title. func workflowMetadataSpec(id int, slug string) string { - return "\n" + - "> ↩ **[Change " + fmt.Sprintf("%04d", id) + " — A change](../../changes/active/" + fmt.Sprintf("%04d", id) + "-" + slug + ".md)**\n" + - "\n\n" + - "# Widget: design\n\nBuild the widget.\n" + return fixtureSpecFile(id, slug) } // assertDeferredCapabilityBlocksClaim proves a `.docket.yml` that actively diff --git a/internal/app/workflow_integration_test.go b/internal/app/workflow_integration_test.go index 4432b0033..42263a9af 100644 --- a/internal/app/workflow_integration_test.go +++ b/internal/app/workflow_integration_test.go @@ -397,7 +397,8 @@ func TestIntegrationWorkflowRepoClaimRaceLosesCleanly(t *testing.T) { m := m t.Run(m.name, func(t *testing.T) { repo := m.build(t, map[string]string{ - recPath: buildReadyChange(id, slug), + recPath: buildReadyChange(id, slug), + fixtureSpecPath(slug): fixtureSpecFile(id, slug), }) ctx := context.Background() @@ -494,7 +495,8 @@ func TestIntegrationWorkflowRepoClaimForeignRunContextSameRevisionContends(t *te m := m t.Run(m.name, func(t *testing.T) { repo := m.build(t, map[string]string{ - recPath: buildReadyChange(id, slug), + recPath: buildReadyChange(id, slug), + fixtureSpecPath(slug): fixtureSpecFile(id, slug), }) ctx := context.Background() nodeA := planningDepsFor(t, cloneOrigin(t, repo.origin)) @@ -556,7 +558,8 @@ func TestIntegrationWorkflowRepoClaimRetryAfterLostResponse(t *testing.T) { m := m t.Run(m.name, func(t *testing.T) { repo := m.build(t, map[string]string{ - recPath: buildReadyChange(id, slug), + recPath: buildReadyChange(id, slug), + fixtureSpecPath(slug): fixtureSpecFile(id, slug), }) node := planningDepsFor(t, repo.invocation) ctx := context.Background() @@ -1288,7 +1291,8 @@ func TestIntegrationWorkflowRepoRefreshClaimAppliesWhenBoardReRenderIsUnchanged( m := m t.Run(m.name, func(t *testing.T) { repo := m.build(t, map[string]string{ - recPath: buildReadyChange(id, slug), + recPath: buildReadyChange(id, slug), + fixtureSpecPath(slug): fixtureSpecFile(id, slug), }) ctx := context.Background() @@ -1369,8 +1373,8 @@ func TestIntegrationWorkflowRepoStackedContextClaimWorkspaceFromParentBranch(t * ) parentRec := groomPath(parentID, parentSlug) childRec := groomPath(childID, childSlug) - // The child is proposed + designed (trivial: true stands in for a spec, - // as in buildReadyChange) and stacked on the live parent. + // The child is proposed + designed (it links a spec, as in + // buildReadyChange) and stacked on the live parent. childBody := strings.Replace(buildReadyChange(childID, childSlug), "stacked_on:\n", "stacked_on: 20\n", 1) @@ -1378,8 +1382,9 @@ func TestIntegrationWorkflowRepoStackedContextClaimWorkspaceFromParentBranch(t * m := m t.Run(m.name, func(t *testing.T) { repo := m.build(t, map[string]string{ - parentRec: lifecycleChange(parentID, parentSlug, "in-progress"), - childRec: childBody, + parentRec: lifecycleChange(parentID, parentSlug, "in-progress"), + childRec: childBody, + fixtureSpecPath(childSlug): fixtureSpecFile(childID, childSlug), }) ctx := context.Background() From 3373fff9ad31c7d58626c313021f7bc70d501e28 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Mon, 19 Oct 2026 20:19:51 -0400 Subject: [PATCH 03/12] test(domain): build-ready fixtures link a spec instead of Trivial --- internal/domain/readiness_test.go | 8 ++++---- internal/domain/selection_test.go | 16 +++++++++------- internal/domain/types_test.go | 2 +- 3 files changed, 14 insertions(+), 12 deletions(-) diff --git a/internal/domain/readiness_test.go b/internal/domain/readiness_test.go index 0af5d715c..90d9dca41 100644 --- a/internal/domain/readiness_test.go +++ b/internal/domain/readiness_test.go @@ -101,7 +101,7 @@ func TestEvaluateReadinessPrecedence(t *testing.T) { }, { name: "a negative id is invalid", - specs: []readySpec{{id: -3, status: StatusProposed, trivial: true}}, + specs: []readySpec{{id: -3, status: StatusProposed, spec: specRef("docs/specs/a.md")}}, subject: -3, want: ReadyInvalid, }, @@ -113,7 +113,7 @@ func TestEvaluateReadinessPrecedence(t *testing.T) { }, { name: "a leading-hyphen slug is invalid", - specs: []readySpec{{id: 2, slug: "-leading", status: StatusProposed, trivial: true}}, + specs: []readySpec{{id: 2, slug: "-leading", status: StatusProposed, spec: specRef("docs/specs/a.md")}}, subject: 2, want: ReadyInvalid, }, @@ -302,7 +302,7 @@ func TestEvaluateReadinessPrecedence(t *testing.T) { // A record with no slug at all cannot be expressed through readySpec, whose // empty slug means "use the default", so this case is built directly. func TestEvaluateReadinessRejectsAnEmptySlug(t *testing.T) { - c := NewChange(ChangeSpec{ID: 2, Status: StatusProposed, Trivial: true}) + c := NewChange(ChangeSpec{ID: 2, Status: StatusProposed, Spec: specRef("docs/specs/a.md")}) s := NewSnapshot(SnapshotSpec{ Policy: RepositoryPolicy{IntegrationBranch: "main"}, Changes: []Change{c}, @@ -347,7 +347,7 @@ func TestEvaluateReadinessPopulatesStackBaseWhenConsulted(t *testing.T) { readySpec{id: 1, status: StatusKilled}, readySpec{id: 2, status: StatusProposed, spec: specRef("s.md"), parent: parentEdge(1)}, readySpec{id: 4, status: StatusInProgress, branch: "feat/four"}, - readySpec{id: 5, status: StatusProposed, trivial: true, parent: parentEdge(4)}, + readySpec{id: 5, status: StatusProposed, spec: specRef("docs/specs/a.md"), parent: parentEdge(4)}, ) blocked, _ := s.Change(2) diff --git a/internal/domain/selection_test.go b/internal/domain/selection_test.go index a9c2fab05..c56125b8c 100644 --- a/internal/domain/selection_test.go +++ b/internal/domain/selection_test.go @@ -20,14 +20,17 @@ type selSpec struct { } // build turns a selSpec into an immutable Change, defaulting to a -// build-ready shape (proposed, and trivial when no spec: reference is given) +// build-ready shape (proposed, with a spec: reference) // unless the case asks for a change carrying no design. func (sp selSpec) build() Change { status := sp.status if status == "" { status = StatusProposed } - trivial := !sp.noDesign && sp.spec.State != FieldPresent + spec := sp.spec + if !sp.noDesign && spec.State != FieldPresent { + spec = specRef("docs/specs/a.md") + } slug := sp.slug if slug == "" { slug = "a-slug" @@ -39,8 +42,7 @@ func (sp selSpec) build() Change { Priority: sp.priority, Created: sp.created, Type: sp.kind, - Trivial: trivial, - Spec: sp.spec, + Spec: spec, }) } @@ -215,7 +217,7 @@ func TestSelectQueueOrdering(t *testing.T) { func TestSelectQueueExcludesNonBuildReady(t *testing.T) { s := selSnapshot( - selSpec{id: 1, priority: PriorityHigh}, // proposed + trivial + selSpec{id: 1, priority: PriorityHigh}, // proposed + spec selSpec{id: 2, priority: PriorityHigh, status: StatusInProgress}, // not proposed selSpec{id: 3, priority: PriorityHigh, status: StatusDone}, // not proposed selSpec{id: 4, priority: PriorityHigh, noDesign: true, spec: OptionalString{State: FieldEmpty}}, @@ -263,7 +265,7 @@ func TestSelectQueueExcludesAWaitingDependency(t *testing.T) { selSpec{id: 2, priority: PriorityHigh}, ) dependent := NewChange(ChangeSpec{ - ID: 3, Status: StatusProposed, Priority: PriorityCritical, Trivial: true, + ID: 3, Status: StatusProposed, Priority: PriorityCritical, Spec: specRef("docs/specs/a.md"), DependsOn: []ChangeID{1}, }) s = NewSnapshot(SnapshotSpec{ @@ -281,7 +283,7 @@ func TestSelectQueueExcludesAWaitingDependency(t *testing.T) { // changes, so a held change never enters the queue. func TestSelectQueueExcludesAHeldChange(t *testing.T) { held := NewChange(ChangeSpec{ - ID: 3, Slug: "a-slug", Status: StatusProposed, Priority: PriorityCritical, Trivial: true, + ID: 3, Slug: "a-slug", Status: StatusProposed, Priority: PriorityCritical, Spec: specRef("docs/specs/a.md"), Hold: holdTrue, }) open := selSpec{id: 2, priority: PriorityHigh}.build() diff --git a/internal/domain/types_test.go b/internal/domain/types_test.go index 38d7b0d22..719b3449e 100644 --- a/internal/domain/types_test.go +++ b/internal/domain/types_test.go @@ -334,7 +334,7 @@ func TestLifecycleActionCarriesDeliverable(t *testing.T) { // TestLifecycleActionCarriesHold pins newChangeBuilder's copy of the hold: a // claim keeps the stored hold rather than dropping it. func TestLifecycleActionCarriesHold(t *testing.T) { - c := NewChange(ChangeSpec{ID: 1, Slug: "s", Status: StatusProposed, Type: "feat", Trivial: true, Hold: holdTrue}) + c := NewChange(ChangeSpec{ID: 1, Slug: "s", Status: StatusProposed, Type: "feat", Spec: specRef("docs/specs/a.md"), Hold: holdTrue}) res, fail := Claim(c, actNow) if fail != nil { t.Fatalf("Claim: %v", fail) From 80f965ef3c0be86ef025d9ffeea1c84239aaba00 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Mon, 19 Oct 2026 20:22:14 -0400 Subject: [PATCH 04/12] refactor(groom): retire the trivial outcome --- internal/app/change_groom.go | 62 ++++-------- internal/app/change_groom_test.go | 150 ++++++----------------------- internal/app/finding_codes.go | 4 +- internal/app/finding_codes_test.go | 7 +- internal/app/schema_vocab.go | 2 +- internal/app/schema_vocab_test.go | 2 +- internal/cli/change.go | 2 +- 7 files changed, 59 insertions(+), 170 deletions(-) diff --git a/internal/app/change_groom.go b/internal/app/change_groom.go index dc1654c5f..82a0ee82d 100644 --- a/internal/app/change_groom.go +++ b/internal/app/change_groom.go @@ -20,17 +20,17 @@ import ( ) // This file is the `change groom` planning operation: it grooms a proposed, -// needs-design change to build-ready by one of two authored outcomes — a full -// spec, or a trivial verdict — or, by the third outcome (revise), edits any -// proposed change in place without changing its groom state: a whole-body -// replace of its existing linked spec and/or owned proposal-section edits, -// never touching spec:, trivial:, or auto_groomable:. The abstain outcome +// needs-design change to build-ready by landing an authored spec (the spec +// outcome) or, by the revise outcome, edits any proposed change in place +// without changing its groom state: a whole-body replace of its existing +// linked spec and/or owned proposal-section edits, never touching spec: or +// auto_groomable:. The abstain outcome // records an autonomous groom's abstain on a needs-design change — // auto_groomable: false plus one dated // "## Auto-groom blocked" entry — under the same groom gate; the re-enable outcome // clears it — auto_groomable: true, the section removed — under that gate too, -// optionally with owned-section edits in the same commit. The spec, trivial, -// revise, and re-enable outcomes also set or lift a hold (hold:, plus the +// optionally with owned-section edits in the same commit. The spec, revise, +// and re-enable outcomes also set or lift a hold (hold:, plus the // optional "## Why on hold" reason section only the hold keys write), which // never changes the groom state; abstain refuses a hold. Every outcome // lands the change's source mutation and every affected v1-owned derived view (the change record's owned proposal sections, @@ -41,7 +41,7 @@ import ( // revision with an exact-blob entity expectation rather than an idempotency key // (a spec-body revise also checks the linked spec file's blob id in Plan), and // it never touches claim metadata. It decides no lifecycle policy beyond the -// groom gate the spec fixes here (proposed, needs-design, not yet trivial) and +// groom gate the spec fixes here (proposed, needs-design) and // the revise gate (any proposed change). // OperationChangeGroom is the operation key `change groom` records in its result @@ -54,21 +54,18 @@ type GroomOutcome string const ( // GroomSpec lands an authored design spec and links it from the change. GroomSpec GroomOutcome = "spec" - // GroomTrivial marks the change trivial with an authored rationale, writing - // no spec file. - GroomTrivial GroomOutcome = "trivial" // GroomRevise edits any proposed change without changing its groom state: // a whole-body replace of its existing linked spec, owned proposal-section // edits, a retitle, relationship-field updates, or a combination. It never - // writes spec:, trivial:, or auto_groomable:, so a change can never flip - // between needs-grooming, spec'd, and trivial through this outcome, and it + // writes spec: or auto_groomable:, so a change can never flip between + // needs-grooming and spec'd through this outcome, and it // never edits the ## Auto-groom blocked section (abstain and re-enable own it). // It may set or lift a hold: a hold excludes the change from autonomous // build selection only, so it is no part of the groom state. GroomRevise GroomOutcome = "revise" // GroomAbstain records an autonomous groom's abstain on a needs-grooming // change: it sets auto_groomable: false and appends one dated entry to the - // ## Auto-groom blocked section. It never writes spec: or trivial:, and it + // ## Auto-groom blocked section. It never writes spec:, and it // accepts no section, spec, relationship, or hold edits — an autonomous // caller cannot rewrite the proposal through it. GroomAbstain GroomOutcome = "abstain" @@ -149,13 +146,13 @@ type ChangeGroomRequest struct { BlockedNote string `json:"blocked_note,omitempty"` // Title, when non-empty, retitles the change (change 0461). The spec, - // trivial, revise, and re-enable outcomes accept it; abstain refuses it, since an + // revise, and re-enable outcomes accept it; abstain refuses it, since an // abstain cannot rewrite the proposal. Empty leaves the title unchanged. A // retitle renames nothing: the slug, record path, spec path, and branch stay put. Title string `json:"title,omitempty"` // Priority, when non-empty, re-prioritizes the change (change 0550). The - // spec, trivial, revise, and re-enable outcomes accept it; abstain refuses + // spec, revise, and re-enable outcomes accept it; abstain refuses // it, since an autonomous abstain cannot re-rank the proposal. Empty leaves // the priority unchanged. It draws on the same closed vocabulary as // change.create's priority. @@ -163,7 +160,7 @@ type ChangeGroomRequest struct { // Deliverable, Type, and BranchPrefix edit how the change ends and how its // next claim names its branch (change 0559). Like Title and Priority, the - // spec, trivial, revise, and re-enable outcomes accept each and abstain + // spec, revise, and re-enable outcomes accept each and abstain // refuses each. An empty Deliverable or Type leaves the field unchanged; // Deliverable draws on change.create's closed vocabulary and Type must be one // of the configured change_types. BranchPrefix is three-state: nil leaves it @@ -180,7 +177,7 @@ type ChangeGroomRequest struct { // false clears the key and removes any "## Why on hold" section. HoldReason // is accepted only with Hold true in the same request; it replaces that // section, and an omitted reason leaves an existing one alone. The spec, - // trivial, revise, and re-enable outcomes accept both; abstain refuses Hold. + // revise, and re-enable outcomes accept both; abstain refuses Hold. Hold *bool `json:"hold,omitempty"` HoldReason string `json:"hold_reason,omitempty"` @@ -229,7 +226,7 @@ func (r ChangeGroomResult) HumanText() string { if r.SpecPath != "" { return fmt.Sprintf("change %04d groomed (spec %s) — %s", r.ID, r.SpecPath, r.Revision) } - return fmt.Sprintf("change %04d groomed (trivial) — %s", r.ID, r.Revision) + return fmt.Sprintf("change %04d groomed — %s", r.ID, r.Revision) default: var b strings.Builder fmt.Fprintf(&b, "change groom: %s", r.Result) @@ -254,8 +251,8 @@ func newChangeGroomResult(result Result, r ChangeGroomResult) ChangeGroomResult // changeGroomReceipt is the canonical receipt persisted with a groom commit. // Field order is alphabetical so json.Marshal emits the canonical, sorted-key -// compact form the engine's receipt validator requires; SpecPath is omitted for -// the trivial outcome. +// compact form the engine's receipt validator requires; SpecPath is omitted when +// no spec file was written or replaced (abstain, re-enable, a sections-only revise). type changeGroomReceipt struct { ID int `json:"id"` Op string `json:"op"` @@ -405,10 +402,6 @@ func validateChangeGroomShape(req ChangeGroomRequest) []StatusFinding { } else if msg := specMarkdownShapeProblem(req.SpecMarkdown); msg != "" { addShape(FCInvalidSpecMarkdown, msg) } - case GroomTrivial: - if !hasAuthoredRationale(req.Sections) { - addShape(FCMissingRationale, "the trivial outcome requires a non-empty authored rationale among the section edits") - } case GroomRevise: if strings.TrimSpace(req.SpecMarkdown) != "" { if msg := specMarkdownShapeProblem(req.SpecMarkdown); msg != "" { @@ -478,7 +471,7 @@ func validateChangeGroomShape(req ChangeGroomRequest) []StatusFinding { } } default: - addShape(FCInvalidOutcome, fmt.Sprintf("outcome %q must be one of spec, trivial, revise, abstain, re-enable", req.Outcome)) + addShape(FCInvalidOutcome, fmt.Sprintf("outcome %q must be one of spec, revise, abstain, re-enable", req.Outcome)) } // A title retitles the change on every other outcome (change 0461); an empty @@ -608,17 +601,6 @@ func autoGroomBlockedMarkdown(oldBody string, present bool, date, note string) s return entry } -// hasAuthoredRationale reports whether the section edits carry at least one -// replace with a non-empty body — the trivial outcome's required rationale. -func hasAuthoredRationale(sections []SectionEditRequest) bool { - for _, s := range sections { - if s.Intent == string(render.SectionReplace) && strings.TrimSpace(s.Markdown) != "" { - return true - } - } - return false -} - // hasRelationshipEdit reports whether the request sets any relationship field: // an explicit list (even empty) for depends_on, related, discovered_from, or // adrs, or any stacked_on (0 clears it). Each one alone is an effective revise. @@ -722,7 +704,7 @@ func (o changeGroomOp) Plan(ctx context.Context, st transaction.AttemptState) (t } // Groom/revise gate. The groom gate admits only a proposed, needs-design // change. The revise gate admits any proposed change, needs-design or - // already groomed: revise never writes spec:, trivial:, or auto_groomable:, + // already groomed: revise never writes spec: or auto_groomable:, // so it cannot change a change's groom state, and a needs-design change // satisfies both gates. Neither gate inspects or sets claim metadata. if o.req.Outcome == GroomRevise { @@ -975,7 +957,7 @@ func (o changeGroomOp) Plan(ctx context.Context, st transaction.AttemptState) (t } if reviseSpec { // A revise that replaced the spec body names the existing linked path; a - // sections-only revise leaves it empty, like the trivial outcome. + // sections-only revise leaves it empty. receiptSpecPath = c.Spec().Value } receipt, err := json.Marshal(changeGroomReceipt{ @@ -1010,8 +992,6 @@ func (o changeGroomOp) fieldEdits(specPath string) []groomFieldEdit { switch o.req.Outcome { case GroomSpec: out = append(out, groomFieldEdit{"spec", document.String(specPath)}) - case GroomTrivial: - out = append(out, groomFieldEdit{"trivial", document.Bool(true)}) case GroomAbstain: out = append(out, groomFieldEdit{"auto_groomable", document.Bool(false)}) case GroomReEnable: diff --git a/internal/app/change_groom_test.go b/internal/app/change_groom_test.go index e2f70e4bf..701b39ea0 100644 --- a/internal/app/change_groom_test.go +++ b/internal/app/change_groom_test.go @@ -94,6 +94,7 @@ func TestChangeGroomRejectsBadShapeWithoutEngineCall(t *testing.T) { {"empty path", func(r *ChangeGroomRequest) { r.Path = "" }, "empty-path"}, {"empty revision", func(r *ChangeGroomRequest) { r.Revision = "" }, "empty-revision"}, {"unknown outcome", func(r *ChangeGroomRequest) { r.Outcome = "maybe" }, "invalid-outcome"}, + {"retired trivial outcome", func(r *ChangeGroomRequest) { r.Outcome = "trivial"; r.SpecMarkdown = "" }, "invalid-outcome"}, {"spec outcome empty markdown", func(r *ChangeGroomRequest) { r.SpecMarkdown = "" }, "empty-spec_markdown"}, {"spec outcome unparseable markdown", func(r *ChangeGroomRequest) { r.SpecMarkdown = "---\nid: 1\n" }, "invalid-spec_markdown"}, // The writer prepends the backlink block itself; an authored one would @@ -134,31 +135,6 @@ func TestChangeGroomRejectsBadShapeWithoutEngineCall(t *testing.T) { } } -func TestChangeGroomTrivialRequiresRationale(t *testing.T) { - req := ChangeGroomRequest{ - ChangeID: 2, - Path: groomPath(2, "add-a-widget"), - Revision: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", - Outcome: GroomTrivial, - // No section carrying an authored rationale. - } - engine := &recordingEngine{} - reader := &fakeChangeReader{pin: mainModePin([]string{"inline"})} - deps := PlanningDeps{Engine: engine, Reader: reader, Clock: testClock()} - - res := ChangeGroom(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 despite a missing trivial rationale") - } - if !hasFindingCode(res.Findings, "missing-rationale") { - t.Errorf("missing finding missing-rationale; got %v", res.Findings) - } -} - func TestChangeGroomRefusesGithubBoardSurface(t *testing.T) { engine := &recordingEngine{} reader := &fakeChangeReader{pin: mainModePin([]string{"inline", "github"})} @@ -274,35 +250,6 @@ func TestChangeGroomPlanSpecOutcomeFileSet(t *testing.T) { } } -func TestChangeGroomPlanTrivialOutcomeFileSet(t *testing.T) { - req := ChangeGroomRequest{ - ChangeID: 2, - Path: groomPath(2, "add-a-widget"), - Revision: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", - Outcome: GroomTrivial, - Sections: []SectionEditRequest{ - {Heading: "## Why", Intent: "replace", Markdown: "Too small to design.\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) - } - assertPlanPaths(t, plan, map[string]transaction.MutationKind{ - groomPath(2, "add-a-widget"): transaction.MutationReplace, - }) - rec := string(groomedRecordBytes(t, plan, groomPath(2, "add-a-widget"))) - if !strings.Contains(rec, "trivial: true") { - t.Errorf("trivial not set true:\n%s", rec) - } - if strings.Contains(rec, "spec: '") { - t.Errorf("trivial groom must not set a spec:\n%s", rec) - } -} - func TestChangeGroomPlanRefusesNonGroomable(t *testing.T) { cases := []struct { name string @@ -1362,11 +1309,39 @@ func TestChangeGroomRetiredRearmOutcomeRefused(t *testing.T) { } // The message echoes the offending value via %q ("rearm"), so assert on the // listed outcome set only: it must end with the live spelling. - if !strings.HasSuffix(msg, "must be one of spec, trivial, revise, abstain, re-enable") { + if !strings.HasSuffix(msg, "must be one of spec, revise, abstain, re-enable") { t.Errorf("invalid-outcome message %q must list exactly the live outcomes ending in re-enable", msg) } } +// TestChangeGroomRetiredTrivialOutcomeRefused pins the retirement of the +// trivial outcome: every build-ready change has a spec, so "trivial" is no +// longer an outcome and the refusal lists only the live set. +func TestChangeGroomRetiredTrivialOutcomeRefused(t *testing.T) { + req := ChangeGroomRequest{ + ChangeID: 2, + Path: groomPath(2, "add-a-widget"), + Revision: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + Outcome: GroomOutcome("trivial"), + Sections: []SectionEditRequest{ + {Heading: "## Why", Intent: "replace", Markdown: "Too small to design.\n"}, + }, + } + findings := validateChangeGroomShape(req) + var msg string + for _, f := range findings { + if f.Code == "invalid-outcome" { + msg = f.Message + } + } + if msg == "" { + t.Fatalf("outcome trivial: want invalid-outcome, got %v", findings) + } + if !strings.HasSuffix(msg, "must be one of spec, revise, abstain, re-enable") { + t.Errorf("invalid-outcome message %q must list exactly the live outcomes", msg) + } +} + func TestChangeGroomPlanReEnableClearsSectionSetsFlagAndBoard(t *testing.T) { files := map[string]string{ groomPath(2, "add-a-widget"): abstainedChange(2, "add-a-widget"), @@ -1540,21 +1515,6 @@ func titleOnlyReviseRequest(title string) ChangeGroomRequest { return r } -// titledTrivialRequest is a well-formed trivial groom of the groomable fixture -// at id 2 that also retitles it. -func titledTrivialRequest(title string) ChangeGroomRequest { - return ChangeGroomRequest{ - ChangeID: 2, - Path: groomPath(2, "add-a-widget"), - Revision: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", - Outcome: GroomTrivial, - Title: title, - Sections: []SectionEditRequest{ - {Heading: "## Why", Intent: "replace", Markdown: "Trivial: a rename only.\n"}, - }, - } -} - func TestChangeGroomTitleShapeValidation(t *testing.T) { withTitle := func(r ChangeGroomRequest, title string) ChangeGroomRequest { r.Title = title @@ -1566,7 +1526,6 @@ func TestChangeGroomTitleShapeValidation(t *testing.T) { code string // "" means the request must pass shape validation }{ {"spec accepts title", withTitle(validGroomSpecRequest(), "Renamed widget"), ""}, - {"trivial accepts title", titledTrivialRequest("Renamed widget"), ""}, {"re-enable accepts title", withTitle(reEnableRequest(), "Renamed widget"), ""}, {"revise accepts a title alone", titleOnlyReviseRequest("Renamed widget"), ""}, {"revise accepts title with sections", withTitle(validReviseRequest(), "Renamed widget"), ""}, @@ -1713,22 +1672,6 @@ func TestChangeGroomPlanTitleOnSpecOutcome(t *testing.T) { } } -func TestChangeGroomPlanTitleOnTrivialOutcome(t *testing.T) { - files := map[string]string{groomPath(2, "add-a-widget"): groomableChange(2, "add-a-widget")} - plan, opRes := groomPlanFor(t, files, baseGroomOp([]string{}, titledTrivialRequest("Renamed widget"))) - if opRes.Refused { - t.Fatalf("unexpected refusal: %v", opRes.Findings) - } - // No spec file is touched. - assertPlanPaths(t, plan, map[string]transaction.MutationKind{ - groomPath(2, "add-a-widget"): transaction.MutationReplace, - }) - rec := string(groomedRecordBytes(t, plan, groomPath(2, "add-a-widget"))) - if !strings.Contains(rec, "title: 'Renamed widget'") || !strings.Contains(rec, "trivial: true") { - t.Errorf("record not retitled/trivialled:\n%s", rec) - } -} - // TestChangeGroomPlanTitleWithSpecBodyRevise pins Review Focus 4: the // whole-body replace already renders the backlink from the groomed record, so // the spec path is declared exactly once, carrying both the new body and title. @@ -1913,7 +1856,6 @@ func TestChangeGroomPriorityShapeValidation(t *testing.T) { not string // a code that must NOT be emitted ("" = no check) }{ {"spec accepts priority", withPriority(validGroomSpecRequest(), "high"), "", ""}, - {"trivial accepts priority", withPriority(titledTrivialRequest("Renamed widget"), "low"), "", ""}, {"re-enable accepts priority", withPriority(reEnableRequest(), "critical"), "", ""}, {"revise accepts a priority alone", priorityOnlyReviseRequest("high"), "", ""}, {"revise accepts priority with sections", withPriority(validReviseRequest(), "medium"), "", ""}, @@ -2033,21 +1975,15 @@ func assertPriorityLanded(t *testing.T, plan transaction.MutationPlan, want stri } // TestChangeGroomPlanPriorityLandsOnEveryAcceptingOutcome pins spec test 1: -// spec, trivial, revise, and re-enable each write the new priority to the +// spec, revise, and re-enable each write the new priority to the // record and the board row in the same plan. func TestChangeGroomPlanPriorityLandsOnEveryAcceptingOutcome(t *testing.T) { - trivial := ChangeGroomRequest{ - ChangeID: 2, Path: groomPath(2, "add-a-widget"), - Revision: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", Outcome: GroomTrivial, - Sections: []SectionEditRequest{{Heading: "## Why", Intent: "replace", Markdown: "Too small to design.\n"}}, - } cases := []struct { name string rec string req ChangeGroomRequest }{ {"spec", groomableChange(2, "add-a-widget"), validGroomSpecRequest()}, - {"trivial", groomableChange(2, "add-a-widget"), trivial}, {"revise", groomableChange(2, "add-a-widget"), priorityOnlyReviseRequest("")}, {"re-enable", abstainedChange(2, "add-a-widget"), reEnableRequest()}, } @@ -2228,18 +2164,12 @@ func resultsArtifactChange(id int, slug string) string { } func TestChangeGroomEditsDeliverableTypeAndPrefixOnEveryAcceptingOutcome(t *testing.T) { - trivial := ChangeGroomRequest{ - ChangeID: 2, Path: groomPath(2, "add-a-widget"), - Revision: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", Outcome: GroomTrivial, - Sections: []SectionEditRequest{{Heading: "## Why", Intent: "replace", Markdown: "Too small to design.\n"}}, - } cases := []struct { name string rec string req ChangeGroomRequest }{ {"spec", groomableChange(2, "add-a-widget"), validGroomSpecRequest()}, - {"trivial", groomableChange(2, "add-a-widget"), trivial}, {"revise", groomableChange(2, "add-a-widget"), fieldOnlyReviseRequest(func(*ChangeGroomRequest) {})}, {"re-enable", abstainedChange(2, "add-a-widget"), reEnableRequest()}, } @@ -2804,14 +2734,8 @@ func TestChangeGroomEachRelationshipFieldAloneIsAValidRevise(t *testing.T) { func TestChangeGroomStackedOnShape(t *testing.T) { const wantMsg = "stacked_on must be a positive change id, or 0 to clear" - trivial := ChangeGroomRequest{ - ChangeID: 2, Path: groomPath(2, "add-a-widget"), - Revision: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", Outcome: GroomTrivial, - Sections: []SectionEditRequest{{Heading: "## Why", Intent: "replace", Markdown: "Too small to design.\n"}}, - } negatives := map[string]ChangeGroomRequest{ "spec": validGroomSpecRequest(), - "trivial": trivial, "revise": fieldOnlyReviseRequest(func(*ChangeGroomRequest) {}), "re-enable": reEnableRequest(), } @@ -2999,18 +2923,12 @@ func holdPlanRecord(t *testing.T, rec string, req ChangeGroomRequest) string { } func TestChangeGroomSetsHoldOnEveryAcceptingOutcome(t *testing.T) { - trivial := ChangeGroomRequest{ - ChangeID: 2, Path: groomPath(2, "add-a-widget"), - Revision: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", Outcome: GroomTrivial, - Sections: []SectionEditRequest{{Heading: "## Why", Intent: "replace", Markdown: "Too small to design.\n"}}, - } cases := []struct { name string rec string req ChangeGroomRequest }{ {"spec", groomableChange(2, "add-a-widget"), validGroomSpecRequest()}, - {"trivial", groomableChange(2, "add-a-widget"), trivial}, {"revise", groomableChange(2, "add-a-widget"), fieldOnlyReviseRequest(func(*ChangeGroomRequest) {})}, {"re-enable", abstainedChange(2, "add-a-widget"), reEnableRequest()}, } @@ -3119,11 +3037,6 @@ func TestChangeGroomHoldAloneIsAValidRevise(t *testing.T) { } func TestChangeGroomHoldRefusals(t *testing.T) { - trivial := ChangeGroomRequest{ - ChangeID: 2, Path: groomPath(2, "add-a-widget"), - Revision: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", Outcome: GroomTrivial, - Sections: []SectionEditRequest{{Heading: "## Why", Intent: "replace", Markdown: "Too small to design.\n"}}, - } revise := fieldOnlyReviseRequest(func(r *ChangeGroomRequest) { r.Priority = "high" }) withHold := func(base ChangeGroomRequest, hold *bool, reason string) ChangeGroomRequest { base.Hold, base.HoldReason = hold, reason @@ -3149,7 +3062,6 @@ func TestChangeGroomHoldRefusals(t *testing.T) { {"reason carrying a heading", withHold(revise, boolPtr(true), "text\n## Heading\n"), FCInvalidHoldReason}, {"reason leaving a fence open", withHold(revise, boolPtr(true), "text\n```\ncode\n"), FCInvalidHoldReason}, {"section edit on spec", withSection(validGroomSpecRequest()), FCInvalidSectionHeading}, - {"section edit on trivial", withSection(trivial), FCInvalidSectionHeading}, {"section edit on revise", withSection(revise), FCInvalidSectionHeading}, {"section edit on revise with a hold", withSection(withHold(revise, boolPtr(true), "")), FCInvalidSectionHeading}, {"section edit on re-enable", withSection(reEnableRequest()), FCInvalidSectionHeading}, diff --git a/internal/app/finding_codes.go b/internal/app/finding_codes.go index 9bc38db6e..22387962a 100644 --- a/internal/app/finding_codes.go +++ b/internal/app/finding_codes.go @@ -158,7 +158,6 @@ const ( FCInvalidSpecMarkdown FindingCode = "invalid-spec_markdown" FCEmptySpecRevision FindingCode = "empty-spec_revision" FCInvalidSpecRevision FindingCode = "invalid-spec_revision" - FCMissingRationale FindingCode = "missing-rationale" FCEmptyRevise FindingCode = "empty-revise" FCEmptyBlockedNote FindingCode = "empty-blocked_note" FCInvalidBlockedNote FindingCode = "invalid-blocked_note" @@ -220,7 +219,7 @@ const ( // through their addShape/adrFinding/learningFinding closures are now registered // FindingCode constants (change 0399, review): invalid-request_id, // invalid-stacked_on, invalid-{target-id,topics,change-id,outcome,pr_number, -// attempt,spec_markdown,spec_revision,spec-section-heading}, missing-rationale, and the +// attempt,spec_markdown,spec_revision,spec-section-heading}, and the // enumerated empty- expansions (empty-{title,why,what_changes, // out_of_scope,context,decision,consequences,alternatives,change-path, // change-revision,target-path,target-revision,hook,apply,war_story,spec_markdown, @@ -347,7 +346,6 @@ var AllFindingCodes = []FindingCode{ FCMetadataWorktreeDirty, FCMigrationIncomplete, FindingCode("missing-claim-stamp"), - FCMissingRationale, FCNotDeferrable, FCNotFound, FindingCode(ReasonImplementedNotPRDeliverable), diff --git a/internal/app/finding_codes_test.go b/internal/app/finding_codes_test.go index 8f2f99d68..4d1a942e6 100644 --- a/internal/app/finding_codes_test.go +++ b/internal/app/finding_codes_test.go @@ -230,13 +230,12 @@ func TestShapeValidatorCodesAreRegistered(t *testing.T) { emitted = append(emitted, validateADRReplaceShape(ADRReplaceRequest{Target: ADRTarget{ID: 0}, Successor: adrContent})...) emitted = append(emitted, validateLearningRecordShape(LearningRecordRequest{Topics: []string{""}})...) emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomSpec})...) - emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomTrivial})...) emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomRevise})...) emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomRevise, SpecMarkdown: "# x\n"})...) - emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomTrivial, SpecRevision: "a"})...) + emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomSpec, SpecRevision: "a"})...) emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomOutcome("bogus")})...) emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomAbstain, Sections: []SectionEditRequest{{Heading: "## Why", Intent: "remove"}}})...) - emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomTrivial, BlockedNote: "x"})...) + emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomSpec, BlockedNote: "x"})...) emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomAbstain, Title: "x"})...) emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomRevise, Title: "a\nb"})...) emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomAbstain, Priority: "high"})...) @@ -269,7 +268,7 @@ func TestShapeValidatorCodesAreRegistered(t *testing.T) { FCInvalidChangeDotID, FCEmptyChangePath, FCEmptyChangeRevision, FCInvalidTargetID, FCEmptyTargetPath, FCEmptyTargetRevision, FCEmptyHook, FCEmptyApply, FCEmptyWarStory, FCInvalidTopics, - FCEmptySpecMarkdown, FCEmptySpecRevision, FCInvalidSpecRevision, FCMissingRationale, FCInvalidOutcome, + FCEmptySpecMarkdown, FCEmptySpecRevision, FCInvalidSpecRevision, FCInvalidOutcome, FCInvalidSpecSectionHeading, FCEmptyReconcileLogEntry, FCEmptyBlockedNote, FCInvalidBlockedNote, FCInvalidSections, FCInvalidPRNumber, FCInvalidAttempt, FCEmptyHead, FCInvalidPriority, FCUnknownPriority, diff --git a/internal/app/schema_vocab.go b/internal/app/schema_vocab.go index c67234291..f8968dd29 100644 --- a/internal/app/schema_vocab.go +++ b/internal/app/schema_vocab.go @@ -71,7 +71,7 @@ func SchemaVocabularies(effects []string) map[string]Vocabulary { v["section_intents"] = Vocabulary{Members: members(len(render.AllSectionIntents), func(i int) string { return string(render.AllSectionIntents[i]) })} - v["groom_outcomes"] = Vocabulary{Members: []string{string(GroomSpec), string(GroomTrivial), string(GroomRevise), string(GroomAbstain), string(GroomReEnable)}} + v["groom_outcomes"] = Vocabulary{Members: []string{string(GroomSpec), string(GroomRevise), string(GroomAbstain), string(GroomReEnable)}} v["change_types"] = Vocabulary{Pattern: changeTypePattern} v["effects"] = Vocabulary{Members: effects} diff --git a/internal/app/schema_vocab_test.go b/internal/app/schema_vocab_test.go index e532eb6f8..6eff3db4b 100644 --- a/internal/app/schema_vocab_test.go +++ b/internal/app/schema_vocab_test.go @@ -45,7 +45,7 @@ func TestSchemaVocabulariesCore(t *testing.T) { assertVocabMembers(t, v, "priorities", []string{"critical", "high", "medium", "low"}) assertVocabMembers(t, v, "section_intents", []string{"preserve", "replace", "remove"}) - assertVocabMembers(t, v, "groom_outcomes", []string{"spec", "trivial", "revise", "abstain", "re-enable"}) + assertVocabMembers(t, v, "groom_outcomes", []string{"spec", "revise", "abstain", "re-enable"}) assertVocabMembers(t, v, "statuses", []string{ "proposed", "in-progress", "blocked", "deferred", "implemented", "stacked-merged", "done", "killed", diff --git a/internal/cli/change.go b/internal/cli/change.go index 6e14e0ca5..cf942a729 100644 --- a/internal/cli/change.go +++ b/internal/cli/change.go @@ -55,7 +55,7 @@ func newChangeCommand(setResult func(app.OperationResult)) *cobra.Command { }, EffectMetadataWrite) groom := changeSubcommand("change", "groom", - "Groom a proposed change to build-ready (spec or trivial), record or clear an auto-groom abstain (abstain, re-enable), or revise any proposed change without changing its groom state, from a JSON request", + "Groom a proposed change to build-ready with a spec, record or clear an auto-groom abstain (abstain, re-enable), or revise any proposed change without changing its groom state, from a JSON request", func(c *cobra.Command, deps app.PlanningDeps, repoDir string, req app.ChangeGroomRequest) { setResult(app.ChangeGroom(c.Context(), deps, repoDir, req)) }, EffectMetadataWrite) From 38abb9888f257bfd2d5ebef58d4a326344d47ce7 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Mon, 19 Oct 2026 20:23:00 -0400 Subject: [PATCH 05/12] refactor(record): new change records carry no trivial line --- internal/render/record.go | 1 - internal/render/record_test.go | 26 +++++++++++++++++++ .../render/testdata/records/change.golden.md | 1 - 3 files changed, 26 insertions(+), 2 deletions(-) diff --git a/internal/render/record.go b/internal/render/record.go index 6f374f6b2..c7b2399ce 100644 --- a/internal/render/record.go +++ b/internal/render/record.go @@ -66,7 +66,6 @@ func ChangeRecord(r NewChangeRecord) ([]byte, error) { {Name: "spec", Value: document.Null()}, {Name: "plan", Value: document.Null()}, {Name: "results", Value: document.Null()}, - {Name: "trivial", Value: document.Bool(false)}, {Name: "auto_groomable", Value: optionalBoolValue(r.AutoGroomable)}, {Name: "hold", Value: holdValue(r.Hold)}, {Name: "branch_prefix", Value: optionalStringValue(r.BranchPrefix)}, diff --git a/internal/render/record_test.go b/internal/render/record_test.go index 9a3d59442..409ec2a54 100644 --- a/internal/render/record_test.go +++ b/internal/render/record_test.go @@ -63,6 +63,32 @@ func TestChangeRecordMatchesGolden(t *testing.T) { } } +// TestChangeRecordHasNoTrivialKey proves a new change record writes no +// trivial: frontmatter line. +func TestChangeRecordHasNoTrivialKey(t *testing.T) { + got, err := render.ChangeRecord(render.NewChangeRecord{ + ID: 312, Slug: "add-planning-mutations", Title: "Add planning mutations: board and ADRs", + Type: "feat", Priority: "medium", Created: goldenDate, + Why: "w", WhatChanges: "wc", OutOfScope: "oos", + }) + if err != nil { + t.Fatalf("ChangeRecord: %v", err) + } + lines := strings.Split(string(got), "\n") + if len(lines) == 0 || lines[0] != "---" { + t.Fatalf("record does not open with frontmatter:\n%s", got) + } + for _, line := range lines[1:] { + if line == "---" { + return + } + if strings.HasPrefix(line, "trivial:") { + t.Fatalf("new change record carries %q", line) + } + } + t.Fatalf("frontmatter never closed:\n%s", got) +} + // TestLearningRecordMatchesGolden pins the canonical learning shape. func TestLearningRecordMatchesGolden(t *testing.T) { got, err := render.LearningRecord(render.NewLearningRecord{ diff --git a/internal/render/testdata/records/change.golden.md b/internal/render/testdata/records/change.golden.md index 53cf6b5f7..1967c10f9 100644 --- a/internal/render/testdata/records/change.golden.md +++ b/internal/render/testdata/records/change.golden.md @@ -16,7 +16,6 @@ adrs: [] spec: plan: results: -trivial: false auto_groomable: hold: branch_prefix: From 51f5bdb91169d1c6e624ee9206e20b3b17b9fdaf Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Mon, 19 Oct 2026 20:31:06 -0400 Subject: [PATCH 06/12] refactor(domain): build-ready requires a spec; trivial is inert data --- internal/app/change_claim_test.go | 22 ++++ internal/app/change_groom.go | 15 +-- internal/app/change_groom_test.go | 116 +++++++++++-------- internal/app/change_implemented.go | 10 +- internal/app/change_integration_test.go | 2 +- internal/app/implementation_context.go | 2 +- internal/app/implementation_context_test.go | 2 +- internal/app/open.go | 9 +- internal/app/open_test.go | 4 +- internal/app/status_test.go | 34 ++++++ internal/app/workflow_integration_test.go | 15 ++- internal/app/workspace_spec.go | 4 +- internal/domain/actions.go | 1 - internal/domain/entities.go | 4 - internal/domain/entities_test.go | 4 - internal/domain/readiness.go | 13 +-- internal/domain/readiness_test.go | 23 +--- internal/render/board.go | 45 +++---- internal/render/board_test.go | 78 +++---------- internal/render/testdata/board/PROVENANCE.md | 8 +- internal/repository/decode.go | 2 - internal/repository/decode_test.go | 37 ++++-- 22 files changed, 216 insertions(+), 234 deletions(-) diff --git a/internal/app/change_claim_test.go b/internal/app/change_claim_test.go index 5c6363e54..883bed896 100644 --- a/internal/app/change_claim_test.go +++ b/internal/app/change_claim_test.go @@ -523,6 +523,28 @@ func assertUnrelatedShapeIntact(t *testing.T, repo *gitRepo, branch string, shap t.Errorf("%s: status no longer reports a finding on the unrelated records; findings %+v", shape.name, st.Findings) } +// TestChangeClaimRefusesLegacyTrivialRecord: a legacy record carrying +// trivial: true and no spec is a stub, not build-ready, so a claim refuses it +// as needs-grooming and writes nothing. +func TestChangeClaimRefusesLegacyTrivialRecord(t *testing.T) { + recPath := groomPath(3, "widget") + src := strings.Replace(lifecycleChange(3, "widget", "proposed"), "\ntrivial: false\n", "\ntrivial: true\n", 1) + if !strings.Contains(src, "\ntrivial: true\n") || !strings.Contains(src, "\nspec:\n") { + t.Fatalf("fixture is not a spec-less legacy trivial record:\n%s", src) + } + plan, opRes := claimPlanFor(t, map[string]string{recPath: src}, baseClaimOp([]string{"inline"}, 3, domain.NewBranchFacts(nil))) + if !opRes.Refused || len(plan.Files) != 0 { + t.Fatalf("claim of a legacy trivial record not refused: refused=%v files=%d", opRes.Refused, len(plan.Files)) + } + found := false + for _, f := range opRes.Findings { + found = found || f.Code == "not-ready-needs-grooming" + } + if !found { + t.Errorf("missing not-ready-needs-grooming; got %v", opRes.Findings) + } +} + // TestChangeClaimAcceptsHeldChangeAndKeepsField: a hold never refuses a claim, // and the claimed record keeps the hold for the human to lift. func TestChangeClaimAcceptsHeldChangeAndKeepsField(t *testing.T) { diff --git a/internal/app/change_groom.go b/internal/app/change_groom.go index 82a0ee82d..733fe7705 100644 --- a/internal/app/change_groom.go +++ b/internal/app/change_groom.go @@ -703,19 +703,20 @@ func (o changeGroomOp) Plan(ctx context.Context, st transaction.AttemptState) (t return refuseGroom("not-found", fmt.Sprintf("change %04d is not present in the current corpus", o.req.ChangeID)) } // Groom/revise gate. The groom gate admits only a proposed, needs-design - // change. The revise gate admits any proposed change, needs-design or - // already groomed: revise never writes spec: or auto_groomable:, - // so it cannot change a change's groom state, and a needs-design change - // satisfies both gates. Neither gate inspects or sets claim metadata. + // change (one with no spec). The revise gate admits any proposed change, + // needs-design or already groomed: revise never writes spec: or + // auto_groomable:, so it cannot change a change's groom state, and a + // needs-design change satisfies both gates. Neither gate inspects or sets + // claim metadata. if o.req.Outcome == GroomRevise { if c.Status() != domain.StatusProposed { return refuseGroom("not-revisable", fmt.Sprintf("change %04d is not a proposed change (status %q)", o.req.ChangeID, c.Status())) } - } else if c.Status() != domain.StatusProposed || c.Spec().Value != "" || c.Trivial() { + } else if c.Status() != domain.StatusProposed || c.Spec().Value != "" { return refuseGroom("not-groomable", - fmt.Sprintf("change %04d is not a proposed, needs-design change (status %q, spec %q, trivial %v)", - o.req.ChangeID, c.Status(), c.Spec().Value, c.Trivial())) + fmt.Sprintf("change %04d is not a proposed, needs-design change (status %q, spec %q)", + o.req.ChangeID, c.Status(), c.Spec().Value)) } // Retitle gate (change 0461). A proposed change carrying branch:, plan:, or diff --git a/internal/app/change_groom_test.go b/internal/app/change_groom_test.go index 701b39ea0..91e15d2a3 100644 --- a/internal/app/change_groom_test.go +++ b/internal/app/change_groom_test.go @@ -11,7 +11,7 @@ import ( ) // groomableChange renders a canonical proposed change record eligible for -// grooming: proposed status, empty spec, trivial false, every relationship +// grooming: proposed status, empty spec, an inert legacy trivial: false line, every relationship // field present and empty, the empty docket:artifacts block, and the four // authored proposal sections (including ## Open questions, so its removal is // observable). @@ -256,7 +256,6 @@ func TestChangeGroomPlanRefusesNonGroomable(t *testing.T) { mutate func(string) string }{ {"already has spec", func(s string) string { return strings.Replace(s, "spec:\n", "spec: 'docs/x.md'\n", 1) }}, - {"already trivial", func(s string) string { return strings.Replace(s, "trivial: false", "trivial: true", 1) }}, {"not proposed", func(s string) string { return strings.Replace(s, "status: proposed\n", "status: blocked\nblocked_by: 'waiting on infra'\n", 1) }}, @@ -356,8 +355,9 @@ func revisableChange(id int, slug, specPath string) string { return strings.Replace(groomableChange(id, slug), "spec:\n", "spec: '"+specPath+"'\n", 1) } -// trivialChange renders a proposed change already groomed by trivial verdict. -func trivialChange(id int, slug string) string { +// legacyTrivialChange renders a record carrying a legacy trivial: true line and +// no spec — a stub. +func legacyTrivialChange(id int, slug string) string { return strings.Replace(groomableChange(id, slug), "trivial: false", "trivial: true", 1) } @@ -628,8 +628,8 @@ func TestChangeGroomPlanReviseSectionsOnly(t *testing.T) { if !strings.Contains(rec, "spec: '"+reviseSpecPath+"'") { t.Errorf("spec field changed under revise:\n%s", rec) } - if !strings.Contains(rec, "trivial: false") { - t.Errorf("trivial field changed under revise:\n%s", rec) + if !strings.Contains(rec, "\ntrivial: false\n") { + t.Errorf("inert legacy trivial: false line not left byte-identical under revise:\n%s", rec) } // A sections-only revise replaced no spec body, so its receipt names none. assertGroomReceiptSpecPath(t, plan, "") @@ -676,8 +676,11 @@ func TestChangeGroomPlanReviseSpecBodyOnly(t *testing.T) { if !strings.Contains(rec, "updated: '2026-08-16'") { t.Errorf("updated not stamped:\n%s", rec) } - if !strings.Contains(rec, "spec: '"+reviseSpecPath+"'") || !strings.Contains(rec, "trivial: false") { - t.Errorf("groomed-outcome fields changed under a spec-only revise:\n%s", rec) + if !strings.Contains(rec, "spec: '"+reviseSpecPath+"'") { + t.Errorf("spec field changed under a spec-only revise:\n%s", rec) + } + if !strings.Contains(rec, "\ntrivial: false\n") { + t.Errorf("inert legacy trivial: false line not left byte-identical under a spec-only revise:\n%s", rec) } // The receipt names the existing linked spec path the revise replaced. assertGroomReceiptSpecPath(t, plan, reviseSpecPath) @@ -695,28 +698,55 @@ func TestChangeGroomPlanReviseBoth(t *testing.T) { }) } -func TestChangeGroomPlanReviseTrivialRationale(t *testing.T) { - // Spec item 4: sections-only revise of a trivial-verdicted change. - files := map[string]string{ - groomPath(2, "add-a-widget"): trivialChange(2, "add-a-widget"), - } - req := validReviseRequest() - // A trivial change links no spec, so there is no spec file to pin. - req.SpecMarkdown, req.SpecRevision = "", "" - plan, opRes := groomPlanFor(t, files, baseGroomOp([]string{}, req)) - if opRes.Refused { - t.Fatalf("unexpected refusal: %v", opRes.Findings) +// TestChangeGroomPlanLegacyTrivialRecordGroomsAsStub pins that a legacy +// record carrying trivial: true and no spec is an ordinary stub: (a) the spec +// outcome grooms it, and (b) a sections-only revise edits it, and both leave the +// legacy trivial: true line byte-identical (it is inert data no writer touches). +func TestChangeGroomPlanLegacyTrivialRecordGroomsAsStub(t *testing.T) { + const legacyLine = "\ntrivial: true\n" + assertLegacyLine := func(t *testing.T, rec string) { + t.Helper() + if n := strings.Count(rec, legacyLine); n != 1 || strings.Contains(rec, "trivial: false") { + t.Errorf("legacy trivial: true line not byte-identical (count %d):\n%s", n, rec) + } } - assertPlanPaths(t, plan, map[string]transaction.MutationKind{ - groomPath(2, "add-a-widget"): transaction.MutationReplace, + + t.Run("spec outcome", func(t *testing.T) { + files := map[string]string{groomPath(2, "add-a-widget"): legacyTrivialChange(2, "add-a-widget")} + plan, opRes := groomPlanFor(t, files, baseGroomOp([]string{}, validGroomSpecRequest())) + if opRes.Refused { + t.Fatalf("spec outcome refused a legacy trivial record: %v", opRes.Findings) + } + specPath := "docs/superpowers/specs/2026-08-16-add-a-widget-design.md" + assertPlanPaths(t, plan, map[string]transaction.MutationKind{ + groomPath(2, "add-a-widget"): transaction.MutationReplace, + specPath: transaction.MutationCreate, + }) + rec := string(groomedRecordBytes(t, plan, groomPath(2, "add-a-widget"))) + if !strings.Contains(rec, "\nspec: '"+specPath+"'\n") { + t.Errorf("spec: not written:\n%s", rec) + } + assertLegacyLine(t, rec) + }) + + t.Run("sections-only revise", func(t *testing.T) { + files := map[string]string{groomPath(2, "add-a-widget"): legacyTrivialChange(2, "add-a-widget")} + plan, opRes := groomPlanFor(t, files, baseGroomOp([]string{}, stubSectionReviseRequest())) + if opRes.Refused { + t.Fatalf("sections-only revise refused a legacy trivial record: %v", opRes.Findings) + } + assertPlanPaths(t, plan, map[string]transaction.MutationKind{ + groomPath(2, "add-a-widget"): transaction.MutationReplace, + }) + rec := string(groomedRecordBytes(t, plan, groomPath(2, "add-a-widget"))) + if !strings.Contains(rec, "Sharpened why.") { + t.Errorf("## Why section not replaced:\n%s", rec) + } + if !strings.Contains(rec, "\nspec:\n") { + t.Errorf("revise of a legacy trivial record wrote a spec link:\n%s", rec) + } + assertLegacyLine(t, rec) }) - rec := string(groomedRecordBytes(t, plan, groomPath(2, "add-a-widget"))) - if !strings.Contains(rec, "trivial: true") { - t.Errorf("trivial verdict lost under revise:\n%s", rec) - } - if strings.Contains(rec, "spec: '") { - t.Errorf("revise of a trivial change wrote a spec link:\n%s", rec) - } } func TestChangeGroomPlanReviseRefusals(t *testing.T) { @@ -726,9 +756,9 @@ func TestChangeGroomPlanReviseRefusals(t *testing.T) { mut func(*ChangeGroomRequest) code string }{ - // Spec item 5: spec_markdown against a trivial-only (no-spec) change. + // Spec item 5: spec_markdown against a legacy trivial (no-spec) record. {"spec-not-linked", map[string]string{ - groomPath(2, "add-a-widget"): trivialChange(2, "add-a-widget"), + groomPath(2, "add-a-widget"): legacyTrivialChange(2, "add-a-widget"), }, func(r *ChangeGroomRequest) {}, "spec-not-linked"}, // A needs-grooming stub is revisable, but it links no spec, so a // spec-body revise of it refuses before any mutation is assembled. @@ -802,7 +832,7 @@ func stubSectionReviseRequest() ChangeGroomRequest { // TestChangeGroomPlanReviseNeedsGroomingStub pins that revise edits a // needs-grooming stub's owned sections and leaves its groom state alone: no -// spec: written, trivial: still false, auto_groomable: untouched, a fresh +// spec: written, the inert trivial: false line untouched, auto_groomable: untouched, a fresh // updated:, the artifacts block intact, and the board row still needs-grooming. func TestChangeGroomPlanReviseNeedsGroomingStub(t *testing.T) { files := map[string]string{ @@ -824,8 +854,8 @@ func TestChangeGroomPlanReviseNeedsGroomingStub(t *testing.T) { if strings.Contains(rec, "spec: '") { t.Errorf("revise of a stub wrote a spec link:\n%s", rec) } - if !strings.Contains(rec, "trivial: false") || strings.Contains(rec, "trivial: true") { - t.Errorf("revise of a stub changed trivial:\n%s", rec) + if !strings.Contains(rec, "\ntrivial: false\n") || strings.Contains(rec, "trivial: true") { + t.Errorf("revise of a stub did not leave the inert trivial: false line byte-identical:\n%s", rec) } if !strings.Contains(rec, "auto_groomable: false") || strings.Contains(rec, "auto_groomable: true") { t.Errorf("revise of a stub changed auto_groomable:\n%s", rec) @@ -931,7 +961,7 @@ func TestChangeGroomPlanReviseAbstainedStubKeepsMarker(t *testing.T) { } // TestChangeGroomPlanReviseSpecNotLinkedMessage pins the reworded refusal: it -// covers both a trivial change and a needs-grooming stub, so it names neither. +// covers any change that links no spec, so it names no groom state. func TestChangeGroomPlanReviseSpecNotLinkedMessage(t *testing.T) { files := map[string]string{groomPath(2, "add-a-widget"): groomableChange(2, "add-a-widget")} plan, opRes := groomPlanFor(t, files, baseGroomOp([]string{}, validReviseRequest())) @@ -1169,7 +1199,8 @@ func TestChangeGroomPlanAbstainSetsFlagSectionAndBoard(t *testing.T) { "updated: '2026-08-16'", "## Auto-groom blocked\n\nRecorded 2026-08-16 (UTC).\n\nThe storage decision needs a human.", "### What to supply", - "\nspec:\n", "trivial: false", // groom scalars untouched + "\nspec:\n", // groom state untouched + "\ntrivial: false\n", // inert legacy line byte-identical "Original why.", "An open question.", // proposal untouched } { if !strings.Contains(rec, want) { @@ -1214,7 +1245,6 @@ func TestChangeGroomPlanAbstainRefusesNonGroomable(t *testing.T) { rec string }{ {"spec'd", revisableChange(2, "add-a-widget", reviseSpecPath)}, - {"trivial", trivialChange(2, "add-a-widget")}, {"not proposed", strings.Replace(groomableChange(2, "add-a-widget"), "status: proposed\n", "status: blocked\nblocked_by: 'waiting on infra'\n", 1)}, } for _, c := range cases { @@ -1413,7 +1443,6 @@ func TestChangeGroomPlanReEnableRefusals(t *testing.T) { code string }{ {"nothing to re-enable", map[string]string{groomPath(2, "add-a-widget"): armed}, "nothing-to-re-enable"}, - {"trivial", map[string]string{groomPath(2, "add-a-widget"): trivialChange(2, "add-a-widget")}, "not-groomable"}, {"spec'd", reviseFixtureFiles(), "not-groomable"}, } for _, c := range cases { @@ -1697,19 +1726,6 @@ func TestChangeGroomPlanTitleWithSpecBodyRevise(t *testing.T) { } } -// TestChangeGroomPlanTitleOnlyReviseOfTrivialChange pins Review Focus 5: a -// trivial-verdicted change links no spec, so a retitle writes only the record. -func TestChangeGroomPlanTitleOnlyReviseOfTrivialChange(t *testing.T) { - files := map[string]string{groomPath(2, "add-a-widget"): trivialChange(2, "add-a-widget")} - plan, opRes := groomPlanFor(t, files, baseGroomOp([]string{}, titleOnlyReviseRequest("Renamed widget"))) - if opRes.Refused { - t.Fatalf("unexpected refusal: %v", opRes.Findings) - } - assertPlanPaths(t, plan, map[string]transaction.MutationKind{ - groomPath(2, "add-a-widget"): transaction.MutationReplace, - }) -} - // revivedReviseFiles is the revise fixture for a proposed change that still // carries feature-branch artifacts (a hand-edited or legacy record): it is an // already-groomed proposed change with branch: and plan: set, whose diff --git a/internal/app/change_implemented.go b/internal/app/change_implemented.go index d1ba177c7..2601702ca 100644 --- a/internal/app/change_implemented.go +++ b/internal/app/change_implemented.go @@ -40,8 +40,8 @@ import ( // (4) exactly one open PR for the feature branch targets the resolved // effective-base branch, names that head, and matches the supplied PR number // (parsePRRef reads the --pr assertion as either the full URL or shorthand); -// (5) a results artifact is attached (required since change 0410, trivial -// changes included) and resolves to a file on the metadata branch that +// (5) a results artifact is attached (required since change 0410, for every +// implemented change) and resolves to a file on the metadata branch that // carries this change's backlink and satisfies the final results content // contract. // @@ -114,8 +114,8 @@ const ( // this change (condition 5); invalid-state. ReasonImplementedResultsIdentity = "results-identity-broken" // ReasonImplementedResultsMissing: the change carries no attached results path; - // a results artifact is REQUIRED at the implemented boundary — trivial changes - // included (change 0410, condition 5); maps to invalid-state. + // a results artifact is REQUIRED at the implemented boundary for every + // implemented change (change 0410, condition 5); maps to invalid-state. ReasonImplementedResultsMissing = "results-missing" // ReasonImplementedResultsInvalid: the attached results artifact fails the FINAL // results content contract on the metadata branch (change 0410, condition 5); @@ -312,7 +312,7 @@ func ChangeMarkImplemented(ctx context.Context, deps PlanningDeps, wdeps Workspa } // (Condition 5) a results artifact is REQUIRED at the implemented boundary - // (change 0410) — for trivial changes too. The attached path must resolve to a + // (change 0410) — for every implemented change. The attached path must resolve to a // file on the pinned metadata tip, carry THIS change's backlink, and satisfy // the FINAL results content contract. The feature head is never consulted. resultsPath := strings.TrimSpace(c.Results().Value) diff --git a/internal/app/change_integration_test.go b/internal/app/change_integration_test.go index 9a8595ea7..1317974c0 100644 --- a/internal/app/change_integration_test.go +++ b/internal/app/change_integration_test.go @@ -468,7 +468,7 @@ func TestIntegrationChangeAuthoringClaimRefusals(t *testing.T) { }, { name: "not build-ready", - files: map[string]string{recPath: lifecycleChange(3, "widget", "proposed")}, // trivial:false, no spec + files: map[string]string{recPath: lifecycleChange(3, "widget", "proposed")}, // no spec reason: "not-ready-" + string(domain.ReadyNeedsGrooming), }, { diff --git a/internal/app/implementation_context.go b/internal/app/implementation_context.go index bc451a7a8..c16badd3b 100644 --- a/internal/app/implementation_context.go +++ b/internal/app/implementation_context.go @@ -69,7 +69,7 @@ type ContextEntitySummary struct { // path, exact loss-preserving source bytes (base64 in JSON, as a Go []byte), // opaque record revision (blob object id), and — for a record — its parsed // summary. A zero ContextEntity (empty Path) means the bundle carries no such -// document (e.g. a trivial change with no spec). +// document (e.g. a change with no spec). type ContextEntity struct { Path string `json:"path,omitempty"` Source []byte `json:"source,omitempty"` diff --git a/internal/app/implementation_context_test.go b/internal/app/implementation_context_test.go index 7512c17c6..80458178f 100644 --- a/internal/app/implementation_context_test.go +++ b/internal/app/implementation_context_test.go @@ -296,7 +296,7 @@ func TestContextImplementationTypedAbsence(t *testing.T) { }, { name: "not ready", - corpus: []StatusBlob{changeBlob(15, "no-design", "feat", "high", "")}, // no spec, not trivial + corpus: []StatusBlob{changeBlob(15, "no-design", "feat", "high", "")}, // no spec req: ImplementationContextRequest{ID: 15}, wantResult: ResultInvalidState, wantReason: "not-ready-" + string(domain.ReadyNeedsGrooming), diff --git a/internal/app/open.go b/internal/app/open.go index aa1ed9048..80211d2ad 100644 --- a/internal/app/open.go +++ b/internal/app/open.go @@ -45,7 +45,6 @@ const ( ReasonOpenUnknownChange = "unknown-change" ReasonOpenAmbiguousChange = "ambiguous-change" ReasonOpenArtifactUnset = "artifact-unset" - ReasonOpenTrivialNoSpec = "trivial-no-spec" ReasonOpenBoardDisabled = "board-disabled" ReasonOpenPRNotURL = "pr-not-url" ReasonOpenPathInvalid = "artifact-path-invalid" @@ -301,18 +300,14 @@ func resolveOpenChange(ctx context.Context, reader StatusReader, pin StatusPin, } // changeArtifactPath returns the repository-relative path what names for c: the -// record itself, or its spec, plan, or results. A trivial change has no spec; -// an unset or malformed field is refused as not there yet. +// record itself, or its spec, plan, or results. An unset or malformed field (a +// stub's spec included) is refused as not there yet. func changeArtifactPath(c domain.Change, what string) (string, *openFailure) { var field domain.OptionalString switch what { case "change": return c.Path(), nil case "spec": - if c.Trivial() { - return "", &openFailure{ResultInvalidState, ReasonOpenTrivialNoSpec, - fmt.Sprintf("change %d is trivial — it has no spec", int(c.ID()))} - } field = c.Spec() case "plan": field = c.Plan() diff --git a/internal/app/open_test.go b/internal/app/open_test.go index ddd2c6aad..252d7248a 100644 --- a/internal/app/open_test.go +++ b/internal/app/open_test.go @@ -96,7 +96,7 @@ const ( oldSpec = "docs/superpowers/specs/2025-12-01-old-design.md" ) -// 7 fully linked, 3 archived, 8 bare, 9 trivial, 10 shorthand pr. +// 7 fully linked, 3 archived, 8 bare, 9 legacy trivial, 10 shorthand pr. func openCorpus() []StatusBlob { return []StatusBlob{ openChange(7, "widget", false, "branch: feat/widget\nspec: "+widgetSpec+"\nplan: "+widgetPlan+"\nresults: "+widgetResults+"\npr: '"+widgetPR+"'\n"), @@ -271,7 +271,7 @@ func TestOpenErrors(t *testing.T) { {"plan", 8, st, ReasonOpenArtifactUnset, "change 8 has no plan yet"}, {"results", 8, st, ReasonOpenArtifactUnset, "change 8 has no results yet"}, {"pr", 8, st, ReasonOpenArtifactUnset, "change 8 has no PR yet"}, - {"spec", 9, st, ReasonOpenTrivialNoSpec, "change 9 is trivial — it has no spec"}, + {"spec", 9, st, ReasonOpenArtifactUnset, "change 9 has no spec yet"}, {"board", 0, st, ReasonOpenBoardDisabled, "this repository has no board (board_surfaces has no inline surface)"}, {"pr", 10, st, ReasonOpenPRNotURL, "change 10 pr: acme/widget#12 is not a URL"}, {"bogus", 7, inv, ReasonOpenInvalidTarget, ""}, diff --git a/internal/app/status_test.go b/internal/app/status_test.go index 6765f5f41..249db5537 100644 --- a/internal/app/status_test.go +++ b/internal/app/status_test.go @@ -712,3 +712,37 @@ func TestStatusReportsHeldChange(t *testing.T) { row.Readiness, row.ReadinessWhy, row.Ready) } } + +// TestStatusLegacyTrivialRecordReadsNeedsGrooming: a legacy record carrying +// trivial: true and no spec is a stub — status reports it needs-grooming and +// keeps it out of the build-ready queue, while a spec'd sibling is ready. +func TestStatusLegacyTrivialRecordReadsNeedsGrooming(t *testing.T) { + fake := &fakeReader{ + pin: docketPin(t), + corpus: []StatusBlob{ + changeBlob(15, "legacy", "feat", "high", "trivial: true\n"), + changeBlob(16, "groomed", "feat", "low", "spec: docs/changes/specs/s16.md\n"), + }, + facts: domain.NewBranchFacts(nil), + artifacts: map[string]bool{"metadata|docs/changes/specs/s16.md": true}, + } + got := Status(context.Background(), fake, StatusOptions{}) + if got.Result != ResultApplied { + t.Fatalf("result = %q, want applied; message=%q", got.Result, got.Message) + } + if len(got.Ready) != 1 || got.Ready[0] != 16 { + t.Errorf("ready = %v, want [16] (the legacy trivial record is not build-ready)", got.Ready) + } + var row *StatusChange + for i := range got.Changes { + if got.Changes[i].ID == 15 { + row = &got.Changes[i] + } + } + if row == nil { + t.Fatalf("no row for legacy change 15: %+v", got.Changes) + } + if row.Readiness != string(domain.ReadyNeedsGrooming) || row.Ready { + t.Errorf("legacy trivial row = readiness %q, ready %v; want needs-grooming, false", row.Readiness, row.Ready) + } +} diff --git a/internal/app/workflow_integration_test.go b/internal/app/workflow_integration_test.go index 42263a9af..de13813fb 100644 --- a/internal/app/workflow_integration_test.go +++ b/internal/app/workflow_integration_test.go @@ -1769,7 +1769,7 @@ func commitSpecMetadataSpec(body string) string { } // commitSpecRecord is change 31 in-progress, its spec: field set to specPath -// ("" leaves it empty — a trivial change). +// ("" leaves it empty — a change claimed with no spec). func commitSpecRecord(specPath string) string { rec := lifecycleChange(31, "copyme", "in-progress") if specPath != "" { @@ -1937,11 +1937,16 @@ func TestIntegrationWorkflowLifecycleCommitSpecRefreshesRevisedSpec(t *testing.T env.assertClean(t) } -// TestIntegrationWorkflowLifecycleCommitSpecTrivialNoSpec: a change with no -// spec has no copy — a no-op that commits nothing. -func TestIntegrationWorkflowLifecycleCommitSpecTrivialNoSpec(t *testing.T) { +// TestIntegrationWorkflowLifecycleCommitSpecNoSpec: a legacy change claimed +// with no spec (its record still carrying an inert trivial: true line) has no +// copy — it still gets the no-spec no-op, which commits nothing. +func TestIntegrationWorkflowLifecycleCommitSpecNoSpec(t *testing.T) { + legacy := strings.Replace(commitSpecRecord(""), "\ntrivial: false\n", "\ntrivial: true\n", 1) + if !strings.Contains(legacy, "\ntrivial: true\n") { + t.Fatal("legacy fixture lacks its trivial: true line") + } env := newCommitSpecEnv(t, nil, map[string]string{ - groomPath(31, "copyme"): commitSpecRecord(""), + groomPath(31, "copyme"): legacy, }) before := env.head(t) res := env.commitSpec(t) diff --git a/internal/app/workspace_spec.go b/internal/app/workspace_spec.go index e451d50f9..43ab69842 100644 --- a/internal/app/workspace_spec.go +++ b/internal/app/workspace_spec.go @@ -42,8 +42,8 @@ const ( SpecCopyRefreshed = "refreshed" // SpecCopyCurrent: the feature head already carries the exact copy (no-op). SpecCopyCurrent = "current" - // SpecCopyNoSpec: the change links no spec (a trivial change), so there is - // no copy (no-op). + // SpecCopyNoSpec: the change links no spec (a legacy record claimed with + // none), so there is no copy (no-op). SpecCopyNoSpec = "no-spec" ) diff --git a/internal/domain/actions.go b/internal/domain/actions.go index 3fb3b121e..0a66d0555 100644 --- a/internal/domain/actions.go +++ b/internal/domain/actions.go @@ -483,7 +483,6 @@ func newChangeBuilder(c Change) *changeBuilder { Spec: c.Spec(), Plan: c.Plan(), Results: c.Results(), - Trivial: c.Trivial(), AutoGroomable: c.AutoGroomable(), Hold: c.Hold(), BranchPrefix: c.BranchPrefix(), diff --git a/internal/domain/entities.go b/internal/domain/entities.go index 09473faa5..02d3899f2 100644 --- a/internal/domain/entities.go +++ b/internal/domain/entities.go @@ -91,7 +91,6 @@ type ChangeSpec struct { Spec OptionalString Plan OptionalString Results OptionalString - Trivial bool AutoGroomable OptionalBool // per-change auto-groom opt-in; only an explicit true opts in Hold OptionalBool // per-change hold; keeps the change out of autonomous build selection BranchPrefix OptionalString // per-change mint-prefix override; durable input @@ -195,9 +194,6 @@ func (c Change) Plan() OptionalString { return c.spec.Plan } // Results returns the optional results artifact reference. func (c Change) Results() OptionalString { return c.spec.Results } -// Trivial reports whether the change is marked trivial. -func (c Change) Trivial() bool { return c.spec.Trivial } - // AutoGroomable returns the optional per-change auto-groom opt-in. Only an // explicit true makes a stub auto-groomable; unset (absent or valueless) and // false both mean it is not. The tri-state is kept so the record writer diff --git a/internal/domain/entities_test.go b/internal/domain/entities_test.go index f18d052a8..e95f317a6 100644 --- a/internal/domain/entities_test.go +++ b/internal/domain/entities_test.go @@ -44,7 +44,6 @@ func fullChangeSpec(t *testing.T) ChangeSpec { Spec: OptionalString{State: FieldPresent, Value: "docs/specs/x.md"}, Plan: OptionalString{State: FieldEmpty}, Results: OptionalString{State: FieldAbsent}, - Trivial: true, Branch: OptionalString{State: FieldPresent, Value: "feat/domain-snapshot"}, ClaimedAt: OptionalTime{State: FieldPresent, Value: time.Date(2026, 8, 13, 4, 5, 6, 0, time.UTC), Raw: "2026-08-13T04:05:06Z"}, PR: OptionalString{State: FieldPresent, Value: "https://example.test/pr/1"}, @@ -111,9 +110,6 @@ func TestChangeAccessorsRoundTrip(t *testing.T) { if got := c.ADRs(); !slices.Equal(got, spec.ADRs) { t.Errorf("ADRs() = %v; want %v", got, spec.ADRs) } - if got := c.Trivial(); got != spec.Trivial { - t.Errorf("Trivial() = %v; want %v", got, spec.Trivial) - } if got := c.Branch(); got != spec.Branch { t.Errorf("Branch() = %+v; want %+v", got, spec.Branch) } diff --git a/internal/domain/readiness.go b/internal/domain/readiness.go index 8baa9a685..8cf66a853 100644 --- a/internal/domain/readiness.go +++ b/internal/domain/readiness.go @@ -54,8 +54,8 @@ type Readiness struct { // on-hold. Every earlier outcome wins, so a held change that is also // waiting, ungroomed, or on an unresolved stack base keeps that reason. // -// A change carries design when it has a non-empty spec: reference or is marked -// trivial; a present-but-empty spec: counts as no spec. +// A change carries design only when it has a non-empty spec: reference; a +// present-but-empty spec: counts as no spec. func EvaluateReadiness(s Snapshot, c Change, facts BranchFacts) Readiness { if c.Status() != StatusProposed { return Readiness{Kind: ReadyNotProposed} @@ -92,16 +92,15 @@ func EvaluateReadiness(s Snapshot, c Change, facts BranchFacts) Readiness { } // NeedsDesign reports whether c still needs a design pass: proposed, carrying -// no spec, and not marked trivial. It deliberately ignores dependency -// satisfaction, so interactive grooming can design a change ahead of the work -// it depends on. +// no spec. It deliberately ignores dependency satisfaction, so interactive +// grooming can design a change ahead of the work it depends on. func NeedsDesign(c Change) bool { return c.Status() == StatusProposed && !hasDesign(c) } // hasDesign reports whether c carries a design outcome — a non-empty spec: -// reference or trivial: true. A spec: key present with no value is no spec. +// reference. A spec: key present with no value is no spec. func hasDesign(c Change) bool { spec := c.Spec() - return c.Trivial() || (spec.State == FieldPresent && spec.Value != "") + return spec.State == FieldPresent && spec.Value != "" } diff --git a/internal/domain/readiness_test.go b/internal/domain/readiness_test.go index 90d9dca41..11c9abd24 100644 --- a/internal/domain/readiness_test.go +++ b/internal/domain/readiness_test.go @@ -8,7 +8,6 @@ type readySpec struct { slug string status Status spec OptionalString - trivial bool dependsOn []ChangeID parent OptionalInt branch string @@ -39,7 +38,6 @@ func (rp readySpec) build() Change { Slug: slug, Status: rp.status, Spec: rp.spec, - Trivial: rp.trivial, DependsOn: rp.dependsOn, StackedOn: rp.parent, Hold: rp.hold, @@ -136,7 +134,7 @@ func TestEvaluateReadinessPrecedence(t *testing.T) { want: ReadyWaitingDependency, }, { - name: "proposed, no spec, not trivial is needs-grooming", + name: "proposed, no spec is needs-grooming", specs: []readySpec{{id: 2, status: StatusProposed}}, subject: 2, want: ReadyNeedsGrooming, @@ -159,12 +157,6 @@ func TestEvaluateReadinessPrecedence(t *testing.T) { subject: 2, want: ReadyBuildReady, }, - { - name: "trivial with no spec is build-ready", - specs: []readySpec{{id: 2, status: StatusProposed, trivial: true}}, - subject: 2, - want: ReadyBuildReady, - }, { name: "spec'd with met dependencies, stacked on an unresolvable parent", specs: []readySpec{ @@ -219,12 +211,6 @@ func TestEvaluateReadinessPrecedence(t *testing.T) { subject: 2, want: ReadyOnHold, }, - { - name: "a held trivial change is on-hold", - specs: []readySpec{{id: 2, status: StatusProposed, trivial: true, hold: holdTrue}}, - subject: 2, - want: ReadyOnHold, - }, { name: "a held stub still needs grooming", specs: []readySpec{{id: 2, status: StatusProposed, hold: holdTrue}}, @@ -379,7 +365,7 @@ func TestNeedsDesign(t *testing.T) { want bool }{ { - name: "proposed with no spec and not trivial needs design", + name: "proposed with no spec needs design", spec: readySpec{id: 2, status: StatusProposed}, want: true, }, @@ -403,11 +389,6 @@ func TestNeedsDesign(t *testing.T) { spec: readySpec{id: 2, status: StatusProposed, spec: specRef("s.md")}, want: false, }, - { - name: "a trivial change needs no design", - spec: readySpec{id: 2, status: StatusProposed, trivial: true}, - want: false, - }, { name: "a non-proposed change needs no design", spec: readySpec{id: 2, status: StatusInProgress}, diff --git a/internal/render/board.go b/internal/render/board.go index 67cb16fae..7abf32562 100644 --- a/internal/render/board.go +++ b/internal/render/board.go @@ -19,9 +19,9 @@ import ( // invalid presentation — see BoardPresentation.validate). Each active change is // classified into exactly one rendered group by boardClassify — a mapping that // is deliberately NOT one-to-one with lifecycle status (finalize-blocked -// implemented changes render Blocked; spec-backed build-ready proposals render -// Groomed). testdata/board/board.golden is the byte-drift guard: it is the -// reviewed canonical render of testdata/board/corpus/ under the DEFAULT +// implemented changes render Blocked; build-ready proposals render Groomed). +// testdata/board/board.golden is the byte-drift guard: it is the reviewed +// canonical render of testdata/board/corpus/ under the DEFAULT // presentation (see testdata/board/PROVENANCE.md), re-founded at change 0367 // when the default output changed by design. A diff there is a real change to // the board surface and must be re-blessed deliberately. @@ -64,11 +64,8 @@ import ( // change carries the bare "## Run halted" body section (HasRunHalted), // else "building". // The Groomed Readiness cell is "build-ready", or "on hold" for a held -// change (a hold is selection-only, so a held spec-backed change stays -// Groomed). +// change (a hold is selection-only, so a held change stays Groomed). // The Proposed Readiness cell: -// build-ready → "build-ready" / "build-ready (trivial)" -// on-hold → "on hold" // needs-grooming → "needs-grooming" // auto-groom-blocked → "auto-groom blocked — needs you" // waiting-dependency → "⏳ waiting on # — not yet built" @@ -79,9 +76,7 @@ import ( // id; the stack cell names the change's immediate stacked_on parent, // zero-padded. The parent-killed cell instead names the killed ancestor // (StackBase.Cause), zero-padded, and carries no "needs you" suffix -// because no marker section drives it. A build-ready proposal that reaches Proposed is necessarily -// trivial-without-spec (spec-backed build-ready is Groomed) and renders -// "build-ready (trivial)". +// because no marker section drives it. // 4. A mermaid graph: "\n```mermaid\ngraph TD\n", then every active change in // ascending id order — one " --> " edge per depends_on entry // (padded), or a bare " " node when it has none — then every archived @@ -140,8 +135,8 @@ type BoardUnrenderable struct { // BoardSection is one rendered board group — a set of allowed values deliberately // distinct from the lifecycle statuses a change carries (change 0367). A change // is classified into exactly one section; the mapping is not one-to-one with -// status (finalize-blocked implemented changes render Blocked, spec-backed -// build-ready proposals render Groomed). +// status (finalize-blocked implemented changes render Blocked, build-ready +// proposals render Groomed). type BoardSection string const ( @@ -283,13 +278,10 @@ func boardClassify(in BoardInput, c domain.Change) (BoardSection, error) { return BoardSectionBuilt, nil case domain.StatusProposed: // Groomed means build-ready (or held, which is build-ready but for the - // hold) AND spec-backed: a trivial build-ready change with an empty - // spec stays Proposed. - if c.Spec().Value != "" { - switch domain.EvaluateReadiness(in.Snapshot, c, in.Facts).Kind { - case domain.ReadyBuildReady, domain.ReadyOnHold: - return BoardSectionGroomed, nil - } + // hold); readiness already requires a spec. + switch domain.EvaluateReadiness(in.Snapshot, c, in.Facts).Kind { + case domain.ReadyBuildReady, domain.ReadyOnHold: + return BoardSectionGroomed, nil } return BoardSectionProposed, nil case domain.StatusDeferred: @@ -737,18 +729,6 @@ func boardGroomedReadinessCell(in BoardInput, c domain.Change) (string, error) { func boardReadinessCell(in BoardInput, c domain.Change) (string, error) { r := domain.EvaluateReadiness(in.Snapshot, c, in.Facts) switch r.Kind { - case domain.ReadyBuildReady: - // The only build-ready row that reaches Proposed is trivial-without-spec - // (spec-backed build-ready is Groomed); mark it so the reader sees why it - // skipped grooming. - if c.Trivial() { - return "build-ready (trivial)", nil - } - return "build-ready", nil - case domain.ReadyOnHold: - // Only a held trivial-without-spec change reaches Proposed with this - // kind (a held spec-backed change is Groomed). - return "on hold", nil case domain.ReadyNeedsGrooming: return "needs-grooming", nil case domain.ReadyAutoGroomBlocked: @@ -762,7 +742,8 @@ func boardReadinessCell(in BoardInput, c domain.Change) (string, error) { } return fmt.Sprintf("⏳ waiting on #%04d — stack base not built", int(c.StackedOn().Value)), nil default: - // A proposed row never reaches here for a well-formed corpus: readiness + // A proposed row never reaches here for a well-formed corpus: a + // build-ready or on-hold change classifies as Groomed, readiness // reports not-proposed only for a non-proposed change, and invalid only // for a duplicate/negative id or an unusable slug. A corpus carrying such // an unrelated defect is still rendered (change 0449), so this is a diff --git a/internal/render/board_test.go b/internal/render/board_test.go index 5b8bc5def..a2103e1d0 100644 --- a/internal/render/board_test.go +++ b/internal/render/board_test.go @@ -151,8 +151,8 @@ func boardWith(t *testing.T, pres render.BoardPresentation, facts domain.BranchF // TestBoardClassifyEveryBucket pins boardClassify's precedence: exactly one // rendered section per active change, including the two precedence edges -// (finalize-blocked implemented → Blocked over Built; spec-backed build-ready → -// Groomed while trivial-build-ready-without-spec stays Proposed). +// (finalize-blocked implemented → Blocked over Built; build-ready → Groomed +// over Proposed). func TestBoardClassifyEveryBucket(t *testing.T) { blocked := domain.NewChange(domain.ChangeSpec{ ID: 1, Slug: "blk", Title: "Blocked", Status: domain.StatusBlocked, @@ -198,12 +198,6 @@ func TestBoardClassifyEveryBucket(t *testing.T) { stackChildSpec.StackedOn = domain.OptionalInt{State: domain.FieldPresent, Value: 9} stackChild := domain.NewChange(stackChildSpec) - // proposed + trivial, no spec (build-ready) → proposed, because the groomed - // label means build-ready AND spec-backed. - trivialSpec := proposedChange(10, "triv", "Trivial") - trivialSpec.Trivial = true - trivial := domain.NewChange(trivialSpec) - needsGrooming := domain.NewChange(proposedChange(11, "needs", "Needs grooming")) // proposed + spec + held → Groomed (a hold is selection-only, not a demotion). @@ -236,7 +230,6 @@ func TestBoardClassifyEveryBucket(t *testing.T) { {"proposed spec held", held, nil, render.BoardSectionGroomed}, {"proposed spec unmet dependency", waiter, []domain.Change{depTarget}, render.BoardSectionProposed}, {"proposed spec unresolved stack base", stackChild, []domain.Change{parent}, render.BoardSectionProposed}, - {"proposed trivial no spec", trivial, nil, render.BoardSectionProposed}, {"proposed needs-grooming", needsGrooming, nil, render.BoardSectionProposed}, {"proposed auto-groom-blocked", agBlocked, nil, render.BoardSectionProposed}, {"deferred lifecycle", deferred, nil, render.BoardSectionDeferred}, @@ -352,7 +345,7 @@ func TestBoardReadinessNeedsMerge(t *testing.T) { // retained auto-groom-blocked marker reports the human call to action. func TestBoardReadinessAutoGroomBlocked(t *testing.T) { c := proposedChange(7, "blocked-groom", "Blocked groom") - c.HasAutoGroomBlocked = true // no spec, not trivial + c.HasAutoGroomBlocked = true // no spec out := string(boardFrom(t, domain.NewChange(c))) if !strings.Contains(out, "| Blocked groom | `` | `untyped` | auto-groom blocked — needs you |") { t.Fatalf("auto-groom-blocked cell not rendered:\n%s", out) @@ -461,25 +454,6 @@ func TestBoardGroomedReadinessCells(t *testing.T) { assertNoRepairNotice(t, out) } -// TestBoardHeldTrivialStaysProposed: a held trivial change without a spec stays -// in Proposed and states "on hold", never "build-ready (trivial)". -func TestBoardHeldTrivialStaysProposed(t *testing.T) { - spec := proposedChange(22, "held-triv", "Held trivial") - spec.Trivial = true - spec.Hold = heldTrue - out := string(boardFrom(t, domain.NewChange(spec))) - if !strings.Contains(out, "## 🟡 Proposed (1)") { - t.Fatalf("held trivial change must render under Proposed:\n%s", out) - } - if !strings.Contains(out, "| [0022](active/0022-held-triv.md) | Held trivial | `` | `untyped` | on hold |\n") { - t.Fatalf("held trivial cell must read on hold:\n%s", out) - } - if strings.Contains(out, "build-ready (trivial)") { - t.Fatalf("held trivial change must not read build-ready (trivial):\n%s", out) - } - assertNoRepairNotice(t, out) -} - // TestBoardHeldWaitingChangeShowsWaitingCell: a held change with an unmet // dependency keeps its earlier readiness, so the board shows the waiting cell // in Proposed, not "on hold". @@ -602,28 +576,17 @@ func killedStackParent(id int, slug string) domain.Change { } // TestBoardReadinessKilledStackParent pins the plain killed-parent cell for a -// spec'd and a trivial proposal stacked on a killed parent. +// spec'd proposal stacked on a killed parent. func TestBoardReadinessKilledStackParent(t *testing.T) { - for _, tc := range []struct { - name string - trivial bool - }{{"spec", false}, {"trivial", true}} { - t.Run(tc.name, func(t *testing.T) { - child := proposedChange(9, "child", "Child") - if tc.trivial { - child.Trivial = true - } else { - child.Spec = optString("docs/superpowers/specs/child-design.md") - } - child.StackedOn = domain.OptionalInt{State: domain.FieldPresent, Value: 8} - out := string(boardFromFacts(t, domain.BranchFacts{}, killedStackParent(8, "parent"), domain.NewChange(child))) - if !strings.Contains(out, "stack parent #0008 killed — re-parent, un-stack, or kill") { - t.Fatalf("killed-parent cell not rendered:\n%s", out) - } - if strings.Contains(out, "waiting on #0008") { - t.Fatalf("killed parent still rendered as waiting:\n%s", out) - } - }) + child := proposedChange(9, "child", "Child") + child.Spec = optString("docs/superpowers/specs/child-design.md") + child.StackedOn = domain.OptionalInt{State: domain.FieldPresent, Value: 8} + out := string(boardFromFacts(t, domain.BranchFacts{}, killedStackParent(8, "parent"), domain.NewChange(child))) + if !strings.Contains(out, "stack parent #0008 killed — re-parent, un-stack, or kill") { + t.Fatalf("killed-parent cell not rendered:\n%s", out) + } + if strings.Contains(out, "waiting on #0008") { + t.Fatalf("killed parent still rendered as waiting:\n%s", out) } } @@ -1228,21 +1191,6 @@ func TestBoardRepeatRenderByteStable(t *testing.T) { } } -// TestBoardProposedTrivialBuildReadyCell pins that a trivial, spec-less -// build-ready proposal renders "build-ready (trivial)" under Proposed (the only -// build-ready row that reaches Proposed — spec-backed build-ready is Groomed). -func TestBoardProposedTrivialBuildReadyCell(t *testing.T) { - spec := proposedChange(10, "triv", "Trivial") - spec.Trivial = true - out := string(boardFrom(t, domain.NewChange(spec))) - if !strings.Contains(out, "## 🟡 Proposed (1)") { - t.Fatalf("Proposed section missing:\n%s", out) - } - if !strings.Contains(out, "| build-ready (trivial) |") { - t.Fatalf("trivial build-ready cell missing:\n%s", out) - } -} - // permutedPresentation differs from the default on BOTH presentation axes: the // section order is reversed AND every section sorts id/asc instead of the // built-in updated/desc. It is the "the presentation genuinely changed" fixture diff --git a/internal/render/testdata/board/PROVENANCE.md b/internal/render/testdata/board/PROVENANCE.md index 7b1e255f4..0903daf9e 100644 --- a/internal/render/testdata/board/PROVENANCE.md +++ b/internal/render/testdata/board/PROVENANCE.md @@ -53,7 +53,7 @@ Sections and rows: - **Proposed** — two readiness bands, sorted `updated desc`: - id 4 (updated 2026-08-04) waiting `⏳ waiting on #3 — not yet built` (dep on a non-built change); - - id 3 (updated 2026-08-03) `needs-grooming` (no spec, not trivial). + - id 3 (updated 2026-08-03) `needs-grooming` (no spec). - **Deferred** — id 6. - **Archive `
`** — id 9 (`done`) and id 10 (`killed`); summary emoji + `done + killed` label; Merged date from the archive filename prefix. @@ -71,17 +71,15 @@ directly instead: - the dated `## Run halted — ` variant NOT lighting the State cell (whole-line decode contract — `TestBoardRunHaltedWholeLineContract`); - the Groomed `on hold` Readiness cell for a held spec-backed change - (`TestBoardGroomedReadinessCells`) and the Proposed `on hold` cell for a held - trivial change (`TestBoardHeldTrivialStaysProposed`); + (`TestBoardGroomedReadinessCells`); - the classification precedence edges (finalize-blocked implemented → Blocked; - spec-backed build-ready → Groomed vs trivial-without-spec → Proposed); + spec-backed build-ready → Groomed); - the Blocked `finalize blocked — needs you` Reason cell; - the Built `merged into #NNNN` State cell for a stacked-merged change; - proposed `⏳ … — needs your merge` (dependency on an `implemented` change); - proposed `auto-groom blocked — needs you`; - proposed `⏳ waiting on #NNNN — stack base not built`; - proposed `stack parent #NNNN killed — re-parent, un-stack, or kill`; -- proposed `build-ready (trivial)` (trivial, spec-less build-ready); - non-default section orders and per-section sort keys, same-date id-desc ties, and the unknown-date band; - the empty-priority / `untyped`-type cells; diff --git a/internal/repository/decode.go b/internal/repository/decode.go index a61d0c9b1..fc927ba8d 100644 --- a/internal/repository/decode.go +++ b/internal/repository/decode.go @@ -122,7 +122,6 @@ type changeWire struct { Spec scalar `yaml:"spec"` Plan scalar `yaml:"plan"` Results scalar `yaml:"results"` - Trivial scalar `yaml:"trivial"` AutoGroomable scalar `yaml:"auto_groomable"` Hold scalar `yaml:"hold"` BranchPrefix scalar `yaml:"branch_prefix"` @@ -576,7 +575,6 @@ func decodeChange(in InputDocument) (domain.Change, []domain.Finding) { spec.Spec = d.optionalString("spec", wire.Spec) spec.Plan = d.optionalString("plan", wire.Plan) spec.Results = d.optionalString("results", wire.Results) - spec.Trivial = d.boolean("trivial", wire.Trivial) spec.AutoGroomable = d.optionalBool("auto_groomable", wire.AutoGroomable) spec.Hold = d.optionalBool("hold", wire.Hold) spec.BranchPrefix = d.optionalString("branch_prefix", wire.BranchPrefix) diff --git a/internal/repository/decode_test.go b/internal/repository/decode_test.go index d507e4c6a..c8fd3d308 100644 --- a/internal/repository/decode_test.go +++ b/internal/repository/decode_test.go @@ -136,9 +136,6 @@ func TestDecodeChangeHappyPath(t *testing.T) { if got := change.Results(); got.State != domain.FieldEmpty { t.Errorf("Results = %+v", got) } - if change.Trivial() { - t.Error("Trivial = true, want false") - } if got := change.Branch(); got.State != domain.FieldPresent || got.Value != "feat/domain-snapshot-validation-graphs-and-selection" { t.Errorf("Branch = %+v", got) @@ -788,19 +785,35 @@ func TestDecodeChangeIDMalformed(t *testing.T) { } } -// TestDecodeChangeBooleanMalformed — trivial/reconciled are booleans; a -// non-boolean is a finding, not a silent false. +// TestDecodeChangeBooleanMalformed — reconciled is a boolean; a non-boolean is +// a finding, not a silent false. func TestDecodeChangeBooleanMalformed(t *testing.T) { - const source = "---\nid: 1\nslug: s\ntrivial: maybe\nreconciled: true\n---\n\nbody\n" + const source = "---\nid: 1\nslug: s\nreconciled: maybe\n---\n\nbody\n" change, findings := decodeChange(input(t, KindChange, LocationActive, "docs/changes/active/0001-s.md", source)) - if change.Trivial() { - t.Error("Trivial = true for a malformed value") + if change.Reconciled() { + t.Error("Reconciled = true for a malformed value") } - if !change.Reconciled() { - t.Error("Reconciled = false, want true") + if !hasFinding(findings, CodeFieldMalformed, "reconciled") { + t.Errorf("no field-malformed finding for reconciled: %v", findingCodes(findings)) } - if !hasFinding(findings, CodeFieldMalformed, "trivial") { - t.Errorf("no field-malformed finding for trivial: %v", findingCodes(findings)) +} + +// TestDecodeLegacyTrivialKeyIsInert — a legacy trivial: line is unread data: +// trivial: true with an empty spec: still needs design, and a malformed +// trivial: value produces no finding. +func TestDecodeLegacyTrivialKeyIsInert(t *testing.T) { + const legacy = "---\nid: 1\nslug: s\nstatus: proposed\nspec:\ntrivial: true\n---\n\nbody\n" + change, findings := decodeChange(input(t, KindChange, LocationActive, "docs/changes/active/0001-s.md", legacy)) + if len(findings) != 0 { + t.Fatalf("legacy trivial: true produced findings: %v", findingCodes(findings)) + } + if !domain.NeedsDesign(change) { + t.Errorf("legacy trivial: true with no spec must need design; spec = %+v", change.Spec()) + } + + const malformed = "---\nid: 1\nslug: s\nstatus: proposed\ntrivial: maybe\n---\n\nbody\n" + if _, findings := decodeChange(input(t, KindChange, LocationActive, "docs/changes/active/0001-s.md", malformed)); len(findings) != 0 { + t.Errorf("malformed legacy trivial: produced findings: %v", findingCodes(findings)) } } From 8454620499b7addedf548130e0c11680c617fe14 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Mon, 19 Oct 2026 20:32:59 -0400 Subject: [PATCH 07/12] docs(skills): build-readiness is a spec; results required for every implemented change --- internal/assets/embedded/manifest.json | 26 +++++++++---------- .../tree/skills/docket-convention/SKILL.md | 11 ++++---- .../skills/docket-implement-next/SKILL.md | 12 ++++----- .../references/results-artifact.md | 4 +-- .../docket-implement-next/results-template.md | 4 +-- .../tree/skills/docket-review/SKILL.md | 2 +- .../tree/skills/docket-status/SKILL.md | 2 +- internal/repoguard/budgets_test.go | 12 ++++----- internal/repoguard/prose_contracts_test.go | 16 ++++++++---- skills/docket-convention/SKILL.md | 11 ++++---- skills/docket-implement-next/SKILL.md | 12 ++++----- .../references/results-artifact.md | 4 +-- .../docket-implement-next/results-template.md | 4 +-- skills/docket-review/SKILL.md | 2 +- skills/docket-status/SKILL.md | 2 +- 15 files changed, 64 insertions(+), 60 deletions(-) diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index 8f7e535ad..4856a35d0 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:9655f89087fb84ac2de7852c2c09408ec7636be9f76c084c4708e905c8947dce", + "asset_set_id": "sha256:4740bc56d75fa1725212080799f9044cd71cfb3e7b2194f07fae9fe9825b4f8f", "entries": [ { "path": ".docket.example.yml", @@ -322,8 +322,8 @@ "path": "skills/docket-convention/SKILL.md", "role": "skill", "mode": 420, - "size": 53753, - "sha256": "46f39cae61f74ff14a8fdc5a5878c3d7fe8a6f9ade4e43e57817c23ee76b8cfe" + "size": 53532, + "sha256": "c53fb6037c675224b506f99373c8a71571b41af9b2ad9c79912b9d8c4d04ca66" }, { "path": "skills/docket-convention/references/agent-layer.md", @@ -378,8 +378,8 @@ "path": "skills/docket-implement-next/SKILL.md", "role": "skill", "mode": 420, - "size": 59470, - "sha256": "4fa089cb4628311bad6750288b0cae3a84b6ba63911992c08979c9df08e389aa" + "size": 59299, + "sha256": "15b342ac83767c92a1a73c105e14fbedd03a47951b357b37dd87b54a02aad144" }, { "path": "skills/docket-implement-next/references/edge-paths.md", @@ -399,15 +399,15 @@ "path": "skills/docket-implement-next/references/results-artifact.md", "role": "skill", "mode": 420, - "size": 5131, - "sha256": "abd74f4dca159ae60d5bcd2aefb4ba16d2e0deffeeabce09b650d69110820aad" + "size": 5071, + "sha256": "b7112b747ec1d24ed5d6a83ff4e537a507be4f60bab28679e540a744ca041937" }, { "path": "skills/docket-implement-next/results-template.md", "role": "skill", "mode": 420, - "size": 3760, - "sha256": "a5f1d87a0d63f764551c6e3301e019886c83b541507b22eb0e935ebc881bed8c" + "size": 3741, + "sha256": "c633d7c6e9ebe1540282f4361eedee0aac082b3f9897c0668a7aec2a275bc0a3" }, { "path": "skills/docket-new-change/SKILL.md", @@ -420,15 +420,15 @@ "path": "skills/docket-review/SKILL.md", "role": "skill", "mode": 420, - "size": 6489, - "sha256": "1e7dcfa45df8283824cc76eb2aa64d37ab04e6c10f60f458454114b3a1e835d1" + "size": 6460, + "sha256": "2589c88417c7af5d25b7b807270c549f98982b519f0545ba7b8c2f72dda4cb62" }, { "path": "skills/docket-status/SKILL.md", "role": "skill", "mode": 420, - "size": 20143, - "sha256": "891b4ed127a7d48e7579790e226c7f1c1feff4351dfc318b23b99dcc72c1516c" + "size": 20121, + "sha256": "6a72745f574d8f2d5c2f868f9abc3d22ac9b4c77efe85586abfb164d487c4280" } ] } diff --git a/internal/assets/embedded/tree/skills/docket-convention/SKILL.md b/internal/assets/embedded/tree/skills/docket-convention/SKILL.md index 32de42c90..f67b32524 100644 --- a/internal/assets/embedded/tree/skills/docket-convention/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-convention/SKILL.md @@ -154,7 +154,7 @@ docket's workflow steps are **roles**, each done by one fixed skill: / # default docs/adrs/ — flat; ADRs are NEVER archived -.md # immutable once Accepted (only its status: line ever changes) README.md # generated ADR index -/ # default docs/results/ — required close-out artifacts (one per implemented change, trivial included) (on the metadata branch; NEVER archived) +/ # default docs/results/ — required close-out artifacts (one per implemented change) (on the metadata branch; NEVER archived) --results.md ``` @@ -162,7 +162,7 @@ The `archive/` filename date prefix is **UTC**: the merge date for a merged chan All of the above lives on the metadata branch, written through the persistent **metadata worktree**: `/.docket/` in a shared repository (gitignored, deliberately not under `.worktrees/` — slug collisions, prune blast radius), or a checkout outside the clone in a private one; skills always use `metadata_worktree_path` (see *Branch model*). -**Results artifact shape and lifecycle.** The results file is a required close-out artifact for every implemented change, trivial included. Its template opens with a required `**Human action:**` statement immediately after the title (a settled assessment at finalization) and carries a required `## Outcome` section plus the conditional sections `## Human actions and testing` (items labeled Important or Optional; optional walkthroughs may cover automated behavior), `## Verification performed`, and `## Known issues and follow-ups` — omit any conditional section, subsections and all, when it would hold no substantive content, and never pad one with `None`/`N/A` filler. The results **file** lives on the metadata branch at `/--results.md`; the `change.attach-results` operation writes the file and the `results:` **field** together, in one commit. The coordinator captures findings at defined checkpoints during implementation (docket-implement-next's Step 6.5 is normative), not in a single final pass. Follow-ups recorded here hold out-of-scope work for human triage — the run checks proposed and deferred changes and names any match, but never mints a change, issue, ADR, or learning automatically. +**Results artifact shape and lifecycle.** The results file is a required close-out artifact for every implemented change. Its template opens with a required `**Human action:**` statement immediately after the title (a settled assessment at finalization) and carries a required `## Outcome` section plus the conditional sections `## Human actions and testing` (items labeled Important or Optional; optional walkthroughs may cover automated behavior), `## Verification performed`, and `## Known issues and follow-ups` — omit any conditional section, subsections and all, when it would hold no substantive content, and never pad one with `None`/`N/A` filler. The results **file** lives on the metadata branch at `/--results.md`; the `change.attach-results` operation writes the file and the `results:` **field** together, in one commit. The coordinator captures findings at defined checkpoints during implementation (docket-implement-next's Step 6.5 is normative), not in a single final pass. Follow-ups recorded here hold out-of-scope work for human triage — the run checks proposed and deferred changes and names any match, but never mints a change, issue, ADR, or learning automatically. ### Change manifest (frontmatter at the top of each change file) @@ -187,7 +187,6 @@ adrs: [24] # ADRs this change cites or produces spec: # superpowers design doc path; set at brainstorm (propose) time, on the metadata branch plan: # plan FILE on the metadata branch; FILE and FIELD written together by change.attach-plan at build time results: # results FILE on the metadata branch; FILE and FIELD written together by change.attach-results at the first checkpoint, required before the implemented transition -trivial: false # true = no spec needed (small mechanical change); still build-ready auto_groomable: # `true` makes a stub auto-groomable; unset or `false` means not hold: # `true` keeps a groomed change out of autonomous build selection; naming it still builds it branch_prefix: # optional one unqualified branch-path component; overrides at mint, consumed only at claim, inert once branch: is populated, survives reclaim @@ -288,13 +287,13 @@ An `Accepted` ADR is immutable except its `status:` line; a non-reversing contex ### Build-readiness & selection (shared definition) -A change is **build-ready** — eligible for `docket-implement-next` — only when it is `proposed`, has a `spec:` **or** `trivial: true`, and all `depends_on` are satisfied (`done`). A `proposed` change with neither a spec nor `trivial: true` is **needs-grooming** (not build-ready). A change carrying `stacked_on:` is additionally build-ready only when the binary resolves its **effective base**; until then its readiness is `stack-base-unresolved` and the board reads *waiting on #A — stack base not built* (*stack parent #A killed — re-parent, un-stack, or kill* when an ancestor was killed). Stacking adds this eligibility condition only — never a ranking one. The implementer's deterministic selection order is `priority` (`critical` > `high` > `medium` > `low`) → age (`created`) → **lowest `id`**. A `created:` that is missing or malformed (not a well-formed `YYYY-MM-DD`) sorts last within its priority band — unknown age never preempts dated work. A held change (`hold: true`) that would be build-ready reads `on-hold`: autonomous selection never picks it, and naming it builds it. +A change is **build-ready** — eligible for `docket-implement-next` — only when it is `proposed`, has a `spec:`, and all `depends_on` are satisfied (`done`). A `proposed` change with no spec is **needs-grooming** (not build-ready). A change carrying `stacked_on:` is additionally build-ready only when the binary resolves its **effective base**; until then its readiness is `stack-base-unresolved` and the board reads *waiting on #A — stack base not built* (*stack parent #A killed — re-parent, un-stack, or kill* when an ancestor was killed). Stacking adds this eligibility condition only — never a ranking one. The implementer's deterministic selection order is `priority` (`critical` > `high` > `medium` > `low`) → age (`created`) → **lowest `id`**. A `created:` that is missing or malformed (not a well-formed `YYYY-MM-DD`) sorts last within its priority band — unknown age never preempts dated work. A held change (`hold: true`) that would be build-ready reads `on-hold`: autonomous selection never picks it, and naming it builds it. ### Autonomous grooming (shared definition) -A change is opted into autonomous grooming only by its own `auto_groomable: true`; unset or `false` means not. The field is human input with one exception: `docket-auto-groom`'s abstain is the single agent write (`change.groom` `outcome: abstain` sets it to `false`). Likewise `hold` is human input except the auto-groomer's `hold: true` on a spec or trivial verdict that needs a person's step. +A change is opted into autonomous grooming only by its own `auto_groomable: true`; unset or `false` means not. The field is human input with one exception: `docket-auto-groom`'s abstain is the single agent write (`change.groom` `outcome: abstain` sets it to `false`). Likewise `hold` is human input except the auto-groomer's `hold: true` on a spec that needs a person's step. -A stub is **auto-groomable** — selectable by `docket-auto-groom` — when it is needs-grooming (`proposed`, no `spec:`, not `trivial: true`) AND it carries `auto_groomable: true`. Unsatisfied `depends_on` does NOT exclude it (the same design-ahead rule as interactive grooming; the implementer's reconcile re-validates at build time). Ranking is the same deterministic selection order as build-ready selection. +A stub is **auto-groomable** — selectable by `docket-auto-groom` — when it is needs-grooming (`proposed`, no `spec:`) AND it carries `auto_groomable: true`. Unsatisfied `depends_on` does NOT exclude it (the same design-ahead rule as interactive grooming; the implementer's reconcile re-validates at build time). Ranking is the same deterministic selection order as build-ready selection. **Abstain rule.** When autonomous grooming cannot safely default a decision, it emits NO spec; it applies `change.groom` with `outcome: abstain`, which flips `auto_groomable: false`, appends a dated entry to the `## Auto-groom blocked` body section, and re-renders the board in one commit. The stub stays needs-grooming — out of the autonomous queue, still in the interactive one. Re-enable = a human supplies the missing context and applies `change.groom` with `outcome: re-enable` (optionally with owned-section edits carrying that context): it sets the flag back to `true` and removes the `## Auto-groom blocked` section in the same commit — never a hand edit (git history keeps the section; its presence drives the board's needs-you cell, so a stale one would mislabel a re-enabled stub). Kill and defer are never autonomous: they surface inside the blocked section as recommendations. diff --git a/internal/assets/embedded/tree/skills/docket-implement-next/SKILL.md b/internal/assets/embedded/tree/skills/docket-implement-next/SKILL.md index e8fef5d33..068061db5 100644 --- a/internal/assets/embedded/tree/skills/docket-implement-next/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-implement-next/SKILL.md @@ -54,7 +54,7 @@ A claim of a `proposed` record that still carries a `## Run halted` section remo ### Step 3 — Reconcile ⭐ -Re-read the step-1 bundle's change + spec bytes against `related` + recently-archived changes, cited + recent ADRs, and CURRENT code, and decide NON-INTERACTIVELY what is true NOW (drop work done elsewhere, adjust scope, fold in new constraints). That judgment is yours; the write is a transaction. **Author** a reconcile request — structured replacement text for the owned proposal sections and still-mutable linked-spec content, the complete desired relations (`depends_on`/`stacked_on`/`related`/`adrs`/`discovered_from`) when reality requires them, and one dated `## Reconcile log` entry — and apply it with the `change.reconcile` operation with `--input ` (the request file carries `id`, the pinned `revision`, and the authored Markdown — never a shell-escaped flag). The transaction checks the exact revision and legal `in-progress` status, sets `reconciled: true`, refreshes the claim, rerenders backlinks/`## Artifacts` block/inline board, validates the whole repository, and commits atomically on the metadata branch, pushed to the metadata remote; unknown frontmatter, unlisted authored sections, line endings, and unrelated files stay byte-identical, and a request naming a non-owned field/section is a typed refusal that writes nothing. A trivial change has no spec — patch the body only. If fresh origin state diverges incompatibly, the operation returns `contended` and writes nothing — never a text-merge; re-read fresh context and re-author. +Re-read the step-1 bundle's change + spec bytes against `related` + recently-archived changes, cited + recent ADRs, and CURRENT code, and decide NON-INTERACTIVELY what is true NOW (drop work done elsewhere, adjust scope, fold in new constraints). That judgment is yours; the write is a transaction. **Author** a reconcile request — structured replacement text for the owned proposal sections and still-mutable linked-spec content, the complete desired relations (`depends_on`/`stacked_on`/`related`/`adrs`/`discovered_from`) when reality requires them, and one dated `## Reconcile log` entry — and apply it with the `change.reconcile` operation with `--input ` (the request file carries `id`, the pinned `revision`, and the authored Markdown — never a shell-escaped flag). The transaction checks the exact revision and legal `in-progress` status, sets `reconciled: true`, refreshes the claim, rerenders backlinks/`## Artifacts` block/inline board, validates the whole repository, and commits atomically on the metadata branch, pushed to the metadata remote; unknown frontmatter, unlisted authored sections, line endings, and unrelated files stay byte-identical, and a request naming a non-owned field/section is a typed refusal that writes nothing. If fresh origin state diverges incompatibly, the operation returns `contended` and writes nothing — never a text-merge; re-read fresh context and re-author. Adjacent follow-up work this pass surfaces is **noted for the final report** — nothing is minted automatically; a human captures reported work deliberately with `docket change create`, guided by the backlog verdict final consolidation attaches (Step 6.5 *Backlog match*). @@ -77,7 +77,7 @@ The `workspace.prepare` operation reloads the authoritative snapshot, resolves t the metadata branch only receives bookkeeping commits — it NEVER determines where code branches start; the feature branch is cut from the resolved effective base (`origin/` in the ordinary case). -**Preparation (parent).** The reconciled **spec is read from the metadata working tree** (**re-sync the metadata worktree immediately before reading it**). Then run the `workspace.commit-spec` operation with `--id `: it commits the spec copy as the branch's first commit (a trivial change reports `no-spec`); a `spec-path-occupied` or `workspace-not-ready` refusal halts. Confirm the worktree is clean and record its HEAD as the **pre-dispatch HEAD**. Resolve nothing new: learnings enablement and every repo path come from the startup-check prepared context. Immediately before the long plan dispatch, **refresh the claim** — the `change.refresh-claim` operation with `--id --revision ` re-stamps `claimed_at` (only) and returns the new revision; a refresh `contended` means a newer record owns the change, so it **stops a NEW dispatch** but **never cancels** a child already running whose outcome must still be inspected. +**Preparation (parent).** The reconciled **spec is read from the metadata working tree** (**re-sync the metadata worktree immediately before reading it**). Then run the `workspace.commit-spec` operation with `--id `: it commits the spec copy as the branch's first commit; a `spec-path-occupied` or `workspace-not-ready` refusal halts. Confirm the worktree is clean and record its HEAD as the **pre-dispatch HEAD**. Resolve nothing new: learnings enablement and every repo path come from the startup-check prepared context. Immediately before the long plan dispatch, **refresh the claim** — the `change.refresh-claim` operation with `--id --revision ` re-stamps `claimed_at` (only) and returns the new revision; a refresh `contended` means a newer record owns the change, so it **stops a NEW dispatch** but **never cancels** a child already running whose outcome must still be inspected. **Plan authoring (dispatched).** The parent stays the orchestrator. @@ -113,7 +113,7 @@ It also contains the branch and base ref, change title and scope, relevant learn ### Step 6.5 — Results (required) -The results artifact is **required for every change, trivial included** — there is no skip and no close-out condition to weigh. Author `/--results.md` from `results-template.md` in a scratch file outside both worktrees; it is written on the metadata branch, never the feature branch. The path is chosen **once per change and reused on every resume** even when the authoring date has since changed (a changed date never mints a second file). Immediately after the H1 title, a **`**Human action:**` statement** says whether human action is needed — during implementation it may say the assessment is pending, but final results give a settled assessment consistent with the rest of the artifact, and the implemented boundary refuses a missing or empty statement. `## Outcome` is required; every other section is **conditional** — omit an empty heading and its subsections rather than filling it, and never write a `None`/`N/A`/`not applicable` body (whole-section filler refuses at the implemented boundary). The `docket:backlink` block above the title is owned by the `change.attach-results` operation — never hand-author its markers. +The results artifact is **required for every implemented change** — there is no skip and no close-out condition to weigh. Author `/--results.md` from `results-template.md` in a scratch file outside both worktrees; it is written on the metadata branch, never the feature branch. The path is chosen **once per change and reused on every resume** even when the authoring date has since changed (a changed date never mints a second file). Immediately after the H1 title, a **`**Human action:**` statement** says whether human action is needed — during implementation it may say the assessment is pending, but final results give a settled assessment consistent with the rest of the artifact, and the implemented boundary refuses a missing or empty statement. `## Outcome` is required; every other section is **conditional** — omit an empty heading and its subsections rather than filling it, and never write a `None`/`N/A`/`not applicable` body (whole-section filler refuses at the implemented boundary). The `docket:backlink` block above the title is owned by the `change.attach-results` operation — never hand-author its markers. **Human actions and testing** labels every item **Important** or **Optional**, written for a mid-level engineer with little knowledge of Docket internals. An **Important** item marks a meaningful verification gap or necessary human judgment (never a new automated merge requirement) — give the reason, when the action matters, and what remains uncertain if skipped. An Optional walkthrough MAY exercise behavior automated tests already cover — a routine suite rerun is not a functional walkthrough. Every item carries prerequisites and setup, concrete steps with observable expected results, and cleanup when it changes persistent state — complete enough to run without reconstructing missing commands. Do not infer coverage from a green suite: inspect the relevant tests and evidence, and where coverage is genuinely uncertain report that uncertainty under Known issues and follow-ups or Verification performed rather than authoring a speculative checklist. The section holds only what a human should do or check — never a record of what the run already checked, which belongs under Verification performed. @@ -146,7 +146,7 @@ The results artifact is **required for every change, trivial included** — ther **Leak check (private repositories).** `workspace.publish` and `pr.publish` refuse `leak-detected` (`blocked`) when anything they would expose carries a docket fingerprint; the result's `leaks` list names each hit (source, commit, file, line, rule, matched text). Nothing was pushed or opened. End the run `halted`: write the hit list into the `change.halt` report — never reword, amend, rebase, or force-push to get past it, and never retry. `leak-check-unverified` (`external-failed`) means the check could not run; treat it as any external failure. `metadata-on-shared-remote` warnings go in the run report only. -**Mark implemented.** The `change.mark-implemented` operation with `--id --revision --head --pr --evidence ` is the final mutation in this scope. Before its transaction it reprobes Git and GitHub and proves: the change is still the exact `in-progress` revision, `reconciled: true`, linked to the verified plan; local and remote feature heads equal the supplied head; valid evidence names that head and a passed gate; exactly one verified PR for the feature branch targets the resolved effective-base branch and names that head; and a results artifact is attached, read from the metadata branch, and satisfies the final content contract and its artifact identity (missing, invalid, or unattached results — trivial changes included — refuse the transition). It then applies the landed transition atomically — `status: implemented` + `pr:` + updated date + the verified evidence as the record's `## Build evidence` section + `## Artifacts` block + inline board + audit receipt (letting the sweep read `pr:`), rendering the board inside that transaction, so no separate Board pass runs. It does NOT clear the claim, delete the branch/workspace, merge, archive, or close descendants. A retry against an already-`implemented` change with matching PR/head returns the prior applied outcome, never a duplicate transition. +**Mark implemented.** The `change.mark-implemented` operation with `--id --revision --head --pr --evidence ` is the final mutation in this scope. Before its transaction it reprobes Git and GitHub and proves: the change is still the exact `in-progress` revision, `reconciled: true`, linked to the verified plan; local and remote feature heads equal the supplied head; valid evidence names that head and a passed gate; exactly one verified PR for the feature branch targets the resolved effective-base branch and names that head; and a results artifact is attached, read from the metadata branch, and satisfies the final content contract and its artifact identity (missing, invalid, or unattached results refuse the transition). It then applies the landed transition atomically — `status: implemented` + `pr:` + updated date + the verified evidence as the record's `## Build evidence` section + `## Artifacts` block + inline board + audit receipt (letting the sweep read `pr:`), rendering the board inside that transaction, so no separate Board pass runs. It does NOT clear the claim, delete the branch/workspace, merge, archive, or close descendants. A retry against an already-`implemented` change with matching PR/head returns the prior applied outcome, never a duplicate transition. **Verify the run.** The `run.verify` operation with `--id ` is read-only: it reports one closed verdict — `run-complete` / `run-unclaimed` / `run-incomplete` / `run-halted` / `run-waiting` — and enumerates every unmet condition with its stable reason and observed identity. Automation keys on the typed verdict, **never** the exit code (all verdicts exit 0). `run-complete` is the receipt that Step 7's postcondition (or the results-artifact ending's) holds; `run-halted` is the closed verdict for a change carrying a `## Run halted` marker — a human is needed, and an attributed caller re-dispatches it through the resume path (the `change.resume-halted` operation with `--acknowledge-quiescent`, Step 2), never a fresh claim. `run-waiting ` is the closed verdict for a change whose gate stopped at a safe, resumable continuation — neither complete nor failed: an attributed caller resumes that exact handoff rather than drawing another change or re-dispatching a fresh run, and precedence is completed-run postconditions first, then a valid `run-waiting`, then ordinary `run-incomplete`; a persisted `run-halted` stays terminal. A run **dispatched with an explicit change id, continuation id, and run key resumes, not restarts**: its FIRST act is the `run.continue` operation with ` `, claiming the recovered drive **before any other work**; it never launches a replacement test, and this is a **continuation, not `run-retry-once`** — the key stays active until a true terminal disposition. Each `run-retry-once` authorizes exactly one next dispatch; the run tracker may grant another on a later eligible attempt while the configured `run.max_attempts` budget allows, and a continuation consumes none of that budget. A gated parent's prompt may also carry a **run context** token; pass it, always as `--run-context`, into every build-owned `gate.drive.start` (`--owner build` — Step 6's evidence re-mint and re-gates, the build role's final suite gate, and each post-repair attempt the build role starts) this run performs — each invoked with `--json` per the shared capture requirement and each always carrying `--change-id ` — and into the Step-2 claim, omitting it only when the prompt carried none (a `run-untracked` or ungated run). Build-task workers never receive it: they run their tests directly and call no gate operation. @@ -160,7 +160,7 @@ Each step below is complete only when its row holds — read from **git**, never |---|---| | 2 Claim | `status: in-progress` + `branch:` + `updated:` + `claimed_at:` committed on the metadata branch **and landed** (local tip == remote tip). | | 3 Reconcile | `reconciled: true` and a dated `## Reconcile log` entry landed on the metadata branch — or, on the kill path, the change archived. | -| 4 Worktree + plan | Step 3's push SHA-confirmed **before** the branch is cut; then the spec copy committed as the first commit on `/` (non-trivial changes), then `plan:` and the plan file with its backlink landed on the metadata branch, the feature HEAD unchanged by planning. | +| 4 Worktree + plan | Step 3's push SHA-confirmed **before** the branch is cut; then the spec copy committed as the first commit on `/`, then `plan:` and the plan file with its backlink landed on the metadata branch, the feature HEAD unchanged by planning. | | 5 Build | the executed plan committed on `/`, with a build-evidence record at `result: green` (or `skipped` / `build-gate-off` under `build.gate: off`) whose `head_sha` **equals branch HEAD**. | | 6 Review + ADRs | that record still present at `head_sha` == HEAD **after** any fix commits, and every ADR the run produced landed in `adrs:`. Known-weak row: on a clean review this reduces to Step 5's, because whether a reviewer ran is not a fact about git. | | 7 PR + stop | the branch pushed (`origin//` resolves), the PR open, and `status: implemented` + `pr:` landed on the metadata branch; `results:` set and the final results file with its backlink on the metadata branch, and the record's `## Build evidence` section naming the PR head. | @@ -201,7 +201,7 @@ A change is drafted against a *snapshot* of the codebase, ADRs, and other in-fli `reconciled: false` at birth; set to `true` only after the reconcile pass completes and commits. It is **(1) an audit signal** — paired with the dated `## Reconcile log` entry, it proves the change was freshened against current reality; **(2) a resume-safety guard** — on any resume of an `in-progress` change, **read `references/edge-paths.md` now (blocking)** for the resume rules. -`reconciled` is **NOT a selection criterion** — build-readiness is `spec:`-or-`trivial: true` plus satisfied `depends_on`; a change sitting at `reconciled: false` is still build-ready, and reconcile happens in step 3, after selection and claim. +`reconciled` is **NOT a selection criterion** — build-readiness is `spec:` plus satisfied `depends_on`; a change sitting at `reconciled: false` is still build-ready, and reconcile happens in step 3, after selection and claim. ## Branch & metadata discipline diff --git a/internal/assets/embedded/tree/skills/docket-implement-next/references/results-artifact.md b/internal/assets/embedded/tree/skills/docket-implement-next/references/results-artifact.md index e7c316b10..0ff999f80 100644 --- a/internal/assets/embedded/tree/skills/docket-implement-next/references/results-artifact.md +++ b/internal/assets/embedded/tree/skills/docket-implement-next/references/results-artifact.md @@ -11,7 +11,7 @@ skill. No plan, no build, no PR. Skip `workspace.commit-spec` — the branch must keep no commits of its own, or cleanup keeps it — plus the plan-writer dispatch, the build role, the build gate, evidence records, the branch diff review, `workspace.publish`, `pr.publish`, and `change.mark-implemented` -(it refuses a `results-artifact` change). The spec, or a trivial change's body, is the plan. +(it refuses a `results-artifact` change). The spec is the plan. **Refresh the claim** (the `change.refresh-claim` operation, at a revision re-read after a re-sync) at each phase boundary below, as the `pr` path does: before the work, before review, and before @@ -52,7 +52,7 @@ so everything it reads travels inline. Dispatch `docket-review-standard` foreground — the default tier when there is no build record — and tell it to review in its results-artifact mode, then stop. Its dispatch payload contains: Feature worktree: -It also contains, inline, the spec body (or the trivial change's body), the results artifact's text, the change title and scope, and the relevant learnings hooks. When the `docket-review` skill is missing, apply the convention's missing-skill rule: review the results inline against the same checks, warning prominently, and dispatch no reviewer. An undispatchable review tier — established only per the convention's *Dispatch-capability resolution* — makes the run **`halt`**. +It also contains, inline, the spec body, the results artifact's text, the change title and scope, and the relevant learnings hooks. When the `docket-review` skill is missing, apply the convention's missing-skill rule: review the results inline against the same checks, warning prominently, and dispatch no reviewer. An undispatchable review tier — established only per the convention's *Dispatch-capability resolution* — makes the run **`halt`**. ## 5. Fix pass diff --git a/internal/assets/embedded/tree/skills/docket-implement-next/results-template.md b/internal/assets/embedded/tree/skills/docket-implement-next/results-template.md index 57069d009..11070f1d1 100644 --- a/internal/assets/embedded/tree/skills/docket-implement-next/results-template.md +++ b/internal/assets/embedded/tree/skills/docket-implement-next/results-template.md @@ -1,5 +1,5 @@ - **Plan authoring (dispatched).** The parent stays the orchestrator. @@ -113,7 +113,7 @@ It also contains the branch and base ref, change title and scope, relevant learn ### Step 6.5 — Results (required) -The results artifact is **required for every change, trivial included** — there is no skip and no close-out condition to weigh. Author `/--results.md` from `results-template.md` in a scratch file outside both worktrees; it is written on the metadata branch, never the feature branch. The path is chosen **once per change and reused on every resume** even when the authoring date has since changed (a changed date never mints a second file). Immediately after the H1 title, a **`**Human action:**` statement** says whether human action is needed — during implementation it may say the assessment is pending, but final results give a settled assessment consistent with the rest of the artifact, and the implemented boundary refuses a missing or empty statement. `## Outcome` is required; every other section is **conditional** — omit an empty heading and its subsections rather than filling it, and never write a `None`/`N/A`/`not applicable` body (whole-section filler refuses at the implemented boundary). The `docket:backlink` block above the title is owned by the `change.attach-results` operation — never hand-author its markers. +The results artifact is **required for every implemented change** — there is no skip and no close-out condition to weigh. Author `/--results.md` from `results-template.md` in a scratch file outside both worktrees; it is written on the metadata branch, never the feature branch. The path is chosen **once per change and reused on every resume** even when the authoring date has since changed (a changed date never mints a second file). Immediately after the H1 title, a **`**Human action:**` statement** says whether human action is needed — during implementation it may say the assessment is pending, but final results give a settled assessment consistent with the rest of the artifact, and the implemented boundary refuses a missing or empty statement. `## Outcome` is required; every other section is **conditional** — omit an empty heading and its subsections rather than filling it, and never write a `None`/`N/A`/`not applicable` body (whole-section filler refuses at the implemented boundary). The `docket:backlink` block above the title is owned by the `change.attach-results` operation — never hand-author its markers. **Human actions and testing** labels every item **Important** or **Optional**, written for a mid-level engineer with little knowledge of Docket internals. An **Important** item marks a meaningful verification gap or necessary human judgment (never a new automated merge requirement) — give the reason, when the action matters, and what remains uncertain if skipped. An Optional walkthrough MAY exercise behavior automated tests already cover — a routine suite rerun is not a functional walkthrough. Every item carries prerequisites and setup, concrete steps with observable expected results, and cleanup when it changes persistent state — complete enough to run without reconstructing missing commands. Do not infer coverage from a green suite: inspect the relevant tests and evidence, and where coverage is genuinely uncertain report that uncertainty under Known issues and follow-ups or Verification performed rather than authoring a speculative checklist. The section holds only what a human should do or check — never a record of what the run already checked, which belongs under Verification performed. @@ -146,7 +146,7 @@ The results artifact is **required for every change, trivial included** — ther **Leak check (private repositories).** `workspace.publish` and `pr.publish` refuse `leak-detected` (`blocked`) when anything they would expose carries a docket fingerprint; the result's `leaks` list names each hit (source, commit, file, line, rule, matched text). Nothing was pushed or opened. End the run `halted`: write the hit list into the `change.halt` report — never reword, amend, rebase, or force-push to get past it, and never retry. `leak-check-unverified` (`external-failed`) means the check could not run; treat it as any external failure. `metadata-on-shared-remote` warnings go in the run report only. -**Mark implemented.** The `change.mark-implemented` operation with `--id --revision --head --pr --evidence ` is the final mutation in this scope. Before its transaction it reprobes Git and GitHub and proves: the change is still the exact `in-progress` revision, `reconciled: true`, linked to the verified plan; local and remote feature heads equal the supplied head; valid evidence names that head and a passed gate; exactly one verified PR for the feature branch targets the resolved effective-base branch and names that head; and a results artifact is attached, read from the metadata branch, and satisfies the final content contract and its artifact identity (missing, invalid, or unattached results — trivial changes included — refuse the transition). It then applies the landed transition atomically — `status: implemented` + `pr:` + updated date + the verified evidence as the record's `## Build evidence` section + `## Artifacts` block + inline board + audit receipt (letting the sweep read `pr:`), rendering the board inside that transaction, so no separate Board pass runs. It does NOT clear the claim, delete the branch/workspace, merge, archive, or close descendants. A retry against an already-`implemented` change with matching PR/head returns the prior applied outcome, never a duplicate transition. +**Mark implemented.** The `change.mark-implemented` operation with `--id --revision --head --pr --evidence ` is the final mutation in this scope. Before its transaction it reprobes Git and GitHub and proves: the change is still the exact `in-progress` revision, `reconciled: true`, linked to the verified plan; local and remote feature heads equal the supplied head; valid evidence names that head and a passed gate; exactly one verified PR for the feature branch targets the resolved effective-base branch and names that head; and a results artifact is attached, read from the metadata branch, and satisfies the final content contract and its artifact identity (missing, invalid, or unattached results refuse the transition). It then applies the landed transition atomically — `status: implemented` + `pr:` + updated date + the verified evidence as the record's `## Build evidence` section + `## Artifacts` block + inline board + audit receipt (letting the sweep read `pr:`), rendering the board inside that transaction, so no separate Board pass runs. It does NOT clear the claim, delete the branch/workspace, merge, archive, or close descendants. A retry against an already-`implemented` change with matching PR/head returns the prior applied outcome, never a duplicate transition. **Verify the run.** The `run.verify` operation with `--id ` is read-only: it reports one closed verdict — `run-complete` / `run-unclaimed` / `run-incomplete` / `run-halted` / `run-waiting` — and enumerates every unmet condition with its stable reason and observed identity. Automation keys on the typed verdict, **never** the exit code (all verdicts exit 0). `run-complete` is the receipt that Step 7's postcondition (or the results-artifact ending's) holds; `run-halted` is the closed verdict for a change carrying a `## Run halted` marker — a human is needed, and an attributed caller re-dispatches it through the resume path (the `change.resume-halted` operation with `--acknowledge-quiescent`, Step 2), never a fresh claim. `run-waiting ` is the closed verdict for a change whose gate stopped at a safe, resumable continuation — neither complete nor failed: an attributed caller resumes that exact handoff rather than drawing another change or re-dispatching a fresh run, and precedence is completed-run postconditions first, then a valid `run-waiting`, then ordinary `run-incomplete`; a persisted `run-halted` stays terminal. A run **dispatched with an explicit change id, continuation id, and run key resumes, not restarts**: its FIRST act is the `run.continue` operation with ` `, claiming the recovered drive **before any other work**; it never launches a replacement test, and this is a **continuation, not `run-retry-once`** — the key stays active until a true terminal disposition. Each `run-retry-once` authorizes exactly one next dispatch; the run tracker may grant another on a later eligible attempt while the configured `run.max_attempts` budget allows, and a continuation consumes none of that budget. A gated parent's prompt may also carry a **run context** token; pass it, always as `--run-context`, into every build-owned `gate.drive.start` (`--owner build` — Step 6's evidence re-mint and re-gates, the build role's final suite gate, and each post-repair attempt the build role starts) this run performs — each invoked with `--json` per the shared capture requirement and each always carrying `--change-id ` — and into the Step-2 claim, omitting it only when the prompt carried none (a `run-untracked` or ungated run). Build-task workers never receive it: they run their tests directly and call no gate operation. @@ -160,7 +160,7 @@ Each step below is complete only when its row holds — read from **git**, never |---|---| | 2 Claim | `status: in-progress` + `branch:` + `updated:` + `claimed_at:` committed on the metadata branch **and landed** (local tip == remote tip). | | 3 Reconcile | `reconciled: true` and a dated `## Reconcile log` entry landed on the metadata branch — or, on the kill path, the change archived. | -| 4 Worktree + plan | Step 3's push SHA-confirmed **before** the branch is cut; then the spec copy committed as the first commit on `/` (non-trivial changes), then `plan:` and the plan file with its backlink landed on the metadata branch, the feature HEAD unchanged by planning. | +| 4 Worktree + plan | Step 3's push SHA-confirmed **before** the branch is cut; then the spec copy committed as the first commit on `/`, then `plan:` and the plan file with its backlink landed on the metadata branch, the feature HEAD unchanged by planning. | | 5 Build | the executed plan committed on `/`, with a build-evidence record at `result: green` (or `skipped` / `build-gate-off` under `build.gate: off`) whose `head_sha` **equals branch HEAD**. | | 6 Review + ADRs | that record still present at `head_sha` == HEAD **after** any fix commits, and every ADR the run produced landed in `adrs:`. Known-weak row: on a clean review this reduces to Step 5's, because whether a reviewer ran is not a fact about git. | | 7 PR + stop | the branch pushed (`origin//` resolves), the PR open, and `status: implemented` + `pr:` landed on the metadata branch; `results:` set and the final results file with its backlink on the metadata branch, and the record's `## Build evidence` section naming the PR head. | @@ -201,7 +201,7 @@ A change is drafted against a *snapshot* of the codebase, ADRs, and other in-fli `reconciled: false` at birth; set to `true` only after the reconcile pass completes and commits. It is **(1) an audit signal** — paired with the dated `## Reconcile log` entry, it proves the change was freshened against current reality; **(2) a resume-safety guard** — on any resume of an `in-progress` change, **read `references/edge-paths.md` now (blocking)** for the resume rules. -`reconciled` is **NOT a selection criterion** — build-readiness is `spec:`-or-`trivial: true` plus satisfied `depends_on`; a change sitting at `reconciled: false` is still build-ready, and reconcile happens in step 3, after selection and claim. +`reconciled` is **NOT a selection criterion** — build-readiness is `spec:` plus satisfied `depends_on`; a change sitting at `reconciled: false` is still build-ready, and reconcile happens in step 3, after selection and claim. ## Branch & metadata discipline diff --git a/skills/docket-implement-next/references/results-artifact.md b/skills/docket-implement-next/references/results-artifact.md index e7c316b10..0ff999f80 100644 --- a/skills/docket-implement-next/references/results-artifact.md +++ b/skills/docket-implement-next/references/results-artifact.md @@ -11,7 +11,7 @@ skill. No plan, no build, no PR. Skip `workspace.commit-spec` — the branch must keep no commits of its own, or cleanup keeps it — plus the plan-writer dispatch, the build role, the build gate, evidence records, the branch diff review, `workspace.publish`, `pr.publish`, and `change.mark-implemented` -(it refuses a `results-artifact` change). The spec, or a trivial change's body, is the plan. +(it refuses a `results-artifact` change). The spec is the plan. **Refresh the claim** (the `change.refresh-claim` operation, at a revision re-read after a re-sync) at each phase boundary below, as the `pr` path does: before the work, before review, and before @@ -52,7 +52,7 @@ so everything it reads travels inline. Dispatch `docket-review-standard` foreground — the default tier when there is no build record — and tell it to review in its results-artifact mode, then stop. Its dispatch payload contains: Feature worktree: -It also contains, inline, the spec body (or the trivial change's body), the results artifact's text, the change title and scope, and the relevant learnings hooks. When the `docket-review` skill is missing, apply the convention's missing-skill rule: review the results inline against the same checks, warning prominently, and dispatch no reviewer. An undispatchable review tier — established only per the convention's *Dispatch-capability resolution* — makes the run **`halt`**. +It also contains, inline, the spec body, the results artifact's text, the change title and scope, and the relevant learnings hooks. When the `docket-review` skill is missing, apply the convention's missing-skill rule: review the results inline against the same checks, warning prominently, and dispatch no reviewer. An undispatchable review tier — established only per the convention's *Dispatch-capability resolution* — makes the run **`halt`**. ## 5. Fix pass diff --git a/skills/docket-implement-next/results-template.md b/skills/docket-implement-next/results-template.md index 57069d009..11070f1d1 100644 --- a/skills/docket-implement-next/results-template.md +++ b/skills/docket-implement-next/results-template.md @@ -1,5 +1,5 @@ -