From 7fa402ad15756724f957371a08e6fa6cd4e6a8ab Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Sun, 18 Oct 2026 22:29:01 -0400 Subject: [PATCH 01/10] Add design spec: Put a groomed change on hold so loops skip it --- ...-off-limits-to-the-autonomous-lo-design.md | 172 ++++++++++++++++++ 1 file changed, 172 insertions(+) create mode 100644 docs/superpowers/specs/2026-10-18-mark-a-build-ready-change-as-off-limits-to-the-autonomous-lo-design.md diff --git a/docs/superpowers/specs/2026-10-18-mark-a-build-ready-change-as-off-limits-to-the-autonomous-lo-design.md b/docs/superpowers/specs/2026-10-18-mark-a-build-ready-change-as-off-limits-to-the-autonomous-lo-design.md new file mode 100644 index 000000000..5a8111e70 --- /dev/null +++ b/docs/superpowers/specs/2026-10-18-mark-a-build-ready-change-as-off-limits-to-the-autonomous-lo-design.md @@ -0,0 +1,172 @@ +# Put a groomed change on hold so loops skip it — design + +Change 0560 — Put a groomed change on hold so loops skip it + +Change #560, groomed 2026-10-18. + +## Why + +A groomed change is build-ready: it has a spec or `trivial: true`, and its dependencies are done. Every build-ready change looks alike to an autonomous loop draining the backlog. That is wrong for two kinds of change: + +- A change that needs a person for some step: signing in somewhere, a manual check, a decision only the person can make. A loop claims it, works until it reaches that step, and halts. A halt stops the loop, so one such change ends the whole drain. +- A change the person has groomed but does not want built yet, for any reason. + +Today the only ways to keep a groomed change away from the loop are to leave it ungroomed on purpose (#547 does this) or to defer it. Deferring shelves the change: grooming can no longer revise it, and even a run that names its id refuses it until someone revives it. #559 settled for a stop-gap: whoever starts a loop lists ids and checks that none of them needs a human. + +## Goals + +- A person can put a **hold** on a change. While the hold is on, no autonomous build selection picks the change: neither a drain over the whole backlog nor a drain over a list of ids, even when the list names it. +- A run that names exactly that one change builds it. Naming a single change is the deliberate act that overrides the hold. +- The hold is generic. It records no required reason. An optional reason can be added as prose when the hold is set. +- Grooming can set and lift the hold from day one, and so can capturing a new change. +- When grooming settles on a spec that needs manual work, docket suggests a hold. The auto-groomer, which has no one to ask, sets the hold itself. +- The board keeps a held change that has a spec in the Groomed table, marked `on hold`. Every groomed row states its readiness. + +## Non-goals + +- **Grooming is unaffected.** A hold does not keep a stub out of `docket-groom-next`'s automatic pick or `docket-auto-groom`'s queue. Grooming already has its own controls: `auto_groomable` opts a stub in or out of autonomous grooming, and groom-next runs with the person present. A hold on a stub is allowed. It takes effect once the stub is groomed. +- **Finalize is unaffected.** A held change that a named run built lands like any other. +- **Carrying on past a halt is a separate change** (#570). Every `halted` disposition still stops the driver. +- **No change to how a run behaves at a human step.** #559 settled that: the run does the work it can and halts at the step. +- The reason is not shown on the board. + +## Design + +### 1. The field + +A new optional frontmatter field, `hold`. `hold: true` puts the change on hold; absent, empty, or `false` means no hold. + +- **Writer.** `render.NewChangeRecord` gains the field, written directly after `auto_groomable` in the manifest order. Update the record golden file. +- **Decode.** Decode it with the same `optionalBool` path as `auto_groomable`, so a bad value raises the existing malformed-field warning, never an error. One difference, on purpose: a malformed `hold` value **reads as held**. The field exists to keep work away from the loop, so a garbled hand edit must fail safe (the change waits) rather than open (the loop builds it). The accessor is true when the value is `true` or malformed. Update the `optionalBool` comment, which says `auto_groomable` is the only optional boolean. +- The field is human input. Two agent writes are allowed: the auto-groomer setting it (section 5), and any operation that carries the record forward unchanged. + +### 2. What a hold does + +The hold is a **selection-only exclusion**. It must not make the change "not ready" in the sense the claim checks, or the named single-id run would be refused too. + +- **Readiness.** `domain.EvaluateReadiness` gains one last step. A change that would otherwise be `build-ready` and is held reads as a new readiness kind, `on-hold`. Every earlier outcome wins: a held stub still reads `needs-grooming` (or `auto-groom-blocked`), a held change with an unmet dependency still reads `waiting-dependency`, and a held change with an unresolved stack base still reads `stack-base-unresolved`. Add the kind to `domain.ReadinessKind`'s closed set and to the function's documented check order. +- **Selection.** `domain.SelectQueue` is unchanged: it keeps only `build-ready`, so a held change drops out of + - the `status` operation's top-level `ready` array, + - `context.implementation` with no `--id`, and + - implement-next's id-allowlist drain, which filters that same `ready` array in skill prose. +- **Claim eligibility.** `domain.ClaimEligibility` treats `on-hold` as eligible, exactly like `build-ready`. So `context.implementation --id`, `change.claim`, and `change.complete` on a `proposed` results-artifact change all accept a held change. The claim leaves the field in place. A change reclaimed back to `proposed` is still held, which is what the person asked for. +- **Status rows.** A held row reports `readiness: on-hold`, `ready: false`, and a `readiness_reason` of "on hold" (`app.readinessReason`). +- **Board.** A held change that has a spec stays in the Groomed table, marked `on hold`. Unlike a change waiting on a dependency, it can still be built by naming it, so it belongs with the groomed changes. + - `render.boardClassify` puts a spec-backed `proposed` change in Groomed when its readiness is `build-ready` or `on-hold`. + - The Groomed table gains a last column, Readiness. Every row states its readiness: exactly `build-ready` or exactly `on hold`. No row is left blank, because a blank cell beside rows that carry a status would leave the reader to guess a default. `on hold` names the state the change is in, not the action of holding it. + - A held trivial change has no spec, so it stays in the Proposed table as every trivial change does today. `render.boardReadinessCell` renders its cell as `on hold` instead of `build-ready (trivial)`. + - Update the column layouts in the `render` package comment, the board golden file, and the golden's `PROVENANCE.md`. +- **In progress table (sibling fix).** Its Readiness column shows the run's state (`run halted — needs you`), not readiness, so rename it State, as the Built table's column is named. A halted row still reads `run halted — needs you`. Every other row, blank today, reads exactly `building`, so no row is left blank. Rename `render.boardInProgressReadinessCell` to `boardInProgressStateCell`, matching `boardBuiltStateCell`, and update `boardSectionTableHeader`, the package comment, the header assertion in `board_test.go`, the board golden file, and `PROVENANCE.md`. +- **Everything else** that keys on readiness: dependents of a held change wait until it is done, and a change stacked on a held parent waits for the stack base as it would for any unbuilt parent. Neither needs code. Grep every switch over `ReadinessKind` (today `app.readinessReason` and `render.boardReadinessCell`, plus the equality checks in `SelectQueue`, `ClaimEligibility`, and `boardClassify`), and confirm each one handles `on-hold` deliberately. + +### 3. Setting and lifting a hold + +**`change.groom`** gains two request keys: + +- `hold` (bool). Omitted keeps the current value, `true` sets the hold, and `false` lifts it. It is accepted on the `spec`, `trivial`, `revise`, and `re-enable` outcomes, like `deliverable`. A `hold` alone is a valid revise, so it counts toward the empty-revise check. The `abstain` outcome refuses it with a new `invalid-hold` code, as it refuses `deliverable`. +- `hold_reason` (string, optional). It is accepted only together with `hold: true` in the same request. Otherwise the request is refused with a new `hold-reason-without-hold` code and nothing is written. + +The reason lives in an operation-owned body section, `## Why on hold`, modelled on `## Why deferred`: + +- `hold: true` with `hold_reason` writes the section, replacing any existing one. +- `hold: true` without `hold_reason` leaves any existing section alone. +- `hold: false` removes the section, so a stale reason never outlives the hold. Git history keeps it. +- The hold keys are the section's only writer. Do not add it to `render.ChangeOwnedHeadings`. A `sections` edit naming `## Why on hold` is refused with `invalid-section-heading` on **every** groom outcome, and the same applies to a `change.reconcile` edit. Today `## Auto-groom blocked` is refused only on revise and re-enable, so this is deliberately wider. +- `hold_reason` gets the same shape checks as `blocked_note`: no column-zero `## ` heading outside fenced code, and no unterminated fence. +- Place the section where `## Why deferred` goes. + +**`change.create`** gains the same `hold` and `hold_reason` keys with the same rules, so a person can capture a change already on hold. + +A hold is set only on a `proposed` change. Revise already refuses other statuses (`not-revisable`), and a deferred change is revived first. Setting or lifting a hold never changes the groom state. As every groom write does, it re-renders the board and the `## Artifacts` block in the same commit. Register both keys in the `docket schema` descriptors, register the new codes in `AllFindingCodes`, and update `internal/app/schema_test.go`. + +### 4. implement-next + +No reference file is needed. The skip happens in the binary, so the skill only learns the new word: + +- Step 1's readiness vocabulary list adds `on-hold`. The list also omits `stack-base-unresolved` and `invalid` today, so add those while editing the line. +- The id-allowlist paragraph and the final report's skip list name "on hold" as a skip reason. +- The named-invocation paragraph says a held change is built when named. +- A hold can be set between the `status` read and the `context.implementation --id` read. On the selection path (no argument, or an id set), a bundle reporting `on-hold` is dropped and reported, like any other bundle that disagrees with the digest. A hold set after that read is already caught: the claim's revision check returns `contended`. + +The terminal dispositions and the driver rule are unchanged. + +### 5. Suggesting a hold during grooming + +- **`docket-groom-next`** (Step 3 or 4): when the settled design needs manual work, meaning a step a person must carry out, suggest a hold before the spec or trivial exit. The person decides. If they agree, send `hold: true` and an optional `hold_reason` in the same `change.groom` request. Step 4 gets a short **Hold** paragraph beside *Deliverable, type, and branch prefix*, covering setting and lifting on the spec, trivial, revise, and re-enable exits. +- **`docket-new-change`**: the same suggestion at its brainstorm and trivial exits. The hold rides in step 5's `change.groom` request, or in `change.create` for a captured stub. +- **`docket-auto-groom`**: when the spec or trivial verdict it emits names a step a person must carry out, send `hold: true` in its groom request, and say so in its run report. It adds a one-line `hold_reason` only when the stub has no `## Why on hold` section yet, so it never overwrites a person's reason. It never sends `hold: false`: lifting a hold is a person's call. The critic is unchanged. +- **`docket-convention`**: + - the manifest template gains `hold:` with a one-line comment; + - *Build-readiness & selection* says a held build-ready change is never selected, and that naming it builds it; + - *Change body sections* lists `## Why on hold`; + - *Autonomous grooming* notes the auto-groomer's hold write. + +Keep each addition short. Agent-read skill prose is paid on every run. Regenerate the embedded skill copies (`go generate ./internal/assets/`) and adjust `internal/repoguard/budgets_test.go` if a budget moves. + +### 6. Decision record + +Record an ADR: **a hold keeps a groomed change out of autonomous build selection, and naming the change overrides it.** It should state: + +- **Context.** ADR-0006's equivalence, that build-ready means the autonomous builder will build it, no longer holds for a held change. +- **Decision.** The hold is a selection-only exclusion, never a claim refusal. Any single-id act (a named run, a claim, completing the change) overrides it. It does not touch grooming or finalize. The auto-groomer sets it for specs that need manual work. A malformed value reads as held. +- **Alternatives rejected:** + - Deferring: it blocks named runs and grooming revisions. + - A readiness gate on the claim: it would refuse the named run. + - Letting the hold also gate grooming picks: more places change, and it duplicates `auto_groomable`. + - Carrying on past halts instead: that is #570, and it needs a typed halt reason. + +### 7. Docs + +Describe current behavior only, with no change citations: + +- `docs/guide/building-without-supervision.md`: the drain section says a held change is skipped and is built when named. +- `docs/guide/capturing-work.md`: grooming can put a change on hold. +- `docs/reference/glossary.md`: a **Hold** entry. +- `docs/reference/cli.md`: the new `change groom` and `change create` request keys. +- Any board doc that lists Readiness cell values. + +Grep for other pages that enumerate readiness values or groom request keys. + +## Tests + +Mutation-test each new guard: strip the behavior and watch the test go red. + +1. **Readiness.** + - A held build-ready change reads `on-hold`. + - A held stub reads `needs-grooming`, and a held stub with `## Auto-groom blocked` reads `auto-groom-blocked`. + - A held change with an unmet dependency reads `waiting-dependency`. + - A held change with an unresolved stack base reads `stack-base-unresolved`. + - `hold: false` and an absent field read `build-ready`. + - A malformed value reads `on-hold` and raises the malformed-field warning. +2. **Selection and claim.** + - `SelectQueue` excludes a held change. + - `ClaimEligibility` accepts `on-hold`. + - `status --json` leaves it out of `ready` and reports the row as `on-hold`, "on hold", `ready: false`. + - `context.implementation` with no id skips it: it picks the next ready change, or returns `no-candidate` when the held change is the only one. + - `context.implementation --id` and `change.claim` accept it, and the claim keeps the field. + - `change.complete` accepts a held `proposed` results-artifact change. +3. **Board.** + - A held spec-backed change renders in the Groomed table with Readiness `on hold`. + - An unheld spec-backed build-ready change renders in the Groomed table with Readiness `build-ready`; no Groomed row has an empty Readiness cell. + - A held trivial change renders in the Proposed table with `on hold`. + - The In progress table's header names the last column State. A halted row reads `run halted — needs you`, and every other row reads `building`; no In progress row has an empty State cell. + - No record fault. +4. **`change.groom`.** + - Set with and without a reason. Replace a reason. Lift, which removes the section. + - An omitted `hold` keeps both the field and the section. + - A `hold` alone is a valid revise. + - Each accepting outcome (spec, trivial, revise, re-enable) writes the field. + - Refusals that write nothing: + - abstain with `hold` (`invalid-hold`); + - `hold_reason` without `hold: true` (`hold-reason-without-hold`); + - a `sections` edit naming `## Why on hold` (`invalid-section-heading`); + - a `hold_reason` carrying a column-zero heading or an unterminated fence. +5. **`change.create`.** Hold with and without a reason; reason-without-hold refuses. +6. **Writer.** The record golden file shows `hold` directly after `auto_groomable`. +7. **Schema.** `docket schema` lists both keys on both operations, and the new codes are registered. + +## Left to the builder + +- The exact spellings of the readiness token (`on-hold` suggested) and the two finding codes. +- How a malformed value surfaces in `status` beyond the existing warning. +- The exact wording of the skill and doc additions, within the limits above. From f3b6caf1e640d9586f6b5afaef11df59f206575a Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Sun, 18 Oct 2026 22:40:41 -0400 Subject: [PATCH 02/10] feat(domain): a held change reads on-hold and stays claim-eligible --- internal/domain/actions.go | 10 ++++- internal/domain/actions_test.go | 48 ++++++++++++++++++++ internal/domain/entities.go | 15 +++++++ internal/domain/readiness.go | 9 +++- internal/domain/readiness_test.go | 75 +++++++++++++++++++++++++++++++ internal/domain/selection.go | 4 +- internal/domain/selection_test.go | 26 +++++++++++ internal/domain/types_test.go | 14 ++++++ 8 files changed, 196 insertions(+), 5 deletions(-) diff --git a/internal/domain/actions.go b/internal/domain/actions.go index a6e4b6f25..3fb3b121e 100644 --- a/internal/domain/actions.go +++ b/internal/domain/actions.go @@ -100,7 +100,10 @@ type DoneFacts struct { // A caller that claims without calling it claims a change with unmet // dependencies, no design, or an unresolved stack base. // -// The refusal keys on EvaluateReadiness: every non-build-ready outcome becomes +// A held change (on-hold) is eligible: the hold excludes it from autonomous +// selection only, and a claim that names it overrides that. +// +// The refusal keys on EvaluateReadiness: every other non-build-ready outcome becomes // the stable reason token "not-ready-", blocked for an unmet precondition // the backlog can still satisfy and invalid-state for a record that cannot be // claimed as it stands (not proposed, or an id more than one record claims). A @@ -111,7 +114,9 @@ func ClaimEligibility(s Snapshot, c Change, facts BranchFacts) *PolicyFailure { return newFailure(c, FailInvalidInput, "unknown-change", nil) } readiness := EvaluateReadiness(s, c, facts) - if readiness.Kind == ReadyBuildReady { + // A hold is a selection-only exclusion: a single-id act names the change + // deliberately and overrides it, so on-hold is as claimable as build-ready. + if readiness.Kind == ReadyBuildReady || readiness.Kind == ReadyOnHold { return nil } kind := FailBlocked @@ -480,6 +485,7 @@ func newChangeBuilder(c Change) *changeBuilder { Results: c.Results(), Trivial: c.Trivial(), AutoGroomable: c.AutoGroomable(), + Hold: c.Hold(), BranchPrefix: c.BranchPrefix(), Branch: c.Branch(), ClaimedAt: c.ClaimedAt(), diff --git a/internal/domain/actions_test.go b/internal/domain/actions_test.go index 56bf3e3f8..93d047214 100644 --- a/internal/domain/actions_test.go +++ b/internal/domain/actions_test.go @@ -877,6 +877,54 @@ func TestClaimEligibility(t *testing.T) { } } +// A hold excludes a change from selection only; a single-id claim still builds +// it, while any earlier readiness blocker still refuses. +func TestClaimEligibilityAcceptsOnHold(t *testing.T) { + tests := []eligibilityCase{ + { + name: "a held spec-backed change is eligible", + specs: []readySpec{{id: 2, status: StatusProposed, spec: specRef("s.md"), hold: holdTrue}}, + subject: 2, + }, + { + name: "a held change on an unresolved stack base refuses the claim", + specs: []readySpec{ + {id: 1, status: StatusProposed, spec: specRef("p.md")}, + {id: 2, status: StatusProposed, spec: specRef("s.md"), parent: parentEdge(1), hold: holdTrue}, + }, + subject: 2, + wantKind: FailBlocked, + wantReason: "not-ready-stack-base-unresolved", + }, + { + name: "a held change with an unmet dependency refuses the claim", + specs: []readySpec{ + {id: 1, status: StatusProposed}, + {id: 2, status: StatusProposed, spec: specRef("s.md"), dependsOn: []ChangeID{1}, hold: holdTrue}, + }, + subject: 2, + wantKind: FailBlocked, + wantReason: "not-ready-waiting-dependency", + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + s := readySnapshot(tt.specs...) + c, _ := s.Change(tt.subject) + fail := ClaimEligibility(s, c, remotes(tt.branches...)) + if tt.wantReason == "" { + if fail != nil { + t.Fatalf("ClaimEligibility = %v; want eligible", fail) + } + return + } + if fail == nil || fail.Kind != tt.wantKind || fail.Reason != tt.wantReason { + t.Fatalf("ClaimEligibility = %v; want %s/%s", fail, tt.wantKind, tt.wantReason) + } + }) + } +} + func TestClaimEligibilityDoesNotTransition(t *testing.T) { c := NewChange(ChangeSpec{ID: 2, Slug: "a-slug", Status: StatusProposed, Type: "feat"}) s := NewSnapshot(SnapshotSpec{ diff --git a/internal/domain/entities.go b/internal/domain/entities.go index b3ac93e7d..09473faa5 100644 --- a/internal/domain/entities.go +++ b/internal/domain/entities.go @@ -93,6 +93,7 @@ type ChangeSpec struct { 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 Branch OptionalString ClaimedAt OptionalTime // second-precision UTC; Raw kept @@ -203,6 +204,20 @@ func (c Change) Trivial() bool { return c.spec.Trivial } // round-trips what the human wrote. func (c Change) AutoGroomable() OptionalBool { return c.spec.AutoGroomable } +// Hold returns the raw tri-state hold field, kept so the record writer +// round-trips what the human wrote. Callers deciding whether the change is +// held read Held. +func (c Change) Hold() OptionalBool { return c.spec.Hold } + +// Held reports whether the change is on hold: an explicit true, or a malformed +// value. A malformed value reads as held because the field exists to keep work +// away from the autonomous loop, so a garbled hand edit fails safe rather than +// releasing the change. Absent, valueless, and false all mean not held. +func (c Change) Held() bool { + h := c.spec.Hold + return h.State == FieldMalformed || (h.State == FieldPresent && h.Value) +} + // BranchPrefix returns the optional per-change mint-prefix override. It is // durable human input consumed only at claim time; once branch: is populated // it is informational and inert. diff --git a/internal/domain/readiness.go b/internal/domain/readiness.go index ebae6fdbe..8d1ae9145 100644 --- a/internal/domain/readiness.go +++ b/internal/domain/readiness.go @@ -9,6 +9,7 @@ type ReadinessKind string // The closed set of readiness outcomes. const ( ReadyBuildReady ReadinessKind = "build-ready" + ReadyOnHold ReadinessKind = "on-hold" ReadyNeedsGrooming ReadinessKind = "needs-grooming" ReadyAutoGroomBlocked ReadinessKind = "auto-groom-blocked" ReadyWaitingDependency ReadinessKind = "waiting-dependency" @@ -47,7 +48,10 @@ type Readiness struct { // 5. stack resolution is consulted ONLY for a change that would otherwise be // build-ready, and an unresolved effective base reports // stack-base-unresolved; otherwise -// 6. the change is build-ready. +// 6. the change is build-ready, unless +// 7. it is held (Change.Held): a would-be build-ready change that is held is +// 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. @@ -80,6 +84,9 @@ func EvaluateReadiness(s Snapshot, c Change, facts BranchFacts) Readiness { if base.Kind != BaseResolved { kind = ReadyStackBaseUnresolved } + if kind == ReadyBuildReady && c.Held() { + kind = ReadyOnHold + } return Readiness{Kind: kind, Dependency: deps, StackBase: base} } diff --git a/internal/domain/readiness_test.go b/internal/domain/readiness_test.go index 53550d34f..0af5d715c 100644 --- a/internal/domain/readiness_test.go +++ b/internal/domain/readiness_test.go @@ -13,8 +13,16 @@ type readySpec struct { parent OptionalInt branch string groomBlocked bool + hold OptionalBool } +// holdTrue is an explicit hold: true; holdBad is a garbled hand edit, which +// reads as held. +var ( + holdTrue = OptionalBool{State: FieldPresent, Value: true, Raw: "true"} + holdBad = OptionalBool{State: FieldMalformed, Raw: "yes"} +) + // specRef is a present, non-empty spec: reference. func specRef(path string) OptionalString { return OptionalString{State: FieldPresent, Value: path} @@ -34,6 +42,7 @@ func (rp readySpec) build() Change { Trivial: rp.trivial, DependsOn: rp.dependsOn, StackedOn: rp.parent, + Hold: rp.hold, HasAutoGroomBlocked: rp.groomBlocked, } @@ -204,6 +213,72 @@ func TestEvaluateReadinessPrecedence(t *testing.T) { subject: 2, want: ReadyBuildReady, }, + { + name: "a held spec-backed change is on-hold", + specs: []readySpec{{id: 2, status: StatusProposed, spec: specRef("s.md"), hold: holdTrue}}, + 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}}, + subject: 2, + want: ReadyNeedsGrooming, + }, + { + name: "a held auto-groom-blocked stub keeps its marker outcome", + specs: []readySpec{{id: 2, status: StatusProposed, groomBlocked: true, hold: holdTrue}}, + subject: 2, + want: ReadyAutoGroomBlocked, + }, + { + name: "a held change with an unmet dependency keeps waiting-dependency", + specs: []readySpec{ + {id: 1, status: StatusProposed}, + {id: 2, status: StatusProposed, spec: specRef("s.md"), dependsOn: []ChangeID{1}, hold: holdTrue}, + }, + subject: 2, + want: ReadyWaitingDependency, + }, + { + name: "a held change on an unresolved stack base keeps stack-base-unresolved", + specs: []readySpec{ + {id: 1, status: StatusProposed, spec: specRef("p.md")}, + {id: 2, status: StatusProposed, spec: specRef("s.md"), parent: parentEdge(1), hold: holdTrue}, + }, + subject: 2, + want: ReadyStackBaseUnresolved, + }, + { + name: "hold: false is build-ready", + specs: []readySpec{{id: 2, status: StatusProposed, spec: specRef("s.md"), hold: OptionalBool{State: FieldPresent, Value: false, Raw: "false"}}}, + subject: 2, + want: ReadyBuildReady, + }, + { + name: "an absent hold is build-ready", + specs: []readySpec{{id: 2, status: StatusProposed, spec: specRef("s.md")}}, + subject: 2, + want: ReadyBuildReady, + }, + { + name: "an empty hold is build-ready", + specs: []readySpec{{id: 2, status: StatusProposed, spec: specRef("s.md"), hold: OptionalBool{State: FieldEmpty}}}, + subject: 2, + want: ReadyBuildReady, + }, + { + name: "a malformed hold reads as held", + specs: []readySpec{{id: 2, status: StatusProposed, spec: specRef("s.md"), hold: holdBad}}, + subject: 2, + want: ReadyOnHold, + }, } for _, tt := range tests { diff --git a/internal/domain/selection.go b/internal/domain/selection.go index 5c2204503..87dbb5375 100644 --- a/internal/domain/selection.go +++ b/internal/domain/selection.go @@ -27,8 +27,8 @@ type SelectionFilter struct { // changes can tie, since the snapshot excludes ambiguous IDs. // // Selection consults EvaluateReadiness, so a change that is not proposed, has -// an unmet dependency, carries no design, or sits on an unresolved stack base -// is excluded — as is a change whose ID more than one record claims, which +// an unmet dependency, carries no design, sits on an unresolved stack base, or +// is held is excluded — as is a change whose ID more than one record claims, which // readiness reports as invalid. The returned slice is freshly allocated; the // caller may sort or truncate it without touching the snapshot. func SelectQueue(s Snapshot, facts BranchFacts, filter SelectionFilter) []Change { diff --git a/internal/domain/selection_test.go b/internal/domain/selection_test.go index b6708feec..a9c2fab05 100644 --- a/internal/domain/selection_test.go +++ b/internal/domain/selection_test.go @@ -277,6 +277,32 @@ func TestSelectQueueExcludesAWaitingDependency(t *testing.T) { } } +// A hold is a selection-only exclusion: SelectQueue keeps only build-ready +// 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, + Hold: holdTrue, + }) + open := selSpec{id: 2, priority: PriorityHigh}.build() + + s := NewSnapshot(SnapshotSpec{ + Policy: RepositoryPolicy{IntegrationBranch: "main"}, + Changes: []Change{held, open}, + }) + if got := ids(SelectQueue(s, remotes(), SelectionFilter{})); !equalIDs(got, []ChangeID{2}) { + t.Fatalf("SelectQueue = %v; want [2] — 3 is on hold", got) + } + + only := NewSnapshot(SnapshotSpec{ + Policy: RepositoryPolicy{IntegrationBranch: "main"}, + Changes: []Change{held}, + }) + if got := ids(SelectQueue(only, remotes(), SelectionFilter{})); len(got) != 0 { + t.Fatalf("SelectQueue = %v; want an empty queue when only a held change exists", got) + } +} + func TestSelectQueueFilters(t *testing.T) { specs := []selSpec{ {id: 1, priority: PriorityHigh, kind: "feature", created: createdOn("2026-01-01")}, diff --git a/internal/domain/types_test.go b/internal/domain/types_test.go index 2f6db6ccf..dbbce2a8e 100644 --- a/internal/domain/types_test.go +++ b/internal/domain/types_test.go @@ -313,6 +313,20 @@ func TestChangeDeliverableEffectiveValue(t *testing.T) { // TestLifecycleActionCarriesDeliverable pins newChangeBuilder's copy: a // lifecycle write must keep the stored deliverable, known or unknown. +func TestLifecycleActionCarriesHold(t *testing.T) { + c := NewChange(ChangeSpec{ID: 1, Slug: "s", Status: StatusProposed, Type: "feat", Trivial: true, Hold: holdTrue}) + res, fail := Claim(c, actNow) + if fail != nil { + t.Fatalf("Claim: %v", fail) + } + if !res.Change.Held() { + t.Error("Held after Claim = false, want true") + } + if got := res.Change.Hold(); got != holdTrue { + t.Errorf("Hold after Claim = %+v, want %+v", got, holdTrue) + } +} + func TestLifecycleActionCarriesDeliverable(t *testing.T) { for _, spec := range []ChangeSpec{ {ID: 1, Slug: "s", Status: StatusProposed, Deliverable: DeliverableResultsArtifact, RawDeliverable: "results-artifact"}, From a3e80e41084b673fbcf5429aae932da324a04bba Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Sun, 18 Oct 2026 22:41:39 -0400 Subject: [PATCH 03/10] feat(repository): decode the hold field; a malformed value reads as held --- internal/repository/decode.go | 7 +++-- internal/repository/decode_test.go | 48 ++++++++++++++++++++++++++++++ 2 files changed, 53 insertions(+), 2 deletions(-) diff --git a/internal/repository/decode.go b/internal/repository/decode.go index 6aed19aeb..a61d0c9b1 100644 --- a/internal/repository/decode.go +++ b/internal/repository/decode.go @@ -124,6 +124,7 @@ type changeWire struct { Results scalar `yaml:"results"` Trivial scalar `yaml:"trivial"` AutoGroomable scalar `yaml:"auto_groomable"` + Hold scalar `yaml:"hold"` BranchPrefix scalar `yaml:"branch_prefix"` Branch scalar `yaml:"branch"` ClaimedAt scalar `yaml:"claimed_at"` @@ -297,9 +298,10 @@ func (d *decoder) boolean(name string, s scalar) bool { // optionalBool converts a scalar into a tri-state boolean: absent and valueless // stay distinguishable from an explicit false, and a value that is not a YAML // boolean is a finding, never a silent true or false. The finding is a -// warning: the only optional boolean is auto_groomable, human input that +// warning: both optional booleans (auto_groomable, hold) are human input that // gates no record validity, so a bad value must not make publish or finalize -// refuse a record that was otherwise valid — it is simply not a true. +// refuse a record that was otherwise valid. Each accessor decides what a +// malformed value means: auto_groomable reads it as not true, hold as held. func (d *decoder) optionalBool(name string, s scalar) domain.OptionalBool { switch d.state(name, s) { case domain.FieldAbsent: @@ -576,6 +578,7 @@ func decodeChange(in InputDocument) (domain.Change, []domain.Finding) { 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) spec.Branch = d.optionalString("branch", wire.Branch) spec.ClaimedAt = d.optionalTime("claimed_at", wire.ClaimedAt, stampLayout) diff --git a/internal/repository/decode_test.go b/internal/repository/decode_test.go index c2b541419..d507e4c6a 100644 --- a/internal/repository/decode_test.go +++ b/internal/repository/decode_test.go @@ -905,3 +905,51 @@ func TestDecodeChangeDeliverable(t *testing.T) { } } } + +// TestDecodeChangeHold pins the hold field's decode: a malformed hand edit +// reads as held with a warning, never an error and never an open change. +func TestDecodeChangeHold(t *testing.T) { + tests := []struct { + name string + line string + wantHeld bool + wantState domain.FieldState + wantWarning bool + }{ + {"true", "hold: true\n", true, domain.FieldPresent, false}, + {"false", "hold: false\n", false, domain.FieldPresent, false}, + {"valueless", "hold:\n", false, domain.FieldEmpty, false}, + {"absent", "", false, domain.FieldAbsent, false}, + {"yes is malformed", "hold: yes\n", true, domain.FieldMalformed, true}, + {"sequence is malformed", "hold: [true]\n", true, domain.FieldMalformed, true}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + in := input(t, KindChange, LocationActive, "docs/changes/active/0001-s.md", + "---\nid: 1\nslug: s\n"+tc.line+"---\n\nbody\n") + change, findings := decodeChange(in) + if got := change.Held(); got != tc.wantHeld { + t.Errorf("Held() = %v, want %v", got, tc.wantHeld) + } + if got := change.Hold().State; got != tc.wantState { + t.Errorf("Hold().State = %v, want %v", got, tc.wantState) + } + warned := false + for _, f := range findings { + if f.Field == "hold" && f.Code == CodeFieldMalformed { + warned = true + if f.Severity != domain.SeverityWarning { + t.Errorf("hold finding severity = %v, want warning", f.Severity) + } + } + if f.Severity == domain.SeverityError { + t.Errorf("unexpected error finding %s on %q", f.Code, f.Field) + } + } + if warned != tc.wantWarning { + t.Errorf("hold field-malformed warning = %v, want %v (codes %v)", + warned, tc.wantWarning, findingCodes(findings)) + } + }) + } +} From a4ea1ebec87eed0bac0531f1433e159758af86c9 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Sun, 18 Oct 2026 22:43:33 -0400 Subject: [PATCH 04/10] feat(app): status reports on-hold; named reads, claims, and completes accept a held change --- internal/app/change_claim_test.go | 18 +++++++ internal/app/change_complete_test.go | 14 ++++++ internal/app/implementation_context.go | 9 ++-- internal/app/implementation_context_test.go | 52 +++++++++++++++++++++ internal/app/status.go | 2 + internal/app/status_test.go | 37 +++++++++++++++ 6 files changed, 129 insertions(+), 3 deletions(-) diff --git a/internal/app/change_claim_test.go b/internal/app/change_claim_test.go index a48e16038..28da92017 100644 --- a/internal/app/change_claim_test.go +++ b/internal/app/change_claim_test.go @@ -522,3 +522,21 @@ 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) } + +// TestChangeClaimAcceptsHeldChangeAndKeepsField: a hold never refuses a claim, +// 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) + 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) + } + rec := killRecordBytes(t, plan, recPath) + if !strings.Contains(rec, "\nhold: true\n") { + t.Errorf("claimed record lost the hold:\n%s", rec) + } + if !strings.Contains(rec, "status: 'in-progress'") && !strings.Contains(rec, "status: in-progress") { + t.Errorf("claimed record not in-progress:\n%s", rec) + } +} diff --git a/internal/app/change_complete_test.go b/internal/app/change_complete_test.go index 6985907dc..f75e1ab25 100644 --- a/internal/app/change_complete_test.go +++ b/internal/app/change_complete_test.go @@ -281,3 +281,17 @@ func TestChangeCompleteResultFromOutcome(t *testing.T) { t.Fatalf("failed = %+v", failed) } } + +// TestChangeCompletePlanFromProposedHeld: completing a held proposed change +// names it by id, so the hold does not refuse it. +func TestChangeCompletePlanFromProposedHeld(t *testing.T) { + src := strings.Replace(completeRecord("proposed"), "trivial: false\n", "trivial: false\nhold: true\n", 1) + plan, opRes := completePlanFor(t, completeFiles(src), baseCompleteOp([]string{"inline"})) + if opRes.Refused { + t.Fatalf("complete of a held change refused: %v", opRes.Findings) + } + rec := killRecordBytes(t, plan, killArchivePath(3, miSlug)) + if !strings.Contains(rec, "status: 'done'") { + t.Errorf("archived record not done:\n%s", rec) + } +} diff --git a/internal/app/implementation_context.go b/internal/app/implementation_context.go index f89d23c99..bc451a7a8 100644 --- a/internal/app/implementation_context.go +++ b/internal/app/implementation_context.go @@ -346,8 +346,10 @@ func ContextImplementation(ctx context.Context, deps PlanningDeps, repoDir strin // selectContextChange resolves the change the bundle describes: the first // build-ready candidate under the selection policy, or the exact requested id. +// A hold is a selection-only exclusion: no-id selection never returns a held +// change, while an explicit id accepts one (ClaimEligibility admits on-hold). // It returns a non-nil result pointer for every typed non-bundle outcome, and a -// build-ready change with a nil pointer on success. +// claim-eligible change with a nil pointer on success. func selectContextChange(snap domain.Snapshot, facts domain.BranchFacts, req ImplementationContextRequest) (domain.Change, *ImplementationContextResult) { if req.ID <= 0 { queue := domain.SelectQueue(snap, facts, domain.SelectionFilter{}) @@ -371,8 +373,9 @@ func selectContextChange(snap domain.Snapshot, facts domain.BranchFacts, req Imp return domain.Change{}, &r } - // The explicit change must be claimable exactly as the selection policy - // requires. ClaimEligibility keys on readiness, so a non-build-ready change + // The explicit change must be claimable exactly as a claim requires. + // ClaimEligibility keys on readiness and admits a held (on-hold) + // change, since naming it overrides the hold; any other non-ready change // carries its exact reason token: an unusable identity is malformed, and // every other non-ready outcome maps to not-ready- (including // stack-base-unresolved for an unresolved effective base). diff --git a/internal/app/implementation_context_test.go b/internal/app/implementation_context_test.go index 80adf6a5a..3484cf2a7 100644 --- a/internal/app/implementation_context_test.go +++ b/internal/app/implementation_context_test.go @@ -625,3 +625,55 @@ func TestContextImplementationReportsDeliverable(t *testing.T) { }) } } + +// TestContextImplementationSkipsHeldChange: with no id, selection passes over a +// held change even when it ranks first, and a corpus whose only candidate is +// held yields no candidate. +func TestContextImplementationSkipsHeldChange(t *testing.T) { + specA := "docs/changes/specs/spec-a.md" + specB := "docs/changes/specs/spec-b.md" + held := changeBlob(11, "alpha", "feat", "high", "spec: "+specA+"\nhold: true\n") + open := changeBlob(12, "beta", "fix", "low", "spec: "+specB+"\n") + artifacts := map[string]StatusArtifact{ + sourceMetadata + "|" + specA: {Found: true, Revision: "sa", Data: []byte("spec a\n")}, + sourceMetadata + "|" + specB: {Found: true, Revision: "sb", Data: []byte("spec b\n")}, + } + + t.Run("unheld sibling selected", func(t *testing.T) { + fake := &fakeReader{pin: docketPin(t), corpus: []StatusBlob{held, open}, artifactData: artifacts} + got := ContextImplementation(context.Background(), contextDeps(fake), "", ImplementationContextRequest{}) + if got.Result != ResultApplied || got.Context == nil { + t.Fatalf("result=%q reason=%q message=%q", got.Result, got.Reason, got.Message) + } + if id := got.Context.Change.Summary.ID; id != 12 { + t.Errorf("selected change %d, want 12 (11 is held)", id) + } + }) + t.Run("only held change", func(t *testing.T) { + fake := &fakeReader{pin: docketPin(t), corpus: []StatusBlob{held}, artifactData: artifacts} + got := ContextImplementation(context.Background(), contextDeps(fake), "", ImplementationContextRequest{}) + if got.Result != ResultNoOp || got.Reason != ReasonContextNoCandidate { + t.Errorf("result=%q reason=%q, want no-op/%q", got.Result, got.Reason, ReasonContextNoCandidate) + } + }) +} + +// TestContextImplementationExplicitIDBuildsHeldChange: a hold is selection-only, +// so naming the held change returns its bundle, claim-eligible. +func TestContextImplementationExplicitIDBuildsHeldChange(t *testing.T) { + spec := "docs/changes/specs/spec-a.md" + fake := &fakeReader{ + pin: docketPin(t), + corpus: []StatusBlob{changeBlob(11, "alpha", "feat", "high", "spec: "+spec+"\nhold: true\n")}, + artifactData: map[string]StatusArtifact{ + sourceMetadata + "|" + spec: {Found: true, Revision: "sa", Data: []byte("spec a\n")}, + }, + } + got := ContextImplementation(context.Background(), contextDeps(fake), "", ImplementationContextRequest{ID: 11}) + if got.Result != ResultApplied || got.Context == nil { + t.Fatalf("result=%q reason=%q message=%q", got.Result, got.Reason, got.Message) + } + if got.Context.Readiness != string(domain.ReadyOnHold) || !got.Context.ClaimEligible { + t.Errorf("readiness=%q claim_eligible=%v, want on-hold/true", got.Context.Readiness, got.Context.ClaimEligible) + } +} diff --git a/internal/app/status.go b/internal/app/status.go index ea3a3f09e..ef9adc4f5 100644 --- a/internal/app/status.go +++ b/internal/app/status.go @@ -549,6 +549,8 @@ func readinessReason(r domain.Readiness) string { switch r.Kind { case domain.ReadyBuildReady: return "ready to build" + case domain.ReadyOnHold: + return "on hold" case domain.ReadyNeedsGrooming: return "needs grooming before it can be built" case domain.ReadyAutoGroomBlocked: diff --git a/internal/app/status_test.go b/internal/app/status_test.go index c80d04d8f..6765f5f41 100644 --- a/internal/app/status_test.go +++ b/internal/app/status_test.go @@ -675,3 +675,40 @@ func TestStatusReportsDeliverable(t *testing.T) { t.Errorf("status row JSON lacks a deliverable key: %s", b) } } + +// TestStatusReportsHeldChange: a held spec-backed change reads on-hold with its +// own reason and stays out of the ready queue, while an unheld sibling is ready. +func TestStatusReportsHeldChange(t *testing.T) { + fake := &fakeReader{ + pin: docketPin(t), + corpus: []StatusBlob{ + changeBlob(11, "held", "feat", "high", "spec: docs/changes/specs/s11.md\nhold: true\n"), + changeBlob(12, "open", "feat", "low", "spec: docs/changes/specs/s12.md\n"), + }, + facts: domain.NewBranchFacts(nil), + artifacts: map[string]bool{ + "metadata|docs/changes/specs/s11.md": true, + "metadata|docs/changes/specs/s12.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] != 12 { + t.Errorf("ready = %v, want [12]", got.Ready) + } + var row *StatusChange + for i := range got.Changes { + if got.Changes[i].ID == 11 { + row = &got.Changes[i] + } + } + if row == nil { + t.Fatalf("no row for held change 11: %+v", got.Changes) + } + if row.Readiness != string(domain.ReadyOnHold) || row.ReadinessWhy != "on hold" || row.Ready { + t.Errorf("held row = readiness %q, reason %q, ready %v; want on-hold, \"on hold\", false", + row.Readiness, row.ReadinessWhy, row.Ready) + } +} From bf3a00e439adbcbabd470c9418c0a61f7a865ec0 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Sun, 18 Oct 2026 22:46:40 -0400 Subject: [PATCH 05/10] feat(board): Groomed rows state build-ready or on hold; In progress column is State --- internal/render/board.go | 67 ++++++--- internal/render/board_test.go | 145 +++++++++++++++++-- internal/render/testdata/board/PROVENANCE.md | 13 +- internal/render/testdata/board/board.golden | 12 +- 4 files changed, 196 insertions(+), 41 deletions(-) diff --git a/internal/render/board.go b/internal/render/board.go index 2669244ee..67cb16fae 100644 --- a/internal/render/board.go +++ b/internal/render/board.go @@ -45,10 +45,10 @@ import ( // the Built State column carries the awaiting-merge wording. Emoji/title // per group: 🟢 In progress, 🔵 Built, 🔴 Blocked, 🟣 Groomed, // 🟡 Proposed, ⚪ Deferred. Column layouts per group: -// in-progress: # | Title | Priority | Type | Spec | Branch | Readiness +// in-progress: # | Title | Priority | Type | Spec | Branch | State // built: # | Title | Priority | Type | PR | State // blocked: # | Title | Priority | Type | PR | Reason -// groomed: # | Title | Priority | Type | Spec +// groomed: # | Title | Priority | Type | Spec | Readiness // proposed: # | Title | Priority | Type | Readiness // deferred: # | Title | Priority | Type // Priority renders the stored spelling, Type the stored token or "untyped" @@ -60,11 +60,15 @@ import ( // lifecycle-blocked change and "finalize blocked — needs you" for a // finalize-blocked implemented change; its PR cell comes from boardPRCell // (empty when no pr:). -// The In progress Readiness cell is "run halted — needs you" when the +// The In progress State cell is "run halted — needs you" when the // change carries the bare "## Run halted" body section (HasRunHalted), -// else empty. +// 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). // 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" @@ -278,11 +282,14 @@ func boardClassify(in BoardInput, c domain.Change) (BoardSection, error) { case domain.StatusStackedMerged: return BoardSectionBuilt, nil case domain.StatusProposed: - // Groomed means build-ready AND spec-backed: a trivial build-ready - // change with an empty spec stays Proposed. - if c.Spec().Value != "" && - domain.EvaluateReadiness(in.Snapshot, c, in.Facts).Kind == domain.ReadyBuildReady { - return BoardSectionGroomed, nil + // 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 + } } return BoardSectionProposed, nil case domain.StatusDeferred: @@ -647,7 +654,7 @@ func boardSectionRow(in BoardInput, s BoardSection, c domain.Change) (string, er case BoardSectionInProgress: return fmt.Sprintf("| [%04d](active/%s) | %s | `%s` | `%s` | [spec](%s) | `%s` | %s |\n", id, base, title, priority, ctype, boardSpecLink(c.Spec().Value), c.Branch().Value, - boardInProgressReadinessCell(c)), nil + boardInProgressStateCell(c)), nil case BoardSectionBuilt: return fmt.Sprintf("| [%04d](active/%s) | %s | `%s` | `%s` | %s | %s |\n", id, base, title, priority, ctype, boardPRCell(c), boardBuiltStateCell(c)), nil @@ -655,8 +662,12 @@ func boardSectionRow(in BoardInput, s BoardSection, c domain.Change) (string, er return fmt.Sprintf("| [%04d](active/%s) | %s | `%s` | `%s` | %s | %s |\n", id, base, title, priority, ctype, boardPRCell(c), boardBlockedReasonCell(c)), nil case BoardSectionGroomed: - return fmt.Sprintf("| [%04d](active/%s) | %s | `%s` | `%s` | [spec](%s) |\n", - id, base, title, priority, ctype, boardSpecLink(c.Spec().Value)), nil + cell, err := boardGroomedReadinessCell(in, c) + if err != nil { + return "", err + } + return fmt.Sprintf("| [%04d](active/%s) | %s | `%s` | `%s` | [spec](%s) | %s |\n", + id, base, title, priority, ctype, boardSpecLink(c.Spec().Value), cell), nil case BoardSectionProposed: cell, err := boardReadinessCell(in, c) if err != nil { @@ -693,16 +704,32 @@ func boardBlockedReasonCell(c domain.Change) string { return c.BlockedBy().Value } -// boardInProgressReadinessCell renders the In progress Readiness cell: an +// boardInProgressStateCell renders the In progress State cell: an // in-progress change carrying the bare "## Run halted" body section (0237's // stop + surface disposition, decoded as HasRunHalted) surfaces the call to // action in the family idiom of boardBlockedReasonCell's -// "finalize blocked — needs you"; every other row renders an empty cell. -func boardInProgressReadinessCell(c domain.Change) string { +// "finalize blocked — needs you"; every other row states "building", so no +// In progress cell is blank. +func boardInProgressStateCell(c domain.Change) string { if c.HasRunHalted() { return "run halted — needs you" } - return "" + return "building" +} + +// boardGroomedReadinessCell renders the Groomed Readiness cell: "build-ready", +// or "on hold" for a held change. boardClassify admits only those two kinds to +// Groomed, so any other kind is a per-record fault that cannot arise from +// classification. +func boardGroomedReadinessCell(in BoardInput, c domain.Change) (string, error) { + switch k := domain.EvaluateReadiness(in.Snapshot, c, in.Facts).Kind; k { + case domain.ReadyBuildReady: + return "build-ready", nil + case domain.ReadyOnHold: + return "on hold", nil + default: + return "", boardRecordFault{fmt.Sprintf("render: board: groomed change %04d has unexpected readiness %q", int(c.ID()), k)} + } } // boardReadinessCell renders the proposed-section Readiness cell from the @@ -718,6 +745,10 @@ func boardReadinessCell(in BoardInput, c domain.Change) (string, error) { 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: @@ -796,13 +827,13 @@ func boardTypeCell(c domain.Change) string { func boardSectionTableHeader(s BoardSection) string { switch s { case BoardSectionInProgress: - return "| # | Title | Priority | Type | Spec | Branch | Readiness |\n|---|-------|----------|------|------|--------|-----------|\n" + return "| # | Title | Priority | Type | Spec | Branch | State |\n|---|-------|----------|------|------|--------|-------|\n" case BoardSectionBuilt: return "| # | Title | Priority | Type | PR | State |\n|---|-------|----------|------|----|-------|\n" case BoardSectionBlocked: return "| # | Title | Priority | Type | PR | Reason |\n|---|-------|----------|------|----|--------|\n" case BoardSectionGroomed: - return "| # | Title | Priority | Type | Spec |\n|---|-------|----------|------|------|\n" + return "| # | Title | Priority | Type | Spec | Readiness |\n|---|-------|----------|------|------|-----------|\n" case BoardSectionProposed: return "| # | Title | Priority | Type | Readiness |\n|---|-------|----------|------|-----------|\n" case BoardSectionDeferred: diff --git a/internal/render/board_test.go b/internal/render/board_test.go index 5b81d8e65..5b8bc5def 100644 --- a/internal/render/board_test.go +++ b/internal/render/board_test.go @@ -206,6 +206,12 @@ func TestBoardClassifyEveryBucket(t *testing.T) { needsGrooming := domain.NewChange(proposedChange(11, "needs", "Needs grooming")) + // proposed + spec + held → Groomed (a hold is selection-only, not a demotion). + heldSpec := proposedChange(14, "held", "Held") + heldSpec.Spec = optString("docs/superpowers/specs/held-design.md") + heldSpec.Hold = domain.OptionalBool{State: domain.FieldPresent, Value: true, Raw: "true"} + held := domain.NewChange(heldSpec) + agBlockedSpec := proposedChange(12, "agb", "AG blocked") agBlockedSpec.HasAutoGroomBlocked = true agBlocked := domain.NewChange(agBlockedSpec) @@ -227,6 +233,7 @@ func TestBoardClassifyEveryBucket(t *testing.T) { {"stacked-merged", stacked, nil, render.BoardSectionBuilt}, {"in-progress", inprog, nil, render.BoardSectionInProgress}, {"proposed spec build-ready", groomed, nil, render.BoardSectionGroomed}, + {"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}, @@ -352,10 +359,11 @@ func TestBoardReadinessAutoGroomBlocked(t *testing.T) { } } -// TestBoardInProgressReadinessRunHalted: an in-progress change carrying the +// TestBoardInProgressStateRunHalted: an in-progress change carrying the // "## Run halted" marker surfaces the human call to action in the trailing -// Readiness cell; a healthy in-progress row renders the cell empty. -func TestBoardInProgressReadinessRunHalted(t *testing.T) { +// State cell; a healthy in-progress row states "building". No In progress cell +// is blank. +func TestBoardInProgressStateRunHalted(t *testing.T) { halted := domain.NewChange(domain.ChangeSpec{ ID: 12, Slug: "halted", Title: "Halted run", Status: domain.StatusInProgress, Branch: domain.OptionalString{State: domain.FieldPresent, Value: "feat/halted"}, @@ -370,15 +378,128 @@ func TestBoardInProgressReadinessRunHalted(t *testing.T) { Location: domain.LocationActive, Path: "docs/changes/active/0013-running.md", }) out := string(boardFrom(t, halted, running)) - if !strings.Contains(out, "| # | Title | Priority | Type | Spec | Branch | Readiness |") { - t.Fatalf("In progress header missing trailing Readiness column:\n%s", out) + if !strings.Contains(out, "| # | Title | Priority | Type | Spec | Branch | State |\n|---|-------|----------|------|------|--------|-------|\n") { + t.Fatalf("In progress header missing trailing State column:\n%s", out) + } + if !strings.Contains(out, "| `feat/halted` | run halted — needs you |\n") { + t.Fatalf("run-halted State cell not rendered:\n%s", out) + } + if !strings.Contains(out, "| `feat/running` | building |\n") { + t.Fatalf("healthy in-progress row must state building:\n%s", out) + } + assertNoBlankLastCell(t, out, "## 🟢 In progress") + assertNoRepairNotice(t, out) +} + +// sectionDataRows returns the table data rows of the section introduced by +// heading (header and separator lines excluded). +func sectionDataRows(t *testing.T, out, heading string) []string { + t.Helper() + body, ok := boardSectionBody(out, heading) + if !ok { + t.Fatalf("section %q missing:\n%s", heading, out) + } + var rows []string + for _, line := range strings.Split(body, "\n") { + if strings.HasPrefix(line, "| [") { + rows = append(rows, line) + } + } + if len(rows) == 0 { + t.Fatalf("section %q has no data rows:\n%s", heading, out) + } + return rows +} + +// assertNoBlankLastCell fails when any data row of the section ends in an +// empty trailing cell. +func assertNoBlankLastCell(t *testing.T, out, heading string) { + t.Helper() + for _, row := range sectionDataRows(t, out, heading) { + if strings.HasSuffix(row, "| |") { + t.Fatalf("section %q row has a blank last cell: %q", heading, row) + } + } +} + +// assertNoRepairNotice fails when the render routed any record to the +// Needs repair notice. +func assertNoRepairNotice(t *testing.T, out string) { + t.Helper() + if strings.Contains(out, "Needs repair") { + t.Fatalf("no fixture may land in the repair notice:\n%s", out) } - if !strings.Contains(out, "| `feat/halted` | run halted — needs you |") { - t.Fatalf("run-halted Readiness cell not rendered:\n%s", out) +} + +// heldTrue is a stored "hold: true". +var heldTrue = domain.OptionalBool{State: domain.FieldPresent, Value: true, Raw: "true"} + +// TestBoardGroomedReadinessCells: a held spec-backed change stays under +// Groomed and states "on hold"; an unheld one states "build-ready". No Groomed +// cell is blank. +func TestBoardGroomedReadinessCells(t *testing.T) { + heldSpec := proposedChange(20, "held", "Held change") + heldSpec.Spec = optString("docs/superpowers/specs/held-design.md") + heldSpec.Hold = heldTrue + readySpec := proposedChange(21, "ready", "Ready change") + readySpec.Spec = optString("docs/superpowers/specs/ready-design.md") + + out := string(boardFrom(t, domain.NewChange(heldSpec), domain.NewChange(readySpec))) + if !strings.Contains(out, "## 🟣 Groomed (2)") { + t.Fatalf("both changes must render under Groomed:\n%s", out) } - if !strings.Contains(out, "| `feat/running` | |") { - t.Fatalf("healthy in-progress row must render an empty Readiness cell:\n%s", out) + if !strings.Contains(out, "| # | Title | Priority | Type | Spec | Readiness |\n|---|-------|----------|------|------|-----------|\n") { + t.Fatalf("Groomed header missing trailing Readiness column:\n%s", out) } + if !strings.Contains(out, "| [0020](active/0020-held.md) | Held change | `` | `untyped` | [spec](../superpowers/specs/held-design.md) | on hold |\n") { + t.Fatalf("held Groomed row must state on hold:\n%s", out) + } + if !strings.Contains(out, "| [0021](active/0021-ready.md) | Ready change | `` | `untyped` | [spec](../superpowers/specs/ready-design.md) | build-ready |\n") { + t.Fatalf("unheld Groomed row must state build-ready:\n%s", out) + } + assertNoBlankLastCell(t, out, "## 🟣 Groomed") + 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". +func TestBoardHeldWaitingChangeShowsWaitingCell(t *testing.T) { + dep := domain.NewChange(proposedChange(30, "dep", "Dep")) + spec := proposedChange(31, "held-wait", "Held waiter") + spec.Spec = optString("docs/superpowers/specs/held-wait-design.md") + spec.DependsOn = []domain.ChangeID{30} + spec.Hold = heldTrue + out := string(boardFrom(t, dep, domain.NewChange(spec))) + if strings.Contains(out, "🟣 Groomed") { + t.Fatalf("a held waiting change must not render under Groomed:\n%s", out) + } + if !strings.Contains(out, "| [0031](active/0031-held-wait.md) | Held waiter | `` | `untyped` | ⏳ waiting on #30 — not yet built |\n") { + t.Fatalf("held waiting change must show the waiting cell:\n%s", out) + } + if strings.Contains(out, "on hold") { + t.Fatalf("held waiting change must not read on hold:\n%s", out) + } + assertNoRepairNotice(t, out) } // TestBoardRunHaltedWholeLineContract: the cell keys on the decode layer's @@ -442,10 +563,10 @@ func TestBoardRunHaltedWholeLineContract(t *testing.T) { } s := string(out) if !strings.Contains(s, "| `feat/bare` | run halted — needs you |") { - t.Fatalf("bare heading did not light the Readiness cell:\n%s", s) + t.Fatalf("bare heading did not light the State cell:\n%s", s) } - if !strings.Contains(s, "| `feat/dated` | |") { - t.Fatalf("dated heading variant must render an empty Readiness cell:\n%s", s) + if !strings.Contains(s, "| `feat/dated` | building |") { + t.Fatalf("dated heading variant must state building:\n%s", s) } } diff --git a/internal/render/testdata/board/PROVENANCE.md b/internal/render/testdata/board/PROVENANCE.md index d09849fb4..7b1e255f4 100644 --- a/internal/render/testdata/board/PROVENANCE.md +++ b/internal/render/testdata/board/PROVENANCE.md @@ -38,18 +38,18 @@ follow the default section order; rows sort `updated desc` within each section. Sections and rows: -- **In progress** — two Readiness bands, sorted `updated desc`: +- **In progress** — two State bands, sorted `updated desc`: - id 1 (updated 2026-08-10), with a `spec:` (Spec cell), a `branch:` (Branch - cell), and no `## Run halted` section (empty Readiness cell); + cell), and no `## Run halted` section (the `building` State cell); - id 8 (updated 2026-08-09), carrying the bare `## Run halted` body section: - the `run halted — needs you` Readiness cell (change 0261). + the `run halted — needs you` State cell (change 0261). - **Built** — id 7, an `implemented` change with no `## Finalize blocked` section: PR cell from a full PR URL and the `awaiting merge` State cell. - **Blocked** — id 5, a lifecycle-`blocked` change: empty PR cell (no `pr:`) and the stored `blocked_by` free-text Reason cell. - **Groomed** — id 2, a `proposed`, spec-backed, build-ready change (its `depends_on: [9]` points at a `done` change, so the dependency is satisfied): - a `[spec](…)` Spec cell. + a `[spec](…)` Spec cell and the `build-ready` Readiness cell. - **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); @@ -68,8 +68,11 @@ Mermaid graph (outside section order/sorting — the presentation never reaches Bands and surfaces the corpus deliberately does **not** cover — unit-tested directly instead: -- the dated `## Run halted — ` variant NOT lighting the Readiness cell +- 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`); - the classification precedence edges (finalize-blocked implemented → Blocked; spec-backed build-ready → Groomed vs trivial-without-spec → Proposed); - the Blocked `finalize blocked — needs you` Reason cell; diff --git a/internal/render/testdata/board/board.golden b/internal/render/testdata/board/board.golden index 80f221f81..83259adea 100644 --- a/internal/render/testdata/board/board.golden +++ b/internal/render/testdata/board/board.golden @@ -4,9 +4,9 @@ ## 🟢 In progress (2) -| # | Title | Priority | Type | Spec | Branch | Readiness | -|---|-------|----------|------|------|--------|-----------| -| [0001](active/0001-inline-board-in-progress.md) | Inline board work in progress | `high` | `feat` | [spec](../superpowers/specs/2026-08-01-inline-board-design.md) | `feat/inline-board` | | +| # | Title | Priority | Type | Spec | Branch | State | +|---|-------|----------|------|------|--------|-------| +| [0001](active/0001-inline-board-in-progress.md) | Inline board work in progress | `high` | `feat` | [spec](../superpowers/specs/2026-08-01-inline-board-design.md) | `feat/inline-board` | building | | [0008](active/0008-run-halted-in-progress.md) | An in-progress run that halted for a human | `high` | `feat` | [spec](../superpowers/specs/2026-08-05-run-halted-design.md) | `feat/run-halted-in-progress` | run halted — needs you | ## 🔵 Built (1) @@ -23,9 +23,9 @@ ## 🟣 Groomed (1) -| # | Title | Priority | Type | Spec | -|---|-------|----------|------|------| -| [0002](active/0002-build-ready-change.md) | A build ready change | `critical` | `feat` | [spec](../superpowers/specs/2026-08-02-build-ready-change-design.md) | +| # | Title | Priority | Type | Spec | Readiness | +|---|-------|----------|------|------|-----------| +| [0002](active/0002-build-ready-change.md) | A build ready change | `critical` | `feat` | [spec](../superpowers/specs/2026-08-02-build-ready-change-design.md) | build-ready | ## 🟡 Proposed (2) From be93bad4c1205f8f751fe1851f9084d86fe72550 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Sun, 18 Oct 2026 22:54:36 -0400 Subject: [PATCH 06/10] feat(groom): hold and hold_reason set and lift a hold with an owned Why on hold section --- internal/app/change_groom.go | 92 +++++++- internal/app/change_groom_test.go | 296 +++++++++++++++++++++++++- internal/app/change_reconcile_test.go | 18 ++ internal/app/finding_codes.go | 10 + internal/app/finding_codes_test.go | 5 + internal/app/schema_test.go | 8 + 6 files changed, 421 insertions(+), 8 deletions(-) diff --git a/internal/app/change_groom.go b/internal/app/change_groom.go index 8b45bc5fa..dc1654c5f 100644 --- a/internal/app/change_groom.go +++ b/internal/app/change_groom.go @@ -29,7 +29,10 @@ import ( // 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. Every outcome +// 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 +// 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, // its typed fields, its artifact block; a new spec file for the spec outcome, a // replaced one for a spec-body revise; the inline board) as one validated @@ -60,12 +63,14 @@ const ( // writes spec:, trivial:, or auto_groomable:, so a change can never flip // between needs-grooming, spec'd, and trivial 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 - // accepts no section, spec, or relationship edits — an autonomous caller - // cannot rewrite the proposal through it. + // accepts no section, spec, relationship, or hold edits — an autonomous + // caller cannot rewrite the proposal through it. GroomAbstain GroomOutcome = "abstain" // GroomReEnable re-enables a needs-grooming change for autonomous grooming: // it sets auto_groomable: true, removes the ## Auto-groom blocked section when @@ -89,6 +94,33 @@ const specsDir = "docs/superpowers/specs" // (domain.ReadyAutoGroomBlocked). const autoGroomBlockedHeading = "## Auto-groom blocked" +// whyOnHoldHeading is the optional reason section for a hold. It is not in +// render.ChangeOwnedHeadings: the hold and hold_reason keys of change.groom and +// change.create are its only writers, so a sections edit naming it is refused +// on every outcome (and on change.reconcile) as an unowned heading. +const whyOnHoldHeading = "## Why on hold" + +// holdReasonProblem reports why a non-empty hold_reason cannot be written, or +// "" when it is usable as the whyOnHoldHeading section body. held is whether +// the same request sets the hold. Callers run it only when the reason is +// non-empty, since an omitted reason sets the hold without one. The +// diagnostics are static and never echo the authored reason. +func holdReasonProblem(held bool, reason string) (FindingCode, string) { + if !held { + return FCHoldReasonWithoutHold, "hold_reason is accepted only with hold: true in the same request; it becomes the \"" + whyOnHoldHeading + "\" section" + } + if strings.TrimSpace(reason) == "" { + return FCInvalidHoldReason, "hold_reason is blank; send the reason for \"" + whyOnHoldHeading + "\", or omit hold_reason to set the hold without one" + } + if err := render.ValidateSectionBody([]byte(reason)); err != nil { + if errors.Is(err, render.ErrSectionBodyUnterminatedFence) { + return FCInvalidHoldReason, "hold_reason leaves a code fence unterminated; close the fence so the sections after \"" + whyOnHoldHeading + "\" stay visible" + } + return FCInvalidHoldReason, "hold_reason carries a column-zero \"## \" heading outside fenced code; the operation owns the \"" + whyOnHoldHeading + "\" heading — author body text, lists, or \"###\"-or-deeper subsections, and put heading examples inside closed code fences" + } + return "", "" +} + // ChangeGroomRequest is the closed, caller-supplied request for one groom. Path // and Revision pin the exact submitted record; the relationship collections are // the complete desired values (a nil collection is left unchanged, an explicit @@ -142,6 +174,16 @@ type ChangeGroomRequest struct { Type string `json:"type,omitempty" docket:"enum=change_types"` BranchPrefix *string `json:"branch_prefix,omitempty"` + // Hold and HoldReason set and lift a hold, which keeps the change out of + // every autonomous build selection while a run naming it still builds it. + // Hold is three-state: nil leaves it unchanged, true writes hold: true, and + // 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. + Hold *bool `json:"hold,omitempty"` + HoldReason string `json:"hold_reason,omitempty"` + DependsOn []int `json:"depends_on"` Related []int `json:"related"` DiscoveredFrom []int `json:"discovered_from"` @@ -373,8 +415,8 @@ func validateChangeGroomShape(req ChangeGroomRequest) []StatusFinding { addShape(FCInvalidSpecMarkdown, msg) } } else if !hasEffectiveSectionEdit(req.Sections) && req.Title == "" && req.Priority == "" && - req.Deliverable == "" && req.Type == "" && req.BranchPrefix == nil && !hasRelationshipEdit(req) { - addShape(FCEmptyRevise, "the revise outcome requires a non-empty spec_markdown, at least one replace/remove section edit, a title, a priority, a deliverable, a type, a branch_prefix, or a relationship field (depends_on, related, discovered_from, adrs, stacked_on)") + req.Deliverable == "" && req.Type == "" && req.BranchPrefix == nil && req.Hold == nil && !hasRelationshipEdit(req) { + addShape(FCEmptyRevise, "the revise outcome requires a non-empty spec_markdown, at least one replace/remove section edit, a title, a priority, a deliverable, a type, a branch_prefix, a hold, or a relationship field (depends_on, related, discovered_from, adrs, stacked_on)") } for _, s := range req.Sections { if s.Heading == autoGroomBlockedHeading { @@ -408,6 +450,9 @@ func validateChangeGroomShape(req ChangeGroomRequest) []StatusFinding { if req.BranchPrefix != nil { addShape(FCInvalidBranchPrefix, "branch_prefix is not accepted by the abstain outcome; an abstain cannot rewrite the proposal") } + if req.Hold != nil { + addShape(FCInvalidHold, "hold is not accepted by the abstain outcome; an abstain cannot rewrite the proposal") + } for _, rel := range []struct { name string set bool @@ -478,6 +523,15 @@ func validateChangeGroomShape(req ChangeGroomRequest) []StatusFinding { } } + // hold_reason rides only with hold: true and becomes the "## Why on hold" + // body, so it gets blocked_note's section-body checks on every outcome. + if req.HoldReason != "" { + if code, msg := holdReasonProblem(req.Hold != nil && *req.Hold, req.HoldReason); code != "" { + addShape(code, msg) + } + } + boundAuthored(&findings, "hold_reason", req.HoldReason) + // blocked_note is the abstain entry's body; nothing else reads it, so it is // refused anywhere else rather than silently ignored. if req.Outcome != GroomAbstain && req.BlockedNote != "" { @@ -773,7 +827,23 @@ func (o changeGroomOp) Plan(ctx context.Context, st transaction.AttemptState) (t edits = append(edits, render.SectionEdit{Heading: autoGroomBlockedHeading, Intent: render.SectionRemove}) } } - edited, err := render.ApplySectionEdits(src, render.ChangeOwnedHeadings, edits) + // A request that sets or lifts a hold also owns "## Why on hold" for this + // splice — and only such a request, so a hand-duplicated reason section never + // blocks an unrelated groom. The owned set is a fresh slice: appending to + // render.ChangeOwnedHeadings could alias the shared package variable. A set + // with a reason replaces the section; a lift removes it only when present, + // because removing an absent section is an ApplySectionEdits error. + owned := render.ChangeOwnedHeadings + if o.req.Hold != nil { + owned = append(append([]string(nil), render.ChangeOwnedHeadings...), whyOnHoldHeading) + switch { + case *o.req.Hold && o.req.HoldReason != "": + edits = append(edits, render.SectionEdit{Heading: whyOnHoldHeading, Intent: render.SectionReplace, Markdown: o.req.HoldReason}) + case !*o.req.Hold && namedSectionPresent(src, whyOnHoldHeading): + edits = append(edits, render.SectionEdit{Heading: whyOnHoldHeading, Intent: render.SectionRemove}) + } + } + edited, err := render.ApplySectionEdits(src, owned, edits) if err != nil { return refuseGroom("section-edit-failed", err.Error()) } @@ -933,7 +1003,8 @@ type groomFieldEdit struct { // values are validated at the shape stage, and the writer quotes every scalar, // so ADR-0071 holds by construction; the candidate snapshot carries them into // the artifact block and the board with no further code. A branch_prefix that -// normalizes to "" clears the field to a valueless key (change 0559). +// normalizes to "" clears the field to a valueless key (change 0559), and so +// does a lifted hold. func (o changeGroomOp) fieldEdits(specPath string) []groomFieldEdit { var out []groomFieldEdit switch o.req.Outcome { @@ -981,6 +1052,13 @@ func (o changeGroomOp) fieldEdits(specPath string) []groomFieldEdit { } out = append(out, groomFieldEdit{"branch_prefix", v}) } + if o.req.Hold != nil { + v := document.Null() + if *o.req.Hold { + v = document.Bool(true) + } + out = append(out, groomFieldEdit{"hold", v}) + } return out } diff --git a/internal/app/change_groom_test.go b/internal/app/change_groom_test.go index f4e9b2e64..e2f70e4bf 100644 --- a/internal/app/change_groom_test.go +++ b/internal/app/change_groom_test.go @@ -2294,7 +2294,7 @@ func TestChangeGroomEachNewFieldAloneIsAValidRevise(t *testing.T) { if msg == "" { t.Fatalf("empty revise not refused; findings %v", findings) } - for _, want := range []string{"deliverable", "type", "branch_prefix"} { + for _, want := range []string{"deliverable", "type", "branch_prefix", "hold"} { if !strings.Contains(msg, want) { t.Errorf("empty-revise message %q does not name %q", msg, want) } @@ -2968,3 +2968,297 @@ func TestChangeGroomRefusalPrintsPlainText(t *testing.T) { t.Errorf("HumanText = %q, want %q", r.HumanText(), want) } } + +// --- hold and hold_reason --------------------------------------------------- + +func boolPtr(b bool) *bool { return &b } + +// heldChange is the groomable fixture at id 2 carrying hold: true, followed by +// a "## Why on hold" section with reason when reason is non-empty. +func heldChange(reason string) string { + rec := strings.Replace(groomableChange(2, "add-a-widget"), "trivial: false\n", "trivial: false\nhold: true\n", 1) + if reason != "" { + rec += "\n" + whyOnHoldHeading + "\n\n" + reason + } + return rec +} + +// holdPlanRecord plans req against a one-record tree holding rec and returns +// the groomed record text, failing on a refusal. +func holdPlanRecord(t *testing.T, rec string, req ChangeGroomRequest) string { + t.Helper() + if findings := validateChangeGroomShape(req); len(findings) != 0 { + t.Fatalf("shape refused: %v", findings) + } + files := map[string]string{groomPath(2, "add-a-widget"): rec} + plan, opRes := groomPlanFor(t, files, baseGroomOp([]string{}, req)) + if opRes.Refused { + t.Fatalf("unexpected refusal: %v", opRes.Findings) + } + return string(groomedRecordBytes(t, plan, groomPath(2, "add-a-widget"))) +} + +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()}, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + req := c.req + req.Hold = boolPtr(true) + rec := holdPlanRecord(t, c.rec, req) + if n := strings.Count(rec, "\nhold: true\n"); n != 1 { + t.Errorf("record carries %d hold: true lines, want 1:\n%s", n, rec) + } + if strings.Contains(rec, whyOnHoldHeading) { + t.Errorf("a hold with no reason wrote %q:\n%s", whyOnHoldHeading, rec) + } + }) + } +} + +func TestChangeGroomHoldReasonSection(t *testing.T) { + revise := func(mut func(*ChangeGroomRequest)) ChangeGroomRequest { return fieldOnlyReviseRequest(mut) } + + t.Run("a set with a reason writes the section at end of file", func(t *testing.T) { + rec := holdPlanRecord(t, groomableChange(2, "add-a-widget"), revise(func(r *ChangeGroomRequest) { + r.Hold, r.HoldReason = boolPtr(true), "Needs a person to rotate the key.\n" + })) + if !strings.Contains(rec, "\nhold: true\n") { + t.Errorf("hold not set:\n%s", rec) + } + if !strings.HasSuffix(rec, "\n\n## Why on hold\n\nNeeds a person to rotate the key.\n") { + t.Errorf("section not appended at end of file:\n%s", rec) + } + }) + + t.Run("a second set with a new reason replaces it", func(t *testing.T) { + rec := holdPlanRecord(t, heldChange("Old reason.\n"), revise(func(r *ChangeGroomRequest) { + r.Hold, r.HoldReason = boolPtr(true), "New reason.\n" + })) + if n := strings.Count(rec, whyOnHoldHeading); n != 1 { + t.Errorf("record carries %d %q headings, want 1:\n%s", n, whyOnHoldHeading, rec) + } + if strings.Contains(rec, "Old reason.") || !strings.Contains(rec, "## Why on hold\n\nNew reason.\n") { + t.Errorf("reason not replaced:\n%s", rec) + } + }) + + t.Run("a set with no reason leaves an existing section alone", func(t *testing.T) { + const section = "\n## Why on hold\n\nKeep this reason.\n" + rec := holdPlanRecord(t, heldChange("Keep this reason.\n"), revise(func(r *ChangeGroomRequest) { + r.Hold, r.Priority = boolPtr(true), "high" + })) + if !strings.HasSuffix(rec, section) || strings.Count(rec, whyOnHoldHeading) != 1 { + t.Errorf("existing section changed:\n%s", rec) + } + }) + + t.Run("a lift clears the field and removes the section", func(t *testing.T) { + rec := holdPlanRecord(t, heldChange("Stale reason.\n"), revise(func(r *ChangeGroomRequest) { + r.Hold = boolPtr(false) + })) + if !strings.Contains(rec, "\nhold:\n") || strings.Contains(rec, "\nhold: true\n") { + t.Errorf("hold not lifted to a valueless key:\n%s", rec) + } + if strings.Contains(rec, whyOnHoldHeading) || strings.Contains(rec, "Stale reason.") { + t.Errorf("section survived the lift:\n%s", rec) + } + if !strings.Contains(rec, "## Open questions\n\nAn open question.\n") { + t.Errorf("the preceding section's text changed:\n%s", rec) + } + }) + + t.Run("a lift on a record with no section succeeds", func(t *testing.T) { + rec := holdPlanRecord(t, heldChange(""), revise(func(r *ChangeGroomRequest) { + r.Hold = boolPtr(false) + })) + if !strings.Contains(rec, "\nhold:\n") { + t.Errorf("hold not lifted:\n%s", rec) + } + }) + + t.Run("an omitted hold keeps the field and the section", func(t *testing.T) { + const section = "\n## Why on hold\n\nStill held.\n" + rec := holdPlanRecord(t, heldChange("Still held.\n"), revise(func(r *ChangeGroomRequest) { + r.Priority = "high" + })) + if !strings.Contains(rec, "\nhold: true\n") || !strings.HasSuffix(rec, section) { + t.Errorf("an omitted hold changed the hold or its section:\n%s", rec) + } + }) +} + +func TestChangeGroomHoldAloneIsAValidRevise(t *testing.T) { + for name, v := range map[string]bool{"set": true, "lift": false} { + t.Run(name, func(t *testing.T) { + req := fieldOnlyReviseRequest(func(r *ChangeGroomRequest) { r.Hold = boolPtr(v) }) + if findings := validateChangeGroomShape(req); len(findings) != 0 { + t.Fatalf("hold-only revise refused: %v", findings) + } + }) + } + findings := validateChangeGroomShape(fieldOnlyReviseRequest(func(*ChangeGroomRequest) {})) + for _, f := range findings { + if f.Code == string(FCEmptyRevise) && !strings.Contains(f.Message, "hold") { + t.Errorf("empty-revise message %q does not name hold", f.Message) + } + } +} + +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 + return base + } + whyOnHoldEdit := []SectionEditRequest{{Heading: whyOnHoldHeading, Intent: "replace", Markdown: "Hand reason.\n"}} + withSection := func(base ChangeGroomRequest) ChangeGroomRequest { + base.Sections = append(append([]SectionEditRequest(nil), base.Sections...), whyOnHoldEdit...) + return base + } + + cases := []struct { + name string + req ChangeGroomRequest + code FindingCode + }{ + {"abstain with hold", withHold(abstainRequest(), boolPtr(true), ""), FCInvalidHold}, + {"abstain lifting a hold", withHold(abstainRequest(), boolPtr(false), ""), FCInvalidHold}, + {"reason with no hold", withHold(revise, nil, "A reason.\n"), FCHoldReasonWithoutHold}, + {"reason with a lift", withHold(revise, boolPtr(false), "A reason.\n"), FCHoldReasonWithoutHold}, + {"reason on abstain with no hold", withHold(abstainRequest(), nil, "A reason.\n"), FCHoldReasonWithoutHold}, + {"whitespace-only reason", withHold(revise, boolPtr(true), " \n\t\n"), FCInvalidHoldReason}, + {"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}, + {"section edit on abstain", withSection(abstainRequest()), FCInvalidSectionHeading}, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + engine := &recordingEngine{} + reader := &fakeChangeReader{pin: mainModePin([]string{"inline"})} + deps := PlanningDeps{Engine: engine, Reader: reader, Clock: testClock()} + + res := ChangeGroom(context.Background(), deps, "", c.req) + + if res.Result != ResultInvalidInput { + t.Fatalf("result = %q, want invalid-input; findings %v", res.Result, res.Findings) + } + if len(engine.calls) != 0 { + t.Errorf("engine called %d times on a shape failure, want 0", len(engine.calls)) + } + if !hasFindingCode(res.Findings, string(c.code)) { + t.Errorf("missing %q; got %v", c.code, res.Findings) + } + }) + } + + // The reason diagnostics are static: they name the owned heading and never + // echo the authored text. + const secret = "SECRET-REASON-TEXT" + for _, reason := range []string{secret + "\n## Heading\n", secret + "\n```\n", " "} { + findings := validateChangeGroomShape(withHold(revise, boolPtr(true), reason)) + for _, f := range findings { + if f.Code != string(FCInvalidHoldReason) { + continue + } + if strings.Contains(f.Message, secret) || !strings.Contains(f.Message, whyOnHoldHeading) { + t.Errorf("hold_reason diagnostic %q must name %q and never echo the reason", f.Message, whyOnHoldHeading) + } + } + } + + // A usable reason with hold: true passes the shape stage. + if findings := validateChangeGroomShape(withHold(revise, boolPtr(true), "Needs a person.\n")); len(findings) != 0 { + t.Errorf("a usable reason was refused: %v", findings) + } +} + +func TestChangeGroomHoldDuplicateSectionRefuses(t *testing.T) { + dup := heldChange("First.\n") + "\n" + whyOnHoldHeading + "\n\nSecond.\n" + cases := map[string]func(*ChangeGroomRequest){ + "set with a reason": func(r *ChangeGroomRequest) { r.Hold, r.HoldReason = boolPtr(true), "New.\n" }, + "set without a reason": func(r *ChangeGroomRequest) { r.Hold = boolPtr(true) }, + "lift": func(r *ChangeGroomRequest) { r.Hold = boolPtr(false) }, + } + for name, mut := range cases { + t.Run(name, func(t *testing.T) { + files := map[string]string{groomPath(2, "add-a-widget"): dup} + plan, opRes := groomPlanFor(t, files, baseGroomOp([]string{}, fieldOnlyReviseRequest(mut))) + if !opRes.Refused { + t.Fatalf("a duplicated %q was not refused; files %v", whyOnHoldHeading, planPaths(plan)) + } + if len(opRes.Findings) != 1 || opRes.Findings[0].Code != string(FCSectionEditFailed) { + t.Errorf("findings = %v, want one %s", opRes.Findings, FCSectionEditFailed) + } + if len(plan.Files) != 0 { + t.Errorf("a refused groom planned files %v", planPaths(plan)) + } + }) + } + + // A request that leaves the hold alone never inspects the section, so a + // hand-duplicated reason does not block an unrelated revise. + files := map[string]string{groomPath(2, "add-a-widget"): dup} + _, opRes := groomPlanFor(t, files, baseGroomOp([]string{}, fieldOnlyReviseRequest(func(r *ChangeGroomRequest) { r.Priority = "high" }))) + if opRes.Refused { + t.Errorf("an unrelated revise refused over a duplicated %q: %v", whyOnHoldHeading, opRes.Findings) + } +} + +func TestChangeGroomOwnedHeadingsStayShared(t *testing.T) { + // The hold keys are the section's only writer, so the shared owned set + // never names it, before or after a Plan that writes it. + before := append([]string(nil), render.ChangeOwnedHeadings...) + files := map[string]string{groomPath(2, "add-a-widget"): heldChange("Reason.\n")} + groomPlanFor(t, files, baseGroomOp([]string{}, fieldOnlyReviseRequest(func(r *ChangeGroomRequest) { + r.Hold, r.HoldReason = boolPtr(true), "Other.\n" + }))) + for _, h := range render.ChangeOwnedHeadings { + if h == whyOnHoldHeading { + t.Fatalf("render.ChangeOwnedHeadings carries %q", whyOnHoldHeading) + } + } + if strings.Join(before, "|") != strings.Join(render.ChangeOwnedHeadings, "|") { + t.Errorf("render.ChangeOwnedHeadings changed: %v -> %v", before, render.ChangeOwnedHeadings) + } +} + +func TestChangeGroomHoldCodesAreRegistered(t *testing.T) { + registered := map[FindingCode]bool{} + for _, code := range AllFindingCodes { + registered[code] = true + } + for code, want := range map[FindingCode]string{ + FCInvalidHold: "invalid-hold", FCHoldReasonWithoutHold: "hold-reason-without-hold", FCInvalidHoldReason: "invalid-hold_reason", + } { + if string(code) != want { + t.Errorf("code %q, want %q", code, want) + } + if !registered[code] { + t.Errorf("%s is not registered in AllFindingCodes", code) + } + } +} diff --git a/internal/app/change_reconcile_test.go b/internal/app/change_reconcile_test.go index d9c6ad2f5..47ff0db38 100644 --- a/internal/app/change_reconcile_test.go +++ b/internal/app/change_reconcile_test.go @@ -138,6 +138,24 @@ func TestChangeReconcileAppliesPatch(t *testing.T) { } } +// TestChangeReconcileRefusesWhyOnHoldSection: the hold keys on change.groom and +// change.create are the only writers of "## Why on hold", so a reconcile +// section edit naming it is refused before any engine call. +func TestChangeReconcileRefusesWhyOnHoldSection(t *testing.T) { + req := validReconcileRequest() + req.Sections = map[string]string{whyOnHoldHeading: "A reason.\n"} + engine := &recordingEngine{} + reader := &fakeChangeReader{pin: mainModePin([]string{"inline"})} + deps := PlanningDeps{Engine: engine, Reader: reader, Clock: testClock()} + + res := ChangeReconcile(context.Background(), deps, "", req) + + if res.Result != ResultInvalidInput || len(engine.calls) != 0 || !hasFindingCode(res.Findings, string(FCInvalidSectionHeading)) { + t.Errorf("result %q, engine calls %d, findings %v; want invalid-input, 0, invalid-section-heading", + res.Result, len(engine.calls), res.Findings) + } +} + // --- TestChangeReconcileRefusesNonOwnedSection ----------------------------- // TestChangeReconcileRefusesNonOwnedSection proves a request naming a non-owned section diff --git a/internal/app/finding_codes.go b/internal/app/finding_codes.go index 2eeb2a28e..9bc38db6e 100644 --- a/internal/app/finding_codes.go +++ b/internal/app/finding_codes.go @@ -170,6 +170,13 @@ const ( FCInvalidAttempt FindingCode = "invalid-attempt" FCEmptyHead FindingCode = "empty-head" + // Hold request findings (change.groom and change.create): abstain refuses a + // hold, a hold_reason needs hold: true in the same request, and a reason + // must be usable as the "## Why on hold" section body. + FCInvalidHold FindingCode = "invalid-hold" + FCHoldReasonWithoutHold FindingCode = "hold-reason-without-hold" + FCInvalidHoldReason FindingCode = "invalid-hold_reason" + // Install-maintenance findings. collection-pending is the reason an explicit // `install collect` reports and the warning code an automatic post-install // collection surfaces when a version tree could not be reclaimed; the primary @@ -288,6 +295,7 @@ var AllFindingCodes = []FindingCode{ FCEmptyWhyDeferred, FCEmptyWhyKilled, FindingCode(ReasonStatusExternal), + FCHoldReasonWithoutHold, FCHookFileNotEditable, FindingCode("illegal-source-status"), FindingCode(ReasonStatusInternalError), @@ -305,6 +313,8 @@ var AllFindingCodes = []FindingCode{ FCInvalidDependsOn, FCInvalidDiscoveredFrom, FCInvalidHead, + FCInvalidHold, + FCInvalidHoldReason, FCInvalidID, FindingCode(ReasonStatusInvalidInput), FCInvalidNoteEntry, diff --git a/internal/app/finding_codes_test.go b/internal/app/finding_codes_test.go index 12c30ce0f..8f2f99d68 100644 --- a/internal/app/finding_codes_test.go +++ b/internal/app/finding_codes_test.go @@ -241,6 +241,10 @@ func TestShapeValidatorCodesAreRegistered(t *testing.T) { emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomRevise, Title: "a\nb"})...) emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomAbstain, Priority: "high"})...) emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomRevise, Priority: "urgent"})...) + held := true + emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomAbstain, Hold: &held})...) + emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomRevise, HoldReason: "x"})...) + emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomRevise, Hold: &held, HoldReason: " "})...) emitted = append(emitted, validateChangeReconcileShape(ChangeReconcileRequest{ Sections: map[string]string{"## Not Owned": "x"}, SpecSections: map[string]string{"not a heading": "x"}, @@ -269,6 +273,7 @@ func TestShapeValidatorCodesAreRegistered(t *testing.T) { FCInvalidSpecSectionHeading, FCEmptyReconcileLogEntry, FCEmptyBlockedNote, FCInvalidBlockedNote, FCInvalidSections, FCInvalidPRNumber, FCInvalidAttempt, FCEmptyHead, FCInvalidPriority, FCUnknownPriority, + FCInvalidHold, FCHoldReasonWithoutHold, FCInvalidHoldReason, } for _, c := range floor { if !seen[string(c)] { diff --git a/internal/app/schema_test.go b/internal/app/schema_test.go index 28a0c7063..24c2c5e4e 100644 --- a/internal/app/schema_test.go +++ b/internal/app/schema_test.go @@ -111,6 +111,14 @@ func TestReflectDescriptorChangeGroomRequest(t *testing.T) { if f := fieldByKey(t, d, "priority"); f.Required || f.Type != "string" || f.Enum != "priorities" { t.Errorf("priority = %+v, want optional string with enum priorities", f) } + // hold is three-state (*bool: omitted keeps, true sets, false lifts) and + // hold_reason rides with hold: true only; neither is required. + if f := fieldByKey(t, d, "hold"); f.Required || f.Repeated || f.Type != "bool" { + t.Errorf("hold = %+v, want optional non-repeated bool", f) + } + if f := fieldByKey(t, d, "hold_reason"); f.Required || f.Repeated || f.Type != "string" { + t.Errorf("hold_reason = %+v, want optional string", f) + } // No caller-supplied spec path: the spec pinned is always the one the // record's spec: field links. for _, f := range d.Fields { From cc5e8bbb51cf6bd839a3fb5cb68c626bb712de9e Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Sun, 18 Oct 2026 22:57:47 -0400 Subject: [PATCH 07/10] feat(create): capture a change already on hold; new records carry hold --- internal/app/change_create.go | 27 ++++ internal/app/change_create_test.go | 153 ++++++++++++++++++ internal/app/schema_test.go | 8 +- internal/render/record.go | 25 ++- internal/render/record_test.go | 47 ++++++ .../render/testdata/records/change.golden.md | 1 + 6 files changed, 257 insertions(+), 4 deletions(-) diff --git a/internal/app/change_create.go b/internal/app/change_create.go index 621ef55b1..4d4bb0329 100644 --- a/internal/app/change_create.go +++ b/internal/app/change_create.go @@ -64,6 +64,13 @@ type ChangeCreateRequest struct { // It is normalized by domain.NormalizeBranchPrefix before it is validated, // digested, or stored; empty after normalization means unset. BranchPrefix string `json:"branch_prefix"` + // Hold captures the change already on hold: true writes hold: true, so no + // autonomous build selection picks it; nil or false writes the valueless + // hold: (not held). + Hold *bool `json:"hold,omitempty"` + // HoldReason is the optional "## Why on hold" section body, accepted only + // with Hold true in the same request. + HoldReason string `json:"hold_reason,omitempty"` } // ChangeCreateResult is the protocol-v1 document `change create` returns. It @@ -139,6 +146,11 @@ type changeCreatePayload struct { // absent: an explicit pr and an omitted field replay each other, and a // pre-0559 retry still replays. Deliverable string `json:"deliverable,omitempty"` + // The hold keys are omitempty, and Hold is true only for a held request, so + // a request carrying neither digests exactly as before hold existed and an + // older retry still replays. + Hold bool `json:"hold,omitempty"` + HoldReason string `json:"hold_reason,omitempty"` } func changeCreateSemanticPayload(req ChangeCreateRequest) changeCreatePayload { @@ -157,9 +169,14 @@ func changeCreateSemanticPayload(req ChangeCreateRequest) changeCreatePayload { AutoGroomable: req.AutoGroomable, BranchPrefix: normalizedBranchPrefix(req), Deliverable: normalizedDeliverable(req), + Hold: requestHeld(req), + HoldReason: req.HoldReason, } } +// requestHeld reports whether the request creates the change already on hold. +func requestHeld(req ChangeCreateRequest) bool { return req.Hold != nil && *req.Hold } + // normalizedDeliverable is the digested spelling of the request's deliverable: // the default "pr" digests exactly as an omitted field. func normalizedDeliverable(req ChangeCreateRequest) string { @@ -353,6 +370,14 @@ func validateChangeCreateShape(req ChangeCreateRequest) []StatusFinding { if msg := branchPrefixProblem(req.BranchPrefix); msg != "" { addShape(FCInvalidBranchPrefix, msg) } + // hold_reason rides only with hold: true and becomes the "## Why on hold" + // body; change.groom shares the same checks. + if req.HoldReason != "" { + if code, msg := holdReasonProblem(requestHeld(req), req.HoldReason); code != "" { + addShape(code, msg) + } + } + boundAuthored(&findings, "hold_reason", req.HoldReason) return findings } @@ -563,6 +588,8 @@ func (o changeCreateOp) Plan(ctx context.Context, st transaction.AttemptState) ( Why: o.req.Why, WhatChanges: o.req.WhatChanges, OutOfScope: o.req.OutOfScope, + Hold: requestHeld(o.req), + WhyOnHold: o.req.HoldReason, }) if err != nil { return transaction.MutationPlan{}, transaction.OperationResult{}, fmt.Errorf("change create: serializing record: %w", err) diff --git a/internal/app/change_create_test.go b/internal/app/change_create_test.go index 33c8df5c0..54bbf89ba 100644 --- a/internal/app/change_create_test.go +++ b/internal/app/change_create_test.go @@ -761,3 +761,156 @@ func TestChangeCreateDigestTreatsPRAsOmitted(t *testing.T) { t.Errorf("unset deliverable appears in the digest payload %s; it would change every pre-0559 digest", b) } } + +// TestChangeCreateHold pins capturing a change already on hold: hold: true is +// written (with the optional reason as the "## Why on hold" section) and decodes +// as held; an omitted hold writes a valueless hold: that decodes as not held. +func TestChangeCreateHold(t *testing.T) { + recPath := "docs/changes/active/0002-add-a-widget.md" + cases := []struct { + name string + hold *bool + reason string + wantLine string + wantSection bool + wantHeld bool + }{ + {"held with reason", boolPtr(true), "Needs a human sign-in.", "\nhold: true\n", true, true}, + {"held alone", boolPtr(true), "", "\nhold: true\n", false, true}, + {"omitted", nil, "", "\nhold:\n", false, false}, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + op := baseOp([]string{}) + op.req.Hold = c.hold + op.req.HoldReason = c.reason + plan, opRes := planFor(t, map[string]string{ + "docs/changes/active/0001-first.md": fixtureChange(1, "first"), + }, op) + if opRes.Refused { + t.Fatalf("unexpected refusal: %v", opRes.Findings) + } + rec := string(groomedRecordBytes(t, plan, recPath)) + if !strings.Contains(rec, c.wantLine) { + t.Errorf("record missing %q:\n%s", c.wantLine, rec) + } + wantSection := "\n## Why on hold\n\n" + c.reason + "\n" + if got := strings.Contains(rec, "## Why on hold"); got != c.wantSection { + t.Errorf("reason section present = %v, want %v:\n%s", got, c.wantSection, rec) + } + if c.wantSection && !strings.HasSuffix(rec, wantSection) { + t.Errorf("record does not end with %q:\n%s", wantSection, rec) + } + snap, err := buildCandidateSnapshot(op.eff, nil, []byte(rec), recPath) + if err != nil { + t.Fatalf("buildCandidateSnapshot: %v", err) + } + ch, out := snap.Change(2) + if out != domain.LookupFound { + t.Fatalf("created record not decodable as change 2") + } + if ch.Held() != c.wantHeld { + t.Errorf("Held() = %v, want %v", ch.Held(), c.wantHeld) + } + }) + } +} + +// TestChangeCreateHoldRefusals pins Review Focus 5 for change.create: an unusable +// hold_reason is refused before any engine call. +func TestChangeCreateHoldRefusals(t *testing.T) { + cases := []struct { + name string + hold *bool + reason string + code string + }{ + {"reason without hold", nil, "Needs a sign-in.", "hold-reason-without-hold"}, + {"reason with hold false", boolPtr(false), "Needs a sign-in.", "hold-reason-without-hold"}, + {"whitespace-only reason", boolPtr(true), " \n\t ", "invalid-hold_reason"}, + {"column-zero heading", boolPtr(true), "text\n## Heading\n", "invalid-hold_reason"}, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + req := validChangeCreateRequest() + req.Hold = c.hold + req.HoldReason = c.reason + engine := &recordingEngine{} + reader := &fakeChangeReader{pin: mainModePin([]string{"inline"})} + deps := PlanningDeps{Engine: engine, Reader: reader, Clock: testClock()} + + res := ChangeCreate(context.Background(), deps, "", req) + + if res.Result != ResultInvalidInput { + t.Fatalf("result = %q, want invalid-input", res.Result) + } + if len(engine.calls) != 0 { + t.Errorf("engine called %d times on a refused hold_reason, want 0", len(engine.calls)) + } + if !hasFindingCode(res.Findings, c.code) { + t.Errorf("missing finding %q; got %v", c.code, res.Findings) + } + }) + } +} + +// TestChangeCreateDigestUnchangedWithoutHold: a request carrying no hold keys +// digests exactly as the payload did before hold existed, so an older retry +// under the same request_id still replays; a held request digests differently. +func TestChangeCreateDigestUnchangedWithoutHold(t *testing.T) { + // legacyPayload is changeCreatePayload as it stood before the hold fields. + type legacyPayload struct { + Title string `json:"title"` + Type string `json:"type"` + Priority string `json:"priority"` + Why string `json:"why"` + WhatChanges string `json:"what_changes"` + OutOfScope string `json:"out_of_scope"` + DependsOn []int `json:"depends_on"` + StackedOn *int `json:"stacked_on"` + Related []int `json:"related"` + DiscoveredFrom []int `json:"discovered_from"` + ADRs []int `json:"adrs"` + AutoGroomable *bool `json:"auto_groomable,omitempty"` + BranchPrefix string `json:"branch_prefix,omitempty"` + Deliverable string `json:"deliverable,omitempty"` + } + req := validChangeCreateRequest() + req.DependsOn = []int{1} + req.AutoGroomable = boolPtr(true) + req.BranchPrefix = "hotfix" + legacy := legacyPayload{ + Title: req.Title, Type: req.Type, Priority: req.Priority, + Why: req.Why, WhatChanges: req.WhatChanges, OutOfScope: req.OutOfScope, + DependsOn: req.DependsOn, AutoGroomable: req.AutoGroomable, BranchPrefix: "hotfix", + } + want, err := canonicalDigest(OperationChangeCreate, legacy) + if err != nil { + t.Fatalf("canonicalDigest: %v", err) + } + got, err := canonicalDigest(OperationChangeCreate, changeCreateSemanticPayload(req)) + if err != nil { + t.Fatalf("canonicalDigest: %v", err) + } + if got != want { + t.Errorf("a request without hold keys digests %s, want the pre-hold %s", got, want) + } + held := req + held.Hold = boolPtr(true) + heldDigest, err := canonicalDigest(OperationChangeCreate, changeCreateSemanticPayload(held)) + if err != nil { + t.Fatalf("canonicalDigest: %v", err) + } + if heldDigest == want { + t.Error("a request with hold: true must digest differently") + } + reasoned := held + reasoned.HoldReason = "Needs a sign-in." + reasonDigest, err := canonicalDigest(OperationChangeCreate, changeCreateSemanticPayload(reasoned)) + if err != nil { + t.Fatalf("canonicalDigest: %v", err) + } + if reasonDigest == heldDigest { + t.Error("a hold_reason must change the digest") + } +} diff --git a/internal/app/schema_test.go b/internal/app/schema_test.go index 24c2c5e4e..2c027488e 100644 --- a/internal/app/schema_test.go +++ b/internal/app/schema_test.go @@ -158,7 +158,7 @@ func TestReflectDescriptorChangeCreateRequest(t *testing.T) { "request_id", "title", "type", "priority", "deliverable", "why", "what_changes", "out_of_scope", "depends_on", "stacked_on", "related", "discovered_from", "adrs", - "auto_groomable", "branch_prefix", + "auto_groomable", "branch_prefix", "hold", "hold_reason", } if !reflect.DeepEqual(keys, want) { t.Fatalf("keys = %v, want %v", keys, want) @@ -184,6 +184,12 @@ func TestReflectDescriptorChangeCreateRequest(t *testing.T) { if f := fieldByKey(t, d, "deliverable"); f.Repeated || f.Type != "string" || f.Required { t.Errorf("deliverable = %+v, want optional string", f) } + if f := fieldByKey(t, d, "hold"); f.Required || f.Repeated || f.Type != "bool" { + t.Errorf("hold = %+v, want optional non-repeated bool", f) + } + if f := fieldByKey(t, d, "hold_reason"); f.Required || f.Repeated || f.Type != "string" { + t.Errorf("hold_reason = %+v, want optional string", f) + } // Required set per Task 4's tags. wantRequired := map[string]bool{ diff --git a/internal/render/record.go b/internal/render/record.go index 98ff471f3..6f374f6b2 100644 --- a/internal/render/record.go +++ b/internal/render/record.go @@ -31,9 +31,14 @@ type NewChangeRecord struct { ADRs []domain.ADRID AutoGroomable *bool // nil ⇒ null (not auto-groomable) BranchPrefix string // already normalized by the app layer; "" ⇒ null + Hold bool // true ⇒ hold: true; false ⇒ a valueless hold: Why string // markdown body, no heading line WhatChanges string // markdown body, no heading line OutOfScope string // markdown body, no heading line + // WhyOnHold is the optional hold reason, a markdown body with no heading + // line; "" writes no section, otherwise "## Why on hold" follows + // "## Out of scope". + WhyOnHold string } // ChangeRecord serializes r as a canonical brand-new proposed change record. @@ -63,19 +68,33 @@ func ChangeRecord(r NewChangeRecord) ([]byte, error) { {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)}, {Name: "branch", Value: document.Null()}, {Name: "pr", Value: document.Null()}, {Name: "blocked_by", Value: document.Null()}, {Name: "reconciled", Value: document.Bool(false)}, } - body := joinSections( + sections := []string{ section("## Artifacts", artifactsBlockBody), section("## Why", r.Why), section("## What changes", r.WhatChanges), section("## Out of scope", r.OutOfScope), - ) - return document.New(fields, body) + } + if r.WhyOnHold != "" { + sections = append(sections, section("## Why on hold", r.WhyOnHold)) + } + return document.New(fields, joinSections(sections...)) +} + +// holdValue renders the hold field: a held record states hold: true, and an +// unheld one carries the canonical valueless null, so every new record names +// the field. +func holdValue(held bool) document.Value { + if held { + return document.Bool(true) + } + return document.Null() } // deliverableOrDefault renders an unset deliverable as pr, so every new diff --git a/internal/render/record_test.go b/internal/render/record_test.go index 46da78a7d..9a3d59442 100644 --- a/internal/render/record_test.go +++ b/internal/render/record_test.go @@ -269,3 +269,50 @@ func TestChangeRecordWritesDeliverableAfterType(t *testing.T) { } } } + +// TestChangeRecordHold pins the hold field and its optional reason section: a +// held record writes hold: true directly after auto_groomable, an unheld one a +// valueless hold:, and a reason lands as the "## Why on hold" section after +// "## Out of scope". +func TestChangeRecordHold(t *testing.T) { + base := render.NewChangeRecord{ + ID: 1, Slug: "s", Title: "T", Type: "feat", Priority: "medium", Created: goldenDate, + Why: "w", WhatChanges: "c", OutOfScope: "oos", + } + + held := base + held.Hold = true + got, err := render.ChangeRecord(held) + if err != nil { + t.Fatalf("ChangeRecord: %v", err) + } + if s := string(got); !strings.Contains(s, "\nauto_groomable:\nhold: true\nbranch_prefix:\n") { + t.Errorf("held record missing hold: true after auto_groomable:\n%s", s) + } + if strings.Contains(string(got), "## Why on hold") { + t.Errorf("held record without a reason wrote the reason section:\n%s", got) + } + + unheld, err := render.ChangeRecord(base) + if err != nil { + t.Fatalf("ChangeRecord: %v", err) + } + if s := string(unheld); !strings.Contains(s, "\nauto_groomable:\nhold:\nbranch_prefix:\n") { + t.Errorf("unheld record missing valueless hold:\n%s", s) + } + + reasoned := held + reasoned.WhyOnHold = "Needs a sign-in." + got, err = render.ChangeRecord(reasoned) + if err != nil { + t.Fatalf("ChangeRecord: %v", err) + } + if s := string(got); !strings.HasSuffix(s, "## Out of scope\n\noos\n\n## Why on hold\n\nNeeds a sign-in.\n") { + t.Errorf("reason section not appended after Out of scope:\n%s", s) + } + for _, b := range [][]byte{got, unheld} { + if _, err := document.Parse(b); err != nil { + t.Errorf("record does not reparse: %v", err) + } + } +} diff --git a/internal/render/testdata/records/change.golden.md b/internal/render/testdata/records/change.golden.md index f817c216c..53cf6b5f7 100644 --- a/internal/render/testdata/records/change.golden.md +++ b/internal/render/testdata/records/change.golden.md @@ -18,6 +18,7 @@ plan: results: trivial: false auto_groomable: +hold: branch_prefix: branch: pr: From afceb1f78d16596179d2c67e83cca8487ce5c7db Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Sun, 18 Oct 2026 23:00:49 -0400 Subject: [PATCH 08/10] docs(skills): grooming can put a change on hold; implement-next skips it unless named --- internal/assets/embedded/manifest.json | 26 +++++++------- .../tree/skills/docket-auto-groom/SKILL.md | 6 ++-- .../tree/skills/docket-convention/SKILL.md | 6 ++-- .../tree/skills/docket-groom-next/SKILL.md | 2 ++ .../skills/docket-implement-next/SKILL.md | 10 +++--- .../tree/skills/docket-new-change/SKILL.md | 2 +- .../tree/skills/docket-status/SKILL.md | 2 +- internal/repoguard/budgets_test.go | 12 +++---- internal/repoguard/prose_contracts_test.go | 36 +++++++++++++++++++ skills/docket-auto-groom/SKILL.md | 6 ++-- skills/docket-convention/SKILL.md | 6 ++-- skills/docket-groom-next/SKILL.md | 2 ++ skills/docket-implement-next/SKILL.md | 10 +++--- skills/docket-new-change/SKILL.md | 2 +- skills/docket-status/SKILL.md | 2 +- 15 files changed, 89 insertions(+), 41 deletions(-) diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index 2c205c305..73932fdc3 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:0ccdcd5ae676726aee8a92a9fbb325556feb1a71ce5701013722e0399940fec0", + "asset_set_id": "sha256:c52083791cb7278c71bf9692cf0fe35e4d677a81b93accde3fd52458f3aeea84", "entries": [ { "path": ".docket.example.yml", @@ -280,8 +280,8 @@ "path": "skills/docket-auto-groom/SKILL.md", "role": "skill", "mode": 420, - "size": 11338, - "sha256": "d4f4404e9183aece4b3c9c7f6c827bbcf46c315b792315909537e404feea385c" + "size": 11651, + "sha256": "94ba139f727b8d5adb50f378b41be03d400c3d04cd172a736e0c7ae69fca1d0b" }, { "path": "skills/docket-brainstorm/SKILL.md", @@ -322,8 +322,8 @@ "path": "skills/docket-convention/SKILL.md", "role": "skill", "mode": 420, - "size": 53256, - "sha256": "c627651f6e3c32aafd6f16d01c1cebf148abf294ed1a0250d6399b4104808d3e" + "size": 53753, + "sha256": "46f39cae61f74ff14a8fdc5a5878c3d7fe8a6f9ade4e43e57817c23ee76b8cfe" }, { "path": "skills/docket-convention/references/agent-layer.md", @@ -371,15 +371,15 @@ "path": "skills/docket-groom-next/SKILL.md", "role": "skill", "mode": 420, - "size": 15747, - "sha256": "bf9848b5007cc5bc6fbe84fa026ad149cfdd796a17387ec8e8d52e31633bb2e7" + "size": 16321, + "sha256": "70e449f09fb60e75747c4c6885104aa34a9241718e29cc8291c30e843ebb2290" }, { "path": "skills/docket-implement-next/SKILL.md", "role": "skill", "mode": 420, - "size": 58728, - "sha256": "6bb121bc2fe047c17220ff4f14ecfd38e24609c3b29002bb7f799a6ce2dfd21f" + "size": 58927, + "sha256": "e8b69c3e9979e5b330f5e1952c09667808bb61ace77b1a09494b4f8b4cec631e" }, { "path": "skills/docket-implement-next/references/edge-paths.md", @@ -413,8 +413,8 @@ "path": "skills/docket-new-change/SKILL.md", "role": "skill", "mode": 420, - "size": 11161, - "sha256": "c0ca8dbea034ef61225cc0e7a0f5e26e813948561e321a337776bee164a1a787" + "size": 11385, + "sha256": "dd38825949fa7a25427f4a2ef4baaf06b8664365f21bf5506fb9207d4d8d5cdd" }, { "path": "skills/docket-review/SKILL.md", @@ -427,8 +427,8 @@ "path": "skills/docket-status/SKILL.md", "role": "skill", "mode": 420, - "size": 20084, - "sha256": "bb8faf8286bea3197159d15d46ece191712d4512ef7fccb79bf42b58215031ff" + "size": 20143, + "sha256": "891b4ed127a7d48e7579790e226c7f1c1feff4351dfc318b23b99dcc72c1516c" } ] } diff --git a/internal/assets/embedded/tree/skills/docket-auto-groom/SKILL.md b/internal/assets/embedded/tree/skills/docket-auto-groom/SKILL.md index 8625279a3..7f3ccd763 100644 --- a/internal/assets/embedded/tree/skills/docket-auto-groom/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-auto-groom/SKILL.md @@ -37,7 +37,7 @@ Read the stub body, its `related`/`depends_on` neighbours (active + recently arc ### Step 3 — Critic pass -Dispatch the dedicated **`docket-auto-groom-critic`** subagent (foreground, at the model/effort its wrapper resolves) — a fresh subagent (never the designer reviewing itself), isolated in its own context, loading only `docket-convention` and never this designer skill — to adversarially attack the draft — specs and trivial verdicts alike. Per assumption, one verdict: **sound** (stands) · **wrong but fixable from available context** (designer revises; ONE bounded revision round; the critic re-checks only the revised items — this re-check is dispatched foreground exactly like the first pass, per the convention's *Composition* never-yield rule) · **needs human context** (⇒ the whole groom abstains — a spec must only be emitted when every decision in it is safe to auto-commit, because emission = build-ready = the autonomous builder will build it). If no dispatch mechanism resolves per the convention's *Dispatch-capability resolution* — never from a tool name — the `docket-auto-groom-critic` dispatch's fallback is **`abstain`**: the groom **abstains** for that stub (→ Step 4's **Abstain** exit) rather than self-reviewing — an author cannot be their own adversarial gate. +Dispatch the dedicated **`docket-auto-groom-critic`** subagent (foreground, at the model/effort its wrapper resolves) — a fresh subagent (never the designer reviewing itself), isolated in its own context, loading only `docket-convention` and never this designer skill — to adversarially attack the draft — specs and trivial verdicts alike. Per assumption, one verdict: **sound** (stands) · **wrong but fixable from available context** (designer revises; ONE bounded revision round; the critic re-checks only the revised items — this re-check is dispatched foreground exactly like the first pass, per the convention's *Composition* never-yield rule) · **needs human context** (⇒ the whole groom abstains — a spec must only be emitted when every decision in it is safe to auto-commit, because emission = build-ready = the autonomous builder will build it unless held). If no dispatch mechanism resolves per the convention's *Dispatch-capability resolution* — never from a tool name — the `docket-auto-groom-critic` dispatch's fallback is **`abstain`**: the groom **abstains** for that stub (→ Step 4's **Abstain** exit) rather than self-reviewing — an author cannot be their own adversarial gate. **Receiving the verdict.** The verdict is read from the critic's **return** — its final report, which the groom is actively blocking on; the groom never backgrounds the critic. The groom never waits for a message, a notification, or any other out-of-band delivery: nothing is registered to deliver one, so that wait never ends. @@ -49,6 +49,8 @@ Dispatch the dedicated **`docket-auto-groom-critic`** subagent (foreground, at t 2. **Trivial** — the critic confirmed no hidden design decisions: apply the `change.groom` operation with `--repo-dir --request ` with `outcome: trivial`, the pinned `path` + `revision`, and an owned-section edit carrying the tightened body and its reasoning as the trivial rationale. The transaction sets `trivial: true` + `updated:` and re-renders the `## Artifacts` block and inline board atomically. Build-ready, no spec. 3. **Abstain** — any needs-human-context verdict, or Step 3's exhausted no-verdict posture: emit NO spec; apply the `change.groom` operation with `--repo-dir --request ` with `outcome: abstain`, the pinned `path` + `revision`, and a `blocked_note` — the undecidable decision(s), what context is missing, what a human should supply, and any recommendation (including "this should probably be killed/deferred because …"), with subsections at `###` or deeper. The transaction sets `auto_groomable: false` + `updated:`, appends a dated entry to the `## Auto-groom blocked` section, and re-renders the inline board — the row flips to **auto-groom blocked — needs you** in that same commit. It accepts no section, spec, or relationship edits. The stub stays needs-grooming, first in `docket-groom-next`'s queue. +**Hold.** When the emitted spec or trivial verdict names a step a person must carry out, add `hold: true` to that exit's request, plus a one-line `hold_reason` only when the stub has no `## Why on hold` section; never send `hold: false` — lifting a hold is a person's call. + **Kill and defer are NEVER autonomous.** Verdict authority over the backlog's composition stays human; the strongest the drain may say is an abstain-with-recommendation. ### Step 5 — The outcome lands (no separate board pass) @@ -57,7 +59,7 @@ Every exit's Step-4 `change.groom` operation is the whole write — it re-checks ### Step 6 — Report -Summarize the drain: groomed N (specs), trivial M, abstained K — each abstain with its one-line reason — plus anything skipped to a lost race. STOP. Grooming never implements; the build-ready output is `docket-implement-next`'s queue. +Summarize the drain: groomed N (specs), trivial M, abstained K — each abstain with its one-line reason — plus each change it held and anything skipped to a lost race. STOP. Grooming never implements; the build-ready output is `docket-implement-next`'s queue. ## Termination & concurrency diff --git a/internal/assets/embedded/tree/skills/docket-convention/SKILL.md b/internal/assets/embedded/tree/skills/docket-convention/SKILL.md index 0d7224c39..32de42c90 100644 --- a/internal/assets/embedded/tree/skills/docket-convention/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-convention/SKILL.md @@ -189,6 +189,7 @@ plan: # plan FILE on the metadata branch; FILE and FIELD wri 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 branch: # minted / (or /) name, set on claim; sole feature-head source of truth after, never reconstructed; branch itself created at build (step 4) pr: # set when the PR is opened @@ -228,6 +229,7 @@ change, never in the frozen artifact. - `## Run halted` — written by the `change.halt` operation when an autonomous run stops needing a human (the `halted` disposition); the heading is **bare**, never dated — the reader is a whole-line match, so the date sits inside the body. **Marker-section state**, in the same family as `## Auto-groom blocked` and `## Finalize blocked`: while the section is present the `run.verify` operation reports `run-halted`, which is what makes a `halted` disposition verifiable in git rather than a claim in a completion report. It is removed by the `change.resume-halted` operation, and by the claim when a halted change is claimed again. - `## Build evidence` — the build-evidence block for the certified feature head, written by `change.mark-implemented`, `finalize.publish`, and `evidence.recertify`; never hand-edited. - `## Why deferred` / `## Why killed` — added when entering those states. +- `## Why on hold` — the optional hold reason, written only by the `hold_reason` key; lifting the hold removes it. The change body is a **PM-altitude proposal** (intent + scope). Detailed design lives in the linked superpowers spec; the task breakdown in the linked superpowers plan. Different zoom levels, no duplication. @@ -286,11 +288,11 @@ 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 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. ### 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`). +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 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. diff --git a/internal/assets/embedded/tree/skills/docket-groom-next/SKILL.md b/internal/assets/embedded/tree/skills/docket-groom-next/SKILL.md index 65e8aa13b..93a4b2141 100644 --- a/internal/assets/embedded/tree/skills/docket-groom-next/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-groom-next/SKILL.md @@ -65,6 +65,8 @@ All six exits reuse existing transitions — this skill introduces no new lifecy **Deliverable, type, and branch prefix.** The same four exits may also carry `deliverable` (`pr` or `results-artifact` — use `results-artifact` when the work ends in findings, not code), `type` (a configured change type), and `branch_prefix` (omit it to keep the current value, send `""` to clear it, or a value to set it); any one alone is a valid revise. Nothing is renamed — the next claim mints the branch from the new `type`/`branch_prefix`. A `results-artifact` change never stacks, so a request that would leave it carrying `stacked_on:`, or stacked on by another change, refuses with `results-artifact-not-stackable`. Abstain refuses all three (`invalid-deliverable`, `invalid-type`, `invalid-branch_prefix`), and an unknown value refuses with `unknown-deliverable`, `unknown-type`, or `invalid-branch_prefix`; each writes nothing — surface it. +**Hold.** When the settled design needs a step a person must carry out, suggest a hold before the spec or trivial exit; the person decides. The same four exits may carry `hold` (`hold: true` sets it, `hold: false` lifts it, omitted keeps it; alone it is a valid revise), and an optional `hold_reason` (only with `hold: true`) writes `## Why on hold`, which lifting removes. A held change is skipped by autonomous build selection and built when named. Abstain refuses it (`invalid-hold`); `hold-reason-without-hold` and `invalid-hold_reason` write nothing — surface them. + **Stacking.** The same four exits may carry `stacked_on`: an id stacks or re-parents, `0` clears it (the fix for a killed stack parent), and omitted or `null` leaves it. Any relationship field alone is a valid revise. A negative value refuses with `invalid-stacked_on`, and changing `stacked_on` once the change has a `branch:` refuses with `not-restackable`; each writes nothing — surface it. ### Step 5 — The transaction lands (no separate board pass) 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 9b8bf01d0..89af8459d 100644 --- a/internal/assets/embedded/tree/skills/docket-implement-next/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-implement-next/SKILL.md @@ -26,7 +26,7 @@ Before anything else in this skill, invoke the `docket-convention` skill via the Run the convention's **startup check** (load the convention; run the capability bootstrap; run the `repository.prepare` operation with `--repo-dir --json` as its own Bash call; validate the protocol-v1 envelope and carry its typed context values forward as literals; act on the disposition). All bookkeeping in this skill (claim, reconcile, `status`, `pr:`, `plan:`, `adrs:`, the plan and results files, build evidence) lands in the metadata worktree (`metadata_worktree_path` in the `repository.prepare` context) on the metadata branch, pushed to the metadata remote (`metadata_remote`) immediately; only the spec copy and the code land on the feature branch. -**Named invocation — no maintenance preflight.** When this run was invoked with exactly **one explicit change id** — an initial named call, an attributed retry carrying the id, or a named resume of an in-progress change — skip the implementation preflight and Step 1's status-digest certification entirely: after the `repository.prepare` operation succeeds, go **directly** to the authoritative `context.implementation` operation with `--id ` and the existing claim/resume path. The named path never runs `maintenance.preflight` or any maintenance sweep first — another change's failing closeout, cleanup, or reclaim can never halt this change before its own claim/gate; anyone who wants those maintenance outcomes runs the explicit `maintenance.preflight` or `maintenance.sweep` operation deliberately, where every problem stays visible. Every local check for the named change is kept — readiness, record revision, dependencies, effective base, claim eligibility, run context, and resume/cancellation — so a malformed, absent, not-ready, or improperly resumed id returns its existing typed refusal, reported with its reason exactly as a scoped-id skip is (ending `drained` when nothing else is in scope); a named request **never falls back to selecting another change**, and shared repository/configuration/transport failures keep the `halted` posture. +**Named invocation — no maintenance preflight.** When this run was invoked with exactly **one explicit change id** — an initial named call, an attributed retry carrying the id, or a named resume of an in-progress change — skip the implementation preflight and Step 1's status-digest certification entirely: after the `repository.prepare` operation succeeds, go **directly** to the authoritative `context.implementation` operation with `--id ` and the existing claim/resume path. The named path never runs `maintenance.preflight` or any maintenance sweep first — another change's failing closeout, cleanup, or reclaim can never halt this change before its own claim/gate; anyone who wants those maintenance outcomes runs the explicit `maintenance.preflight` or `maintenance.sweep` operation deliberately, where every problem stays visible. Every local check for the named change is kept — readiness, record revision, dependencies, effective base, claim eligibility, run context, and resume/cancellation. A held change (`on-hold`) is built when named. So a malformed, absent, not-ready, or improperly resumed id returns its existing typed refusal, reported with its reason exactly as a scoped-id skip is (ending `drained` when nothing else is in scope); a named request **never falls back to selecting another change**, and shared repository/configuration/transport failures keep the `halted` posture. **The named change's own merged dependencies.** Skipping the sweep never declares a dependency satisfied. When the named path's `context.implementation` read refuses `not-ready-waiting-dependency`, **read `references/edge-paths.md` now (blocking)** for the bounded closeout of the named change's own `implemented` dependencies — never any other change's. @@ -36,11 +36,11 @@ Run the convention's **startup check** (load the convention; run the capability Build-readiness and ranking are defined by the convention's **Build-readiness & selection** section — that definition is the authority here, and this step only describes how to ACQUIRE the set it defines. -**Acquisition.** Run the `status` operation with `--json` — a write-free read; on the selection path, only AFTER Step 0's `maintenance.preflight` run and metadata re-sync (the snapshot is taken pre-sweep otherwise and would list already-merged changes). A named invocation takes no ready-queue digest — it arrives here already holding Step 0's directive to read the explicit-id bundle below. Validate the envelope before trusting it: `protocol_version` MUST be `1` and `operation` MUST be `status`. The top-level `ready` array IS the build-ready queue, already in the convention's deterministic order — final tie-break LOWEST `id`, so concurrent implementers converge on one winner. Per-change skip reasons come from each `changes[]` entry's `readiness` / `readiness_reason` fields (`readiness` vocabulary: `build-ready`, `needs-grooming`, `waiting-dependency`, `not-proposed`, `auto-groom-blocked`; `readiness_reason` carries the human-readable phrase). +**Acquisition.** Run the `status` operation with `--json` — a write-free read; on the selection path, only AFTER Step 0's `maintenance.preflight` run and metadata re-sync (the snapshot is taken pre-sweep otherwise and would list already-merged changes). A named invocation takes no ready-queue digest — it arrives here already holding Step 0's directive to read the explicit-id bundle below. Validate the envelope before trusting it: `protocol_version` MUST be `1` and `operation` MUST be `status`. The top-level `ready` array IS the build-ready queue, already in the convention's deterministic order — final tie-break LOWEST `id`, so concurrent implementers converge on one winner. Per-change skip reasons come from each `changes[]` entry's `readiness` / `readiness_reason` fields (`readiness` vocabulary: `build-ready`, `on-hold`, `needs-grooming`, `waiting-dependency`, `stack-base-unresolved`, `not-proposed`, `auto-groom-blocked`, `invalid`; `readiness_reason` carries the human-readable phrase). -The digest is an **accelerator, not the sole channel**: the authoritative read is the `context.implementation` operation with `--id ` (no `--id` applies the same selection policy; an attributed retry passes the id). It loads ONE fresh snapshot and returns the change's source bytes, exact opaque **record revision**, readiness, claim-eligibility, resolved effective base, integration branch, and workflow config — the single bundle the claim and every later operation key on, so no step re-reads the change file. **Judgment on that bundle stays yours.** CONFIRM build-readiness before claiming — a stale digest costs a re-pick, never a bad build; a typed no-candidate/absent-id/duplicate-id/not-ready/unsupported-config outcome is surfaced, never overridden. If the bundle disagrees with the digest, drop that candidate, take the next, and REPORT it. **The exit status and the envelope's shape together govern the disposition.** A **non-zero exit**, or stdout that will not parse as a JSON envelope, **is a hard error** (config export failure, refused bootstrap guard, missing metadata worktree, failed render, or malformed output) — surface its stderr diagnostic and STOP with the **`halted`** disposition; never fall back to `active/` for a hard error, and never report `drained` for one. On **exit 0** with a valid envelope, an **empty `ready` array** (`ready: []`) means the queue is genuinely empty → `drained`. A parseable envelope that is **missing the `ready` key altogether** is malformed machine output — **reject it and STOP with `halted`**, exactly as for a hard error: the typed contract always carries `ready`, so there is no walk-`active/`-yourself degradation. Likewise a failed `protocol_version`/`operation` check. +The digest is an **accelerator, not the sole channel**: the authoritative read is the `context.implementation` operation with `--id ` (no `--id` applies the same selection policy; an attributed retry passes the id). It loads ONE fresh snapshot and returns the change's source bytes, exact opaque **record revision**, readiness, claim-eligibility, resolved effective base, integration branch, and workflow config — the single bundle the claim and every later operation key on, so no step re-reads the change file. **Judgment on that bundle stays yours.** CONFIRM build-readiness before claiming — a stale digest costs a re-pick, never a bad build; a typed no-candidate/absent-id/duplicate-id/not-ready/unsupported-config outcome is surfaced, never overridden. If the bundle disagrees with the digest, drop that candidate, take the next, and REPORT it; on the selection path a bundle reporting `on-hold` is dropped and reported the same way. **The exit status and the envelope's shape together govern the disposition.** A **non-zero exit**, or stdout that will not parse as a JSON envelope, **is a hard error** (config export failure, refused bootstrap guard, missing metadata worktree, failed render, or malformed output) — surface its stderr diagnostic and STOP with the **`halted`** disposition; never fall back to `active/` for a hard error, and never report `drained` for one. On **exit 0** with a valid envelope, an **empty `ready` array** (`ready: []`) means the queue is genuinely empty → `drained`. A parseable envelope that is **missing the `ready` key altogether** is malformed machine output — **reject it and STOP with `halted`**, exactly as for a hard error: the typed contract always carries `ready`, so there is no walk-`active/`-yourself degradation. Likewise a failed `protocol_version`/`operation` check. -**Scope (id allowlist).** With no argument the candidate set is the whole `ready` queue. A caller may pass an **id allowlist** of two or more ids — `docket-implement-next 90,92,94` — and selection is then **restricted to that set**, preserving the queue's order *within* it. (A **single explicit id** is not an allowlist: it is a named invocation and takes Step 0's named branch, never this filter.) The allowlist is a filter, **never a dependency override**: a scoped id that is not currently build-ready+claimable — needs-grooming, already `in-progress`, or waiting on an unmerged `depends_on` — is **skipped with its reason** (read it off that id's `changes[]` entry — a non-`proposed` `status` there is skipped for that status — or from the change file if it has none — already archived, or no such id), never force-built, and never aborts the run. +**Scope (id allowlist).** With no argument the candidate set is the whole `ready` queue. A caller may pass an **id allowlist** of two or more ids — `docket-implement-next 90,92,94` — and selection is then **restricted to that set**, preserving the queue's order *within* it. (A **single explicit id** is not an allowlist: it is a named invocation and takes Step 0's named branch, never this filter.) The allowlist is a filter, **never a dependency override**: a scoped id that is not currently build-ready+claimable — needs-grooming, on hold, already `in-progress`, or waiting on an unmerged `depends_on` — is **skipped with its reason** (read it off that id's `changes[]` entry — a non-`proposed` `status` there is skipped for that status — or from the change file if it has none — already archived, or no such id), never force-built, and never aborts the run. **Empty queue → `drained`.** If no candidate in scope is build-ready+claimable, build nothing and end the run with the **`drained`** disposition (see *Terminal disposition*) — the driver's stop signal. @@ -189,7 +189,7 @@ disposition, a review outcome, "complete" — is by construction an aborted run, reports. `advanced` is claimable only when **Step 7's postcondition** or the **results-artifact ending's** holds — stated in *Step postconditions* above, not here. -The final report **enumerates** what happened: the change built (if any), each change **skipped with its reason** (needs-grooming / already `in-progress` / waiting on an unmerged `depends_on` / outside the id allowlist), any follow-up work **reported for deliberate capture**, each with its backlog verdict when final consolidation produced one (Step 6.5 *Backlog match*), and which disposition ended the run. +The final report **enumerates** what happened: the change built (if any), each change **skipped with its reason** (needs-grooming / on hold / already `in-progress` / waiting on an unmerged `depends_on` / outside the id allowlist), any follow-up work **reported for deliberate capture**, each with its backlog verdict when final consolidation produced one (Step 6.5 *Backlog match*), and which disposition ended the run. ### Atomic board rendering diff --git a/internal/assets/embedded/tree/skills/docket-new-change/SKILL.md b/internal/assets/embedded/tree/skills/docket-new-change/SKILL.md index d4f0b60e8..bc8736445 100644 --- a/internal/assets/embedded/tree/skills/docket-new-change/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-new-change/SKILL.md @@ -32,7 +32,7 @@ The default path for any non-trivial new change. Five steps: 4. **Create the proposed change** — submit the record through one atomic transaction: the `change.create` operation (resolve argv from the capability catalog) with `--repo-dir --request `. Its closed JSON request carries `title`, `type` (one configured `change_type` — `create` refuses an unknown or empty type, so no created change is ever left `untyped`, and there is no template comment to replace), `priority` (default `medium`), `deliverable: results-artifact` when the work ends in findings, not code (omit it for the default `pr`), the PM-altitude `why`/`what_changes`/`out_of_scope` body distilled from the brainstorm (design detail lives in the linked spec, NOT here), the resolved `depends_on`/`related`/`adrs`/`discovered_from` from step 3, `stacked_on` when the work builds on another change's **unmerged** branch (set it and **read [stacked-changes.md](../docket-convention/references/stacked-changes.md) now (blocking)** first — stacking changes how it is built, merged, and closed out), and the stable `request_id` from step 1. The transaction allocates the id, derives the slug, serializes the canonical `status: proposed` record (`created`/`updated` = the commit's UTC date), renders its `## Artifacts` block, and re-renders the inline board — one metadata commit under an exact-lease push, returning the new `id`/`slug`/`path`. - **Two draft-time scalars ride in the same request** — `auto_groomable` and `branch_prefix`. When the human says the change may be designed without them, send `auto_groomable: true` (so `docket-auto-groom` carries it to build-ready; `false` opts it out). When they name a branch prefix ("use the `hotfix/` prefix"), send it as typed in `branch_prefix` — the operation normalizes it and refuses an unusable value with `invalid-branch_prefix` before anything is written: show the human that finding and ask for a new value. Omit `auto_groomable` to leave the change not auto-groomable; omit `branch_prefix` to use ``. + **Two draft-time scalars ride in the same request** — `auto_groomable` and `branch_prefix`. When the human says the change may be designed without them, send `auto_groomable: true` (so `docket-auto-groom` carries it to build-ready; `false` opts it out). When they name a branch prefix ("use the `hotfix/` prefix"), send it as typed in `branch_prefix` — the operation normalizes it and refuses an unusable value with `invalid-branch_prefix` before anything is written: show the human that finding and ask for a new value. Omit `auto_groomable` to leave the change not auto-groomable; omit `branch_prefix` to use ``. When the design needs a step a person must carry out, suggest a hold; if the human agrees, send `hold: true` (and an optional `hold_reason`) here for a captured stub, or in the step-5 or trivial-path `change.groom` request. 5. **Groom to build-ready & land** — read the created record's `path` + exact **record revision** (blob object id) from the `status` operation (with `--json`), then apply the spec atomically: the `change.groom` operation with `--repo-dir --request ` carrying the change id, the pinned `path` + `revision`, `outcome: spec`, the `spec_markdown` from step 2, and any owned proposal-section rewrites. In one metadata commit the transaction writes the spec file, sets `spec:` + `updated:`, stamps the spec's `docket:backlink` block, re-renders the `## Artifacts` block, and re-renders the inline board (pushed under an exact-lease push) — **no separate Board pass**. A revision-mismatch / `contended` refusal writes nothing: re-sync (re-run the `repository.prepare` operation), re-read `path` + `revision`, retry. STOP. Never implements. To adjust a just-landed spec or its owned sections afterwards, run `docket-groom-next ` — its explicit-id path routes an already-groomed change to `change.groom` with `outcome: revise`; never re-run this skill or hand-edit the spec file. diff --git a/internal/assets/embedded/tree/skills/docket-status/SKILL.md b/internal/assets/embedded/tree/skills/docket-status/SKILL.md index bdb6f77dc..77fc4a0c8 100644 --- a/internal/assets/embedded/tree/skills/docket-status/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-status/SKILL.md @@ -103,7 +103,7 @@ The mechanics below live entirely in the Go operations — this is a compact map ### Board -Renders each surface in `board_surfaces` (config; default `[inline]`) from the same one dependency-resolution pass, computed once. Readiness cells: a dependency-waiting change shows **⏳ waiting on #N — not yet built** or **⏳ waiting on #N — needs your merge**; a `proposed` change with no spec, not `trivial: true`, and not waiting shows **needs-grooming** — or **auto-groom blocked — needs you** when its body carries an `## Auto-groom blocked` section. +Renders each surface in `board_surfaces` (config; default `[inline]`) from the same one dependency-resolution pass, computed once. Readiness cells: a dependency-waiting change shows **⏳ waiting on #N — not yet built** or **⏳ waiting on #N — needs your merge**; a `proposed` change with no spec, not `trivial: true`, and not waiting shows **needs-grooming** — or **auto-groom blocked — needs you** when its body carries an `## Auto-groom blocked` section; a held change that would be build-ready shows **on hold**. When `board_surfaces` includes `inline`, the docket app is the single gated writer of `BOARD.md`: every board-authoritative typed mutation re-renders it inside the owning metadata transaction and commits the result to the metadata branch in the same commit as the record it reflects, only when it actually changed, so nothing else ever touches the file. This skill **never hand-edits `BOARD.md`, never hand-renders it, and never 3-way merges it**; on a rebase conflict, let the owning operation regenerate it — never a hand-merge — and continue. When `board_surfaces` omits `inline`, there is simply no board. Where present, `BOARD.md` is the live planning view and stays on `docket` — never published to the integration branch. diff --git a/internal/repoguard/budgets_test.go b/internal/repoguard/budgets_test.go index 62fc8eea9..9c27f2f04 100644 --- a/internal/repoguard/budgets_test.go +++ b/internal/repoguard/budgets_test.go @@ -187,7 +187,7 @@ type skillBudget struct { // exact new counts. var skillBudgets = []skillBudget{ {"docket-adr/SKILL.md", 86, 1143}, // 0531: the metadata worktree and remote come from the repository.prepare context (86/1129 -> 86/1143); 0502: one metadata layout — the docket branch and the .docket/ worktree (86/1123 -> 86/1129); 0502: the adr-unpublished health-check text is deleted (86/1148 -> 86/1123); 0502: the deferred-publication section and narration are deleted (110/1600 -> 86/1148) - {"docket-auto-groom/SKILL.md", 64, 1638}, // 0532: the private-repository writing rule and visibility hand-off (64/1606 -> 64/1638); 0531: the metadata worktree and remote come from the repository.prepare context (64/1597 -> 64/1606); 0502: "loop" means /loop only (64/1596 -> 64/1597); 0502: one metadata layout — the docket branch and the .docket/ worktree (64/1595 -> 64/1596); 0502: the spec draft stays out of .docket/ (64/1572 -> 64/1595); 0502: auto-groom is per-change only (64/1582 -> 64/1572); 0502: the dummy-mode pointer is deleted (66/1625 -> 64/1582); 0382: typed change.groom abstain replaces the plain-git abstain commit prose (word ceiling 1750 -> 1627) + {"docket-auto-groom/SKILL.md", 66, 1695}, // 0560: a spec or trivial verdict needing a person's step is sent with hold: true; never hold: false (64/1638 -> 66/1695); 0532: the private-repository writing rule and visibility hand-off (64/1606 -> 64/1638); 0531: the metadata worktree and remote come from the repository.prepare context (64/1597 -> 64/1606); 0502: "loop" means /loop only (64/1596 -> 64/1597); 0502: one metadata layout — the docket branch and the .docket/ worktree (64/1595 -> 64/1596); 0502: the spec draft stays out of .docket/ (64/1572 -> 64/1595); 0502: auto-groom is per-change only (64/1582 -> 64/1572); 0502: the dummy-mode pointer is deleted (66/1625 -> 64/1582); 0382: typed change.groom abstain replaces the plain-git abstain commit prose (word ceiling 1750 -> 1627) {"docket-brainstorm/SKILL.md", 83, 722}, // 0532: the private-repository writing rule and visibility hand-off (81/690 -> 83/722); 0502 review: the scope stop names new-change Steps 3–5 accurately (81/685 -> 81/690); 0502: the role runs on a human request, not a binding (80/671 -> 81/680); 0502: drop change citations and Go v1 narration (81/680 -> 81/679); 0502: description names the human request, no binding or change citation (81/679 -> 81/685) {"docket-build/SKILL.md", 386, 3878}, // 0532: the private-repository writing rule and visibility hand-off (384/3852 -> 386/3878); 0531: the metadata worktree and remote come from the repository.prepare context (384/3851 -> 384/3852); 0502: the install operation replaces install.sh; the wrapper skills list (385/3850 -> 385/3856); 0502: the observation-budget and build-checkpoint export reads are deleted (395/3942 -> 385/3850); 0502: fixed build role; undispatchable tier halts (398/3974 -> 395/3942); 0502: the gate-execution pointer paragraph is deleted with the reference (403/4007 -> 398/3974); 0493: the gate relaunch is retired (404/4023 -> 403/4007); 0491: the run id is retired (406/4037 -> 404/4023); 0488 review fix: +the dispatch payload names the branch (406/4034 -> 406/4037); 0488 review: build-owned starts carry --change-id/--run-context (404/4018 -> 406/4034); 0488: workers run tests directly; the dispatch payload carries no worker scope identity, the task-level WAITING/takeover section is gone, the controller runs every post-repair attempt, +time-limit audit (439/4479 -> 404/4018); 0467 review fix: +the repair dispatch payload carries the run id for the build-owned post-fix re-run (436/4443 -> 439/4479); 0467: +run-id threading on prepare-scope and the build-owned start; the bundle carries no run id (432/4391 -> 436/4443); 0459: +continuation carries the claimed verdict, closed-scope statement, and fresh prepare-scope bundle (424/4284 -> 432/4391); 0405: sequential-drive contract; 0420: shell-safe capture; 0421: budgeted repair cycle (see note above); 0502: drop change citations and Go v1 narration (385/3856 -> 384/3851) // 0154: docket-build/references/delegation-execution.md removed — it was the @@ -196,7 +196,7 @@ var skillBudgets = []skillBudget{ {"docket-build/references/gate-driver.md", 138, 1552}, // 0502 review: the raw-verb section names finalize's repaired-head re-gate (137/1546 -> 138/1552); 0502: "loop" means /loop only (137/1550 -> 137/1546); 0502: finalize's repaired-head re-gate is a direct caller (136/1523 -> 137/1550); 0502: the gate-execution intro reference is deleted (138/1555 -> 136/1523); 0502: renamed from gate-caller-loop.md; 0497: +halted-gate tree-survives finding relay (134/1510 -> 138/1555); 0491: the run id is retired (134/1513 -> 134/1510); 0490: the admission section describes the supervisor-held worktree lock; launch-unconfirmed is no longer a refusal (136/1511 -> 134/1513); 0488 review fix: finalize reaches the driver only through finalize.rebase; task-era handoff clauses dropped (word ceiling 1504 -> 1511); 0488 review: start row carries --change-id (word ceiling 1491 -> 1504); 0488: worker-scope/takeover/acknowledge rows and the parent-takeover section removed; callers are the full-suite gates (175/1872 -> 136/1491); 0467: +prepare-scope --run-id and scope-inherited start run id (word ceiling 1826 -> 1872); 0375: +worktree-admission section (word ceiling 1750 -> 1826) {"docket-build/references/task-routing.md", 50, 500}, {"docket-build-task/SKILL.md", 173, 1695}, // 0532: the private-repository writing rule and visibility hand-off (168/1640 -> 173/1695); 0531: the metadata worktree and remote come from the repository.prepare context (168/1637 -> 168/1640); 0488: scoped drive protocol replaced by direct foreground tests under timeout; three outcomes (211/2235 -> 168/1637); 0467 review fix: +the repair re-run run-id exception (206/2183 -> 211/2235); 0467: +the run id rides on the scope, never the bundle (204/2151 -> 206/2183); 0459: +post-handoff continuation never acknowledges or reuses the transferred scope (188/1964 -> 204/2151); 0405: sequential-drive receipt and acknowledgement; 0420: shell-safe capture; 0375: worktree-busy-not-a-retry rule (179/1842 -> 188/1964) - {"docket-convention/SKILL.md", 360, 7331}, // 0565: a kill refuses on built stacked descendants; the killed-parent board text and exits table (360/7317 -> 360/7331); 0568: deferred is entered only from proposed (363/7317 -> 360/7317); 0559: the manifest lists deliverable; done means a merged PR or a completed results artifact; archive dates and change.complete (361/7276 -> 363/7317); 0533: editing visibility never moves a repository; repository.set-visibility does (361/7263 -> 361/7276); 0532: the private-repository writing rule and visibility hand-off (359/7160 -> 361/7263); 0531 review: skills say "the metadata branch", naming `docket` once for shared mode (359/7155 -> 359/7160); 0531: the metadata worktree and remote come from the repository.prepare context (357/7062 -> 359/7155); 0530: plan, results, and build evidence live on the docket branch — the plan-writer's one metadata operation, the attach operations as file-backlink writers, relative same-branch links, and the new ## Build evidence record section (357/7026 -> 357/7062); 0529 review: the backlink block names its PR-body writers beside artifact.backlink, one shared renderer (357/7004 -> 357/7026); 0515: the repair sign-off is retired; a green repair merges (357/7007 -> 357/7004); 0502 rebase onto 0510: kept the backlog-match follow-up clause in the results-artifact paragraph (357/7004 -> 357/7007); 0502 review: the review-tier dispatch is the controller's own (357/6995 -> 357/7004); 0502: configuration read paths corrected — operations read .docket.yml from origin's default-branch tip, the repository setup operations from the primary worktree (357/6959 -> 357/6995); 0502: "loop" means /loop only (357/7036 -> 357/7037); 0502: one metadata layout — the docket branch and the .docket/ worktree (357/7035 -> 357/7036); 0502: agent layer names user-level wrappers and global-only pins (357/7024 -> 357/7035); 0502: typed operations replace the Bash-era script names; ## Run halted facts corrected (359/7092 -> 357/7024); 0502: terminal publish, the learnings cap, and the repository auto_groom default are deleted (362/7256 -> 359/7092); 0502: the auto-capture export paragraph is deleted (370/7334 -> 362/7256); 0502: the configuration contract rewritten from the schema (371/7488 -> 370/7334); 0502: fixed role skills; halt posture (372/7660 -> 371/7488); 0502: record blocks mirror the renderers (367/7619 -> 372/7660); 0502: the dummy-mode shared definition is deleted (390/7848 -> 367/7619); 0410: +required-results lifecycle prose; 0399: +schema request/result contract prose; 0388: +sync-integration prose (see note above); 0502: drop change citations and Go v1 narration (357/7037 -> 357/6958); 0502: the harness adapter is named without a docket source path (357/6958 -> 357/6959) + {"docket-convention/SKILL.md", 362, 7411}, // 0560: the hold manifest field, its selection rule, the ## Why on hold section, and the auto-groomer's hold write (360/7331 -> 362/7411); 0565: a kill refuses on built stacked descendants; the killed-parent board text and exits table (360/7317 -> 360/7331); 0568: deferred is entered only from proposed (363/7317 -> 360/7317); 0559: the manifest lists deliverable; done means a merged PR or a completed results artifact; archive dates and change.complete (361/7276 -> 363/7317); 0533: editing visibility never moves a repository; repository.set-visibility does (361/7263 -> 361/7276); 0532: the private-repository writing rule and visibility hand-off (359/7160 -> 361/7263); 0531 review: skills say "the metadata branch", naming `docket` once for shared mode (359/7155 -> 359/7160); 0531: the metadata worktree and remote come from the repository.prepare context (357/7062 -> 359/7155); 0530: plan, results, and build evidence live on the docket branch — the plan-writer's one metadata operation, the attach operations as file-backlink writers, relative same-branch links, and the new ## Build evidence record section (357/7026 -> 357/7062); 0529 review: the backlink block names its PR-body writers beside artifact.backlink, one shared renderer (357/7004 -> 357/7026); 0515: the repair sign-off is retired; a green repair merges (357/7007 -> 357/7004); 0502 rebase onto 0510: kept the backlog-match follow-up clause in the results-artifact paragraph (357/7004 -> 357/7007); 0502 review: the review-tier dispatch is the controller's own (357/6995 -> 357/7004); 0502: configuration read paths corrected — operations read .docket.yml from origin's default-branch tip, the repository setup operations from the primary worktree (357/6959 -> 357/6995); 0502: "loop" means /loop only (357/7036 -> 357/7037); 0502: one metadata layout — the docket branch and the .docket/ worktree (357/7035 -> 357/7036); 0502: agent layer names user-level wrappers and global-only pins (357/7024 -> 357/7035); 0502: typed operations replace the Bash-era script names; ## Run halted facts corrected (359/7092 -> 357/7024); 0502: terminal publish, the learnings cap, and the repository auto_groom default are deleted (362/7256 -> 359/7092); 0502: the auto-capture export paragraph is deleted (370/7334 -> 362/7256); 0502: the configuration contract rewritten from the schema (371/7488 -> 370/7334); 0502: fixed role skills; halt posture (372/7660 -> 371/7488); 0502: record blocks mirror the renderers (367/7619 -> 372/7660); 0502: the dummy-mode shared definition is deleted (390/7848 -> 367/7619); 0410: +required-results lifecycle prose; 0399: +schema request/result contract prose; 0388: +sync-integration prose (see note above); 0502: drop change citations and Go v1 narration (357/7037 -> 357/6958); 0502: the harness adapter is named without a docket source path (357/6958 -> 357/6959) // 0154: docket-convention/github-board-mirror.md removed — the GitHub mirror is // retired (unsupported, mutation-blocking); its budget row is deleted with it. {"docket-convention/references/agent-layer.md", 214, 1990}, // 0552: the user-level settings.json also carries the finalize allow rules (212/1951 -> 214/1990); 0546: the per-agent cache_ttl pin, its shipped 1h default, and the machine-wide controls docket leaves unset (168/1593 -> 212/1951); 0538: init and repository.configure-harnesses set agent_harnesses; repository.check reports harnesses-unset (164/1553 -> 168/1593); 0535: a private repository's instructions file and its user-level triggers (148/1419 -> 164/1553); 0502: rewritten around user-level wrappers and global-only pins (202/2346 -> 148/1419); 0502: the legacy agents-file migration clause is deleted (202/2349 -> 202/2346) @@ -205,15 +205,15 @@ var skillBudgets = []skillBudget{ {"docket-convention/references/stacked-changes.md", 223, 2217}, // 0567: carried children are cleaned right after the root once their work is proven (219/2173 -> 223/2217); 0565: a kill refuses on built stacked descendants; the killed-parent board text and exits table (214/2149 -> 219/2173); 0502: typed operations and binary-emitted findings replace the Bash-era names (213/2125 -> 214/2149); 0502: the deferred descendant-publication sentence is deleted (215/2140 -> 213/2125); 0327: +carry-preservation contract prose (see note above) {"docket-finalize-change/SKILL.md", 243, 6254}, // 0567: step 10 cleans each carried_ids child after the root (243/6191 -> 243/6254); 0551: step 1 checks the change out into its own workspace first (241/6033 -> 243/6191); 0532 review: both finalize gate dispatches carry the Visibility payload line (239/6020 -> 241/6033); 0532: the private-repository writing rule and visibility hand-off (239/6000 -> 239/6020); 0529 review: the PR-backlink repoint is a best-effort follow-up after the archive push, for root-archived descendants too (239/5984 -> 239/6000); 0529: close-out repoints the merged PR description's backlink; pr-backlink-pending is a retryable warning (239/5936 -> 239/5984); 0525 review: workspace-remnant rides any finished-workspace disposition and is named in the final report; branch-rules-unavailable comes only from the probing run (239/5910 -> 239/5936); 0525: plan-gated merges carry branch-rules-unavailable into closeout notes; cleanup reports workspace-remnant and names what blocked a workspace (239/5820 -> 239/5910); 0515 review: the refused-notes fallback names every dropped note in the final report (238/5809 -> 239/5820); 0515 review: a repair whose run halts before closeout is named in finalize.block and carried into a later closeout (238/5708 -> 238/5809); 0515: the repair sign-off is retired; a green repair merges (238/5808 -> 238/5708); 0517: the repaired-head evidence.record carries --owner finalize and records finalize.test_command (238/5790 -> 238/5808); 0502 review: clear-block re-reads the revision after the block lands (238/5771 -> 238/5790); 0502: repair sign-off records finalize.block before publishing the repaired head (238/5733 -> 238/5771); 0502: "loop" means /loop only (238/5729 -> 238/5733); 0502: repair sign-off is the human running finalize.clear-block (238/5666 -> 238/5729); 0502: the repaired head is re-gated through the gate driver (236/5568 -> 238/5666); 0502: the dummy-mode paragraph is deleted (238/5641 -> 236/5568); 0455: +record-invalid refusal (structural scope, findings remedy, merged-outside-docket precedence) in step 8 (word ceiling 5520 -> 5647); 0442: +post-publication base-advance guidance (word ceiling 5421 -> 5520); de-duplicated the shared forward-rebase mechanic against the 0438 unpublished-case paragraph (reclaimed 57 words), but the distinct published-refresh facts plus the retained 0438 guidance cannot fit the old ceiling without deleting required guidance; 0411: +reconciliation-write recovery exception paragraph in the resolver loop (ceilings 238/5232 -> 239/5421); 0413: +generated-bundle mixed-conflict handoff sentence in the resolver-loop block (word ceiling 5200 -> 5232); 0419: +repair-attempt budget payload line and rewired repair contract (line ceiling 236 -> 238); 0393: +exact payload, marker, and direct-dispatch lines atop 0349/0410 (see note above) {"docket-finalize-change/references/gate-failure.md", 162, 2111}, // 0532 review: the gate-agent payload names Visibility (161/2109 -> 162/2111); 0515 review: the refused-notes fallback names every dropped note in the final report (160/2098 -> 161/2109); 0515 review: a repair whose run halts before closeout is named in finalize.block and carried into a later closeout (153/2005 -> 160/2098); 0515: the repair sign-off is retired; a green repair merges (160/2086 -> 153/2005); 0517: the repaired-head evidence.record carries --owner finalize (159/2081 -> 160/2086); 0502 review: clear-block re-reads the revision after the block lands (157/2062 -> 159/2081); 0502: repair sign-off records finalize.block before publishing the repaired head (155/2028 -> 157/2062); 0502: the embedded-bundle rule is conditioned on docket's own repository (155/2024 -> 155/2028); 0502: "loop" means /loop only (155/2027 -> 155/2024); 0502: repair sign-off is the human running finalize.clear-block; the marker lifecycle names what removes it (154/2013 -> 155/2027); 0502: the repaired head is re-gated through the gate driver (148/1937 -> 154/2013); 0497: +wait-for-the-leftover-group sentence (146/1901 -> 148/1937); 0493: the gate relaunch is retired (145/1892 -> 146/1901); 0491: the run id is retired (145/1894 -> 145/1892); 0490: the shared-slot note became the shared worktree-lock note (147/1901 -> 145/1894); 0411: +reconciliation-write exception section and abort-set carve-out (ceilings 135/1472 -> 147/1901); 0413: +conflicted_paths-lists-authored-only rule in the resolver-report section (line ceiling 133 -> 135, word ceiling 1465 -> 1472); 0419: +repair-attempt budget payload and rewired repair contract prose (word ceiling 1450 -> 1465); 0349: +reserve-before-dispatch resolver protocol prose; 0375: +worktree-slot note for the scopeless finalize gate (120/1300 -> 133/1450) - {"docket-groom-next/SKILL.md", 76, 2282}, // 0559: the Step-4 deliverable, type, and branch_prefix paragraph (78/2215 -> 76/2282); 0550: the Step-4 reprioritize paragraph and the stub-edit priority route (76/2141 -> 78/2215); 0532: the private-repository writing rule and visibility hand-off (76/2109 -> 76/2141); 0531: the metadata worktree and remote come from the repository.prepare context (76/2102 -> 76/2109); 0502 rebase onto 0509: carried the edit-a-stub revise route and groom-exit-scoped STOPs (76/2012 -> 76/2102); 0502: "loop" means /loop only (76/2011 -> 76/2012); 0502: one metadata layout — the docket branch and the .docket/ worktree (76/2010 -> 76/2011); 0502: selection bands key on auto_groomable itself (76/2009 -> 76/2010); 0502: invoke superpowers:brainstorming by name (76/2037 -> 76/2009); 0502: the dummy-mode pointer is deleted (78/2080 -> 76/2037); 0461: +Step-4 retitle paragraph (title on change.groom; lines 77 -> 78, words 1996 -> 2081); +not-retitleable refusal code (2081 -> 2082); 0382: +typed rearm exit (word ceiling 1889 -> 1996); 0445: +revise route for already-groomed explicit ids (Step 1) and the fifth Step-4 exit (word ceiling 1650 -> 1813); +spec_version pin for a spec-body revise (1813 -> 1849); +revise spec_markdown excludes the backlink block (1849 -> 1850); +revise in the description and the revise contended/board clauses (1850 -> 1889) - {"docket-implement-next/SKILL.md", 218, 8518}, // 0559: the results-artifact ending pointer, postcondition row, and advanced meaning (215/8411 -> 218/8518); 0532: the private-repository writing rule and visibility hand-off (212/8282 -> 215/8411); 0531: the metadata worktree and remote come from the repository.prepare context (216/8443 -> 212/8282); 0517: evidence.record reads the gate command from build configuration (216/8438 -> 216/8443); 0502 rebase onto 0510: carried the Step 6.5 Backlog match paragraph and verdict pointers (214/8039 -> 216/8438); 0502 review: the controller dispatches the review tier wrapper; the skill dispatches nothing (214/8023 -> 214/8039); 0502: "loop" means /loop only (214/8058 -> 214/8057); 0502: one metadata layout — the docket branch and the .docket/ worktree (214/8042 -> 214/8058); 0502: the review payload names the resolved build.gate value; build_gate spellings become build.gate (214/8020 -> 214/8042); 0502: change.reclaim replaces reclaim-claims; the claim removes a leftover ## Run halted (214/8009 -> 214/8020); 0502: terminal-publication narration is deleted (214/8037 -> 214/8009); 0502: the severity floor is read as review.min_fix_severity through diagnostic.config (214/8034 -> 214/8037); 0502: the fixed role skills replace the $SKILL_* sites (214/8257 -> 214/8034); 0502: the dummy-mode paragraph and PR-body clause are deleted (216/8356 -> 214/8257); 0497: +Step 5 halted-build evidence kept verbatim in ## Run halted (216/8325 -> 216/8356); 0498 review: checkpoint (ii) persist wording (8320 -> 8325); 0498: +Step 6.5 review-findings homes, condensation exception, Human-actions class rule (214/8161 -> 216/8320); 0491: the run id is retired (214/8183 -> 214/8161); 0488 review: build-owned starts carry --change-id/--run-context (word ceiling 8162 -> 8183); 0488: run context and run id name only build-owned starts (word ceiling 8175 -> 8162); 0467 review fix: +the repair worker's post-fix re-run is a build-owned start (word ceiling 8165 -> 8175); 0467: +run id threaded to prepare-scope and build-owned starts (word ceiling 8080 -> 8165); 0455: +pr.publish record-invalid refusal clause (word ceiling 8025 -> 8080); 0448: +named-invocation branch; bounded own-dependency closeout moved to edge-paths.md (ceilings 210/7716 -> 214/8270 -> 214/8025); 0393: +exact payload, marker, and direct-dispatch lines atop 0410/0354/0376; 0375: +run-tracker resume pointer (word ceiling 7530 -> 7547); 0440: reader-first results prose; 0502: drop change citations and Go v1 narration (214/8057 -> 214/8023) + {"docket-groom-next/SKILL.md", 78, 2370}, // 0560: the Step-4 hold paragraph (76/2282 -> 78/2370); 0559: the Step-4 deliverable, type, and branch_prefix paragraph (78/2215 -> 76/2282); 0550: the Step-4 reprioritize paragraph and the stub-edit priority route (76/2141 -> 78/2215); 0532: the private-repository writing rule and visibility hand-off (76/2109 -> 76/2141); 0531: the metadata worktree and remote come from the repository.prepare context (76/2102 -> 76/2109); 0502 rebase onto 0509: carried the edit-a-stub revise route and groom-exit-scoped STOPs (76/2012 -> 76/2102); 0502: "loop" means /loop only (76/2011 -> 76/2012); 0502: one metadata layout — the docket branch and the .docket/ worktree (76/2010 -> 76/2011); 0502: selection bands key on auto_groomable itself (76/2009 -> 76/2010); 0502: invoke superpowers:brainstorming by name (76/2037 -> 76/2009); 0502: the dummy-mode pointer is deleted (78/2080 -> 76/2037); 0461: +Step-4 retitle paragraph (title on change.groom; lines 77 -> 78, words 1996 -> 2081); +not-retitleable refusal code (2081 -> 2082); 0382: +typed rearm exit (word ceiling 1889 -> 1996); 0445: +revise route for already-groomed explicit ids (Step 1) and the fifth Step-4 exit (word ceiling 1650 -> 1813); +spec_version pin for a spec-body revise (1813 -> 1849); +revise spec_markdown excludes the backlink block (1849 -> 1850); +revise in the description and the revise contended/board clauses (1850 -> 1889) + {"docket-implement-next/SKILL.md", 218, 8548}, // 0560: on-hold joins the readiness vocabulary and skip reasons; a held change is built when named (218/8518 -> 218/8548); 0559: the results-artifact ending pointer, postcondition row, and advanced meaning (215/8411 -> 218/8518); 0532: the private-repository writing rule and visibility hand-off (212/8282 -> 215/8411); 0531: the metadata worktree and remote come from the repository.prepare context (216/8443 -> 212/8282); 0517: evidence.record reads the gate command from build configuration (216/8438 -> 216/8443); 0502 rebase onto 0510: carried the Step 6.5 Backlog match paragraph and verdict pointers (214/8039 -> 216/8438); 0502 review: the controller dispatches the review tier wrapper; the skill dispatches nothing (214/8023 -> 214/8039); 0502: "loop" means /loop only (214/8058 -> 214/8057); 0502: one metadata layout — the docket branch and the .docket/ worktree (214/8042 -> 214/8058); 0502: the review payload names the resolved build.gate value; build_gate spellings become build.gate (214/8020 -> 214/8042); 0502: change.reclaim replaces reclaim-claims; the claim removes a leftover ## Run halted (214/8009 -> 214/8020); 0502: terminal-publication narration is deleted (214/8037 -> 214/8009); 0502: the severity floor is read as review.min_fix_severity through diagnostic.config (214/8034 -> 214/8037); 0502: the fixed role skills replace the $SKILL_* sites (214/8257 -> 214/8034); 0502: the dummy-mode paragraph and PR-body clause are deleted (216/8356 -> 214/8257); 0497: +Step 5 halted-build evidence kept verbatim in ## Run halted (216/8325 -> 216/8356); 0498 review: checkpoint (ii) persist wording (8320 -> 8325); 0498: +Step 6.5 review-findings homes, condensation exception, Human-actions class rule (214/8161 -> 216/8320); 0491: the run id is retired (214/8183 -> 214/8161); 0488 review: build-owned starts carry --change-id/--run-context (word ceiling 8162 -> 8183); 0488: run context and run id name only build-owned starts (word ceiling 8175 -> 8162); 0467 review fix: +the repair worker's post-fix re-run is a build-owned start (word ceiling 8165 -> 8175); 0467: +run id threaded to prepare-scope and build-owned starts (word ceiling 8080 -> 8165); 0455: +pr.publish record-invalid refusal clause (word ceiling 8025 -> 8080); 0448: +named-invocation branch; bounded own-dependency closeout moved to edge-paths.md (ceilings 210/7716 -> 214/8270 -> 214/8025); 0393: +exact payload, marker, and direct-dispatch lines atop 0410/0354/0376; 0375: +run-tracker resume pointer (word ceiling 7530 -> 7547); 0440: reader-first results prose; 0502: drop change citations and Go v1 narration (214/8057 -> 214/8023) {"docket-implement-next/references/edge-paths.md", 109, 1265}, // 0532: the private-repository writing rule and visibility hand-off (109/1226 -> 109/1265); 0531: the metadata worktree and remote come from the repository.prepare context (118/1499 -> 109/1226); 0502: one metadata layout — the docket branch and the .docket/ worktree (118/1507 -> 118/1509); 0502: run.verify replaces verify-run (118/1505 -> 118/1507); 0502: terminal-publication narration is deleted (118/1513 -> 118/1505); 0502: the deferred results-only permit clause is deleted (118/1546 -> 118/1513); 0502: no custom plan location (118/1547 -> 118/1546); 0491: the run id is retired (118/1554 -> 118/1547); 0410: +resume/recovery + required-results reconciliation; 0375: +run-tracker resume refusals (78/1091 -> 93/1261); 0448: +named own-dependency closeout moved from SKILL.md (93/1261 -> 118/1554); 0502: drop change citations and Go v1 narration (118/1509 -> 118/1499) {"docket-implement-next/references/fix-pass.md", 189, 1963}, // 0532: the private-repository writing rule and visibility hand-off (187/1943 -> 189/1963); 0502 rebase onto 0510: carried the backlog-verdict pointer for reported findings (186/1929 -> 187/1943); 0502: "loop" means /loop only (190/1962 -> 190/1967); 0502: undispatchable fix worker halts (192/1991 -> 190/1962); 0502: renamed from fix-loop.md; 0498 review: results-file antecedent (1989 -> 1991); 0498: +review-findings condensation at final consolidation (190/1958 -> 192/1989); 0410: +findings-to-results checkpoint linkage (see note above); 0502: drop change citations and Go v1 narration (190/1967 -> 186/1929) {"docket-implement-next/references/results-artifact.md", 79, 775}, // 0559: new — the results-artifact ending (no plan, build, or PR; review, complete, clean up) {"docket-implement-next/results-template.md", 70, 545}, // 0502 rebase onto 0510: carried the backlog verdict and next action in the Known issues placeholder (68/506 -> 70/545); 0502: inline review replaces the custom review skill (68/511 -> 68/510); 0498: +whole-branch review summary line in Verification performed (64/446 -> 68/511); 0440: reader-first template — action statement + merged Known issues (see note above); 0502: drop change citations and Go v1 narration (68/510 -> 68/506) {"docket-review/SKILL.md", 127, 1059}, // 0559: the results-artifact mode (114/966 -> 127/1049); 0559: Inputs and evidence sections defer to results-artifact mode (127/1049 -> 127/1059); 0531: the metadata worktree and remote come from the repository.prepare context (114/965 -> 114/966); 0502: the evidence rule keys on the payload's build.gate value; gate-off skipped records are expected (110/913 -> 114/965); 0410: +findings-return capture contract (see note above) - {"docket-new-change/SKILL.md", 53, 1598}, // 0559: the create request carries deliverable: results-artifact for findings-only work (57/1635 -> 53/1598); 0532: the private-repository writing rule and visibility hand-off (57/1603 -> 57/1635); 0531: the metadata worktree and remote come from the repository.prepare context (57/1596 -> 57/1603); 0502 review: omitted draft-time scalars are described exactly (57/1591 -> 57/1596); 0502: "loop" means /loop only (57/1593 -> 57/1591); 0502: one metadata layout — the docket branch and the .docket/ worktree (57/1590 -> 57/1593); 0502: terminal-publication narration and the repository auto_groom default are deleted (57/1609 -> 57/1590); 0502: invoke superpowers:brainstorming by name (57/1636 -> 57/1609); 0502: the dummy-mode pointer is deleted (59/1674 -> 57/1636); 0445: +pointer to the docket-groom-next revise path after landing (word ceiling 1700 -> 1706); 0382: draft-time scalars moved into change.create (ceiling 1706 -> 1675) - {"docket-status/SKILL.md", 126, 2983}, // 0539: derived-view drift is named by family and each finding's own remedy is relayed instead of a code list (126/2923 -> 126/2983); 0531: the metadata worktree and remote come from the repository.prepare context (126/2921 -> 126/2923); 0530: artifact-missing names where a plan or results file may live — the docket branch, or the integration branch for a record closed before the move (126/2904 -> 126/2921); 0529 review: full-scope cleanup retries also repoint stale merged-PR description backlinks; repair --pr-backlinks previews them (126/2880 -> 126/2904); 0502: one metadata layout — the docket branch and the .docket/ worktree (126/2876 -> 126/2880); 0502: findings named as the binary emits them (126/2852 -> 126/2876); 0502: deferred learnings and publication narration is deleted (127/2956 -> 126/2852); 0502: the dummy-mode pointer is deleted (129/2985 -> 127/2956); 0388: +sync-integration prose (see note above) + {"docket-new-change/SKILL.md", 53, 1636}, // 0560: suggest a hold; it rides change.create or change.groom (53/1598 -> 53/1636); 0559: the create request carries deliverable: results-artifact for findings-only work (57/1635 -> 53/1598); 0532: the private-repository writing rule and visibility hand-off (57/1603 -> 57/1635); 0531: the metadata worktree and remote come from the repository.prepare context (57/1596 -> 57/1603); 0502 review: omitted draft-time scalars are described exactly (57/1591 -> 57/1596); 0502: "loop" means /loop only (57/1593 -> 57/1591); 0502: one metadata layout — the docket branch and the .docket/ worktree (57/1590 -> 57/1593); 0502: terminal-publication narration and the repository auto_groom default are deleted (57/1609 -> 57/1590); 0502: invoke superpowers:brainstorming by name (57/1636 -> 57/1609); 0502: the dummy-mode pointer is deleted (59/1674 -> 57/1636); 0445: +pointer to the docket-groom-next revise path after landing (word ceiling 1700 -> 1706); 0382: draft-time scalars moved into change.create (ceiling 1706 -> 1675) + {"docket-status/SKILL.md", 126, 2993}, // 0560: a held change shows on hold (126/2983 -> 126/2993); 0539: derived-view drift is named by family and each finding's own remedy is relayed instead of a code list (126/2923 -> 126/2983); 0531: the metadata worktree and remote come from the repository.prepare context (126/2921 -> 126/2923); 0530: artifact-missing names where a plan or results file may live — the docket branch, or the integration branch for a record closed before the move (126/2904 -> 126/2921); 0529 review: full-scope cleanup retries also repoint stale merged-PR description backlinks; repair --pr-backlinks previews them (126/2880 -> 126/2904); 0502: one metadata layout — the docket branch and the .docket/ worktree (126/2876 -> 126/2880); 0502: findings named as the binary emits them (126/2852 -> 126/2876); 0502: deferred learnings and publication narration is deleted (127/2956 -> 126/2852); 0502: the dummy-mode pointer is deleted (129/2985 -> 127/2956); 0388: +sync-integration prose (see note above) } // wcLines counts lines the way `wc -l` does: the number of newline bytes. diff --git a/internal/repoguard/prose_contracts_test.go b/internal/repoguard/prose_contracts_test.go index 142428ba2..b7286adc6 100644 --- a/internal/repoguard/prose_contracts_test.go +++ b/internal/repoguard/prose_contracts_test.go @@ -448,6 +448,42 @@ var proseContracts = []proseContract{ present: []string{"A typed `/docket-implement-next` runs untracked."}}, {sentinel: "change_0556_tracked_start", file: "docs/concepts/run-tracker.md", present: []string{"A typed `/docket-implement-next` runs untracked."}}, + // change 0560 — a hold keeps a groomed change out of autonomous build + // selection; naming it builds it. Each phrase binds the word to its claim. + {sentinel: "change_0560_hold", file: "skills/docket-implement-next/SKILL.md", + present: []string{ + "`readiness` vocabulary: `build-ready`, `on-hold`, `needs-grooming`, `waiting-dependency`, `stack-base-unresolved`, `not-proposed`, `auto-groom-blocked`, `invalid`;", + "— needs-grooming, on hold, already `in-progress`", + "(needs-grooming / on hold / already `in-progress`", + "A held change (`on-hold`) is built when named.", + "on the selection path a bundle reporting `on-hold` is dropped and reported the same way", + }}, + {sentinel: "change_0560_hold", file: "skills/docket-groom-next/SKILL.md", + present: []string{ + "**Hold.** When the settled design needs a step a person must carry out, suggest a hold", + "`hold: true` sets it, `hold: false` lifts it", + "an optional `hold_reason` (only with `hold: true`) writes `## Why on hold`", + "Abstain refuses it (`invalid-hold`)", + "`hold-reason-without-hold` and `invalid-hold_reason` write nothing", + }}, + {sentinel: "change_0560_hold", file: "skills/docket-new-change/SKILL.md", + present: []string{"When the design needs a step a person must carry out, suggest a hold; if the human agrees, send `hold: true`"}}, + {sentinel: "change_0560_hold", file: "skills/docket-auto-groom/SKILL.md", + present: []string{ + "names a step a person must carry out, add `hold: true`", + "never send `hold: false`", + "each change it held", + "the autonomous builder will build it unless held", + }}, + {sentinel: "change_0560_hold", file: "skills/docket-convention/SKILL.md", + present: []string{ + "\nhold: # `true` keeps a groomed change out of autonomous build selection; naming it still builds it", + "autonomous selection never picks it, and naming it builds it", + "- `## Why on hold` — ", + "`hold` is human input except the auto-groomer's `hold: true`", + }}, + {sentinel: "change_0560_hold", file: "skills/docket-status/SKILL.md", + present: []string{"a held change that would be build-ready shows **on hold**"}}, } // scanProse checks one file's content against a contract, returning a violation diff --git a/skills/docket-auto-groom/SKILL.md b/skills/docket-auto-groom/SKILL.md index 8625279a3..7f3ccd763 100644 --- a/skills/docket-auto-groom/SKILL.md +++ b/skills/docket-auto-groom/SKILL.md @@ -37,7 +37,7 @@ Read the stub body, its `related`/`depends_on` neighbours (active + recently arc ### Step 3 — Critic pass -Dispatch the dedicated **`docket-auto-groom-critic`** subagent (foreground, at the model/effort its wrapper resolves) — a fresh subagent (never the designer reviewing itself), isolated in its own context, loading only `docket-convention` and never this designer skill — to adversarially attack the draft — specs and trivial verdicts alike. Per assumption, one verdict: **sound** (stands) · **wrong but fixable from available context** (designer revises; ONE bounded revision round; the critic re-checks only the revised items — this re-check is dispatched foreground exactly like the first pass, per the convention's *Composition* never-yield rule) · **needs human context** (⇒ the whole groom abstains — a spec must only be emitted when every decision in it is safe to auto-commit, because emission = build-ready = the autonomous builder will build it). If no dispatch mechanism resolves per the convention's *Dispatch-capability resolution* — never from a tool name — the `docket-auto-groom-critic` dispatch's fallback is **`abstain`**: the groom **abstains** for that stub (→ Step 4's **Abstain** exit) rather than self-reviewing — an author cannot be their own adversarial gate. +Dispatch the dedicated **`docket-auto-groom-critic`** subagent (foreground, at the model/effort its wrapper resolves) — a fresh subagent (never the designer reviewing itself), isolated in its own context, loading only `docket-convention` and never this designer skill — to adversarially attack the draft — specs and trivial verdicts alike. Per assumption, one verdict: **sound** (stands) · **wrong but fixable from available context** (designer revises; ONE bounded revision round; the critic re-checks only the revised items — this re-check is dispatched foreground exactly like the first pass, per the convention's *Composition* never-yield rule) · **needs human context** (⇒ the whole groom abstains — a spec must only be emitted when every decision in it is safe to auto-commit, because emission = build-ready = the autonomous builder will build it unless held). If no dispatch mechanism resolves per the convention's *Dispatch-capability resolution* — never from a tool name — the `docket-auto-groom-critic` dispatch's fallback is **`abstain`**: the groom **abstains** for that stub (→ Step 4's **Abstain** exit) rather than self-reviewing — an author cannot be their own adversarial gate. **Receiving the verdict.** The verdict is read from the critic's **return** — its final report, which the groom is actively blocking on; the groom never backgrounds the critic. The groom never waits for a message, a notification, or any other out-of-band delivery: nothing is registered to deliver one, so that wait never ends. @@ -49,6 +49,8 @@ Dispatch the dedicated **`docket-auto-groom-critic`** subagent (foreground, at t 2. **Trivial** — the critic confirmed no hidden design decisions: apply the `change.groom` operation with `--repo-dir --request ` with `outcome: trivial`, the pinned `path` + `revision`, and an owned-section edit carrying the tightened body and its reasoning as the trivial rationale. The transaction sets `trivial: true` + `updated:` and re-renders the `## Artifacts` block and inline board atomically. Build-ready, no spec. 3. **Abstain** — any needs-human-context verdict, or Step 3's exhausted no-verdict posture: emit NO spec; apply the `change.groom` operation with `--repo-dir --request ` with `outcome: abstain`, the pinned `path` + `revision`, and a `blocked_note` — the undecidable decision(s), what context is missing, what a human should supply, and any recommendation (including "this should probably be killed/deferred because …"), with subsections at `###` or deeper. The transaction sets `auto_groomable: false` + `updated:`, appends a dated entry to the `## Auto-groom blocked` section, and re-renders the inline board — the row flips to **auto-groom blocked — needs you** in that same commit. It accepts no section, spec, or relationship edits. The stub stays needs-grooming, first in `docket-groom-next`'s queue. +**Hold.** When the emitted spec or trivial verdict names a step a person must carry out, add `hold: true` to that exit's request, plus a one-line `hold_reason` only when the stub has no `## Why on hold` section; never send `hold: false` — lifting a hold is a person's call. + **Kill and defer are NEVER autonomous.** Verdict authority over the backlog's composition stays human; the strongest the drain may say is an abstain-with-recommendation. ### Step 5 — The outcome lands (no separate board pass) @@ -57,7 +59,7 @@ Every exit's Step-4 `change.groom` operation is the whole write — it re-checks ### Step 6 — Report -Summarize the drain: groomed N (specs), trivial M, abstained K — each abstain with its one-line reason — plus anything skipped to a lost race. STOP. Grooming never implements; the build-ready output is `docket-implement-next`'s queue. +Summarize the drain: groomed N (specs), trivial M, abstained K — each abstain with its one-line reason — plus each change it held and anything skipped to a lost race. STOP. Grooming never implements; the build-ready output is `docket-implement-next`'s queue. ## Termination & concurrency diff --git a/skills/docket-convention/SKILL.md b/skills/docket-convention/SKILL.md index 0d7224c39..32de42c90 100644 --- a/skills/docket-convention/SKILL.md +++ b/skills/docket-convention/SKILL.md @@ -189,6 +189,7 @@ plan: # plan FILE on the metadata branch; FILE and FIELD wri 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 branch: # minted / (or /) name, set on claim; sole feature-head source of truth after, never reconstructed; branch itself created at build (step 4) pr: # set when the PR is opened @@ -228,6 +229,7 @@ change, never in the frozen artifact. - `## Run halted` — written by the `change.halt` operation when an autonomous run stops needing a human (the `halted` disposition); the heading is **bare**, never dated — the reader is a whole-line match, so the date sits inside the body. **Marker-section state**, in the same family as `## Auto-groom blocked` and `## Finalize blocked`: while the section is present the `run.verify` operation reports `run-halted`, which is what makes a `halted` disposition verifiable in git rather than a claim in a completion report. It is removed by the `change.resume-halted` operation, and by the claim when a halted change is claimed again. - `## Build evidence` — the build-evidence block for the certified feature head, written by `change.mark-implemented`, `finalize.publish`, and `evidence.recertify`; never hand-edited. - `## Why deferred` / `## Why killed` — added when entering those states. +- `## Why on hold` — the optional hold reason, written only by the `hold_reason` key; lifting the hold removes it. The change body is a **PM-altitude proposal** (intent + scope). Detailed design lives in the linked superpowers spec; the task breakdown in the linked superpowers plan. Different zoom levels, no duplication. @@ -286,11 +288,11 @@ 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 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. ### 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`). +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 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. diff --git a/skills/docket-groom-next/SKILL.md b/skills/docket-groom-next/SKILL.md index 65e8aa13b..93a4b2141 100644 --- a/skills/docket-groom-next/SKILL.md +++ b/skills/docket-groom-next/SKILL.md @@ -65,6 +65,8 @@ All six exits reuse existing transitions — this skill introduces no new lifecy **Deliverable, type, and branch prefix.** The same four exits may also carry `deliverable` (`pr` or `results-artifact` — use `results-artifact` when the work ends in findings, not code), `type` (a configured change type), and `branch_prefix` (omit it to keep the current value, send `""` to clear it, or a value to set it); any one alone is a valid revise. Nothing is renamed — the next claim mints the branch from the new `type`/`branch_prefix`. A `results-artifact` change never stacks, so a request that would leave it carrying `stacked_on:`, or stacked on by another change, refuses with `results-artifact-not-stackable`. Abstain refuses all three (`invalid-deliverable`, `invalid-type`, `invalid-branch_prefix`), and an unknown value refuses with `unknown-deliverable`, `unknown-type`, or `invalid-branch_prefix`; each writes nothing — surface it. +**Hold.** When the settled design needs a step a person must carry out, suggest a hold before the spec or trivial exit; the person decides. The same four exits may carry `hold` (`hold: true` sets it, `hold: false` lifts it, omitted keeps it; alone it is a valid revise), and an optional `hold_reason` (only with `hold: true`) writes `## Why on hold`, which lifting removes. A held change is skipped by autonomous build selection and built when named. Abstain refuses it (`invalid-hold`); `hold-reason-without-hold` and `invalid-hold_reason` write nothing — surface them. + **Stacking.** The same four exits may carry `stacked_on`: an id stacks or re-parents, `0` clears it (the fix for a killed stack parent), and omitted or `null` leaves it. Any relationship field alone is a valid revise. A negative value refuses with `invalid-stacked_on`, and changing `stacked_on` once the change has a `branch:` refuses with `not-restackable`; each writes nothing — surface it. ### Step 5 — The transaction lands (no separate board pass) diff --git a/skills/docket-implement-next/SKILL.md b/skills/docket-implement-next/SKILL.md index 9b8bf01d0..89af8459d 100644 --- a/skills/docket-implement-next/SKILL.md +++ b/skills/docket-implement-next/SKILL.md @@ -26,7 +26,7 @@ Before anything else in this skill, invoke the `docket-convention` skill via the Run the convention's **startup check** (load the convention; run the capability bootstrap; run the `repository.prepare` operation with `--repo-dir --json` as its own Bash call; validate the protocol-v1 envelope and carry its typed context values forward as literals; act on the disposition). All bookkeeping in this skill (claim, reconcile, `status`, `pr:`, `plan:`, `adrs:`, the plan and results files, build evidence) lands in the metadata worktree (`metadata_worktree_path` in the `repository.prepare` context) on the metadata branch, pushed to the metadata remote (`metadata_remote`) immediately; only the spec copy and the code land on the feature branch. -**Named invocation — no maintenance preflight.** When this run was invoked with exactly **one explicit change id** — an initial named call, an attributed retry carrying the id, or a named resume of an in-progress change — skip the implementation preflight and Step 1's status-digest certification entirely: after the `repository.prepare` operation succeeds, go **directly** to the authoritative `context.implementation` operation with `--id ` and the existing claim/resume path. The named path never runs `maintenance.preflight` or any maintenance sweep first — another change's failing closeout, cleanup, or reclaim can never halt this change before its own claim/gate; anyone who wants those maintenance outcomes runs the explicit `maintenance.preflight` or `maintenance.sweep` operation deliberately, where every problem stays visible. Every local check for the named change is kept — readiness, record revision, dependencies, effective base, claim eligibility, run context, and resume/cancellation — so a malformed, absent, not-ready, or improperly resumed id returns its existing typed refusal, reported with its reason exactly as a scoped-id skip is (ending `drained` when nothing else is in scope); a named request **never falls back to selecting another change**, and shared repository/configuration/transport failures keep the `halted` posture. +**Named invocation — no maintenance preflight.** When this run was invoked with exactly **one explicit change id** — an initial named call, an attributed retry carrying the id, or a named resume of an in-progress change — skip the implementation preflight and Step 1's status-digest certification entirely: after the `repository.prepare` operation succeeds, go **directly** to the authoritative `context.implementation` operation with `--id ` and the existing claim/resume path. The named path never runs `maintenance.preflight` or any maintenance sweep first — another change's failing closeout, cleanup, or reclaim can never halt this change before its own claim/gate; anyone who wants those maintenance outcomes runs the explicit `maintenance.preflight` or `maintenance.sweep` operation deliberately, where every problem stays visible. Every local check for the named change is kept — readiness, record revision, dependencies, effective base, claim eligibility, run context, and resume/cancellation. A held change (`on-hold`) is built when named. So a malformed, absent, not-ready, or improperly resumed id returns its existing typed refusal, reported with its reason exactly as a scoped-id skip is (ending `drained` when nothing else is in scope); a named request **never falls back to selecting another change**, and shared repository/configuration/transport failures keep the `halted` posture. **The named change's own merged dependencies.** Skipping the sweep never declares a dependency satisfied. When the named path's `context.implementation` read refuses `not-ready-waiting-dependency`, **read `references/edge-paths.md` now (blocking)** for the bounded closeout of the named change's own `implemented` dependencies — never any other change's. @@ -36,11 +36,11 @@ Run the convention's **startup check** (load the convention; run the capability Build-readiness and ranking are defined by the convention's **Build-readiness & selection** section — that definition is the authority here, and this step only describes how to ACQUIRE the set it defines. -**Acquisition.** Run the `status` operation with `--json` — a write-free read; on the selection path, only AFTER Step 0's `maintenance.preflight` run and metadata re-sync (the snapshot is taken pre-sweep otherwise and would list already-merged changes). A named invocation takes no ready-queue digest — it arrives here already holding Step 0's directive to read the explicit-id bundle below. Validate the envelope before trusting it: `protocol_version` MUST be `1` and `operation` MUST be `status`. The top-level `ready` array IS the build-ready queue, already in the convention's deterministic order — final tie-break LOWEST `id`, so concurrent implementers converge on one winner. Per-change skip reasons come from each `changes[]` entry's `readiness` / `readiness_reason` fields (`readiness` vocabulary: `build-ready`, `needs-grooming`, `waiting-dependency`, `not-proposed`, `auto-groom-blocked`; `readiness_reason` carries the human-readable phrase). +**Acquisition.** Run the `status` operation with `--json` — a write-free read; on the selection path, only AFTER Step 0's `maintenance.preflight` run and metadata re-sync (the snapshot is taken pre-sweep otherwise and would list already-merged changes). A named invocation takes no ready-queue digest — it arrives here already holding Step 0's directive to read the explicit-id bundle below. Validate the envelope before trusting it: `protocol_version` MUST be `1` and `operation` MUST be `status`. The top-level `ready` array IS the build-ready queue, already in the convention's deterministic order — final tie-break LOWEST `id`, so concurrent implementers converge on one winner. Per-change skip reasons come from each `changes[]` entry's `readiness` / `readiness_reason` fields (`readiness` vocabulary: `build-ready`, `on-hold`, `needs-grooming`, `waiting-dependency`, `stack-base-unresolved`, `not-proposed`, `auto-groom-blocked`, `invalid`; `readiness_reason` carries the human-readable phrase). -The digest is an **accelerator, not the sole channel**: the authoritative read is the `context.implementation` operation with `--id ` (no `--id` applies the same selection policy; an attributed retry passes the id). It loads ONE fresh snapshot and returns the change's source bytes, exact opaque **record revision**, readiness, claim-eligibility, resolved effective base, integration branch, and workflow config — the single bundle the claim and every later operation key on, so no step re-reads the change file. **Judgment on that bundle stays yours.** CONFIRM build-readiness before claiming — a stale digest costs a re-pick, never a bad build; a typed no-candidate/absent-id/duplicate-id/not-ready/unsupported-config outcome is surfaced, never overridden. If the bundle disagrees with the digest, drop that candidate, take the next, and REPORT it. **The exit status and the envelope's shape together govern the disposition.** A **non-zero exit**, or stdout that will not parse as a JSON envelope, **is a hard error** (config export failure, refused bootstrap guard, missing metadata worktree, failed render, or malformed output) — surface its stderr diagnostic and STOP with the **`halted`** disposition; never fall back to `active/` for a hard error, and never report `drained` for one. On **exit 0** with a valid envelope, an **empty `ready` array** (`ready: []`) means the queue is genuinely empty → `drained`. A parseable envelope that is **missing the `ready` key altogether** is malformed machine output — **reject it and STOP with `halted`**, exactly as for a hard error: the typed contract always carries `ready`, so there is no walk-`active/`-yourself degradation. Likewise a failed `protocol_version`/`operation` check. +The digest is an **accelerator, not the sole channel**: the authoritative read is the `context.implementation` operation with `--id ` (no `--id` applies the same selection policy; an attributed retry passes the id). It loads ONE fresh snapshot and returns the change's source bytes, exact opaque **record revision**, readiness, claim-eligibility, resolved effective base, integration branch, and workflow config — the single bundle the claim and every later operation key on, so no step re-reads the change file. **Judgment on that bundle stays yours.** CONFIRM build-readiness before claiming — a stale digest costs a re-pick, never a bad build; a typed no-candidate/absent-id/duplicate-id/not-ready/unsupported-config outcome is surfaced, never overridden. If the bundle disagrees with the digest, drop that candidate, take the next, and REPORT it; on the selection path a bundle reporting `on-hold` is dropped and reported the same way. **The exit status and the envelope's shape together govern the disposition.** A **non-zero exit**, or stdout that will not parse as a JSON envelope, **is a hard error** (config export failure, refused bootstrap guard, missing metadata worktree, failed render, or malformed output) — surface its stderr diagnostic and STOP with the **`halted`** disposition; never fall back to `active/` for a hard error, and never report `drained` for one. On **exit 0** with a valid envelope, an **empty `ready` array** (`ready: []`) means the queue is genuinely empty → `drained`. A parseable envelope that is **missing the `ready` key altogether** is malformed machine output — **reject it and STOP with `halted`**, exactly as for a hard error: the typed contract always carries `ready`, so there is no walk-`active/`-yourself degradation. Likewise a failed `protocol_version`/`operation` check. -**Scope (id allowlist).** With no argument the candidate set is the whole `ready` queue. A caller may pass an **id allowlist** of two or more ids — `docket-implement-next 90,92,94` — and selection is then **restricted to that set**, preserving the queue's order *within* it. (A **single explicit id** is not an allowlist: it is a named invocation and takes Step 0's named branch, never this filter.) The allowlist is a filter, **never a dependency override**: a scoped id that is not currently build-ready+claimable — needs-grooming, already `in-progress`, or waiting on an unmerged `depends_on` — is **skipped with its reason** (read it off that id's `changes[]` entry — a non-`proposed` `status` there is skipped for that status — or from the change file if it has none — already archived, or no such id), never force-built, and never aborts the run. +**Scope (id allowlist).** With no argument the candidate set is the whole `ready` queue. A caller may pass an **id allowlist** of two or more ids — `docket-implement-next 90,92,94` — and selection is then **restricted to that set**, preserving the queue's order *within* it. (A **single explicit id** is not an allowlist: it is a named invocation and takes Step 0's named branch, never this filter.) The allowlist is a filter, **never a dependency override**: a scoped id that is not currently build-ready+claimable — needs-grooming, on hold, already `in-progress`, or waiting on an unmerged `depends_on` — is **skipped with its reason** (read it off that id's `changes[]` entry — a non-`proposed` `status` there is skipped for that status — or from the change file if it has none — already archived, or no such id), never force-built, and never aborts the run. **Empty queue → `drained`.** If no candidate in scope is build-ready+claimable, build nothing and end the run with the **`drained`** disposition (see *Terminal disposition*) — the driver's stop signal. @@ -189,7 +189,7 @@ disposition, a review outcome, "complete" — is by construction an aborted run, reports. `advanced` is claimable only when **Step 7's postcondition** or the **results-artifact ending's** holds — stated in *Step postconditions* above, not here. -The final report **enumerates** what happened: the change built (if any), each change **skipped with its reason** (needs-grooming / already `in-progress` / waiting on an unmerged `depends_on` / outside the id allowlist), any follow-up work **reported for deliberate capture**, each with its backlog verdict when final consolidation produced one (Step 6.5 *Backlog match*), and which disposition ended the run. +The final report **enumerates** what happened: the change built (if any), each change **skipped with its reason** (needs-grooming / on hold / already `in-progress` / waiting on an unmerged `depends_on` / outside the id allowlist), any follow-up work **reported for deliberate capture**, each with its backlog verdict when final consolidation produced one (Step 6.5 *Backlog match*), and which disposition ended the run. ### Atomic board rendering diff --git a/skills/docket-new-change/SKILL.md b/skills/docket-new-change/SKILL.md index d4f0b60e8..bc8736445 100644 --- a/skills/docket-new-change/SKILL.md +++ b/skills/docket-new-change/SKILL.md @@ -32,7 +32,7 @@ The default path for any non-trivial new change. Five steps: 4. **Create the proposed change** — submit the record through one atomic transaction: the `change.create` operation (resolve argv from the capability catalog) with `--repo-dir --request `. Its closed JSON request carries `title`, `type` (one configured `change_type` — `create` refuses an unknown or empty type, so no created change is ever left `untyped`, and there is no template comment to replace), `priority` (default `medium`), `deliverable: results-artifact` when the work ends in findings, not code (omit it for the default `pr`), the PM-altitude `why`/`what_changes`/`out_of_scope` body distilled from the brainstorm (design detail lives in the linked spec, NOT here), the resolved `depends_on`/`related`/`adrs`/`discovered_from` from step 3, `stacked_on` when the work builds on another change's **unmerged** branch (set it and **read [stacked-changes.md](../docket-convention/references/stacked-changes.md) now (blocking)** first — stacking changes how it is built, merged, and closed out), and the stable `request_id` from step 1. The transaction allocates the id, derives the slug, serializes the canonical `status: proposed` record (`created`/`updated` = the commit's UTC date), renders its `## Artifacts` block, and re-renders the inline board — one metadata commit under an exact-lease push, returning the new `id`/`slug`/`path`. - **Two draft-time scalars ride in the same request** — `auto_groomable` and `branch_prefix`. When the human says the change may be designed without them, send `auto_groomable: true` (so `docket-auto-groom` carries it to build-ready; `false` opts it out). When they name a branch prefix ("use the `hotfix/` prefix"), send it as typed in `branch_prefix` — the operation normalizes it and refuses an unusable value with `invalid-branch_prefix` before anything is written: show the human that finding and ask for a new value. Omit `auto_groomable` to leave the change not auto-groomable; omit `branch_prefix` to use ``. + **Two draft-time scalars ride in the same request** — `auto_groomable` and `branch_prefix`. When the human says the change may be designed without them, send `auto_groomable: true` (so `docket-auto-groom` carries it to build-ready; `false` opts it out). When they name a branch prefix ("use the `hotfix/` prefix"), send it as typed in `branch_prefix` — the operation normalizes it and refuses an unusable value with `invalid-branch_prefix` before anything is written: show the human that finding and ask for a new value. Omit `auto_groomable` to leave the change not auto-groomable; omit `branch_prefix` to use ``. When the design needs a step a person must carry out, suggest a hold; if the human agrees, send `hold: true` (and an optional `hold_reason`) here for a captured stub, or in the step-5 or trivial-path `change.groom` request. 5. **Groom to build-ready & land** — read the created record's `path` + exact **record revision** (blob object id) from the `status` operation (with `--json`), then apply the spec atomically: the `change.groom` operation with `--repo-dir --request ` carrying the change id, the pinned `path` + `revision`, `outcome: spec`, the `spec_markdown` from step 2, and any owned proposal-section rewrites. In one metadata commit the transaction writes the spec file, sets `spec:` + `updated:`, stamps the spec's `docket:backlink` block, re-renders the `## Artifacts` block, and re-renders the inline board (pushed under an exact-lease push) — **no separate Board pass**. A revision-mismatch / `contended` refusal writes nothing: re-sync (re-run the `repository.prepare` operation), re-read `path` + `revision`, retry. STOP. Never implements. To adjust a just-landed spec or its owned sections afterwards, run `docket-groom-next ` — its explicit-id path routes an already-groomed change to `change.groom` with `outcome: revise`; never re-run this skill or hand-edit the spec file. diff --git a/skills/docket-status/SKILL.md b/skills/docket-status/SKILL.md index bdb6f77dc..77fc4a0c8 100644 --- a/skills/docket-status/SKILL.md +++ b/skills/docket-status/SKILL.md @@ -103,7 +103,7 @@ The mechanics below live entirely in the Go operations — this is a compact map ### Board -Renders each surface in `board_surfaces` (config; default `[inline]`) from the same one dependency-resolution pass, computed once. Readiness cells: a dependency-waiting change shows **⏳ waiting on #N — not yet built** or **⏳ waiting on #N — needs your merge**; a `proposed` change with no spec, not `trivial: true`, and not waiting shows **needs-grooming** — or **auto-groom blocked — needs you** when its body carries an `## Auto-groom blocked` section. +Renders each surface in `board_surfaces` (config; default `[inline]`) from the same one dependency-resolution pass, computed once. Readiness cells: a dependency-waiting change shows **⏳ waiting on #N — not yet built** or **⏳ waiting on #N — needs your merge**; a `proposed` change with no spec, not `trivial: true`, and not waiting shows **needs-grooming** — or **auto-groom blocked — needs you** when its body carries an `## Auto-groom blocked` section; a held change that would be build-ready shows **on hold**. When `board_surfaces` includes `inline`, the docket app is the single gated writer of `BOARD.md`: every board-authoritative typed mutation re-renders it inside the owning metadata transaction and commits the result to the metadata branch in the same commit as the record it reflects, only when it actually changed, so nothing else ever touches the file. This skill **never hand-edits `BOARD.md`, never hand-renders it, and never 3-way merges it**; on a rebase conflict, let the owning operation regenerate it — never a hand-merge — and continue. When `board_surfaces` omits `inline`, there is simply no board. Where present, `BOARD.md` is the live planning view and stays on `docket` — never published to the integration branch. From 35514c7c61d44b936716791ef419471151e2e1e2 Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Sun, 18 Oct 2026 23:01:49 -0400 Subject: [PATCH 09/10] docs: a held change is skipped by drains and built when named --- docs/concepts/change-lifecycle.md | 3 ++- docs/guide/building-without-supervision.md | 3 +++ docs/guide/capturing-work.md | 3 +++ docs/reference/cli.md | 3 ++- docs/reference/glossary.md | 21 +++++++++++++++++++-- 5 files changed, 29 insertions(+), 4 deletions(-) diff --git a/docs/concepts/change-lifecycle.md b/docs/concepts/change-lifecycle.md index 3935908b4..e83823116 100644 --- a/docs/concepts/change-lifecycle.md +++ b/docs/concepts/change-lifecycle.md @@ -54,7 +54,8 @@ human has to memorize a flowchart to file a piece of work. trivial mark is **needs-grooming** — it needs a design conversation first. A proposed change that has a **spec** (the design document a change links to, written before building) or is marked trivial, and whose dependencies are all - `done`, is **build-ready**. + `done`, is **build-ready**. A build-ready change on hold reads **on-hold**: + autonomous drains skip it, and it is built only when named. - **in-progress** means a build has taken a **claim** — the moment a change is picked up for building; it records which branch will carry the work and when it was taken. Grooming a change to build-ready takes no claim; only building does, diff --git a/docs/guide/building-without-supervision.md b/docs/guide/building-without-supervision.md index 0481a9ea0..7512dbafa 100644 --- a/docs/guide/building-without-supervision.md +++ b/docs/guide/building-without-supervision.md @@ -164,6 +164,9 @@ build work stays isolated and the driver's own context stays small: order. A named change that is not build-ready — still needs design, already in progress, or waiting on an unmerged dependency — is skipped this drain with its reason, not waited on. +A change on [hold](../reference/glossary.md#hold) is skipped by both drains; it is built only +when you name it alone. + Budget and iteration caps belong to the driver, not to docket, which does not reimplement them. The one invariant the driver never breaks is the PR handoff: **a build run never merges.** A dependency on a `pr` change therefore only clears between drains, once its pull request is merged outside the diff --git a/docs/guide/capturing-work.md b/docs/guide/capturing-work.md index f8f80b1fd..c0efe50c0 100644 --- a/docs/guide/capturing-work.md +++ b/docs/guide/capturing-work.md @@ -84,6 +84,9 @@ your at-a-glance view. It groups every change into six sections — in progress, groomed, proposed, and deferred — with one Type cell per row and a note like `⏳ waiting on # — needs your merge` where a dependency is holding something up. The section order and each section's sorting are configurable with `board.section_order` and `board.sorting`. +Grooming can also put a change on hold, keeping it out of autonomous builds: the Groomed table's +Readiness cell reads `build-ready` or `on hold`. The In progress table's State cell reads `building` +or `run halted — needs you`. Every docket write re-renders the board, so there is no separate step to regenerate it. One honest caveat about dependencies: chains serialize on the PR handoff. A change that depends diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 9987a3b19..df4edce47 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -26,7 +26,8 @@ Each line is a pointer: the command, what its verbs govern, and where to read th foreground root thread). Verbs: `docket agent --help`. - **`docket capabilities`** — emit the binary's complete executable command catalog (read-only, repository-independent). Verbs: `docket capabilities --help`. -- **`docket change`** — create and transition changes in the backlog. Verbs: `docket change --help`. +- **`docket change`** — create and transition changes in the backlog. Verbs: `docket change --help` + (`docket schema` lists the request keys, including `hold`). - **`docket context`** — assemble read-only context bundles for the implementation workflow. Verbs: `docket context --help`. - **`docket development`** — contributor operations against a docket checkout: install from a checkout and run the complete test suite. Verbs: `docket development --help`. diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index 0c2583712..bb069d839 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -572,6 +572,21 @@ docket change resume-halted --id 412 --revision --acknowledge-quiescent **quiescent** (no longer writing). Without it, on revision drift, or on a live gate lock, the operation refuses and writes nothing. +### Hold + +A **hold** (`hold: true` on the change record) keeps an otherwise build-ready change out of +autonomous build selection; its readiness reads `on-hold` and the board shows **on hold**. A +malformed value reads as held, with a warning. Naming the change alone overrides the hold: a named +run, a claim, or `change complete` proceeds. Grooming and finalize ignore it. `change.groom` and +`change.create` set it with `hold: true` (an optional `hold_reason` writes `## Why on hold`) and +`change.groom` lifts it with `hold: false`. + +**Used for:** a groomed change that needs manual steps, so a drain does not pick it up. + +```sh +docket status --json | jq '.changes[] | select(.readiness=="on-hold") | .id' +``` + ### Owned sections / section intents (`preserve` / `replace` / `remove`) **Owned sections** are the change-body headings that typed operations may write: `## Why`, @@ -601,7 +616,8 @@ finalize run they start) takes the change the rest of the way. It is a handoff t **Build-ready** is a proposed change that has a spec or is marked trivial and whose dependencies are all `done`. **Needs-grooming** is a proposed change with neither a spec nor a trivial mark; it needs a design conversation first. Anything not `proposed` reads `not-proposed`. Status reports -four more kinds: `auto-groom-blocked`, `waiting-dependency`, `stack-base-unresolved`, and `invalid` +five more kinds: `on-hold` (see [Hold](#hold)), `auto-groom-blocked`, `waiting-dependency`, +`stack-base-unresolved`, and `invalid` (see [Readiness reason](#readiness-reason--waiting-on-n--needs-you-cells)). **Used for:** selection. Only build-ready changes can be implemented; only needs-grooming changes @@ -617,7 +633,7 @@ docket status --json | jq '.changes[] | {id, readiness, readiness_reason, unmet_ `docket status --json`, for example "ready to build" or "waiting on unmet dependencies". It is prose, not a parseable code; key on `readiness`. The board renders the same state as cells like **⏳ waiting on #N — not yet built**, **… — needs your merge**, -**stack parent #A killed — re-parent, un-stack, or kill**, and the "needs you" cells +**stack parent #A killed — re-parent, un-stack, or kill**, **on hold**, and the "needs you" cells (**auto-groom blocked**, **run halted**, **finalize blocked**). **Used for:** seeing why a change is not moving. A "needs you" cell always comes from a @@ -2392,6 +2408,7 @@ docket development install --source ~/dev/docket - [Groom](#groom) - [Groom outcome revise](#groom-outcome-revise) - [Halt / resume-halted](#halt--resume-halted) +- [Hold](#hold) - [Harness](#harness) - [Harness defaults sidecar (agents/harness-defaults.yml)](#harness-defaults-sidecar-agentsharness-defaultsyml) - [Health check / health code](#health-check--health-code) From 5650c888949653c20535ccc9570ee9cb8914f43f Mon Sep 17 00:00:00 2001 From: Daniel Hanold Date: Sun, 18 Oct 2026 23:17:57 -0400 Subject: [PATCH 10/10] fix: address six minor review findings on the hold 1. ReadinessKind doc: selection reads Kind == ReadyBuildReady; a named build goes through ClaimEligibility, which also admits ReadyOnHold. 2. Glossary: revise lists the hold among its editable fields and says a hold moves a change between build-ready and on-hold; the Readiness entry says only build-ready changes are selected and a held change is built only when named. 3. docket-groom-next Step 5: a revise keeps the row's readiness unless it sets or lifts a hold. 4. docket-implement-next Step 1: on the named path on-hold also qualifies at the build-readiness confirm. 5. Glossary index: Hold moves to its alphabetical place after Health check. 6. types_test.go: TestLifecycleActionCarriesHold moves after the deliverable test, which gets its doc comment back, with its own comment. Regenerated embedded assets; raised the two moved skill word budgets. --- docs/reference/glossary.md | 9 +++--- internal/assets/embedded/manifest.json | 10 +++---- .../tree/skills/docket-groom-next/SKILL.md | 2 +- .../skills/docket-implement-next/SKILL.md | 2 +- internal/domain/readiness.go | 7 +++-- internal/domain/types_test.go | 30 ++++++++++--------- internal/repoguard/budgets_test.go | 4 +-- skills/docket-groom-next/SKILL.md | 2 +- skills/docket-implement-next/SKILL.md | 2 +- 9 files changed, 36 insertions(+), 32 deletions(-) diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index bb069d839..e61299684 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -620,8 +620,8 @@ five more kinds: `on-hold` (see [Hold](#hold)), `auto-groom-blocked`, `waiting-d `stack-base-unresolved`, and `invalid` (see [Readiness reason](#readiness-reason--waiting-on-n--needs-you-cells)). -**Used for:** selection. Only build-ready changes can be implemented; only needs-grooming changes -can be groomed. Selection order is priority → age (`created`) → lowest id. +**Used for:** selection. Only build-ready changes are selected for a build; a held change is built +only when named. Only needs-grooming changes can be groomed. Selection order is priority → age (`created`) → lowest id. ```sh docket status --json | jq '.changes[] | {id, readiness, readiness_reason, unmet_dependencies}' @@ -745,7 +745,8 @@ docket change groom --request groom.json The `change.groom` outcome that edits any `proposed` change without changing its groom state: a needs-grooming stub stays needs-grooming, and a spec'd or trivial change stays build-ready. It can replace the linked spec's body (only when the change links a spec) and edit owned sections, the -title, the priority, the type, the deliverable, the branch prefix, and relationship fields. It never sets `spec:`, `trivial:`, or +title, the priority, the type, the deliverable, the hold, the branch prefix, and relationship fields. A +hold moves a change between build-ready and on-hold. It never sets `spec:`, `trivial:`, or `auto_groomable:`, and it never edits `## Auto-groom blocked`, which only abstain and re-enable write. @@ -2408,10 +2409,10 @@ docket development install --source ~/dev/docket - [Groom](#groom) - [Groom outcome revise](#groom-outcome-revise) - [Halt / resume-halted](#halt--resume-halted) -- [Hold](#hold) - [Harness](#harness) - [Harness defaults sidecar (agents/harness-defaults.yml)](#harness-defaults-sidecar-agentsharness-defaultsyml) - [Health check / health code](#health-check--health-code) +- [Hold](#hold) - [Id / slug](#id--slug) - [Implementation context](#implementation-context) - [Implement-next / the drainer](#implement-next--the-drainer) diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index 73932fdc3..99fea5a70 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:c52083791cb7278c71bf9692cf0fe35e4d677a81b93accde3fd52458f3aeea84", + "asset_set_id": "sha256:fa6e5df41b394961fade11d17cad0451e4449ef2cc12af98625cdd812f5c7192", "entries": [ { "path": ".docket.example.yml", @@ -371,15 +371,15 @@ "path": "skills/docket-groom-next/SKILL.md", "role": "skill", "mode": 420, - "size": 16321, - "sha256": "70e449f09fb60e75747c4c6885104aa34a9241718e29cc8291c30e843ebb2290" + "size": 16352, + "sha256": "3fc4bb2d3d8c6d1def93d24b18e15f70d7792d7514060cb2ace588c0e5b4bfb3" }, { "path": "skills/docket-implement-next/SKILL.md", "role": "skill", "mode": 420, - "size": 58927, - "sha256": "e8b69c3e9979e5b330f5e1952c09667808bb61ace77b1a09494b4f8b4cec631e" + "size": 58972, + "sha256": "a320347018fbf89758d72a880ce0f9cebcd35ed47b27ebd1afd7fb41b742916c" }, { "path": "skills/docket-implement-next/references/edge-paths.md", diff --git a/internal/assets/embedded/tree/skills/docket-groom-next/SKILL.md b/internal/assets/embedded/tree/skills/docket-groom-next/SKILL.md index 93a4b2141..9c4bf1022 100644 --- a/internal/assets/embedded/tree/skills/docket-groom-next/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-groom-next/SKILL.md @@ -71,7 +71,7 @@ All six exits reuse existing transitions — this skill introduces no new lifecy ### Step 5 — The transaction lands (no separate board pass) -The Step-4 typed op is the whole write: it re-checks the pinned exact `revision`, commits the change record, the spec, the `## Artifacts` block, and the inline board in one metadata commit pushed to the metadata remote under an exact-lease push — so there is no separate hand-staged commit and **no separate Board pass** (the readiness cell flips from needs-grooming, or the row leaves the Proposed section on a kill or defer, in that same commit; a revise keeps the row's readiness; a re-enable returns an abstained row to needs-grooming). On a `contended` refusal the op writes nothing: re-sync (re-run the `repository.prepare` operation), re-read the record's `path` + `revision` from the `status` operation, and — on a groom exit, if it is no longer needs-grooming (someone else groomed, killed, or claimed it) — STOP and report rather than overwrite; otherwise re-author and retry. On a revise, also re-read the spec (a fresh `spec_revision`) and stop if the change is no longer `proposed` or a stub edit finds it groomed (`spec:` or `trivial: true`). STOP — grooming never implements. +The Step-4 typed op is the whole write: it re-checks the pinned exact `revision`, commits the change record, the spec, the `## Artifacts` block, and the inline board in one metadata commit pushed to the metadata remote under an exact-lease push — so there is no separate hand-staged commit and **no separate Board pass** (the readiness cell flips from needs-grooming, or the row leaves the Proposed section on a kill or defer, in that same commit; a revise keeps the row's readiness unless it sets or lifts a hold; a re-enable returns an abstained row to needs-grooming). On a `contended` refusal the op writes nothing: re-sync (re-run the `repository.prepare` operation), re-read the record's `path` + `revision` from the `status` operation, and — on a groom exit, if it is no longer needs-grooming (someone else groomed, killed, or claimed it) — STOP and report rather than overwrite; otherwise re-author and retry. On a revise, also re-read the spec (a fresh `spec_revision`) and stop if the change is no longer `proposed` or a stub edit finds it groomed (`spec:` or `trivial: true`). STOP — grooming never implements. ## Concurrency — no claim 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 89af8459d..94e17a919 100644 --- a/internal/assets/embedded/tree/skills/docket-implement-next/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-implement-next/SKILL.md @@ -38,7 +38,7 @@ Build-readiness and ranking are defined by the convention's **Build-readiness & **Acquisition.** Run the `status` operation with `--json` — a write-free read; on the selection path, only AFTER Step 0's `maintenance.preflight` run and metadata re-sync (the snapshot is taken pre-sweep otherwise and would list already-merged changes). A named invocation takes no ready-queue digest — it arrives here already holding Step 0's directive to read the explicit-id bundle below. Validate the envelope before trusting it: `protocol_version` MUST be `1` and `operation` MUST be `status`. The top-level `ready` array IS the build-ready queue, already in the convention's deterministic order — final tie-break LOWEST `id`, so concurrent implementers converge on one winner. Per-change skip reasons come from each `changes[]` entry's `readiness` / `readiness_reason` fields (`readiness` vocabulary: `build-ready`, `on-hold`, `needs-grooming`, `waiting-dependency`, `stack-base-unresolved`, `not-proposed`, `auto-groom-blocked`, `invalid`; `readiness_reason` carries the human-readable phrase). -The digest is an **accelerator, not the sole channel**: the authoritative read is the `context.implementation` operation with `--id ` (no `--id` applies the same selection policy; an attributed retry passes the id). It loads ONE fresh snapshot and returns the change's source bytes, exact opaque **record revision**, readiness, claim-eligibility, resolved effective base, integration branch, and workflow config — the single bundle the claim and every later operation key on, so no step re-reads the change file. **Judgment on that bundle stays yours.** CONFIRM build-readiness before claiming — a stale digest costs a re-pick, never a bad build; a typed no-candidate/absent-id/duplicate-id/not-ready/unsupported-config outcome is surfaced, never overridden. If the bundle disagrees with the digest, drop that candidate, take the next, and REPORT it; on the selection path a bundle reporting `on-hold` is dropped and reported the same way. **The exit status and the envelope's shape together govern the disposition.** A **non-zero exit**, or stdout that will not parse as a JSON envelope, **is a hard error** (config export failure, refused bootstrap guard, missing metadata worktree, failed render, or malformed output) — surface its stderr diagnostic and STOP with the **`halted`** disposition; never fall back to `active/` for a hard error, and never report `drained` for one. On **exit 0** with a valid envelope, an **empty `ready` array** (`ready: []`) means the queue is genuinely empty → `drained`. A parseable envelope that is **missing the `ready` key altogether** is malformed machine output — **reject it and STOP with `halted`**, exactly as for a hard error: the typed contract always carries `ready`, so there is no walk-`active/`-yourself degradation. Likewise a failed `protocol_version`/`operation` check. +The digest is an **accelerator, not the sole channel**: the authoritative read is the `context.implementation` operation with `--id ` (no `--id` applies the same selection policy; an attributed retry passes the id). It loads ONE fresh snapshot and returns the change's source bytes, exact opaque **record revision**, readiness, claim-eligibility, resolved effective base, integration branch, and workflow config — the single bundle the claim and every later operation key on, so no step re-reads the change file. **Judgment on that bundle stays yours.** CONFIRM build-readiness (on the named path `on-hold` also qualifies) before claiming — a stale digest costs a re-pick, never a bad build; a typed no-candidate/absent-id/duplicate-id/not-ready/unsupported-config outcome is surfaced, never overridden. If the bundle disagrees with the digest, drop that candidate, take the next, and REPORT it; on the selection path a bundle reporting `on-hold` is dropped and reported the same way. **The exit status and the envelope's shape together govern the disposition.** A **non-zero exit**, or stdout that will not parse as a JSON envelope, **is a hard error** (config export failure, refused bootstrap guard, missing metadata worktree, failed render, or malformed output) — surface its stderr diagnostic and STOP with the **`halted`** disposition; never fall back to `active/` for a hard error, and never report `drained` for one. On **exit 0** with a valid envelope, an **empty `ready` array** (`ready: []`) means the queue is genuinely empty → `drained`. A parseable envelope that is **missing the `ready` key altogether** is malformed machine output — **reject it and STOP with `halted`**, exactly as for a hard error: the typed contract always carries `ready`, so there is no walk-`active/`-yourself degradation. Likewise a failed `protocol_version`/`operation` check. **Scope (id allowlist).** With no argument the candidate set is the whole `ready` queue. A caller may pass an **id allowlist** of two or more ids — `docket-implement-next 90,92,94` — and selection is then **restricted to that set**, preserving the queue's order *within* it. (A **single explicit id** is not an allowlist: it is a named invocation and takes Step 0's named branch, never this filter.) The allowlist is a filter, **never a dependency override**: a scoped id that is not currently build-ready+claimable — needs-grooming, on hold, already `in-progress`, or waiting on an unmerged `depends_on` — is **skipped with its reason** (read it off that id's `changes[]` entry — a non-`proposed` `status` there is skipped for that status — or from the change file if it has none — already archived, or no such id), never force-built, and never aborts the run. diff --git a/internal/domain/readiness.go b/internal/domain/readiness.go index 8d1ae9145..8baa9a685 100644 --- a/internal/domain/readiness.go +++ b/internal/domain/readiness.go @@ -1,9 +1,10 @@ package domain // ReadinessKind tags a change's readiness outcome. Readiness is a typed value -// rather than a Boolean: a caller that only wants "can this be built" reads -// Kind == ReadyBuildReady, while a caller reporting to a human keeps the exact -// reason the change is not ready. +// rather than a Boolean: selection reads Kind == ReadyBuildReady, "may this +// named change be built" goes through ClaimEligibility (which also admits +// ReadyOnHold), and a caller reporting to a human keeps the exact reason the +// change is not ready. type ReadinessKind string // The closed set of readiness outcomes. diff --git a/internal/domain/types_test.go b/internal/domain/types_test.go index dbbce2a8e..38d7b0d22 100644 --- a/internal/domain/types_test.go +++ b/internal/domain/types_test.go @@ -313,20 +313,6 @@ func TestChangeDeliverableEffectiveValue(t *testing.T) { // TestLifecycleActionCarriesDeliverable pins newChangeBuilder's copy: a // lifecycle write must keep the stored deliverable, known or unknown. -func TestLifecycleActionCarriesHold(t *testing.T) { - c := NewChange(ChangeSpec{ID: 1, Slug: "s", Status: StatusProposed, Type: "feat", Trivial: true, Hold: holdTrue}) - res, fail := Claim(c, actNow) - if fail != nil { - t.Fatalf("Claim: %v", fail) - } - if !res.Change.Held() { - t.Error("Held after Claim = false, want true") - } - if got := res.Change.Hold(); got != holdTrue { - t.Errorf("Hold after Claim = %+v, want %+v", got, holdTrue) - } -} - func TestLifecycleActionCarriesDeliverable(t *testing.T) { for _, spec := range []ChangeSpec{ {ID: 1, Slug: "s", Status: StatusProposed, Deliverable: DeliverableResultsArtifact, RawDeliverable: "results-artifact"}, @@ -344,3 +330,19 @@ 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}) + res, fail := Claim(c, actNow) + if fail != nil { + t.Fatalf("Claim: %v", fail) + } + if !res.Change.Held() { + t.Error("Held after Claim = false, want true") + } + if got := res.Change.Hold(); got != holdTrue { + t.Errorf("Hold after Claim = %+v, want %+v", got, holdTrue) + } +} diff --git a/internal/repoguard/budgets_test.go b/internal/repoguard/budgets_test.go index 9c27f2f04..fa87438e2 100644 --- a/internal/repoguard/budgets_test.go +++ b/internal/repoguard/budgets_test.go @@ -205,8 +205,8 @@ var skillBudgets = []skillBudget{ {"docket-convention/references/stacked-changes.md", 223, 2217}, // 0567: carried children are cleaned right after the root once their work is proven (219/2173 -> 223/2217); 0565: a kill refuses on built stacked descendants; the killed-parent board text and exits table (214/2149 -> 219/2173); 0502: typed operations and binary-emitted findings replace the Bash-era names (213/2125 -> 214/2149); 0502: the deferred descendant-publication sentence is deleted (215/2140 -> 213/2125); 0327: +carry-preservation contract prose (see note above) {"docket-finalize-change/SKILL.md", 243, 6254}, // 0567: step 10 cleans each carried_ids child after the root (243/6191 -> 243/6254); 0551: step 1 checks the change out into its own workspace first (241/6033 -> 243/6191); 0532 review: both finalize gate dispatches carry the Visibility payload line (239/6020 -> 241/6033); 0532: the private-repository writing rule and visibility hand-off (239/6000 -> 239/6020); 0529 review: the PR-backlink repoint is a best-effort follow-up after the archive push, for root-archived descendants too (239/5984 -> 239/6000); 0529: close-out repoints the merged PR description's backlink; pr-backlink-pending is a retryable warning (239/5936 -> 239/5984); 0525 review: workspace-remnant rides any finished-workspace disposition and is named in the final report; branch-rules-unavailable comes only from the probing run (239/5910 -> 239/5936); 0525: plan-gated merges carry branch-rules-unavailable into closeout notes; cleanup reports workspace-remnant and names what blocked a workspace (239/5820 -> 239/5910); 0515 review: the refused-notes fallback names every dropped note in the final report (238/5809 -> 239/5820); 0515 review: a repair whose run halts before closeout is named in finalize.block and carried into a later closeout (238/5708 -> 238/5809); 0515: the repair sign-off is retired; a green repair merges (238/5808 -> 238/5708); 0517: the repaired-head evidence.record carries --owner finalize and records finalize.test_command (238/5790 -> 238/5808); 0502 review: clear-block re-reads the revision after the block lands (238/5771 -> 238/5790); 0502: repair sign-off records finalize.block before publishing the repaired head (238/5733 -> 238/5771); 0502: "loop" means /loop only (238/5729 -> 238/5733); 0502: repair sign-off is the human running finalize.clear-block (238/5666 -> 238/5729); 0502: the repaired head is re-gated through the gate driver (236/5568 -> 238/5666); 0502: the dummy-mode paragraph is deleted (238/5641 -> 236/5568); 0455: +record-invalid refusal (structural scope, findings remedy, merged-outside-docket precedence) in step 8 (word ceiling 5520 -> 5647); 0442: +post-publication base-advance guidance (word ceiling 5421 -> 5520); de-duplicated the shared forward-rebase mechanic against the 0438 unpublished-case paragraph (reclaimed 57 words), but the distinct published-refresh facts plus the retained 0438 guidance cannot fit the old ceiling without deleting required guidance; 0411: +reconciliation-write recovery exception paragraph in the resolver loop (ceilings 238/5232 -> 239/5421); 0413: +generated-bundle mixed-conflict handoff sentence in the resolver-loop block (word ceiling 5200 -> 5232); 0419: +repair-attempt budget payload line and rewired repair contract (line ceiling 236 -> 238); 0393: +exact payload, marker, and direct-dispatch lines atop 0349/0410 (see note above) {"docket-finalize-change/references/gate-failure.md", 162, 2111}, // 0532 review: the gate-agent payload names Visibility (161/2109 -> 162/2111); 0515 review: the refused-notes fallback names every dropped note in the final report (160/2098 -> 161/2109); 0515 review: a repair whose run halts before closeout is named in finalize.block and carried into a later closeout (153/2005 -> 160/2098); 0515: the repair sign-off is retired; a green repair merges (160/2086 -> 153/2005); 0517: the repaired-head evidence.record carries --owner finalize (159/2081 -> 160/2086); 0502 review: clear-block re-reads the revision after the block lands (157/2062 -> 159/2081); 0502: repair sign-off records finalize.block before publishing the repaired head (155/2028 -> 157/2062); 0502: the embedded-bundle rule is conditioned on docket's own repository (155/2024 -> 155/2028); 0502: "loop" means /loop only (155/2027 -> 155/2024); 0502: repair sign-off is the human running finalize.clear-block; the marker lifecycle names what removes it (154/2013 -> 155/2027); 0502: the repaired head is re-gated through the gate driver (148/1937 -> 154/2013); 0497: +wait-for-the-leftover-group sentence (146/1901 -> 148/1937); 0493: the gate relaunch is retired (145/1892 -> 146/1901); 0491: the run id is retired (145/1894 -> 145/1892); 0490: the shared-slot note became the shared worktree-lock note (147/1901 -> 145/1894); 0411: +reconciliation-write exception section and abort-set carve-out (ceilings 135/1472 -> 147/1901); 0413: +conflicted_paths-lists-authored-only rule in the resolver-report section (line ceiling 133 -> 135, word ceiling 1465 -> 1472); 0419: +repair-attempt budget payload and rewired repair contract prose (word ceiling 1450 -> 1465); 0349: +reserve-before-dispatch resolver protocol prose; 0375: +worktree-slot note for the scopeless finalize gate (120/1300 -> 133/1450) - {"docket-groom-next/SKILL.md", 78, 2370}, // 0560: the Step-4 hold paragraph (76/2282 -> 78/2370); 0559: the Step-4 deliverable, type, and branch_prefix paragraph (78/2215 -> 76/2282); 0550: the Step-4 reprioritize paragraph and the stub-edit priority route (76/2141 -> 78/2215); 0532: the private-repository writing rule and visibility hand-off (76/2109 -> 76/2141); 0531: the metadata worktree and remote come from the repository.prepare context (76/2102 -> 76/2109); 0502 rebase onto 0509: carried the edit-a-stub revise route and groom-exit-scoped STOPs (76/2012 -> 76/2102); 0502: "loop" means /loop only (76/2011 -> 76/2012); 0502: one metadata layout — the docket branch and the .docket/ worktree (76/2010 -> 76/2011); 0502: selection bands key on auto_groomable itself (76/2009 -> 76/2010); 0502: invoke superpowers:brainstorming by name (76/2037 -> 76/2009); 0502: the dummy-mode pointer is deleted (78/2080 -> 76/2037); 0461: +Step-4 retitle paragraph (title on change.groom; lines 77 -> 78, words 1996 -> 2081); +not-retitleable refusal code (2081 -> 2082); 0382: +typed rearm exit (word ceiling 1889 -> 1996); 0445: +revise route for already-groomed explicit ids (Step 1) and the fifth Step-4 exit (word ceiling 1650 -> 1813); +spec_version pin for a spec-body revise (1813 -> 1849); +revise spec_markdown excludes the backlink block (1849 -> 1850); +revise in the description and the revise contended/board clauses (1850 -> 1889) - {"docket-implement-next/SKILL.md", 218, 8548}, // 0560: on-hold joins the readiness vocabulary and skip reasons; a held change is built when named (218/8518 -> 218/8548); 0559: the results-artifact ending pointer, postcondition row, and advanced meaning (215/8411 -> 218/8518); 0532: the private-repository writing rule and visibility hand-off (212/8282 -> 215/8411); 0531: the metadata worktree and remote come from the repository.prepare context (216/8443 -> 212/8282); 0517: evidence.record reads the gate command from build configuration (216/8438 -> 216/8443); 0502 rebase onto 0510: carried the Step 6.5 Backlog match paragraph and verdict pointers (214/8039 -> 216/8438); 0502 review: the controller dispatches the review tier wrapper; the skill dispatches nothing (214/8023 -> 214/8039); 0502: "loop" means /loop only (214/8058 -> 214/8057); 0502: one metadata layout — the docket branch and the .docket/ worktree (214/8042 -> 214/8058); 0502: the review payload names the resolved build.gate value; build_gate spellings become build.gate (214/8020 -> 214/8042); 0502: change.reclaim replaces reclaim-claims; the claim removes a leftover ## Run halted (214/8009 -> 214/8020); 0502: terminal-publication narration is deleted (214/8037 -> 214/8009); 0502: the severity floor is read as review.min_fix_severity through diagnostic.config (214/8034 -> 214/8037); 0502: the fixed role skills replace the $SKILL_* sites (214/8257 -> 214/8034); 0502: the dummy-mode paragraph and PR-body clause are deleted (216/8356 -> 214/8257); 0497: +Step 5 halted-build evidence kept verbatim in ## Run halted (216/8325 -> 216/8356); 0498 review: checkpoint (ii) persist wording (8320 -> 8325); 0498: +Step 6.5 review-findings homes, condensation exception, Human-actions class rule (214/8161 -> 216/8320); 0491: the run id is retired (214/8183 -> 214/8161); 0488 review: build-owned starts carry --change-id/--run-context (word ceiling 8162 -> 8183); 0488: run context and run id name only build-owned starts (word ceiling 8175 -> 8162); 0467 review fix: +the repair worker's post-fix re-run is a build-owned start (word ceiling 8165 -> 8175); 0467: +run id threaded to prepare-scope and build-owned starts (word ceiling 8080 -> 8165); 0455: +pr.publish record-invalid refusal clause (word ceiling 8025 -> 8080); 0448: +named-invocation branch; bounded own-dependency closeout moved to edge-paths.md (ceilings 210/7716 -> 214/8270 -> 214/8025); 0393: +exact payload, marker, and direct-dispatch lines atop 0410/0354/0376; 0375: +run-tracker resume pointer (word ceiling 7530 -> 7547); 0440: reader-first results prose; 0502: drop change citations and Go v1 narration (214/8057 -> 214/8023) + {"docket-groom-next/SKILL.md", 78, 2377}, // 0560 review: a revise that sets or lifts a hold changes the row's readiness (78/2370 -> 78/2377); 0560: the Step-4 hold paragraph (76/2282 -> 78/2370); 0559: the Step-4 deliverable, type, and branch_prefix paragraph (78/2215 -> 76/2282); 0550: the Step-4 reprioritize paragraph and the stub-edit priority route (76/2141 -> 78/2215); 0532: the private-repository writing rule and visibility hand-off (76/2109 -> 76/2141); 0531: the metadata worktree and remote come from the repository.prepare context (76/2102 -> 76/2109); 0502 rebase onto 0509: carried the edit-a-stub revise route and groom-exit-scoped STOPs (76/2012 -> 76/2102); 0502: "loop" means /loop only (76/2011 -> 76/2012); 0502: one metadata layout — the docket branch and the .docket/ worktree (76/2010 -> 76/2011); 0502: selection bands key on auto_groomable itself (76/2009 -> 76/2010); 0502: invoke superpowers:brainstorming by name (76/2037 -> 76/2009); 0502: the dummy-mode pointer is deleted (78/2080 -> 76/2037); 0461: +Step-4 retitle paragraph (title on change.groom; lines 77 -> 78, words 1996 -> 2081); +not-retitleable refusal code (2081 -> 2082); 0382: +typed rearm exit (word ceiling 1889 -> 1996); 0445: +revise route for already-groomed explicit ids (Step 1) and the fifth Step-4 exit (word ceiling 1650 -> 1813); +spec_version pin for a spec-body revise (1813 -> 1849); +revise spec_markdown excludes the backlink block (1849 -> 1850); +revise in the description and the revise contended/board clauses (1850 -> 1889) + {"docket-implement-next/SKILL.md", 218, 8555}, // 0560 review: on the named path on-hold also qualifies at the Step-1 confirm (218/8548 -> 218/8555); 0560: on-hold joins the readiness vocabulary and skip reasons; a held change is built when named (218/8518 -> 218/8548); 0559: the results-artifact ending pointer, postcondition row, and advanced meaning (215/8411 -> 218/8518); 0532: the private-repository writing rule and visibility hand-off (212/8282 -> 215/8411); 0531: the metadata worktree and remote come from the repository.prepare context (216/8443 -> 212/8282); 0517: evidence.record reads the gate command from build configuration (216/8438 -> 216/8443); 0502 rebase onto 0510: carried the Step 6.5 Backlog match paragraph and verdict pointers (214/8039 -> 216/8438); 0502 review: the controller dispatches the review tier wrapper; the skill dispatches nothing (214/8023 -> 214/8039); 0502: "loop" means /loop only (214/8058 -> 214/8057); 0502: one metadata layout — the docket branch and the .docket/ worktree (214/8042 -> 214/8058); 0502: the review payload names the resolved build.gate value; build_gate spellings become build.gate (214/8020 -> 214/8042); 0502: change.reclaim replaces reclaim-claims; the claim removes a leftover ## Run halted (214/8009 -> 214/8020); 0502: terminal-publication narration is deleted (214/8037 -> 214/8009); 0502: the severity floor is read as review.min_fix_severity through diagnostic.config (214/8034 -> 214/8037); 0502: the fixed role skills replace the $SKILL_* sites (214/8257 -> 214/8034); 0502: the dummy-mode paragraph and PR-body clause are deleted (216/8356 -> 214/8257); 0497: +Step 5 halted-build evidence kept verbatim in ## Run halted (216/8325 -> 216/8356); 0498 review: checkpoint (ii) persist wording (8320 -> 8325); 0498: +Step 6.5 review-findings homes, condensation exception, Human-actions class rule (214/8161 -> 216/8320); 0491: the run id is retired (214/8183 -> 214/8161); 0488 review: build-owned starts carry --change-id/--run-context (word ceiling 8162 -> 8183); 0488: run context and run id name only build-owned starts (word ceiling 8175 -> 8162); 0467 review fix: +the repair worker's post-fix re-run is a build-owned start (word ceiling 8165 -> 8175); 0467: +run id threaded to prepare-scope and build-owned starts (word ceiling 8080 -> 8165); 0455: +pr.publish record-invalid refusal clause (word ceiling 8025 -> 8080); 0448: +named-invocation branch; bounded own-dependency closeout moved to edge-paths.md (ceilings 210/7716 -> 214/8270 -> 214/8025); 0393: +exact payload, marker, and direct-dispatch lines atop 0410/0354/0376; 0375: +run-tracker resume pointer (word ceiling 7530 -> 7547); 0440: reader-first results prose; 0502: drop change citations and Go v1 narration (214/8057 -> 214/8023) {"docket-implement-next/references/edge-paths.md", 109, 1265}, // 0532: the private-repository writing rule and visibility hand-off (109/1226 -> 109/1265); 0531: the metadata worktree and remote come from the repository.prepare context (118/1499 -> 109/1226); 0502: one metadata layout — the docket branch and the .docket/ worktree (118/1507 -> 118/1509); 0502: run.verify replaces verify-run (118/1505 -> 118/1507); 0502: terminal-publication narration is deleted (118/1513 -> 118/1505); 0502: the deferred results-only permit clause is deleted (118/1546 -> 118/1513); 0502: no custom plan location (118/1547 -> 118/1546); 0491: the run id is retired (118/1554 -> 118/1547); 0410: +resume/recovery + required-results reconciliation; 0375: +run-tracker resume refusals (78/1091 -> 93/1261); 0448: +named own-dependency closeout moved from SKILL.md (93/1261 -> 118/1554); 0502: drop change citations and Go v1 narration (118/1509 -> 118/1499) {"docket-implement-next/references/fix-pass.md", 189, 1963}, // 0532: the private-repository writing rule and visibility hand-off (187/1943 -> 189/1963); 0502 rebase onto 0510: carried the backlog-verdict pointer for reported findings (186/1929 -> 187/1943); 0502: "loop" means /loop only (190/1962 -> 190/1967); 0502: undispatchable fix worker halts (192/1991 -> 190/1962); 0502: renamed from fix-loop.md; 0498 review: results-file antecedent (1989 -> 1991); 0498: +review-findings condensation at final consolidation (190/1958 -> 192/1989); 0410: +findings-to-results checkpoint linkage (see note above); 0502: drop change citations and Go v1 narration (190/1967 -> 186/1929) {"docket-implement-next/references/results-artifact.md", 79, 775}, // 0559: new — the results-artifact ending (no plan, build, or PR; review, complete, clean up) diff --git a/skills/docket-groom-next/SKILL.md b/skills/docket-groom-next/SKILL.md index 93a4b2141..9c4bf1022 100644 --- a/skills/docket-groom-next/SKILL.md +++ b/skills/docket-groom-next/SKILL.md @@ -71,7 +71,7 @@ All six exits reuse existing transitions — this skill introduces no new lifecy ### Step 5 — The transaction lands (no separate board pass) -The Step-4 typed op is the whole write: it re-checks the pinned exact `revision`, commits the change record, the spec, the `## Artifacts` block, and the inline board in one metadata commit pushed to the metadata remote under an exact-lease push — so there is no separate hand-staged commit and **no separate Board pass** (the readiness cell flips from needs-grooming, or the row leaves the Proposed section on a kill or defer, in that same commit; a revise keeps the row's readiness; a re-enable returns an abstained row to needs-grooming). On a `contended` refusal the op writes nothing: re-sync (re-run the `repository.prepare` operation), re-read the record's `path` + `revision` from the `status` operation, and — on a groom exit, if it is no longer needs-grooming (someone else groomed, killed, or claimed it) — STOP and report rather than overwrite; otherwise re-author and retry. On a revise, also re-read the spec (a fresh `spec_revision`) and stop if the change is no longer `proposed` or a stub edit finds it groomed (`spec:` or `trivial: true`). STOP — grooming never implements. +The Step-4 typed op is the whole write: it re-checks the pinned exact `revision`, commits the change record, the spec, the `## Artifacts` block, and the inline board in one metadata commit pushed to the metadata remote under an exact-lease push — so there is no separate hand-staged commit and **no separate Board pass** (the readiness cell flips from needs-grooming, or the row leaves the Proposed section on a kill or defer, in that same commit; a revise keeps the row's readiness unless it sets or lifts a hold; a re-enable returns an abstained row to needs-grooming). On a `contended` refusal the op writes nothing: re-sync (re-run the `repository.prepare` operation), re-read the record's `path` + `revision` from the `status` operation, and — on a groom exit, if it is no longer needs-grooming (someone else groomed, killed, or claimed it) — STOP and report rather than overwrite; otherwise re-author and retry. On a revise, also re-read the spec (a fresh `spec_revision`) and stop if the change is no longer `proposed` or a stub edit finds it groomed (`spec:` or `trivial: true`). STOP — grooming never implements. ## Concurrency — no claim diff --git a/skills/docket-implement-next/SKILL.md b/skills/docket-implement-next/SKILL.md index 89af8459d..94e17a919 100644 --- a/skills/docket-implement-next/SKILL.md +++ b/skills/docket-implement-next/SKILL.md @@ -38,7 +38,7 @@ Build-readiness and ranking are defined by the convention's **Build-readiness & **Acquisition.** Run the `status` operation with `--json` — a write-free read; on the selection path, only AFTER Step 0's `maintenance.preflight` run and metadata re-sync (the snapshot is taken pre-sweep otherwise and would list already-merged changes). A named invocation takes no ready-queue digest — it arrives here already holding Step 0's directive to read the explicit-id bundle below. Validate the envelope before trusting it: `protocol_version` MUST be `1` and `operation` MUST be `status`. The top-level `ready` array IS the build-ready queue, already in the convention's deterministic order — final tie-break LOWEST `id`, so concurrent implementers converge on one winner. Per-change skip reasons come from each `changes[]` entry's `readiness` / `readiness_reason` fields (`readiness` vocabulary: `build-ready`, `on-hold`, `needs-grooming`, `waiting-dependency`, `stack-base-unresolved`, `not-proposed`, `auto-groom-blocked`, `invalid`; `readiness_reason` carries the human-readable phrase). -The digest is an **accelerator, not the sole channel**: the authoritative read is the `context.implementation` operation with `--id ` (no `--id` applies the same selection policy; an attributed retry passes the id). It loads ONE fresh snapshot and returns the change's source bytes, exact opaque **record revision**, readiness, claim-eligibility, resolved effective base, integration branch, and workflow config — the single bundle the claim and every later operation key on, so no step re-reads the change file. **Judgment on that bundle stays yours.** CONFIRM build-readiness before claiming — a stale digest costs a re-pick, never a bad build; a typed no-candidate/absent-id/duplicate-id/not-ready/unsupported-config outcome is surfaced, never overridden. If the bundle disagrees with the digest, drop that candidate, take the next, and REPORT it; on the selection path a bundle reporting `on-hold` is dropped and reported the same way. **The exit status and the envelope's shape together govern the disposition.** A **non-zero exit**, or stdout that will not parse as a JSON envelope, **is a hard error** (config export failure, refused bootstrap guard, missing metadata worktree, failed render, or malformed output) — surface its stderr diagnostic and STOP with the **`halted`** disposition; never fall back to `active/` for a hard error, and never report `drained` for one. On **exit 0** with a valid envelope, an **empty `ready` array** (`ready: []`) means the queue is genuinely empty → `drained`. A parseable envelope that is **missing the `ready` key altogether** is malformed machine output — **reject it and STOP with `halted`**, exactly as for a hard error: the typed contract always carries `ready`, so there is no walk-`active/`-yourself degradation. Likewise a failed `protocol_version`/`operation` check. +The digest is an **accelerator, not the sole channel**: the authoritative read is the `context.implementation` operation with `--id ` (no `--id` applies the same selection policy; an attributed retry passes the id). It loads ONE fresh snapshot and returns the change's source bytes, exact opaque **record revision**, readiness, claim-eligibility, resolved effective base, integration branch, and workflow config — the single bundle the claim and every later operation key on, so no step re-reads the change file. **Judgment on that bundle stays yours.** CONFIRM build-readiness (on the named path `on-hold` also qualifies) before claiming — a stale digest costs a re-pick, never a bad build; a typed no-candidate/absent-id/duplicate-id/not-ready/unsupported-config outcome is surfaced, never overridden. If the bundle disagrees with the digest, drop that candidate, take the next, and REPORT it; on the selection path a bundle reporting `on-hold` is dropped and reported the same way. **The exit status and the envelope's shape together govern the disposition.** A **non-zero exit**, or stdout that will not parse as a JSON envelope, **is a hard error** (config export failure, refused bootstrap guard, missing metadata worktree, failed render, or malformed output) — surface its stderr diagnostic and STOP with the **`halted`** disposition; never fall back to `active/` for a hard error, and never report `drained` for one. On **exit 0** with a valid envelope, an **empty `ready` array** (`ready: []`) means the queue is genuinely empty → `drained`. A parseable envelope that is **missing the `ready` key altogether** is malformed machine output — **reject it and STOP with `halted`**, exactly as for a hard error: the typed contract always carries `ready`, so there is no walk-`active/`-yourself degradation. Likewise a failed `protocol_version`/`operation` check. **Scope (id allowlist).** With no argument the candidate set is the whole `ready` queue. A caller may pass an **id allowlist** of two or more ids — `docket-implement-next 90,92,94` — and selection is then **restricted to that set**, preserving the queue's order *within* it. (A **single explicit id** is not an allowlist: it is a named invocation and takes Step 0's named branch, never this filter.) The allowlist is a filter, **never a dependency override**: a scoped id that is not currently build-ready+claimable — needs-grooming, on hold, already `in-progress`, or waiting on an unmerged `depends_on` — is **skipped with its reason** (read it off that id's `changes[]` entry — a non-`proposed` `status` there is skipped for that status — or from the change file if it has none — already archived, or no such id), never force-built, and never aborts the run.