diff --git a/README.md b/README.md index b8cec24fa..64af24422 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ the audit trail — and the whole interface between you and the autonomous skill | Stage | What docket commits | Where it lives | |---|---|---| | Plan | The change file: why, what changes, out of scope, dependencies, priority, type | `docs/changes/active/` on the `docket` metadata branch; rendered on `BOARD.md` | -| Design | The spec, linked from the change (or `trivial: true` for small mechanical work) | `docs/superpowers/specs/` on the metadata branch | +| Design | The spec, linked from the change | `docs/superpowers/specs/` on the metadata branch | | Build | A dated reconcile log, the implementation plan, one verified commit per task | The change body and `docs/superpowers/plans/` on the metadata branch; the commits on the feature branch | | Test | The build-evidence record — suite command, result, head SHA — plus the results file and the review's disposition table | The change body's `## Build evidence` section and `docs/results/` on the metadata branch; the table in the PR body | | Deploy | The merge (proven reachable), the archived change record, a cleaned branch and worktree, a re-rendered board | `docs/changes/archive/`; `BOARD.md` | diff --git a/agents/docket-auto-groom-critic.md b/agents/docket-auto-groom-critic.md index 14d19dd38..b4d0bce05 100644 --- a/agents/docket-auto-groom-critic.md +++ b/agents/docket-auto-groom-critic.md @@ -1,6 +1,6 @@ --- name: docket-auto-groom-critic -description: Adversarial reviewer of an auto-groom draft spec or trivial verdict — attacks it, never improves it, and returns exactly one verdict per the dispatching skill's protocol. +description: Adversarial reviewer of an auto-groom draft spec — attacks it, never improves it, and returns exactly one verdict per the dispatching skill's protocol. skills: [docket-convention] worktree-scope: metadata --- diff --git a/agents/docket-auto-groom.md b/agents/docket-auto-groom.md index 2b7c4907b..e7243a89d 100644 --- a/agents/docket-auto-groom.md +++ b/agents/docket-auto-groom.md @@ -1,6 +1,6 @@ --- name: docket-auto-groom -description: Use when individual stubs opted into autonomous grooming (their `auto_groomable` is `true`) and you want the auto-groomable needs-grooming queue drained with no human — selecting each auto-groomable stub deterministically and designing it via a default-biased self-brainstorm gated by an adversarial critic, exiting each stub with a linked spec, a trivial verdict, or an abstain back to the human queue. Kill and defer are never autonomous. Writes markdown only — never branches, worktrees, or code. +description: Use when individual stubs opted into autonomous grooming (their `auto_groomable` is `true`) and you want the auto-groomable needs-grooming queue drained with no human — selecting each auto-groomable stub deterministically and designing it via a default-biased self-brainstorm gated by an adversarial critic, exiting each stub with a linked spec or an abstain back to the human queue. Kill and defer are never autonomous. Writes markdown only — never branches, worktrees, or code. skills: [docket-auto-groom, docket-convention] worktree-scope: metadata launch: root-coordinator diff --git a/cursor-rules/dispatch/docket-auto-groom-critic.md b/cursor-rules/dispatch/docket-auto-groom-critic.md index 195c80164..42b7ca10d 100644 --- a/cursor-rules/dispatch/docket-auto-groom-critic.md +++ b/cursor-rules/dispatch/docket-auto-groom-critic.md @@ -1,11 +1,11 @@ ## docket-auto-groom-critic — dispatch only This agent wraps no skill and is normally dispatched **by** docket-auto-groom as its adversarial gate, -not invoked directly. If you are asked to adversarially review an auto-groom draft spec or trivial -verdict, dispatch it rather than reviewing inline. +not invoked directly. If you are asked to adversarially review an auto-groom draft spec, dispatch it +rather than reviewing inline. Dispatch to the subagent `docket-auto-groom-critic`, foreground, using this mode's subagent-launch -mechanism. The prompt must include the draft spec / trivial verdict under review and the dispatching +mechanism. The prompt must include the draft spec under review and the dispatching skill's verdict protocol. Do NOT let it improve the draft — it only attacks and returns exactly one verdict. diff --git a/docs/comparison/ai-native-sdlc-playbook.md b/docs/comparison/ai-native-sdlc-playbook.md index 1a83aa87f..9cbc8fb54 100644 --- a/docs/comparison/ai-native-sdlc-playbook.md +++ b/docs/comparison/ai-native-sdlc-playbook.md @@ -50,12 +50,11 @@ fail-closed operations. In return docket has depth the playbook never mentions. | Capability | Playbook | docket | Status | |---|---|---|---| -| Spec committed beside the intent | `spec.md` beside `intent.md` as the audit record. | Spec on the metadata branch; `spec:`, `## Artifacts`, and the backlink written in one commit. Build-ready = spec or trivial. | Both | +| Spec committed beside the intent | `spec.md` beside `intent.md` as the audit record. | Spec on the metadata branch; `spec:`, `## Artifacts`, and the backlink written in one commit. Build-ready = spec. | Both | | Flagged concerns resolved before build | Policy concerns resolved with policy owners. | Consultant critique concerns; auto-groom critic verdicts (sound / fixable / needs-human). Design concerns, not organisational policy. | Both (different source) | | Organisational policy skills at spec time | Brand, security, compliance, UX skills guide the session. | docket ships no policy skills; the harness's own may fire. | Playbook only | | Autonomous design with an adversarial gate | Not described. | `docket-auto-groom` + isolated critic; one revision round; abstain writes `## Auto-groom blocked`; kill and defer never autonomous. | docket only | | Pinned-model spec author | Not described. | `docket-brainstorm` dispatches `docket-brainstorm-consultant` once; capture-then-groom pins the whole conversation. | docket only | -| Trivial path | Not described. | `trivial: true` keeps a small change build-ready with no spec. | docket only | | Grooming queue and selection bands | Not described. | Deterministic next-stub selection; abstained, then human-only, then auto-groomable. Grooming takes no claim. | docket only | | Measurement | Intent-to-spec time; rework by spec commits after the first plan commit. | None; reconcile-log entries make rework derivable. | Playbook only | @@ -130,7 +129,7 @@ fail-closed operations. In return docket has depth the playbook never mentions. | Stage | Playbook artifact | docket artifact | |---|---|---| | 1 | `intent.md` | Change file on `docket`: frontmatter + Why / What changes / Out of scope / Open questions; board row. | -| 2 | `spec.md` | Spec file on `docket` with a backlink header; `spec:` and `## Artifacts` on the change; or `trivial: true`. | +| 2 | `spec.md` | Spec file on `docket` with a backlink header; `spec:` and `## Artifacts` on the change. | | 3 | `plan.md` + the diff | `## Reconcile log` and `reconciled: true`; plan on the metadata branch (frozen once closed out); one verified commit per task. | | 4 | PR with test results | Build-evidence record in the change record; results file; review disposition table in the PR body. | | 5 | Merged PR / commit | Merge proven reachable; change archived as `archive/--.md` with optional `## Closeout notes`; branch and worktree cleaned; board re-rendered. | @@ -163,7 +162,7 @@ no-test-edits guard during repair; an intake path from production or scanner fin | Page (goal) | Stage | Content | From today's README | |---|---|---|---| | README — what docket automates, and where you stay in control | Landing | Thesis in the playbook's vocabulary; artifact chain; reconcile; install; daily loop; map | Intro, How it works, Why docket, Quickstart | -| Capturing work that outlives the session | 1 | Change file and manifest; lifecycle and board; priorities, types, dependencies, stacking; scan mode, trivial, discovered work | Lifecycle, convention manifest, auto_capture / change_types | +| Capturing work that outlives the session | 1 | Change file and manifest; lifecycle and board; priorities, types, dependencies, stacking; scan mode, discovered work | Lifecycle, convention manifest, auto_capture / change_types | | Designing before building | 2 | Interactive grooming; autonomous grooming and the critic; consultant specs | Quickstart step 2, consultant brainstorm | | Building without supervision | 3 | implement-next; reconcile; plan authoring; build tiers and escalation; worktrees, claims, /loop, dispositions | Why docket, docket-build, draining hands-free | | Proving the build | 4 | Build gate and evidence; gate driver and budgets; integration repair; configuring the suite | docket-build gate paragraphs, gate references, tests/README | diff --git a/docs/concepts/change-lifecycle.md b/docs/concepts/change-lifecycle.md index e83823116..b2a998f91 100644 --- a/docs/concepts/change-lifecycle.md +++ b/docs/concepts/change-lifecycle.md @@ -28,7 +28,7 @@ human has to memorize a flowchart to file a piece of work. ├──────────────► needs-grooming ────(design a spec)──┐ │ (no spec yet) │ │ ▼ - └──(has a spec or trivial mark, deps done)───────► build-ready + └──(has a spec, deps done)───────────────────────► build-ready │ (build takes a claim) ▼ @@ -50,11 +50,10 @@ human has to memorize a flowchart to file a piece of work. killed — abandoned as obsolete; final, kept in the archive ``` -- **proposed** is the raw entry. A proposed change with neither a spec nor a - 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**. A build-ready change on hold reads **on-hold**: +- **proposed** is the raw entry. A proposed change with no spec 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) and whose dependencies are all `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 diff --git a/docs/guide/building-without-supervision.md b/docs/guide/building-without-supervision.md index ce481d43a..5c1a7ef0a 100644 --- a/docs/guide/building-without-supervision.md +++ b/docs/guide/building-without-supervision.md @@ -65,8 +65,8 @@ any work continues. A single implement-next run walks a fixed path and then stops: -1. **Pick.** It selects the next **build-ready** change (a proposed change that has a spec or is - marked trivial and whose dependencies are all `done`). It never touches work that is not ready. +1. **Pick.** It selects the next **build-ready** change (a proposed change that has a spec and + whose dependencies are all `done`). It never touches work that is not ready. 2. **Claim.** It takes a **claim** on that change (the moment a change is picked up for building; it records which branch will carry the work and when it was taken) with a conflict-checked write on the change's status, so two runs in parallel can never grab the same change. The claim carries a diff --git a/docs/guide/capturing-work.md b/docs/guide/capturing-work.md index 557fb9c25..456307897 100644 --- a/docs/guide/capturing-work.md +++ b/docs/guide/capturing-work.md @@ -29,9 +29,8 @@ write in prose. As you meet them, the manifest fields are: - `depends_on` — the ids of other changes that must be `done` before this one can start. - `spec`, `plan`, `results` — the design document a change links to, written before building; the task-by-task breakdown a build follows, written on the metadata branch; and the required - close-out record of what a build actually did (one per implemented change, trivial included). + close-out record of what a build actually did (one per implemented change). Filled in as the change moves through its life. -- `trivial` — a flag that says "this is small and mechanical enough to skip the design step." - `branch`, `pr` — the feature branch and pull request, recorded once the build starts. The exact field list and its rules are owned by the reference tier — see @@ -47,8 +46,8 @@ proposed → in-progress → implemented → done ``` - **proposed** — captured, waiting to be built. A proposed change that has not been designed - enough to build (no spec, not marked `trivial`) sits in a **needs-grooming** state (a - proposed change with neither a spec nor a trivial mark; it needs a design conversation first) + enough to build (no spec) sits in a **needs-grooming** state (a proposed change with no spec; + it needs a design conversation first) until it is groomed — see [Designing before building](./designing-before-building.md). - **in-progress** — a run has claimed it and is building. - **implemented** — a pull request is open, waiting for your merge. @@ -120,7 +119,7 @@ is when you write it down. **A fully designed change.** When you already know what you want, capture it with the `docket-new-change` skill — a **skill** being a named, reusable instruction set an agent loads for one job. You describe the idea, docket brainstorms it with you into a **build-ready** change (a -proposed change that has a spec or is marked trivial and whose dependencies are all `done`) — a +proposed change that has a spec and whose dependencies are all `done`) — a spec written, dependencies noted — and commits the change file to the backlog. Because the backlog is durable, you can capture now and build later; the idea does not evaporate with the session. @@ -130,10 +129,8 @@ design step — it lands at `needs-grooming` and waits. You groom it later, in a whatever model you choose. Grooming is its own page: [Designing before building](./designing-before-building.md). -**Small and mechanical.** When the work is so small and mechanical that a design conversation -would be ceremony — a rename, a dependency bump — mark it `trivial`. A trivial change skips -needs-grooming entirely and is build-ready the moment its dependencies are clear, without a -spec. +**Small and mechanical.** Small work — a rename, a dependency bump — still gets a spec, just a +short one. **Scan mode.** Instead of describing one idea, you can point the new-change skill at the project and have it *scan* for candidate work — gaps, TODOs, obvious follow-ups — and mint them as diff --git a/docs/guide/designing-before-building.md b/docs/guide/designing-before-building.md index 3d9e58e32..93c0b70fe 100644 --- a/docs/guide/designing-before-building.md +++ b/docs/guide/designing-before-building.md @@ -8,11 +8,10 @@ an adversarial check, and have a high-tier consultant write the final design doc A **change** (one unit of planned work, roughly one pull request, tracked as one markdown file) that was captured as a rough stub lands in the **needs-grooming** state (a proposed change -with neither a spec nor a trivial mark; it needs a design conversation first). Grooming is what -moves it out of that state and into **build-ready** (a proposed change that has a spec or is -marked trivial and whose dependencies are all `done`). The output of grooming is a **spec** (the -design document a change links to, written before building) — or, for genuinely mechanical work, -a `trivial` mark that skips the spec. +with no spec; it needs a design conversation first). Grooming is what moves it out of that +state and into **build-ready** (a proposed change that has a spec and whose dependencies are all +`done`). The output of grooming is a **spec** (the design document a change links to, written +before building). ## Grooming a stub with a conversation @@ -36,7 +35,7 @@ auto-groom skill drains the ones you have marked auto-groomable with **no human Each stub is designed by a default-biased self-brainstorm, and — this is the safety rail — every resulting design is gated by an **adversarial critic**: a separately-run reviewer whose only job is to attack the draft. A design that survives the critic exits as a build-ready spec; one the -critic rejects (or that comes out genuinely trivial) is handled accordingly, and anything the +critic rejects is handled accordingly, and anything the groomer cannot settle confidently is handed back to your interactive queue rather than forced through. Such a stub shows as **auto-groom blocked — needs you** on the board. Once you have supplied the diff --git a/docs/install/models-and-effort.md b/docs/install/models-and-effort.md index 72b263c22..3e905bb15 100644 --- a/docs/install/models-and-effort.md +++ b/docs/install/models-and-effort.md @@ -17,7 +17,7 @@ worker with its own context, pinned to a model and effort (`docket-implement-nex The two interactive skills, `docket-new-change` and `docket-groom-next`, run at whatever model and effort your session uses, so you choose them. Pick by preference and by how complex you expect the -change to be: a quick stub, a trivial verdict, or a small revise needs little, while a net-new +change to be: a quick stub or a small revise needs little, while a net-new design, a cross-cutting change, or a stub whose premise needs tracing through the code is worth your strongest model at higher effort. diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index c3b1c1da7..c035ae15e 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -384,7 +384,7 @@ docket learning update --request finding-update.json # {path, revision, hook, The frontmatter block at the top of a change file. Its fields (`status`, `priority`, `type`, `depends_on`, `stacked_on`, `related`, `discovered_from`, `adrs`, `spec`, `plan`, `results`, -`trivial`, `auto_groomable`, `deliverable`, `branch`, `claimed_at`, `pr`, `blocked_by`, `reconciled`, …) are owned +`auto_groomable`, `deliverable`, `branch`, `claimed_at`, `pr`, `blocked_by`, `reconciled`, …) are owned by the `docket-convention` skill (see [`fields.md`](fields.md)). **Used for:** the machine-readable state of a change. Edit it only through typed operations; a @@ -415,7 +415,7 @@ it: `change halt` / `change resume-halted`, `finalize block` / `finalize clear-b ### Results The close-out record of what a build actually did — required for every implemented change, -trivial included, and the whole deliverable of a `results-artifact` change. +and the whole deliverable of a `results-artifact` change. **Used for:** telling the human what to check (`**Human action:**`, `## Outcome`, verification, known follow-ups). `change attach-results` writes the file in `` on the metadata @@ -445,18 +445,11 @@ the merge, the `## Artifacts` block adds a `Spec (merged)` row linking that copy ### Stub -A change captured without a design — `proposed`, no spec, not trivial. In lifecycle terms it is +A change captured without a design — `proposed`, no spec. In lifecycle terms it is **needs-grooming**. **Used for:** capturing an idea quickly and designing it later with grooming. -### Trivial - -A change marked `trivial: true` — small and mechanical enough to need no spec. - -**Used for:** skipping the design step. A trivial change with its dependencies done is -build-ready without a spec. - --- ## Change lifecycle and statuses @@ -613,10 +606,9 @@ finalize run they start) takes the change the rest of the way. It is a handoff t ### Readiness: build-ready / needs-grooming / not-proposed -**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 -five more kinds: `on-hold` (see [Hold](#hold)), `auto-groom-blocked`, `waiting-dependency`, +**Build-ready** is a proposed change that has a spec and whose dependencies are all `done`. +**Needs-grooming** is a proposed change with no spec; it needs a design conversation first. +Anything not `proposed` reads `not-proposed`. Status reports 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)). @@ -709,12 +701,11 @@ the parent holds the dialogue with you, then dispatches the **consultant** **Used for:** turning intent into a spec during `docket-new-change` or `docket-groom-next`. -### Capture modes: designed / rough stub / trivial / scan +### Capture modes: designed / rough stub / scan The ways work enters the backlog. **Designed**: brainstorm with `docket-new-change` into a spec, so the change is build-ready. **Rough stub**: capture without a design; it waits at needs-grooming. -**Trivial**: mark it `trivial` and skip design. **Scan mode**: point `docket-new-change` at the -project to mint several stubs in one pass. +**Scan mode**: point `docket-new-change` at the project to mint several stubs in one pass. **Used for:** matching capture effort to how finished the idea is. Scan mode is opt-in and only creates stubs; it never designs or builds. Work an unattended run discovers is reported in its final @@ -728,12 +719,12 @@ self-critiquing. ### Groom -Taking a stub through design to build-ready. Exits: a linked spec, a trivial verdict, a kill, a -defer, a revise of a `proposed` change (it keeps its groom state), or (autonomous only) an abstain. +Taking a stub through design to build-ready. Exits: a linked spec, a kill, a defer, a +revise of a `proposed` change (it keeps its groom state), or (autonomous only) an abstain. **Used for:** the step between capturing and building. Interactive grooming is `docket-groom-next`; the typed write underneath is `change.groom` with an `outcome` of `spec`, -`trivial`, `revise`, `abstain`, or `re-enable`. +`revise`, `abstain`, or `re-enable`. ```sh docket schema --operation change.groom @@ -743,10 +734,10 @@ docket change groom --request groom.json ### Groom outcome `revise` 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 +needs-grooming stub stays needs-grooming, and a spec'd 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 hold, the branch prefix, and relationship fields. A -hold moves a change between build-ready and on-hold. It never sets `spec:`, `trivial:`, or +hold moves a change between build-ready and on-hold. It never sets `spec:` or `auto_groomable:`, and it never edits `## Auto-groom blocked`, which only abstain and re-enable write. @@ -1716,8 +1707,8 @@ has recorded yet. Its dispatch fallback is `inline`: without dispatch it runs in ### docket-auto-groom The autonomous groomer. It drains every auto-groomable stub in one invocation. For each stub -it drafts a spec with an `## Assumptions` block, or a trivial verdict, then has the critic attack it. -Each stub exits as spec, trivial, or abstain. +it drafts a spec with an `## Assumptions` block, then has the critic attack it. +Each stub exits as spec or abstain. **Used for:** grooming overnight or from a routine. Kill and defer are never autonomous. Arm a stub by committing `auto_groomable: true` on it. @@ -1782,7 +1773,7 @@ skip. See *Finalize*. ### docket-groom-next The interactive groomer. It selects the next needs-grooming stub (or the id you name), opens with a -cold-start recap, and brainstorms it with you. It exits with spec, trivial, kill, defer, revise, or +cold-start recap, and brainstorms it with you. It exits with spec, kill, defer, revise, or re-enable. It never takes a claim and never mints ids. **Used for:** designing stubs together with you. Naming an already-groomed id, or asking to edit a @@ -1796,8 +1787,8 @@ stub rather than groom it, routes to `revise`. It runs inline at the session mod ### docket-new-change The interactive producer, and the entry point a human runs to propose work. It allocates the change -through `change.create`, brainstorms the design with you, and grooms it to a spec in one step. The -trivial path skips the brainstorm; scan mode mints stubs. +through `change.create`, brainstorms the design with you, and grooms it to a spec in one step. Scan +mode mints stubs. **Used for:** capturing an idea as a tracked change. It writes markdown only, never branches or code, and it stops at the spec. To adjust a spec afterwards, use `docket-groom-next ` rather than @@ -2135,7 +2126,7 @@ below. | `cleanup_dispositions` | `cleaned` `already-clean` `pending` `retained` `children-retarget-required` `rebase-scratch-cleared` | `finalize cleanup`, `gate cleanup` | | `closeout_dispositions` | `done-archived` `stacked-merged` `root-archived` `already-closed-out` `contended` `blocked` `unknown` `failed` | `finalize closeout` | | `complete_dispositions` | `completed` `already-completed` `contended` `failed` | `change complete` | -| `groom_outcomes` | `spec` `trivial` `revise` `abstain` `re-enable` | `change groom` (request `outcome`) | +| `groom_outcomes` | `spec` `revise` `abstain` `re-enable` | `change groom` (request `outcome`) | | `halt_dispositions` | `halted` `resumed` `contended` `refused` `failed` | `change halt`, `change resume-halted` | | `merge_dispositions` | `merged` `already-merged` `contended` `not-mergeable` `denied` `blocked` `unknown` | `finalize merge` | | `publish_dispositions` | `published` `noop` `contended` `unknown` `blocked` | `finalize publish` | @@ -2357,7 +2348,7 @@ docket development install --source ~/dev/docket - [Build tier / escalation](#build-tier--escalation) - [Cancel](#cancel) - [Capability catalog](#capability-catalog) -- [Capture modes: designed / rough stub / trivial / scan](#capture-modes-designed--rough-stub--trivial--scan) +- [Capture modes: designed / rough stub / scan](#capture-modes-designed--rough-stub--scan) - [Change](#change) - [Change types](#change-types) - [Claim / claim lease / reclaim](#claim--claim-lease--reclaim) @@ -2504,7 +2495,6 @@ docket development install --source ~/dev/docket - [Sweep](#sweep) - [Sync integration](#sync-integration) - [Tri-state verdict / halt exit code](#tri-state-verdict--halt-exit-code) -- [Trivial](#trivial) - [Two invocation paths: skill-invoke vs agent-dispatch](#two-invocation-paths-skill-invoke-vs-agent-dispatch) - [Uninstall](#uninstall) - [Verify-run](#run-verify) — see Run verify diff --git a/docs/superpowers/specs/2026-10-19-retire-trivial-every-build-ready-change-has-a-spec-design.md b/docs/superpowers/specs/2026-10-19-retire-trivial-every-build-ready-change-has-a-spec-design.md new file mode 100644 index 000000000..0dec57ee9 --- /dev/null +++ b/docs/superpowers/specs/2026-10-19-retire-trivial-every-build-ready-change-has-a-spec-design.md @@ -0,0 +1,183 @@ +# Every build-ready change has a spec — retire `trivial` + +Change 0573 — Retire trivial: every build-ready change has a spec + +## Why + +Grooming can end in a *trivial verdict*: no spec file, `trivial: true` on the record, and the +change body's owned sections (`## Why`, `## What changes`, `## Out of scope`) carry whatever the +groom decided. In practice this exit loses work. Grooming only offers it after a design +conversation has already happened — research done, alternatives weighed, decisions made — and the +trivial exit then asks the agent to squeeze that into "the tightened body as the trivial +rationale." Nothing requires the decisions or the rejected alternatives to survive, there is no +heading for them, and the result never reaches the PR or `main` (a spec is committed as the +feature branch's first commit; a trivial body stays on the metadata branch only). + +The exit also saves almost nothing. The flag changes only build-readiness and whether a spec file +exists: implement-next still reconciles, writes a plan, builds, reviews, and writes a results file +for a trivial change. The one thing skipped is writing the design down. + +History matches: every trivial verdict since about #325 (14 changes) came out of a groom; the +capture-time trivial path in `docket-new-change` was last used around #358. The human always +declines the trivial suggestion now, because the research has nowhere reliable to go. + +The suggestion itself mostly comes from the brainstorm role: `superpowers:brainstorming` sizes +small work as "described in chat, no written design." Removing the exit without countering that +sizing would leave the agent still proposing to skip the spec, with no place to record the choice. + +## Goal + +One rule: **a change is build-ready only when it has a spec** (plus the unchanged conditions: +`proposed`, dependencies `done`, stack base resolved, and the hold rule). Every groom that makes a +change build-ready writes a spec, sized to the change — a rename gets a short one. + +## Non-goals + +- Rewriting archived records or other repositories' records. Docket is pre-1.0.0; an unbuilt + `trivial: true` change in another repository simply drops back to needs-grooming. +- The broader trimming of superpowers brainstorming steps docket does not use (builder check, + visual companion, spike offers, its own spec location) — that is #566. This change counters + only the "no written design" sizing outcome, because it is the trivial suggestion's source. +- Changing what a spec must contain, how the plan-writer reads it, or the reconcile pass. + +## Anti-goals + +- A groom that settles decisions but leaves no written place for them. +- A new check, finding, warning, or gate about legacy `trivial:` lines. They are inert data. +- Rewriting history: archived records keep their `trivial: true` lines byte-for-byte. + +## Decisions + +### 1. Readiness and the domain model + +`trivial` leaves the domain model entirely. Build-ready = `proposed` + non-empty `spec:` + the +existing dependency, stack-base, and hold conditions. Needs-grooming = `proposed` with no spec. +Auto-groomable = needs-grooming + `auto_groomable: true`. + +Remove `Trivial` from the change entity, the readiness evaluation, the claim/action facts that +copy it, and the decoder's wire struct. The decoder already treats unknown frontmatter keys as +compatibility data ("Unknown keys are compatibility data and stay in the document; they are not +decoded here and never fail the decode"), so a legacy `trivial: true` line stays in the file, +untouched by every writer, and means nothing. A legacy record with `trivial: true` and no spec +reads as needs-grooming. + +### 2. New records + +`change.create` stops writing a `trivial:` line into the frontmatter template. + +### 3. The groom operation + +`change.groom` drops the `trivial` outcome. Remaining outcomes: `spec`, `revise`, `abstain`, +`re-enable`. A request naming `outcome: trivial` refuses through the existing invalid-outcome +finding and writes nothing — no special "retired" message. Remove what only the trivial outcome +used: the missing-rationale finding code and its `hasAuthoredRationale` helper, the +`groomed (trivial)` receipt text, the `trivial` field edit, and the trivial checks in the +revise/stub-edit gates (a stub edit now refuses only when the change has a spec). The schema's +`groom_outcomes` vocabulary and the `change groom` CLI help drop `trivial`. + +### 4. The board + +Every build-ready or held proposed change now has a spec, so it renders in the Groomed section. +Drop the `build-ready (trivial)` cell and the comments and branches that existed only for +trivial-without-spec rows in the Proposed section. + +### 5. `docket open` + +The `trivial-no-spec` reason goes. Asking for the spec of a change with no spec — a stub, or a +legacy trivial record — gets the existing `artifact-unset` answer ("change N has no spec yet"). + +### 6. Spec always — the brainstorm direction + +`docket-groom-next` and `docket-new-change` tell the brainstorm role, at the point they invoke it, +that its artifact is always a written spec, sized to the change: a small change gets a short spec, +and the brainstorm never concludes that a change needs no written design. Phrase it by shape (what +outcome to avoid), never by citing a vendored superpowers heading. Keep it to the minimum prose that +does the job; these skills are read on every groom. + +`docket-groom-next`: delete the trivial exit (Step 4 becomes five exits) and every "or trivial" / +"not trivial" / "trivial rationale" clause in selection, the revise route, retitle, reprioritize, +deliverable, hold, and stacking paragraphs. + +`docket-new-change`: delete the *Trivial path* section and its *When to use* bullet. Small work is +captured through brainstorm mode (with a short spec) or as a stub groomed later. + +### 7. Auto-groom + +Autonomous grooming has two exits: **spec** and **abstain**. The designer pass drops the +"genuinely mechanical → trivial verdict" sentence; a mechanical stub gets a short spec with its +`## Assumptions` block like any other. The critic attacks a spec, never a verdict. Update the +drain summary (`groomed N, abstained K`), the termination paragraph, the hold paragraph, the skill +and agent descriptions, and the critic agent's description. + +### 8. ADR + +Record a new ADR that supersedes ADR-0006 (through `docket-adr` during the build): every +build-ready change carries a spec; autonomous grooming has two exits (spec, abstain); ADR-0006's two +bounds (an adversarial critic gates every build-ready exit; kill and defer are never autonomous) +carry forward unchanged. ADR-0153 (hold) already narrows ADR-0006's "build-ready means the +autonomous builder will build it" for held changes; the new ADR keeps that hold exception and +relates to ADR-0153, so the supersession does not silently restore the old rule (my call). The new +ADR's *Alternatives considered* records why the trivial exit was retired rather than repaired +(requiring decisions in the trivial body still keeps the design off the PR and saves nothing over a +short spec). ADR-0129 mentions `trivial` only inside a historical rename table and stays as it is. + +### 9. Skill, agent, and doc prose + +Docs describe only current behavior: delete `trivial` mentions outright, with no "formerly" notes. +The set below comes from a repo-wide grep. Watch the spelling "non-trivial": most uses are +ordinary English, but two refer to the flag and change too (implement-next's "(non-trivial +changes)" beside the spec copy, and new-change's "The default path for any non-trivial new +change"). Frozen point-in-time snapshots stay untouched: `docs/release/v1.0.0-alpha.2/*` and +`internal/install/legacydata/*`. + +- `skills/docket-convention/SKILL.md` — manifest's `trivial:` line, build-readiness, + needs-grooming, auto-groomable, the hold sentence, and "trivial included" in the results lines. +- `skills/docket-groom-next/SKILL.md`, `skills/docket-new-change/SKILL.md`, + `skills/docket-auto-groom/SKILL.md` — as in decisions 6 and 7. +- `skills/docket-implement-next/SKILL.md` — reconcile's "A trivial change has no spec — patch the + body only", commit-spec's "(a trivial change reports `no-spec`)", the "trivial included" + results line, and the `reconciled` paragraph's readiness restatement. +- `skills/docket-implement-next/references/results-artifact.md`, + `skills/docket-implement-next/results-template.md`, `skills/docket-review/SKILL.md`, + `skills/docket-status/SKILL.md` — "or a trivial change's body", "trivial included", and the + board-cell list. +- `agents/docket-auto-groom.md`, `agents/docket-auto-groom-critic.md` — descriptions; then + regenerate the harness goldens that embed them (`internal/harness/*/testdata/golden/docket-auto-groom*`). +- `cursor-rules/dispatch/docket-auto-groom-critic.md` — hand-maintained; "draft spec / trivial + verdict" appears twice. +- `README.md`, `docs/guide/capturing-work.md`, `docs/guide/designing-before-building.md`, + `docs/guide/building-without-supervision.md`, `docs/concepts/change-lifecycle.md`, + `docs/reference/glossary.md` (including the `### Trivial` entry and the "Capture modes" entry), + `docs/install/models-and-effort.md` ("a trivial verdict"), and + `docs/comparison/ai-native-sdlc-playbook.md` (the "Trivial path" row, "or `trivial: true`", and + the capture-modes list). + +"Required for every change, trivial included" becomes "required for every implemented change." +Regenerate embedded assets after skill edits (`go generate ./internal/assets/`). + +### 10. Tests + +- About 40 test setups use `trivial: true` as a cheap way to make a change build-ready. Give them + a spec instead (a minimal spec file plus `spec:`), through a shared fixture helper where one + fits. +- Delete tests that exist only for the trivial outcome, the trivial board cell, or the + `trivial-no-spec` open reason. +- Update pinned prose and budgets that move: `internal/repoguard/prose_contracts_test.go` (the + "trivial included" phrases) and `internal/repoguard/budgets_test.go` (skill line/byte budgets). +- New coverage: `outcome: trivial` refuses as an invalid outcome and writes nothing; a record + carrying `trivial: true` and no spec reads as needs-grooming, and a groom of it keeps the + `trivial: true` line byte-identical; a newly created record has no `trivial:` key. +- The status-corpus testdata records keep their `trivial: true` lines; they now double as proof + that the key is inert. + +### 11. `workspace.commit-spec` keeps `no-spec` (my call) + +Once readiness requires a spec, a change claimed after the upgrade always has one. A change claimed +*before* it with `trivial: true` and no spec could still be in progress when the binary is +swapped, so `no-spec` stays as the quiet no-op it is today and that build finishes. Only its +"trivial" comment and implement-next's "(a trivial change reports `no-spec`)" clause change. + +## Left to the builder + +- The fixture helper's shape and where it lives. +- Exact wording of the brainstorm direction, within decision 6's constraints. diff --git a/internal/app/change_claim_test.go b/internal/app/change_claim_test.go index 28da92017..883bed896 100644 --- a/internal/app/change_claim_test.go +++ b/internal/app/change_claim_test.go @@ -14,10 +14,10 @@ import ( ) // claimableChange renders a proposed, build-ready change: the canonical proposed -// record with trivial: true (so it carries a design outcome) and no claim -// fields yet. Claiming it must INSERT branch/claimed_at/reconciled. +// record linking a spec (so it carries a design) and no claim fields yet. +// Claiming it must INSERT branch/claimed_at/reconciled. func claimableChange(id int, slug string) string { - return strings.Replace(lifecycleChange(id, slug, "proposed"), "trivial: false\n", "trivial: true\n", 1) + return withLinkedSpec(lifecycleChange(id, slug, "proposed"), fixtureSpecPath(slug)) } // stackedOn rewrites a record's empty stacked_on edge to point at parent. @@ -523,11 +523,33 @@ func assertUnrelatedShapeIntact(t *testing.T, repo *gitRepo, branch string, shap t.Errorf("%s: status no longer reports a finding on the unrelated records; findings %+v", shape.name, st.Findings) } +// TestChangeClaimRefusesLegacyTrivialRecord: a legacy record carrying +// trivial: true and no spec is a stub, not build-ready, so a claim refuses it +// as needs-grooming and writes nothing. +func TestChangeClaimRefusesLegacyTrivialRecord(t *testing.T) { + recPath := groomPath(3, "widget") + src := strings.Replace(lifecycleChange(3, "widget", "proposed"), "\ntrivial: false\n", "\ntrivial: true\n", 1) + if !strings.Contains(src, "\ntrivial: true\n") || !strings.Contains(src, "\nspec:\n") { + t.Fatalf("fixture is not a spec-less legacy trivial record:\n%s", src) + } + plan, opRes := claimPlanFor(t, map[string]string{recPath: src}, baseClaimOp([]string{"inline"}, 3, domain.NewBranchFacts(nil))) + if !opRes.Refused || len(plan.Files) != 0 { + t.Fatalf("claim of a legacy trivial record not refused: refused=%v files=%d", opRes.Refused, len(plan.Files)) + } + found := false + for _, f := range opRes.Findings { + found = found || f.Code == "not-ready-needs-grooming" + } + if !found { + t.Errorf("missing not-ready-needs-grooming; got %v", opRes.Findings) + } +} + // TestChangeClaimAcceptsHeldChangeAndKeepsField: a hold never refuses a claim, // and the claimed record keeps the hold for the human to lift. func TestChangeClaimAcceptsHeldChangeAndKeepsField(t *testing.T) { recPath := groomPath(3, "widget") - src := strings.Replace(claimableChange(3, "widget"), "trivial: true\n", "trivial: true\nhold: true\n", 1) + src := strings.Replace(claimableChange(3, "widget"), "trivial: false\n", "trivial: false\nhold: true\n", 1) plan, opRes := claimPlanFor(t, map[string]string{recPath: src}, baseClaimOp([]string{"inline"}, 3, domain.NewBranchFacts(nil))) if opRes.Refused { t.Fatalf("claim of a held change refused: %v", opRes.Findings) diff --git a/internal/app/change_groom.go b/internal/app/change_groom.go index dc1654c5f..733fe7705 100644 --- a/internal/app/change_groom.go +++ b/internal/app/change_groom.go @@ -20,17 +20,17 @@ import ( ) // This file is the `change groom` planning operation: it grooms a proposed, -// needs-design change to build-ready by one of two authored outcomes — a full -// spec, or a trivial verdict — or, by the third outcome (revise), edits any -// proposed change in place without changing its groom state: a whole-body -// replace of its existing linked spec and/or owned proposal-section edits, -// never touching spec:, trivial:, or auto_groomable:. The abstain outcome +// needs-design change to build-ready by landing an authored spec (the spec +// outcome) or, by the revise outcome, edits any proposed change in place +// without changing its groom state: a whole-body replace of its existing +// linked spec and/or owned proposal-section edits, never touching spec: or +// auto_groomable:. The abstain outcome // records an autonomous groom's abstain on a needs-design change — // auto_groomable: false plus one dated // "## Auto-groom blocked" entry — under the same groom gate; the re-enable outcome // clears it — auto_groomable: true, the section removed — under that gate too, -// optionally with owned-section edits in the same commit. The spec, trivial, -// revise, and re-enable outcomes also set or lift a hold (hold:, plus the +// optionally with owned-section edits in the same commit. The spec, revise, +// and re-enable outcomes also set or lift a hold (hold:, plus the // optional "## Why on hold" reason section only the hold keys write), which // never changes the groom state; abstain refuses a hold. Every outcome // lands the change's source mutation and every affected v1-owned derived view (the change record's owned proposal sections, @@ -41,7 +41,7 @@ import ( // revision with an exact-blob entity expectation rather than an idempotency key // (a spec-body revise also checks the linked spec file's blob id in Plan), and // it never touches claim metadata. It decides no lifecycle policy beyond the -// groom gate the spec fixes here (proposed, needs-design, not yet trivial) and +// groom gate the spec fixes here (proposed, needs-design) and // the revise gate (any proposed change). // OperationChangeGroom is the operation key `change groom` records in its result @@ -54,21 +54,18 @@ type GroomOutcome string const ( // GroomSpec lands an authored design spec and links it from the change. GroomSpec GroomOutcome = "spec" - // GroomTrivial marks the change trivial with an authored rationale, writing - // no spec file. - GroomTrivial GroomOutcome = "trivial" // GroomRevise edits any proposed change without changing its groom state: // a whole-body replace of its existing linked spec, owned proposal-section // edits, a retitle, relationship-field updates, or a combination. It never - // writes spec:, trivial:, or auto_groomable:, so a change can never flip - // between needs-grooming, spec'd, and trivial through this outcome, and it + // writes spec: or auto_groomable:, so a change can never flip between + // needs-grooming and spec'd through this outcome, and it // never edits the ## Auto-groom blocked section (abstain and re-enable own it). // It may set or lift a hold: a hold excludes the change from autonomous // build selection only, so it is no part of the groom state. GroomRevise GroomOutcome = "revise" // GroomAbstain records an autonomous groom's abstain on a needs-grooming // change: it sets auto_groomable: false and appends one dated entry to the - // ## Auto-groom blocked section. It never writes spec: or trivial:, and it + // ## Auto-groom blocked section. It never writes spec:, and it // accepts no section, spec, relationship, or hold edits — an autonomous // caller cannot rewrite the proposal through it. GroomAbstain GroomOutcome = "abstain" @@ -149,13 +146,13 @@ type ChangeGroomRequest struct { BlockedNote string `json:"blocked_note,omitempty"` // Title, when non-empty, retitles the change (change 0461). The spec, - // trivial, revise, and re-enable outcomes accept it; abstain refuses it, since an + // revise, and re-enable outcomes accept it; abstain refuses it, since an // abstain cannot rewrite the proposal. Empty leaves the title unchanged. A // retitle renames nothing: the slug, record path, spec path, and branch stay put. Title string `json:"title,omitempty"` // Priority, when non-empty, re-prioritizes the change (change 0550). The - // spec, trivial, revise, and re-enable outcomes accept it; abstain refuses + // spec, revise, and re-enable outcomes accept it; abstain refuses // it, since an autonomous abstain cannot re-rank the proposal. Empty leaves // the priority unchanged. It draws on the same closed vocabulary as // change.create's priority. @@ -163,7 +160,7 @@ type ChangeGroomRequest struct { // Deliverable, Type, and BranchPrefix edit how the change ends and how its // next claim names its branch (change 0559). Like Title and Priority, the - // spec, trivial, revise, and re-enable outcomes accept each and abstain + // spec, revise, and re-enable outcomes accept each and abstain // refuses each. An empty Deliverable or Type leaves the field unchanged; // Deliverable draws on change.create's closed vocabulary and Type must be one // of the configured change_types. BranchPrefix is three-state: nil leaves it @@ -180,7 +177,7 @@ type ChangeGroomRequest struct { // false clears the key and removes any "## Why on hold" section. HoldReason // is accepted only with Hold true in the same request; it replaces that // section, and an omitted reason leaves an existing one alone. The spec, - // trivial, revise, and re-enable outcomes accept both; abstain refuses Hold. + // revise, and re-enable outcomes accept both; abstain refuses Hold. Hold *bool `json:"hold,omitempty"` HoldReason string `json:"hold_reason,omitempty"` @@ -229,7 +226,7 @@ func (r ChangeGroomResult) HumanText() string { if r.SpecPath != "" { return fmt.Sprintf("change %04d groomed (spec %s) — %s", r.ID, r.SpecPath, r.Revision) } - return fmt.Sprintf("change %04d groomed (trivial) — %s", r.ID, r.Revision) + return fmt.Sprintf("change %04d groomed — %s", r.ID, r.Revision) default: var b strings.Builder fmt.Fprintf(&b, "change groom: %s", r.Result) @@ -254,8 +251,8 @@ func newChangeGroomResult(result Result, r ChangeGroomResult) ChangeGroomResult // changeGroomReceipt is the canonical receipt persisted with a groom commit. // Field order is alphabetical so json.Marshal emits the canonical, sorted-key -// compact form the engine's receipt validator requires; SpecPath is omitted for -// the trivial outcome. +// compact form the engine's receipt validator requires; SpecPath is omitted when +// no spec file was written or replaced (abstain, re-enable, a sections-only revise). type changeGroomReceipt struct { ID int `json:"id"` Op string `json:"op"` @@ -405,10 +402,6 @@ func validateChangeGroomShape(req ChangeGroomRequest) []StatusFinding { } else if msg := specMarkdownShapeProblem(req.SpecMarkdown); msg != "" { addShape(FCInvalidSpecMarkdown, msg) } - case GroomTrivial: - if !hasAuthoredRationale(req.Sections) { - addShape(FCMissingRationale, "the trivial outcome requires a non-empty authored rationale among the section edits") - } case GroomRevise: if strings.TrimSpace(req.SpecMarkdown) != "" { if msg := specMarkdownShapeProblem(req.SpecMarkdown); msg != "" { @@ -478,7 +471,7 @@ func validateChangeGroomShape(req ChangeGroomRequest) []StatusFinding { } } default: - addShape(FCInvalidOutcome, fmt.Sprintf("outcome %q must be one of spec, trivial, revise, abstain, re-enable", req.Outcome)) + addShape(FCInvalidOutcome, fmt.Sprintf("outcome %q must be one of spec, revise, abstain, re-enable", req.Outcome)) } // A title retitles the change on every other outcome (change 0461); an empty @@ -608,17 +601,6 @@ func autoGroomBlockedMarkdown(oldBody string, present bool, date, note string) s return entry } -// hasAuthoredRationale reports whether the section edits carry at least one -// replace with a non-empty body — the trivial outcome's required rationale. -func hasAuthoredRationale(sections []SectionEditRequest) bool { - for _, s := range sections { - if s.Intent == string(render.SectionReplace) && strings.TrimSpace(s.Markdown) != "" { - return true - } - } - return false -} - // hasRelationshipEdit reports whether the request sets any relationship field: // an explicit list (even empty) for depends_on, related, discovered_from, or // adrs, or any stacked_on (0 clears it). Each one alone is an effective revise. @@ -721,19 +703,20 @@ func (o changeGroomOp) Plan(ctx context.Context, st transaction.AttemptState) (t return refuseGroom("not-found", fmt.Sprintf("change %04d is not present in the current corpus", o.req.ChangeID)) } // Groom/revise gate. The groom gate admits only a proposed, needs-design - // change. The revise gate admits any proposed change, needs-design or - // already groomed: revise never writes spec:, trivial:, or auto_groomable:, - // so it cannot change a change's groom state, and a needs-design change - // satisfies both gates. Neither gate inspects or sets claim metadata. + // change (one with no spec). The revise gate admits any proposed change, + // needs-design or already groomed: revise never writes spec: or + // auto_groomable:, so it cannot change a change's groom state, and a + // needs-design change satisfies both gates. Neither gate inspects or sets + // claim metadata. if o.req.Outcome == GroomRevise { if c.Status() != domain.StatusProposed { return refuseGroom("not-revisable", fmt.Sprintf("change %04d is not a proposed change (status %q)", o.req.ChangeID, c.Status())) } - } else if c.Status() != domain.StatusProposed || c.Spec().Value != "" || c.Trivial() { + } else if c.Status() != domain.StatusProposed || c.Spec().Value != "" { return refuseGroom("not-groomable", - fmt.Sprintf("change %04d is not a proposed, needs-design change (status %q, spec %q, trivial %v)", - o.req.ChangeID, c.Status(), c.Spec().Value, c.Trivial())) + fmt.Sprintf("change %04d is not a proposed, needs-design change (status %q, spec %q)", + o.req.ChangeID, c.Status(), c.Spec().Value)) } // Retitle gate (change 0461). A proposed change carrying branch:, plan:, or @@ -975,7 +958,7 @@ func (o changeGroomOp) Plan(ctx context.Context, st transaction.AttemptState) (t } if reviseSpec { // A revise that replaced the spec body names the existing linked path; a - // sections-only revise leaves it empty, like the trivial outcome. + // sections-only revise leaves it empty. receiptSpecPath = c.Spec().Value } receipt, err := json.Marshal(changeGroomReceipt{ @@ -1010,8 +993,6 @@ func (o changeGroomOp) fieldEdits(specPath string) []groomFieldEdit { switch o.req.Outcome { case GroomSpec: out = append(out, groomFieldEdit{"spec", document.String(specPath)}) - case GroomTrivial: - out = append(out, groomFieldEdit{"trivial", document.Bool(true)}) case GroomAbstain: out = append(out, groomFieldEdit{"auto_groomable", document.Bool(false)}) case GroomReEnable: diff --git a/internal/app/change_groom_test.go b/internal/app/change_groom_test.go index e2f70e4bf..91e15d2a3 100644 --- a/internal/app/change_groom_test.go +++ b/internal/app/change_groom_test.go @@ -11,7 +11,7 @@ import ( ) // groomableChange renders a canonical proposed change record eligible for -// grooming: proposed status, empty spec, trivial false, every relationship +// grooming: proposed status, empty spec, an inert legacy trivial: false line, every relationship // field present and empty, the empty docket:artifacts block, and the four // authored proposal sections (including ## Open questions, so its removal is // observable). @@ -94,6 +94,7 @@ func TestChangeGroomRejectsBadShapeWithoutEngineCall(t *testing.T) { {"empty path", func(r *ChangeGroomRequest) { r.Path = "" }, "empty-path"}, {"empty revision", func(r *ChangeGroomRequest) { r.Revision = "" }, "empty-revision"}, {"unknown outcome", func(r *ChangeGroomRequest) { r.Outcome = "maybe" }, "invalid-outcome"}, + {"retired trivial outcome", func(r *ChangeGroomRequest) { r.Outcome = "trivial"; r.SpecMarkdown = "" }, "invalid-outcome"}, {"spec outcome empty markdown", func(r *ChangeGroomRequest) { r.SpecMarkdown = "" }, "empty-spec_markdown"}, {"spec outcome unparseable markdown", func(r *ChangeGroomRequest) { r.SpecMarkdown = "---\nid: 1\n" }, "invalid-spec_markdown"}, // The writer prepends the backlink block itself; an authored one would @@ -134,31 +135,6 @@ func TestChangeGroomRejectsBadShapeWithoutEngineCall(t *testing.T) { } } -func TestChangeGroomTrivialRequiresRationale(t *testing.T) { - req := ChangeGroomRequest{ - ChangeID: 2, - Path: groomPath(2, "add-a-widget"), - Revision: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", - Outcome: GroomTrivial, - // No section carrying an authored rationale. - } - engine := &recordingEngine{} - reader := &fakeChangeReader{pin: mainModePin([]string{"inline"})} - deps := PlanningDeps{Engine: engine, Reader: reader, Clock: testClock()} - - res := ChangeGroom(context.Background(), deps, "", req) - - if res.Result != ResultInvalidInput { - t.Fatalf("result = %q, want invalid-input", res.Result) - } - if len(engine.calls) != 0 { - t.Errorf("engine called despite a missing trivial rationale") - } - if !hasFindingCode(res.Findings, "missing-rationale") { - t.Errorf("missing finding missing-rationale; got %v", res.Findings) - } -} - func TestChangeGroomRefusesGithubBoardSurface(t *testing.T) { engine := &recordingEngine{} reader := &fakeChangeReader{pin: mainModePin([]string{"inline", "github"})} @@ -274,42 +250,12 @@ func TestChangeGroomPlanSpecOutcomeFileSet(t *testing.T) { } } -func TestChangeGroomPlanTrivialOutcomeFileSet(t *testing.T) { - req := ChangeGroomRequest{ - ChangeID: 2, - Path: groomPath(2, "add-a-widget"), - Revision: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", - Outcome: GroomTrivial, - Sections: []SectionEditRequest{ - {Heading: "## Why", Intent: "replace", Markdown: "Too small to design.\n"}, - }, - } - files := map[string]string{ - groomPath(2, "add-a-widget"): groomableChange(2, "add-a-widget"), - } - plan, opRes := groomPlanFor(t, files, baseGroomOp([]string{}, req)) - if opRes.Refused { - t.Fatalf("unexpected refusal: %v", opRes.Findings) - } - assertPlanPaths(t, plan, map[string]transaction.MutationKind{ - groomPath(2, "add-a-widget"): transaction.MutationReplace, - }) - rec := string(groomedRecordBytes(t, plan, groomPath(2, "add-a-widget"))) - if !strings.Contains(rec, "trivial: true") { - t.Errorf("trivial not set true:\n%s", rec) - } - if strings.Contains(rec, "spec: '") { - t.Errorf("trivial groom must not set a spec:\n%s", rec) - } -} - func TestChangeGroomPlanRefusesNonGroomable(t *testing.T) { cases := []struct { name string mutate func(string) string }{ {"already has spec", func(s string) string { return strings.Replace(s, "spec:\n", "spec: 'docs/x.md'\n", 1) }}, - {"already trivial", func(s string) string { return strings.Replace(s, "trivial: false", "trivial: true", 1) }}, {"not proposed", func(s string) string { return strings.Replace(s, "status: proposed\n", "status: blocked\nblocked_by: 'waiting on infra'\n", 1) }}, @@ -409,8 +355,9 @@ func revisableChange(id int, slug, specPath string) string { return strings.Replace(groomableChange(id, slug), "spec:\n", "spec: '"+specPath+"'\n", 1) } -// trivialChange renders a proposed change already groomed by trivial verdict. -func trivialChange(id int, slug string) string { +// legacyTrivialChange renders a record carrying a legacy trivial: true line and +// no spec — a stub. +func legacyTrivialChange(id int, slug string) string { return strings.Replace(groomableChange(id, slug), "trivial: false", "trivial: true", 1) } @@ -681,8 +628,8 @@ func TestChangeGroomPlanReviseSectionsOnly(t *testing.T) { if !strings.Contains(rec, "spec: '"+reviseSpecPath+"'") { t.Errorf("spec field changed under revise:\n%s", rec) } - if !strings.Contains(rec, "trivial: false") { - t.Errorf("trivial field changed under revise:\n%s", rec) + if !strings.Contains(rec, "\ntrivial: false\n") { + t.Errorf("inert legacy trivial: false line not left byte-identical under revise:\n%s", rec) } // A sections-only revise replaced no spec body, so its receipt names none. assertGroomReceiptSpecPath(t, plan, "") @@ -729,8 +676,11 @@ func TestChangeGroomPlanReviseSpecBodyOnly(t *testing.T) { if !strings.Contains(rec, "updated: '2026-08-16'") { t.Errorf("updated not stamped:\n%s", rec) } - if !strings.Contains(rec, "spec: '"+reviseSpecPath+"'") || !strings.Contains(rec, "trivial: false") { - t.Errorf("groomed-outcome fields changed under a spec-only revise:\n%s", rec) + if !strings.Contains(rec, "spec: '"+reviseSpecPath+"'") { + t.Errorf("spec field changed under a spec-only revise:\n%s", rec) + } + if !strings.Contains(rec, "\ntrivial: false\n") { + t.Errorf("inert legacy trivial: false line not left byte-identical under a spec-only revise:\n%s", rec) } // The receipt names the existing linked spec path the revise replaced. assertGroomReceiptSpecPath(t, plan, reviseSpecPath) @@ -748,28 +698,55 @@ func TestChangeGroomPlanReviseBoth(t *testing.T) { }) } -func TestChangeGroomPlanReviseTrivialRationale(t *testing.T) { - // Spec item 4: sections-only revise of a trivial-verdicted change. - files := map[string]string{ - groomPath(2, "add-a-widget"): trivialChange(2, "add-a-widget"), - } - req := validReviseRequest() - // A trivial change links no spec, so there is no spec file to pin. - req.SpecMarkdown, req.SpecRevision = "", "" - plan, opRes := groomPlanFor(t, files, baseGroomOp([]string{}, req)) - if opRes.Refused { - t.Fatalf("unexpected refusal: %v", opRes.Findings) +// TestChangeGroomPlanLegacyTrivialRecordGroomsAsStub pins that a legacy +// record carrying trivial: true and no spec is an ordinary stub: (a) the spec +// outcome grooms it, and (b) a sections-only revise edits it, and both leave the +// legacy trivial: true line byte-identical (it is inert data no writer touches). +func TestChangeGroomPlanLegacyTrivialRecordGroomsAsStub(t *testing.T) { + const legacyLine = "\ntrivial: true\n" + assertLegacyLine := func(t *testing.T, rec string) { + t.Helper() + if n := strings.Count(rec, legacyLine); n != 1 || strings.Contains(rec, "trivial: false") { + t.Errorf("legacy trivial: true line not byte-identical (count %d):\n%s", n, rec) + } } - assertPlanPaths(t, plan, map[string]transaction.MutationKind{ - groomPath(2, "add-a-widget"): transaction.MutationReplace, + + t.Run("spec outcome", func(t *testing.T) { + files := map[string]string{groomPath(2, "add-a-widget"): legacyTrivialChange(2, "add-a-widget")} + plan, opRes := groomPlanFor(t, files, baseGroomOp([]string{}, validGroomSpecRequest())) + if opRes.Refused { + t.Fatalf("spec outcome refused a legacy trivial record: %v", opRes.Findings) + } + specPath := "docs/superpowers/specs/2026-08-16-add-a-widget-design.md" + assertPlanPaths(t, plan, map[string]transaction.MutationKind{ + groomPath(2, "add-a-widget"): transaction.MutationReplace, + specPath: transaction.MutationCreate, + }) + rec := string(groomedRecordBytes(t, plan, groomPath(2, "add-a-widget"))) + if !strings.Contains(rec, "\nspec: '"+specPath+"'\n") { + t.Errorf("spec: not written:\n%s", rec) + } + assertLegacyLine(t, rec) + }) + + t.Run("sections-only revise", func(t *testing.T) { + files := map[string]string{groomPath(2, "add-a-widget"): legacyTrivialChange(2, "add-a-widget")} + plan, opRes := groomPlanFor(t, files, baseGroomOp([]string{}, stubSectionReviseRequest())) + if opRes.Refused { + t.Fatalf("sections-only revise refused a legacy trivial record: %v", opRes.Findings) + } + assertPlanPaths(t, plan, map[string]transaction.MutationKind{ + groomPath(2, "add-a-widget"): transaction.MutationReplace, + }) + rec := string(groomedRecordBytes(t, plan, groomPath(2, "add-a-widget"))) + if !strings.Contains(rec, "Sharpened why.") { + t.Errorf("## Why section not replaced:\n%s", rec) + } + if !strings.Contains(rec, "\nspec:\n") { + t.Errorf("revise of a legacy trivial record wrote a spec link:\n%s", rec) + } + assertLegacyLine(t, rec) }) - rec := string(groomedRecordBytes(t, plan, groomPath(2, "add-a-widget"))) - if !strings.Contains(rec, "trivial: true") { - t.Errorf("trivial verdict lost under revise:\n%s", rec) - } - if strings.Contains(rec, "spec: '") { - t.Errorf("revise of a trivial change wrote a spec link:\n%s", rec) - } } func TestChangeGroomPlanReviseRefusals(t *testing.T) { @@ -779,9 +756,9 @@ func TestChangeGroomPlanReviseRefusals(t *testing.T) { mut func(*ChangeGroomRequest) code string }{ - // Spec item 5: spec_markdown against a trivial-only (no-spec) change. + // Spec item 5: spec_markdown against a legacy trivial (no-spec) record. {"spec-not-linked", map[string]string{ - groomPath(2, "add-a-widget"): trivialChange(2, "add-a-widget"), + groomPath(2, "add-a-widget"): legacyTrivialChange(2, "add-a-widget"), }, func(r *ChangeGroomRequest) {}, "spec-not-linked"}, // A needs-grooming stub is revisable, but it links no spec, so a // spec-body revise of it refuses before any mutation is assembled. @@ -855,7 +832,7 @@ func stubSectionReviseRequest() ChangeGroomRequest { // TestChangeGroomPlanReviseNeedsGroomingStub pins that revise edits a // needs-grooming stub's owned sections and leaves its groom state alone: no -// spec: written, trivial: still false, auto_groomable: untouched, a fresh +// spec: written, the inert trivial: false line untouched, auto_groomable: untouched, a fresh // updated:, the artifacts block intact, and the board row still needs-grooming. func TestChangeGroomPlanReviseNeedsGroomingStub(t *testing.T) { files := map[string]string{ @@ -877,8 +854,8 @@ func TestChangeGroomPlanReviseNeedsGroomingStub(t *testing.T) { if strings.Contains(rec, "spec: '") { t.Errorf("revise of a stub wrote a spec link:\n%s", rec) } - if !strings.Contains(rec, "trivial: false") || strings.Contains(rec, "trivial: true") { - t.Errorf("revise of a stub changed trivial:\n%s", rec) + if !strings.Contains(rec, "\ntrivial: false\n") || strings.Contains(rec, "trivial: true") { + t.Errorf("revise of a stub did not leave the inert trivial: false line byte-identical:\n%s", rec) } if !strings.Contains(rec, "auto_groomable: false") || strings.Contains(rec, "auto_groomable: true") { t.Errorf("revise of a stub changed auto_groomable:\n%s", rec) @@ -984,7 +961,7 @@ func TestChangeGroomPlanReviseAbstainedStubKeepsMarker(t *testing.T) { } // TestChangeGroomPlanReviseSpecNotLinkedMessage pins the reworded refusal: it -// covers both a trivial change and a needs-grooming stub, so it names neither. +// covers any change that links no spec, so it names no groom state. func TestChangeGroomPlanReviseSpecNotLinkedMessage(t *testing.T) { files := map[string]string{groomPath(2, "add-a-widget"): groomableChange(2, "add-a-widget")} plan, opRes := groomPlanFor(t, files, baseGroomOp([]string{}, validReviseRequest())) @@ -1222,7 +1199,8 @@ func TestChangeGroomPlanAbstainSetsFlagSectionAndBoard(t *testing.T) { "updated: '2026-08-16'", "## Auto-groom blocked\n\nRecorded 2026-08-16 (UTC).\n\nThe storage decision needs a human.", "### What to supply", - "\nspec:\n", "trivial: false", // groom scalars untouched + "\nspec:\n", // groom state untouched + "\ntrivial: false\n", // inert legacy line byte-identical "Original why.", "An open question.", // proposal untouched } { if !strings.Contains(rec, want) { @@ -1267,7 +1245,6 @@ func TestChangeGroomPlanAbstainRefusesNonGroomable(t *testing.T) { rec string }{ {"spec'd", revisableChange(2, "add-a-widget", reviseSpecPath)}, - {"trivial", trivialChange(2, "add-a-widget")}, {"not proposed", strings.Replace(groomableChange(2, "add-a-widget"), "status: proposed\n", "status: blocked\nblocked_by: 'waiting on infra'\n", 1)}, } for _, c := range cases { @@ -1362,11 +1339,39 @@ func TestChangeGroomRetiredRearmOutcomeRefused(t *testing.T) { } // The message echoes the offending value via %q ("rearm"), so assert on the // listed outcome set only: it must end with the live spelling. - if !strings.HasSuffix(msg, "must be one of spec, trivial, revise, abstain, re-enable") { + if !strings.HasSuffix(msg, "must be one of spec, revise, abstain, re-enable") { t.Errorf("invalid-outcome message %q must list exactly the live outcomes ending in re-enable", msg) } } +// TestChangeGroomRetiredTrivialOutcomeRefused pins the retirement of the +// trivial outcome: every build-ready change has a spec, so "trivial" is no +// longer an outcome and the refusal lists only the live set. +func TestChangeGroomRetiredTrivialOutcomeRefused(t *testing.T) { + req := ChangeGroomRequest{ + ChangeID: 2, + Path: groomPath(2, "add-a-widget"), + Revision: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + Outcome: GroomOutcome("trivial"), + Sections: []SectionEditRequest{ + {Heading: "## Why", Intent: "replace", Markdown: "Too small to design.\n"}, + }, + } + findings := validateChangeGroomShape(req) + var msg string + for _, f := range findings { + if f.Code == "invalid-outcome" { + msg = f.Message + } + } + if msg == "" { + t.Fatalf("outcome trivial: want invalid-outcome, got %v", findings) + } + if !strings.HasSuffix(msg, "must be one of spec, revise, abstain, re-enable") { + t.Errorf("invalid-outcome message %q must list exactly the live outcomes", msg) + } +} + func TestChangeGroomPlanReEnableClearsSectionSetsFlagAndBoard(t *testing.T) { files := map[string]string{ groomPath(2, "add-a-widget"): abstainedChange(2, "add-a-widget"), @@ -1438,7 +1443,6 @@ func TestChangeGroomPlanReEnableRefusals(t *testing.T) { code string }{ {"nothing to re-enable", map[string]string{groomPath(2, "add-a-widget"): armed}, "nothing-to-re-enable"}, - {"trivial", map[string]string{groomPath(2, "add-a-widget"): trivialChange(2, "add-a-widget")}, "not-groomable"}, {"spec'd", reviseFixtureFiles(), "not-groomable"}, } for _, c := range cases { @@ -1540,21 +1544,6 @@ func titleOnlyReviseRequest(title string) ChangeGroomRequest { return r } -// titledTrivialRequest is a well-formed trivial groom of the groomable fixture -// at id 2 that also retitles it. -func titledTrivialRequest(title string) ChangeGroomRequest { - return ChangeGroomRequest{ - ChangeID: 2, - Path: groomPath(2, "add-a-widget"), - Revision: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", - Outcome: GroomTrivial, - Title: title, - Sections: []SectionEditRequest{ - {Heading: "## Why", Intent: "replace", Markdown: "Trivial: a rename only.\n"}, - }, - } -} - func TestChangeGroomTitleShapeValidation(t *testing.T) { withTitle := func(r ChangeGroomRequest, title string) ChangeGroomRequest { r.Title = title @@ -1566,7 +1555,6 @@ func TestChangeGroomTitleShapeValidation(t *testing.T) { code string // "" means the request must pass shape validation }{ {"spec accepts title", withTitle(validGroomSpecRequest(), "Renamed widget"), ""}, - {"trivial accepts title", titledTrivialRequest("Renamed widget"), ""}, {"re-enable accepts title", withTitle(reEnableRequest(), "Renamed widget"), ""}, {"revise accepts a title alone", titleOnlyReviseRequest("Renamed widget"), ""}, {"revise accepts title with sections", withTitle(validReviseRequest(), "Renamed widget"), ""}, @@ -1713,22 +1701,6 @@ func TestChangeGroomPlanTitleOnSpecOutcome(t *testing.T) { } } -func TestChangeGroomPlanTitleOnTrivialOutcome(t *testing.T) { - files := map[string]string{groomPath(2, "add-a-widget"): groomableChange(2, "add-a-widget")} - plan, opRes := groomPlanFor(t, files, baseGroomOp([]string{}, titledTrivialRequest("Renamed widget"))) - if opRes.Refused { - t.Fatalf("unexpected refusal: %v", opRes.Findings) - } - // No spec file is touched. - assertPlanPaths(t, plan, map[string]transaction.MutationKind{ - groomPath(2, "add-a-widget"): transaction.MutationReplace, - }) - rec := string(groomedRecordBytes(t, plan, groomPath(2, "add-a-widget"))) - if !strings.Contains(rec, "title: 'Renamed widget'") || !strings.Contains(rec, "trivial: true") { - t.Errorf("record not retitled/trivialled:\n%s", rec) - } -} - // TestChangeGroomPlanTitleWithSpecBodyRevise pins Review Focus 4: the // whole-body replace already renders the backlink from the groomed record, so // the spec path is declared exactly once, carrying both the new body and title. @@ -1754,19 +1726,6 @@ func TestChangeGroomPlanTitleWithSpecBodyRevise(t *testing.T) { } } -// TestChangeGroomPlanTitleOnlyReviseOfTrivialChange pins Review Focus 5: a -// trivial-verdicted change links no spec, so a retitle writes only the record. -func TestChangeGroomPlanTitleOnlyReviseOfTrivialChange(t *testing.T) { - files := map[string]string{groomPath(2, "add-a-widget"): trivialChange(2, "add-a-widget")} - plan, opRes := groomPlanFor(t, files, baseGroomOp([]string{}, titleOnlyReviseRequest("Renamed widget"))) - if opRes.Refused { - t.Fatalf("unexpected refusal: %v", opRes.Findings) - } - assertPlanPaths(t, plan, map[string]transaction.MutationKind{ - groomPath(2, "add-a-widget"): transaction.MutationReplace, - }) -} - // revivedReviseFiles is the revise fixture for a proposed change that still // carries feature-branch artifacts (a hand-edited or legacy record): it is an // already-groomed proposed change with branch: and plan: set, whose @@ -1913,7 +1872,6 @@ func TestChangeGroomPriorityShapeValidation(t *testing.T) { not string // a code that must NOT be emitted ("" = no check) }{ {"spec accepts priority", withPriority(validGroomSpecRequest(), "high"), "", ""}, - {"trivial accepts priority", withPriority(titledTrivialRequest("Renamed widget"), "low"), "", ""}, {"re-enable accepts priority", withPriority(reEnableRequest(), "critical"), "", ""}, {"revise accepts a priority alone", priorityOnlyReviseRequest("high"), "", ""}, {"revise accepts priority with sections", withPriority(validReviseRequest(), "medium"), "", ""}, @@ -2033,21 +1991,15 @@ func assertPriorityLanded(t *testing.T, plan transaction.MutationPlan, want stri } // TestChangeGroomPlanPriorityLandsOnEveryAcceptingOutcome pins spec test 1: -// spec, trivial, revise, and re-enable each write the new priority to the +// spec, revise, and re-enable each write the new priority to the // record and the board row in the same plan. func TestChangeGroomPlanPriorityLandsOnEveryAcceptingOutcome(t *testing.T) { - trivial := ChangeGroomRequest{ - ChangeID: 2, Path: groomPath(2, "add-a-widget"), - Revision: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", Outcome: GroomTrivial, - Sections: []SectionEditRequest{{Heading: "## Why", Intent: "replace", Markdown: "Too small to design.\n"}}, - } cases := []struct { name string rec string req ChangeGroomRequest }{ {"spec", groomableChange(2, "add-a-widget"), validGroomSpecRequest()}, - {"trivial", groomableChange(2, "add-a-widget"), trivial}, {"revise", groomableChange(2, "add-a-widget"), priorityOnlyReviseRequest("")}, {"re-enable", abstainedChange(2, "add-a-widget"), reEnableRequest()}, } @@ -2228,18 +2180,12 @@ func resultsArtifactChange(id int, slug string) string { } func TestChangeGroomEditsDeliverableTypeAndPrefixOnEveryAcceptingOutcome(t *testing.T) { - trivial := ChangeGroomRequest{ - ChangeID: 2, Path: groomPath(2, "add-a-widget"), - Revision: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", Outcome: GroomTrivial, - Sections: []SectionEditRequest{{Heading: "## Why", Intent: "replace", Markdown: "Too small to design.\n"}}, - } cases := []struct { name string rec string req ChangeGroomRequest }{ {"spec", groomableChange(2, "add-a-widget"), validGroomSpecRequest()}, - {"trivial", groomableChange(2, "add-a-widget"), trivial}, {"revise", groomableChange(2, "add-a-widget"), fieldOnlyReviseRequest(func(*ChangeGroomRequest) {})}, {"re-enable", abstainedChange(2, "add-a-widget"), reEnableRequest()}, } @@ -2804,14 +2750,8 @@ func TestChangeGroomEachRelationshipFieldAloneIsAValidRevise(t *testing.T) { func TestChangeGroomStackedOnShape(t *testing.T) { const wantMsg = "stacked_on must be a positive change id, or 0 to clear" - trivial := ChangeGroomRequest{ - ChangeID: 2, Path: groomPath(2, "add-a-widget"), - Revision: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", Outcome: GroomTrivial, - Sections: []SectionEditRequest{{Heading: "## Why", Intent: "replace", Markdown: "Too small to design.\n"}}, - } negatives := map[string]ChangeGroomRequest{ "spec": validGroomSpecRequest(), - "trivial": trivial, "revise": fieldOnlyReviseRequest(func(*ChangeGroomRequest) {}), "re-enable": reEnableRequest(), } @@ -2999,18 +2939,12 @@ func holdPlanRecord(t *testing.T, rec string, req ChangeGroomRequest) string { } func TestChangeGroomSetsHoldOnEveryAcceptingOutcome(t *testing.T) { - trivial := ChangeGroomRequest{ - ChangeID: 2, Path: groomPath(2, "add-a-widget"), - Revision: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", Outcome: GroomTrivial, - Sections: []SectionEditRequest{{Heading: "## Why", Intent: "replace", Markdown: "Too small to design.\n"}}, - } cases := []struct { name string rec string req ChangeGroomRequest }{ {"spec", groomableChange(2, "add-a-widget"), validGroomSpecRequest()}, - {"trivial", groomableChange(2, "add-a-widget"), trivial}, {"revise", groomableChange(2, "add-a-widget"), fieldOnlyReviseRequest(func(*ChangeGroomRequest) {})}, {"re-enable", abstainedChange(2, "add-a-widget"), reEnableRequest()}, } @@ -3119,11 +3053,6 @@ func TestChangeGroomHoldAloneIsAValidRevise(t *testing.T) { } func TestChangeGroomHoldRefusals(t *testing.T) { - trivial := ChangeGroomRequest{ - ChangeID: 2, Path: groomPath(2, "add-a-widget"), - Revision: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", Outcome: GroomTrivial, - Sections: []SectionEditRequest{{Heading: "## Why", Intent: "replace", Markdown: "Too small to design.\n"}}, - } revise := fieldOnlyReviseRequest(func(r *ChangeGroomRequest) { r.Priority = "high" }) withHold := func(base ChangeGroomRequest, hold *bool, reason string) ChangeGroomRequest { base.Hold, base.HoldReason = hold, reason @@ -3149,7 +3078,6 @@ func TestChangeGroomHoldRefusals(t *testing.T) { {"reason carrying a heading", withHold(revise, boolPtr(true), "text\n## Heading\n"), FCInvalidHoldReason}, {"reason leaving a fence open", withHold(revise, boolPtr(true), "text\n```\ncode\n"), FCInvalidHoldReason}, {"section edit on spec", withSection(validGroomSpecRequest()), FCInvalidSectionHeading}, - {"section edit on trivial", withSection(trivial), FCInvalidSectionHeading}, {"section edit on revise", withSection(revise), FCInvalidSectionHeading}, {"section edit on revise with a hold", withSection(withHold(revise, boolPtr(true), "")), FCInvalidSectionHeading}, {"section edit on re-enable", withSection(reEnableRequest()), FCInvalidSectionHeading}, diff --git a/internal/app/change_implemented.go b/internal/app/change_implemented.go index d1ba177c7..2601702ca 100644 --- a/internal/app/change_implemented.go +++ b/internal/app/change_implemented.go @@ -40,8 +40,8 @@ import ( // (4) exactly one open PR for the feature branch targets the resolved // effective-base branch, names that head, and matches the supplied PR number // (parsePRRef reads the --pr assertion as either the full URL or shorthand); -// (5) a results artifact is attached (required since change 0410, trivial -// changes included) and resolves to a file on the metadata branch that +// (5) a results artifact is attached (required since change 0410, for every +// implemented change) and resolves to a file on the metadata branch that // carries this change's backlink and satisfies the final results content // contract. // @@ -114,8 +114,8 @@ const ( // this change (condition 5); invalid-state. ReasonImplementedResultsIdentity = "results-identity-broken" // ReasonImplementedResultsMissing: the change carries no attached results path; - // a results artifact is REQUIRED at the implemented boundary — trivial changes - // included (change 0410, condition 5); maps to invalid-state. + // a results artifact is REQUIRED at the implemented boundary for every + // implemented change (change 0410, condition 5); maps to invalid-state. ReasonImplementedResultsMissing = "results-missing" // ReasonImplementedResultsInvalid: the attached results artifact fails the FINAL // results content contract on the metadata branch (change 0410, condition 5); @@ -312,7 +312,7 @@ func ChangeMarkImplemented(ctx context.Context, deps PlanningDeps, wdeps Workspa } // (Condition 5) a results artifact is REQUIRED at the implemented boundary - // (change 0410) — for trivial changes too. The attached path must resolve to a + // (change 0410) — for every implemented change. The attached path must resolve to a // file on the pinned metadata tip, carry THIS change's backlink, and satisfy // the FINAL results content contract. The feature head is never consulted. resultsPath := strings.TrimSpace(c.Results().Value) diff --git a/internal/app/change_implemented_integration_test.go b/internal/app/change_implemented_integration_test.go index 6408f6292..705e09599 100644 --- a/internal/app/change_implemented_integration_test.go +++ b/internal/app/change_implemented_integration_test.go @@ -39,7 +39,7 @@ func TestIntegrationRecordOpsMarkImplementedAcceptsSkippedEvidence(t *testing.T) // Through the production engine, the committed record carries the skipped // evidence it verified as its "## Build evidence" section. recPath := groomPath(3, miSlug) - real := newWorkingRepo(t, map[string]string{recPath: miRecord(3, miSlug, miPlanPath(), miResultsPath, true, false)}) + real := newWorkingRepo(t, map[string]string{recPath: miRecord(3, miSlug, miPlanPath(), miResultsPath, true)}) realHead := miAdvanceHead(t, real) advanceDocketOrigin(t, real, miMetadataResults()) if res := miRealRunWith(t, real, recPath, realHead, prSkippedEvidenceBytes(t, realHead)); res.Result != ResultApplied { @@ -62,7 +62,7 @@ func TestIntegrationRecordOpsMarkImplementedUnrelatedInvalidRecordProgress(t *te requireRealGit(t) recPath := groomPath(3, miSlug) repo := newWorkingRepo(t, map[string]string{ - recPath: miRecord(3, miSlug, miPlanPath(), miResultsPath, true, false), + recPath: miRecord(3, miSlug, miPlanPath(), miResultsPath, true), unrelatedBrokenPath: unrelatedBrokenBytes, }) head := miAdvanceHead(t, repo) @@ -79,7 +79,7 @@ func TestIntegrationRecordOpsMarkImplementedUnrelatedInvalidRecordProgress(t *te func TestIntegrationRecordOpsMarkImplementedUnrelatedInvalidRecordRefusals(t *testing.T) { requireRealGit(t) recPath := groomPath(3, miSlug) - src := miRecord(3, miSlug, miPlanPath(), miResultsPath, true, false) + src := miRecord(3, miSlug, miPlanPath(), miResultsPath, true) for _, c := range unrelatedRefusalCases(t, 3, recPath, src, lifecycleChange(3, "dupe", "in-progress")) { t.Run(c.name, func(t *testing.T) { repo := newWorkingRepo(t, c.files) diff --git a/internal/app/change_implemented_test.go b/internal/app/change_implemented_test.go index fb61acf1e..c8b1ede31 100644 --- a/internal/app/change_implemented_test.go +++ b/internal/app/change_implemented_test.go @@ -20,14 +20,11 @@ const miRevision = "1234123412341234123412341234123412341234" // miRecord renders an in-progress change record with the given plan/results // linkage and reconciled flag — the shape mark-implemented reprobes. -func miRecord(id int, slug, plan, results string, reconciled, trivial bool) string { +func miRecord(id int, slug, plan, results string, reconciled bool) string { src := lifecycleChange(id, slug, "in-progress") if !reconciled { src = strings.Replace(src, "reconciled: true", "reconciled: false", 1) } - if trivial { - src = strings.Replace(src, "trivial: false", "trivial: true", 1) - } if plan != "" { src = strings.Replace(src, "plan:\n", "plan: '"+plan+"'\n", 1) } @@ -100,7 +97,7 @@ func TestMarkImplementedApplies(t *testing.T) { recPath := groomPath(3, "widget") planPath := "docs/superpowers/plans/2026-08-17-widget-plan.md" files := map[string]string{ - recPath: miRecord(3, "widget", planPath, "", true, false), + recPath: miRecord(3, "widget", planPath, "", true), "docs/changes/BOARD.md": "# Backlog\n\nold\n", } plan, opRes := implementedPlanFor(t, files, baseImplementedOp([]string{"inline"}, 3, "github.com/acme/widget#42")) @@ -216,7 +213,6 @@ func miAdvanceHead(t *testing.T, repo *gitRepo) string { // condition's stable reason, having never called the engine. type miKit struct { reconciled bool - trivial bool plan string results string revision string // corpus blob revision @@ -243,7 +239,7 @@ func buildMI(t *testing.T, client *gitcli.Client, invocation string, k miKit) ( Location: repository.LocationActive, Path: groomPath(3, miSlug), Revision: k.revision, - Data: []byte(miDeliverable(miRecord(3, miSlug, k.plan, k.results, k.reconciled, k.trivial), k.deliverable)), + Data: []byte(miDeliverable(miRecord(3, miSlug, k.plan, k.results, k.reconciled), k.deliverable)), } artifacts := map[string]StatusArtifact{} for p, content := range miMetadataResults() { diff --git a/internal/app/change_integration_test.go b/internal/app/change_integration_test.go index a203e39e7..1317974c0 100644 --- a/internal/app/change_integration_test.go +++ b/internal/app/change_integration_test.go @@ -468,7 +468,7 @@ func TestIntegrationChangeAuthoringClaimRefusals(t *testing.T) { }, { name: "not build-ready", - files: map[string]string{recPath: lifecycleChange(3, "widget", "proposed")}, // trivial:false, no spec + files: map[string]string{recPath: lifecycleChange(3, "widget", "proposed")}, // no spec reason: "not-ready-" + string(domain.ReadyNeedsGrooming), }, { @@ -1944,20 +1944,11 @@ func TestIntegrationChangeRuntimeMarkImplementedConditions(t *testing.T) { }, reason: ReasonImplementedPRReferenceMismatch, }, - { // condition 5 — required (change 0410): an empty results field refuses, - // trivial changes included (there is no trivial exemption to remove). + { // condition 5 — required (change 0410): an empty results field refuses. name: "no results artifact is attached", mutate: func(k *miKit) { k.results = "" }, reason: ReasonImplementedResultsMissing, }, - { // condition 5 — required for a trivial change too (pin, not a branch change). - name: "trivial change with no results artifact still refuses", - mutate: func(k *miKit) { - k.results = "" - k.trivial = true - }, - reason: ReasonImplementedResultsMissing, - }, { // condition 5 — the attached path is a metadata file with the correct // backlink, but its FINAL content is filler (## Findings and limitations → None.). name: "attached results fail the final content contract", diff --git a/internal/app/claim_workflow_git_test.go b/internal/app/claim_workflow_git_test.go index 29429d40c..aaae49d7c 100644 --- a/internal/app/claim_workflow_git_test.go +++ b/internal/app/claim_workflow_git_test.go @@ -2,7 +2,6 @@ package app import ( "github.com/danielhanold/docket/internal/repository/transaction" - "strings" "testing" ) @@ -25,12 +24,12 @@ import ( // origin, never the invocation clone's stale local tree. // buildReadyChange renders a proposed, unstacked, build-ready change record: the -// canonical groomable record with trivial flipped true, so EvaluateReadiness -// reports build-ready (design present) and ClaimEligibility passes without a -// separate spec artifact. It is the fixture the claim race/retry tests start -// from — a change a fresh context read reports claim-eligible. +// canonical groomable record linking a spec, so EvaluateReadiness reports +// build-ready (design present) and ClaimEligibility passes. It is the fixture +// the claim race/retry tests start from — a change a fresh context read reports +// claim-eligible. func buildReadyChange(id int, slug string) string { - return strings.Replace(groomableChange(id, slug), "trivial: false\n", "trivial: true\n", 1) + return withLinkedSpec(groomableChange(id, slug), fixtureSpecPath(slug)) } // --- claim race: two claimants, same context revision, one loses cleanly ----- diff --git a/internal/app/finalize_cleanup_integration_test.go b/internal/app/finalize_cleanup_integration_test.go index b88c2e70e..089cda88d 100644 --- a/internal/app/finalize_cleanup_integration_test.go +++ b/internal/app/finalize_cleanup_integration_test.go @@ -973,10 +973,10 @@ func TestIntegrationFinalizeCleanupResultsArtifactRealGit(t *testing.T) { slug = "research" ) recPath := groomPath(id, slug) - rec := strings.Replace(groomableChange(id, slug), "trivial: false\n", "trivial: true\n", 1) + rec := withLinkedSpec(groomableChange(id, slug), fixtureSpecPath(slug)) rec = strings.Replace(rec, "type: feat\n", "type: feat\ndeliverable: results-artifact\n", 1) m := planRepoModes()[0] - repo := buildConfiguredRepoWith(t, m, map[string]string{recPath: rec}) + repo := buildConfiguredRepoWith(t, m, map[string]string{recPath: rec, fixtureSpecPath(slug): fixtureSpecFile(id, slug)}) lw := prepareLeakWorkspace(t, repo, m.branch, id, recPath, false) runGit(t, lw.wp, "push", "-q", "origin", "HEAD:"+lw.featureRef) @@ -995,7 +995,7 @@ func TestIntegrationFinalizeCleanupResultsArtifactPrivate(t *testing.T) { requireRealGit(t) create := validChangeCreateRequest() create.Deliverable = string(domain.DeliverableResultsArtifact) - lw, lay := newPrivateLeakWorkspaceFor(t, create, false) + lw, lay := newPrivateLeakWorkspaceFor(t, create) meta := lay.DefaultBareRemote recPath := runGit(t, meta, "ls-tree", "-r", "--name-only", privateFixtureBranch, "docs/changes/active/") if strings.Contains(recPath, "\n") || recPath == "" { @@ -1085,10 +1085,10 @@ func TestIntegrationFinalizeCleanupResultsArtifactNeverPrepared(t *testing.T) { ) setup := func(t *testing.T) (*gitRepo, realNode, FinalizeDeps, *workspace.Service) { recPath := groomPath(id, slug) - rec := strings.Replace(groomableChange(id, slug), "trivial: false\n", "trivial: true\n", 1) + rec := withLinkedSpec(groomableChange(id, slug), fixtureSpecPath(slug)) rec = strings.Replace(rec, "type: feat\n", "type: feat\ndeliverable: results-artifact\n", 1) m := planRepoModes()[0] - repo := buildConfiguredRepoWith(t, m, map[string]string{recPath: rec}) + repo := buildConfiguredRepoWith(t, m, map[string]string{recPath: rec, fixtureSpecPath(slug): fixtureSpecFile(id, slug)}) node, deps, svc := completeNeverPrepared(t, repo, m.branch, id, recPath) return repo, node, deps, svc } @@ -1219,10 +1219,10 @@ func TestIntegrationFinalizeCleanupLeftoverBranchFullSweep(t *testing.T) { setup := func(t *testing.T) (*leakWorkspace, FinalizeDeps) { t.Helper() recPath := groomPath(id, slug) - rec := strings.Replace(groomableChange(id, slug), "trivial: false\n", "trivial: true\n", 1) + rec := withLinkedSpec(groomableChange(id, slug), fixtureSpecPath(slug)) rec = strings.Replace(rec, "type: feat\n", "type: feat\ndeliverable: results-artifact\n", 1) m := planRepoModes()[0] - repo := buildConfiguredRepoWith(t, m, map[string]string{recPath: rec}) + repo := buildConfiguredRepoWith(t, m, map[string]string{recPath: rec, fixtureSpecPath(slug): fixtureSpecFile(id, slug)}) lw := prepareLeakWorkspace(t, repo, m.branch, id, recPath, false) deps := completeLeakWorkspace(t, lw, repo.meta, m.branch, recPath) diff --git a/internal/app/finalize_e2e_test.go b/internal/app/finalize_e2e_test.go index 32bd336fc..511731af5 100644 --- a/internal/app/finalize_e2e_test.go +++ b/internal/app/finalize_e2e_test.go @@ -289,7 +289,10 @@ func reachImplemented(t *testing.T, m planRepoMode, docketBin, ghBin string) *e2 ) recPath := groomPath(id, slug) planPath := "docs/superpowers/plans/2026-08-17-widget-plan.md" - env := newImplEnv(t, m, docketBin, ghBin, map[string]string{recPath: buildReadyChange(id, slug)}) + env := newImplEnv(t, m, docketBin, ghBin, map[string]string{ + recPath: buildReadyChange(id, slug), + fixtureSpecPath(slug): fixtureSpecFile(id, slug), + }) c := env.implement(t, id, slug, planPath, "Add the widget") return &e2eState{ repo: env.repo, mode: m, node: env.node, wdeps: env.wdeps, @@ -848,6 +851,8 @@ func TestE2EStack(t *testing.T) { env := newImplEnv(t, m, docketBin, ghBin, map[string]string{ groomPath(rootID, rootSlug): buildReadyChange(rootID, rootSlug), groomPath(childID, childSlug): stackedBuildReadyChange(childID, childSlug, rootID), + fixtureSpecPath(rootSlug): fixtureSpecFile(rootID, rootSlug), + fixtureSpecPath(childSlug): fixtureSpecFile(childID, childSlug), }) root := env.implement(t, rootID, rootSlug, "docs/superpowers/plans/2026-08-17-widget-plan.md", "Add the widget") child := env.implement(t, childID, childSlug, "docs/superpowers/plans/2026-08-17-gadget-plan.md", "Add the gadget") @@ -1088,6 +1093,9 @@ func TestE2EStackThreeLevelCleanedBySweep(t *testing.T) { groomPath(rootID, rootSlug): buildReadyChange(rootID, rootSlug), groomPath(childID, childSlug): stackedBuildReadyChange(childID, childSlug, rootID), groomPath(grandID, grandSlug): stackedBuildReadyChange(grandID, grandSlug, childID), + fixtureSpecPath(rootSlug): fixtureSpecFile(rootID, rootSlug), + fixtureSpecPath(childSlug): fixtureSpecFile(childID, childSlug), + fixtureSpecPath(grandSlug): fixtureSpecFile(grandID, grandSlug), }) root := env.implement(t, rootID, rootSlug, "docs/superpowers/plans/2026-08-17-widget-plan.md", "Add the widget") child := env.implement(t, childID, childSlug, "docs/superpowers/plans/2026-08-17-gadget-plan.md", "Add the gadget") @@ -1165,6 +1173,8 @@ func TestE2EStackLeftoverCleanedBySweep(t *testing.T) { env := newImplEnv(t, m, docketBin, ghBin, map[string]string{ groomPath(rootID, rootSlug): buildReadyChange(rootID, rootSlug), groomPath(childID, childSlug): stackedBuildReadyChange(childID, childSlug, rootID), + fixtureSpecPath(rootSlug): fixtureSpecFile(rootID, rootSlug), + fixtureSpecPath(childSlug): fixtureSpecFile(childID, childSlug), }) root := env.implement(t, rootID, rootSlug, "docs/superpowers/plans/2026-08-17-widget-plan.md", "Add the widget") child := env.implement(t, childID, childSlug, "docs/superpowers/plans/2026-08-17-gadget-plan.md", "Add the gadget") @@ -1222,6 +1232,8 @@ func TestE2EStackParentLandedFirst(t *testing.T) { env := newImplEnv(t, m, docketBin, ghBin, map[string]string{ groomPath(parentID, parentSlug): buildReadyChange(parentID, parentSlug), groomPath(childID, childSlug): stackedBuildReadyChange(childID, childSlug, parentID), + fixtureSpecPath(parentSlug): fixtureSpecFile(parentID, parentSlug), + fixtureSpecPath(childSlug): fixtureSpecFile(childID, childSlug), }) parent := env.implement(t, parentID, parentSlug, "docs/superpowers/plans/2026-08-17-widget-plan.md", "Add the widget") child := env.implement(t, childID, childSlug, "docs/superpowers/plans/2026-08-17-gadget-plan.md", "Add the gadget") @@ -1676,8 +1688,10 @@ func reachInProgress(t *testing.T, docketBin, ghBin string) *e2eState { requireRealGit(t) m := planRepoModes()[0] records := map[string]string{ - groomPath(3, "widget"): buildReadyChange(3, "widget"), - groomPath(4, "gadget"): buildReadyChange(4, "gadget"), + groomPath(3, "widget"): buildReadyChange(3, "widget"), + groomPath(4, "gadget"): buildReadyChange(4, "gadget"), + fixtureSpecPath("widget"): fixtureSpecFile(3, "widget"), + fixtureSpecPath("gadget"): fixtureSpecFile(4, "gadget"), } repo := newWorkingRepo(t, mergeMaps(map[string]string{ ".docket.yml": "reclaim:\n lease_ttl: 1\n auto: false\nbuild:\n test_command: 'exit 0'\nfinalize:\n test_command: 'exit 0'\n", diff --git a/internal/app/finding_codes.go b/internal/app/finding_codes.go index 9bc38db6e..22387962a 100644 --- a/internal/app/finding_codes.go +++ b/internal/app/finding_codes.go @@ -158,7 +158,6 @@ const ( FCInvalidSpecMarkdown FindingCode = "invalid-spec_markdown" FCEmptySpecRevision FindingCode = "empty-spec_revision" FCInvalidSpecRevision FindingCode = "invalid-spec_revision" - FCMissingRationale FindingCode = "missing-rationale" FCEmptyRevise FindingCode = "empty-revise" FCEmptyBlockedNote FindingCode = "empty-blocked_note" FCInvalidBlockedNote FindingCode = "invalid-blocked_note" @@ -220,7 +219,7 @@ const ( // through their addShape/adrFinding/learningFinding closures are now registered // FindingCode constants (change 0399, review): invalid-request_id, // invalid-stacked_on, invalid-{target-id,topics,change-id,outcome,pr_number, -// attempt,spec_markdown,spec_revision,spec-section-heading}, missing-rationale, and the +// attempt,spec_markdown,spec_revision,spec-section-heading}, and the // enumerated empty- expansions (empty-{title,why,what_changes, // out_of_scope,context,decision,consequences,alternatives,change-path, // change-revision,target-path,target-revision,hook,apply,war_story,spec_markdown, @@ -347,7 +346,6 @@ var AllFindingCodes = []FindingCode{ FCMetadataWorktreeDirty, FCMigrationIncomplete, FindingCode("missing-claim-stamp"), - FCMissingRationale, FCNotDeferrable, FCNotFound, FindingCode(ReasonImplementedNotPRDeliverable), diff --git a/internal/app/finding_codes_test.go b/internal/app/finding_codes_test.go index 8f2f99d68..4d1a942e6 100644 --- a/internal/app/finding_codes_test.go +++ b/internal/app/finding_codes_test.go @@ -230,13 +230,12 @@ func TestShapeValidatorCodesAreRegistered(t *testing.T) { emitted = append(emitted, validateADRReplaceShape(ADRReplaceRequest{Target: ADRTarget{ID: 0}, Successor: adrContent})...) emitted = append(emitted, validateLearningRecordShape(LearningRecordRequest{Topics: []string{""}})...) emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomSpec})...) - emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomTrivial})...) emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomRevise})...) emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomRevise, SpecMarkdown: "# x\n"})...) - emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomTrivial, SpecRevision: "a"})...) + emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomSpec, SpecRevision: "a"})...) emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomOutcome("bogus")})...) emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomAbstain, Sections: []SectionEditRequest{{Heading: "## Why", Intent: "remove"}}})...) - emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomTrivial, BlockedNote: "x"})...) + emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomSpec, BlockedNote: "x"})...) emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomAbstain, Title: "x"})...) emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomRevise, Title: "a\nb"})...) emitted = append(emitted, validateChangeGroomShape(ChangeGroomRequest{Outcome: GroomAbstain, Priority: "high"})...) @@ -269,7 +268,7 @@ func TestShapeValidatorCodesAreRegistered(t *testing.T) { FCInvalidChangeDotID, FCEmptyChangePath, FCEmptyChangeRevision, FCInvalidTargetID, FCEmptyTargetPath, FCEmptyTargetRevision, FCEmptyHook, FCEmptyApply, FCEmptyWarStory, FCInvalidTopics, - FCEmptySpecMarkdown, FCEmptySpecRevision, FCInvalidSpecRevision, FCMissingRationale, FCInvalidOutcome, + FCEmptySpecMarkdown, FCEmptySpecRevision, FCInvalidSpecRevision, FCInvalidOutcome, FCInvalidSpecSectionHeading, FCEmptyReconcileLogEntry, FCEmptyBlockedNote, FCInvalidBlockedNote, FCInvalidSections, FCInvalidPRNumber, FCInvalidAttempt, FCEmptyHead, FCInvalidPriority, FCUnknownPriority, diff --git a/internal/app/implementation_context.go b/internal/app/implementation_context.go index bc451a7a8..c16badd3b 100644 --- a/internal/app/implementation_context.go +++ b/internal/app/implementation_context.go @@ -69,7 +69,7 @@ type ContextEntitySummary struct { // path, exact loss-preserving source bytes (base64 in JSON, as a Go []byte), // opaque record revision (blob object id), and — for a record — its parsed // summary. A zero ContextEntity (empty Path) means the bundle carries no such -// document (e.g. a trivial change with no spec). +// document (e.g. a change with no spec). type ContextEntity struct { Path string `json:"path,omitempty"` Source []byte `json:"source,omitempty"` diff --git a/internal/app/implementation_context_test.go b/internal/app/implementation_context_test.go index 3484cf2a7..80458178f 100644 --- a/internal/app/implementation_context_test.go +++ b/internal/app/implementation_context_test.go @@ -296,7 +296,7 @@ func TestContextImplementationTypedAbsence(t *testing.T) { }, { name: "not ready", - corpus: []StatusBlob{changeBlob(15, "no-design", "feat", "high", "")}, // no spec, not trivial + corpus: []StatusBlob{changeBlob(15, "no-design", "feat", "high", "")}, // no spec req: ImplementationContextRequest{ID: 15}, wantResult: ResultInvalidState, wantReason: "not-ready-" + string(domain.ReadyNeedsGrooming), @@ -573,7 +573,7 @@ func TestContextImplementationBranchFactsFailure(t *testing.T) { // change is selected. func TestImplementationContextAutoSelectionSurvivesMalformedStackBranch(t *testing.T) { pin := docketPin(t) - inner := &fakeReader{pin: pin, corpus: malformedStackCorpus(t), facts: domain.NewBranchFacts(map[string]bool{"feat/ok": true})} + inner := &fakeReader{pin: pin, corpus: malformedStackCorpus(t), facts: domain.NewBranchFacts(map[string]bool{"feat/ok": true}), artifactData: stackFixtureSpecArtifacts()} reader := poisoned(inner, "feat/a..parent", "feat/a:b", "feat/a:c") got := ContextImplementation(context.Background(), PlanningDeps{Reader: reader, Clock: testClock()}, "", ImplementationContextRequest{}) if got.Result == ResultExternalFailed { diff --git a/internal/app/leak_check_private_integration_test.go b/internal/app/leak_check_private_integration_test.go index c59a31fbe..9115a65f0 100644 --- a/internal/app/leak_check_private_integration_test.go +++ b/internal/app/leak_check_private_integration_test.go @@ -10,6 +10,7 @@ import ( "strings" "testing" + "github.com/danielhanold/docket/internal/domain" "github.com/danielhanold/docket/internal/githubcli" "github.com/danielhanold/docket/internal/layout" "github.com/danielhanold/docket/internal/workspace" @@ -39,9 +40,10 @@ type leakWorkspace struct { // prepareLeakWorkspace runs the opening steps of driveClaimToImplemented in // order — context, claim, reconcile, workspace prepare, and the spec-copy commit -// — and fails unless each applies. A change without a spec (spec false) must -// report no-spec instead, and its prepared head stands in for the spec commit. -func prepareLeakWorkspace(t *testing.T, repo *gitRepo, branch string, id int, recPath string, spec bool) *leakWorkspace { +// — and fails unless each applies. With commitSpec false the spec-copy step is +// skipped (as a results-artifact ending skips it), and the prepared head stands +// in for the spec commit. +func prepareLeakWorkspace(t *testing.T, repo *gitRepo, branch string, id int, recPath string, commitSpec bool) *leakWorkspace { t.Helper() ctx := context.Background() node := planningDepsFor(t, repo.invocation) @@ -70,11 +72,7 @@ func prepareLeakWorkspace(t *testing.T, repo *gitRepo, branch string, id int, re if prep.Result != ResultApplied { t.Fatalf("workspace prepare = %q (reason %q msg %q)", prep.Result, prep.Reason, prep.Message) } - cs := WorkspaceCommitSpec(ctx, node.deps, wdeps, node.dir, WorkspaceIDRequest{ID: id}) - if !spec { - if cs.Result != ResultNoOp || cs.Disposition != SpecCopyNoSpec { - t.Fatalf("workspace commit-spec = (%q, %q) (reason %q msg %q), want no-op/no-spec", cs.Result, cs.Disposition, cs.Reason, cs.Message) - } + if !commitSpec { return &leakWorkspace{ node: node, wdeps: wdeps, id: id, wp: prep.Path, specCommit: runGit(t, prep.Path, "rev-parse", "HEAD"), @@ -82,6 +80,7 @@ func prepareLeakWorkspace(t *testing.T, repo *gitRepo, branch string, id int, re origin: repo.origin, writer: repo.writer, invocation: repo.invocation, } } + cs := WorkspaceCommitSpec(ctx, node.deps, wdeps, node.dir, WorkspaceIDRequest{ID: id}) if cs.Result != ResultApplied || cs.Disposition != SpecCopyCommitted { t.Fatalf("workspace commit-spec = (%q, %q) (reason %q msg %q), want applied/committed", cs.Result, cs.Disposition, cs.Reason, cs.Message) } @@ -107,12 +106,13 @@ func prepareLeakWorkspace(t *testing.T, repo *gitRepo, branch string, id int, re // a spec — and prepares its workspace against the dckt store. func newPrivateLeakWorkspace(t *testing.T) (*leakWorkspace, layout.Layout) { t.Helper() - return newPrivateLeakWorkspaceFor(t, validChangeCreateRequest(), true) + return newPrivateLeakWorkspaceFor(t, validChangeCreateRequest()) } // newPrivateLeakWorkspaceFor is newPrivateLeakWorkspace for the given create -// request, groomed with a spec (spec true) or as trivial (no spec copy). -func newPrivateLeakWorkspaceFor(t *testing.T, create ChangeCreateRequest, spec bool) (*leakWorkspace, layout.Layout) { +// request. The change is always groomed with a spec; the spec copy is committed +// unless the change ends in a results artifact, whose ending skips that step. +func newPrivateLeakWorkspaceFor(t *testing.T, create ChangeCreateRequest) (*leakWorkspace, layout.Layout) { t.Helper() ctx := context.Background() r, _ := newPrivateInitRepo(t, nil) @@ -141,15 +141,12 @@ func newPrivateLeakWorkspaceFor(t *testing.T, create ChangeCreateRequest, spec b Outcome: GroomSpec, SpecMarkdown: "# Widget: design\n\nBuild the widget.\n", } - if !spec { - req.Outcome, req.SpecMarkdown = GroomTrivial, "" - req.Sections = []SectionEditRequest{{Heading: "## Why", Intent: "replace", Markdown: "Too small to design.\n"}} - } groom := ChangeGroom(ctx, node.deps, node.dir, req) - if groom.Result != ResultApplied || (spec && groom.SpecPath == "") { - t.Fatalf("change groom = %q (%s, findings %v), want applied (with a spec: %v)", groom.Result, groom.HumanText(), groom.Findings, spec) + if groom.Result != ResultApplied || groom.SpecPath == "" { + t.Fatalf("change groom = %q (%s, findings %v), want applied with a spec", groom.Result, groom.HumanText(), groom.Findings) } - return prepareLeakWorkspace(t, repo, privateFixtureBranch, created.ID, created.Path, spec), lay + commitSpec := create.Deliverable != string(domain.DeliverableResultsArtifact) + return prepareLeakWorkspace(t, repo, privateFixtureBranch, created.ID, created.Path, commitSpec), lay } // newSharedLeakWorkspace builds the shared (docket-branch) fixture @@ -439,14 +436,16 @@ func TestIntegrationPrivateModeLeakCheckUnverifiedPushesNothing(t *testing.T) { // TestIntegrationPrivateModeLeakCheckScansBranchName proves the // pushed feature branch name is scanned like any other published text: a -// trivial change titled "Fix the dckt alias" — no spec copy, clean commits — -// still refuses, because its slug puts dckt in the branch origin would show. +// change titled "Fix the alias table" with branch prefix dckt-fix — clean +// title, slug, spec copy, and commits — still refuses, because its prefix puts +// dckt in the branch origin would show. (A bare dckt prefix cannot be used: the +// private store's local dckt branch blocks a dckt/ ref.) func TestIntegrationPrivateModeLeakCheckScansBranchName(t *testing.T) { create := validChangeCreateRequest() - create.Title, create.Type = "Fix the dckt alias", "fix" - lw, _ := newPrivateLeakWorkspaceFor(t, create, false) - if lw.featureRef != "refs/heads/fix/fix-the-dckt-alias" { - t.Fatalf("feature ref = %q, want refs/heads/fix/fix-the-dckt-alias", lw.featureRef) + create.Title, create.Type, create.BranchPrefix = "Fix the alias table", "fix", "dckt-fix" + lw, _ := newPrivateLeakWorkspaceFor(t, create) + if lw.featureRef != "refs/heads/dckt-fix/fix-the-alias-table" { + t.Fatalf("feature ref = %q, want refs/heads/dckt-fix/fix-the-alias-table", lw.featureRef) } head := commitInWorkspace(t, lw.wp, "Tidy the alias table", map[string]string{"aliases.txt": "tidy\n"}) diff --git a/internal/app/named_branch_facts_test.go b/internal/app/named_branch_facts_test.go index 95d0e90be..429473323 100644 --- a/internal/app/named_branch_facts_test.go +++ b/internal/app/named_branch_facts_test.go @@ -49,14 +49,26 @@ func poisoned(inner StatusReader, branches ...string) *poisonBranchReader { return &poisonBranchReader{StatusReader: inner, poison: set} } +// stackFixtureSpecPath is the spec every stackFixtureBlob record links. +const stackFixtureSpecPath = "docs/superpowers/specs/x-design.md" + +// stackFixtureSpecArtifacts serves stackFixtureSpecPath from the metadata +// branch, for a fake reader whose operation reads the linked spec. +func stackFixtureSpecArtifacts() map[string]StatusArtifact { + return map[string]StatusArtifact{ + sourceMetadata + "|" + stackFixtureSpecPath: {Found: true, Revision: "specx", Data: []byte("# X: design\n")}, + } +} + // stackFixtureBlob renders a change record for the stackBranchesFor fixture. +// Every record links stackFixtureSpecPath, so a proposed one is build-ready. func stackFixtureBlob(id int, slug, status, branch, extra string) StatusBlob { branchField := "" if branch != "" { branchField = "branch: '" + branch + "'\nclaimed_at: '2026-01-03T00:00:00Z'\nreconciled: true\n" } - fm := fmt.Sprintf("---\nid: %d\nslug: %s\ntitle: Change %d\nstatus: '%s'\npriority: medium\ntype: feat\ncreated: 2026-01-02\ntrivial: true\n%s%s---\n\nBody of %d.\n", - id, slug, id, status, branchField, extra, id) + fm := fmt.Sprintf("---\nid: %d\nslug: %s\ntitle: Change %d\nstatus: '%s'\npriority: medium\ntype: feat\ncreated: 2026-01-02\nspec: '%s'\n%s%s---\n\nBody of %d.\n", + id, slug, id, status, stackFixtureSpecPath, branchField, extra, id) return StatusBlob{ Kind: repository.KindChange, Location: repository.LocationActive, @@ -122,7 +134,7 @@ func TestContextImplementationNamedIDProbesOnlyOwnStack(t *testing.T) { t.Run("unrelated-poison-does-not-block", func(t *testing.T) { corpus := append(append([]StatusBlob(nil), unrelated...), stackFixtureBlob(30, "b", "proposed", "", "")) - reader := poisoned(&fakeReader{pin: pin, corpus: corpus, facts: domain.NewBranchFacts(nil)}, "feat/a-parent") + reader := poisoned(&fakeReader{pin: pin, corpus: corpus, facts: domain.NewBranchFacts(nil), artifactData: stackFixtureSpecArtifacts()}, "feat/a-parent") got := ContextImplementation(context.Background(), PlanningDeps{Reader: reader, Clock: testClock()}, "", ImplementationContextRequest{ID: 30}) if got.Result != ResultApplied { t.Fatalf("named context beside an unprobeable unrelated stack = %q (%s: %s), want applied", got.Result, got.Reason, got.Message) diff --git a/internal/app/named_isolation_integration_test.go b/internal/app/named_isolation_integration_test.go index 5d368a190..2d4f7212a 100644 --- a/internal/app/named_isolation_integration_test.go +++ b/internal/app/named_isolation_integration_test.go @@ -185,6 +185,7 @@ func TestIntegrationNamedImplementationFlowIsolation(t *testing.T) { resultsPath := "docs/results/2026-08-17-widget-results.md" records := namedIsolationUnrelatedStack(t) records[recPath] = buildReadyChange(id, slug) + records[fixtureSpecPath(slug)] = fixtureSpecFile(id, slug) records[unrelatedBrokenPath] = unrelatedBrokenBytes repo := newDocketModeRepo(t, map[string]string{".docket.yml": "integration_branch: main\nbuild:\n test_command: 'go test ./...'\nfinalize:\n test_command: 'go test ./...'\n"}, @@ -309,6 +310,7 @@ func TestIntegrationNamedClaimRefusesDefectiveDependency(t *testing.T) { } records := namedIsolationUnrelatedStack(t) records[recPath] = b + records[fixtureSpecPath("widget")] = fixtureSpecFile(id, "widget") records[depPath] = dep records[unrelatedBrokenPath] = unrelatedBrokenBytes repo := newWorkingRepo(t, records) diff --git a/internal/app/open.go b/internal/app/open.go index aa1ed9048..80211d2ad 100644 --- a/internal/app/open.go +++ b/internal/app/open.go @@ -45,7 +45,6 @@ const ( ReasonOpenUnknownChange = "unknown-change" ReasonOpenAmbiguousChange = "ambiguous-change" ReasonOpenArtifactUnset = "artifact-unset" - ReasonOpenTrivialNoSpec = "trivial-no-spec" ReasonOpenBoardDisabled = "board-disabled" ReasonOpenPRNotURL = "pr-not-url" ReasonOpenPathInvalid = "artifact-path-invalid" @@ -301,18 +300,14 @@ func resolveOpenChange(ctx context.Context, reader StatusReader, pin StatusPin, } // changeArtifactPath returns the repository-relative path what names for c: the -// record itself, or its spec, plan, or results. A trivial change has no spec; -// an unset or malformed field is refused as not there yet. +// record itself, or its spec, plan, or results. An unset or malformed field (a +// stub's spec included) is refused as not there yet. func changeArtifactPath(c domain.Change, what string) (string, *openFailure) { var field domain.OptionalString switch what { case "change": return c.Path(), nil case "spec": - if c.Trivial() { - return "", &openFailure{ResultInvalidState, ReasonOpenTrivialNoSpec, - fmt.Sprintf("change %d is trivial — it has no spec", int(c.ID()))} - } field = c.Spec() case "plan": field = c.Plan() diff --git a/internal/app/open_test.go b/internal/app/open_test.go index ddd2c6aad..252d7248a 100644 --- a/internal/app/open_test.go +++ b/internal/app/open_test.go @@ -96,7 +96,7 @@ const ( oldSpec = "docs/superpowers/specs/2025-12-01-old-design.md" ) -// 7 fully linked, 3 archived, 8 bare, 9 trivial, 10 shorthand pr. +// 7 fully linked, 3 archived, 8 bare, 9 legacy trivial, 10 shorthand pr. func openCorpus() []StatusBlob { return []StatusBlob{ openChange(7, "widget", false, "branch: feat/widget\nspec: "+widgetSpec+"\nplan: "+widgetPlan+"\nresults: "+widgetResults+"\npr: '"+widgetPR+"'\n"), @@ -271,7 +271,7 @@ func TestOpenErrors(t *testing.T) { {"plan", 8, st, ReasonOpenArtifactUnset, "change 8 has no plan yet"}, {"results", 8, st, ReasonOpenArtifactUnset, "change 8 has no results yet"}, {"pr", 8, st, ReasonOpenArtifactUnset, "change 8 has no PR yet"}, - {"spec", 9, st, ReasonOpenTrivialNoSpec, "change 9 is trivial — it has no spec"}, + {"spec", 9, st, ReasonOpenArtifactUnset, "change 9 has no spec yet"}, {"board", 0, st, ReasonOpenBoardDisabled, "this repository has no board (board_surfaces has no inline surface)"}, {"pr", 10, st, ReasonOpenPRNotURL, "change 10 pr: acme/widget#12 is not a URL"}, {"bogus", 7, inv, ReasonOpenInvalidTarget, ""}, diff --git a/internal/app/planning_git_test.go b/internal/app/planning_git_test.go index c231cc44b..68141ea66 100644 --- a/internal/app/planning_git_test.go +++ b/internal/app/planning_git_test.go @@ -267,8 +267,7 @@ func assertIndexMatchesCommitted(t *testing.T, origin, branch, repoDir string) { // killableChangeWithSpec renders a proposed change record carrying a spec pointer // at specPath, so a kill exercises the metadata-resident-spec backlink retarget. func killableChangeWithSpec(id int, slug, specPath string) string { - src := groomableChange(id, slug) - return strings.Replace(src, "spec:\n", "spec: "+specPath+"\n", 1) + return withLinkedSpec(groomableChange(id, slug), specPath) } // specWithBacklink renders a minimal spec file: a docket:backlink managed block diff --git a/internal/app/repository_set_visibility_integration_test.go b/internal/app/repository_set_visibility_integration_test.go index faa34f8e2..a68b07fb9 100644 --- a/internal/app/repository_set_visibility_integration_test.go +++ b/internal/app/repository_set_visibility_integration_test.go @@ -1367,6 +1367,7 @@ func TestIntegrationRepoVisibilitySwitchRoundTripPreservesRecords(t *testing.T) dotDocket := filepath.Join(r.invocation, layout.SharedWorktreeDir) runGit(t, dotDocket, "fetch", "-q", "origin", layout.SharedName) runGit(t, dotDocket, "merge", "-q", "--ff-only", "FETCH_HEAD") + r.writeDocketFileAndPush(t, fixtureSpecPath("widget"), fixtureSpecFile(claimID, "widget"), "the spec the change links") r.writeDocketFileAndPush(t, recPath, buildReadyChange(claimID, "widget"), "a build-ready change to claim") node := planningDepsFor(t, r.invocation) bundle := ContextImplementation(ctx, node.deps, node.dir, ImplementationContextRequest{ID: claimID}) diff --git a/internal/app/runtracker_verdict_integration_test.go b/internal/app/runtracker_verdict_integration_test.go index 78c449f41..439daaf15 100644 --- a/internal/app/runtracker_verdict_integration_test.go +++ b/internal/app/runtracker_verdict_integration_test.go @@ -1706,10 +1706,10 @@ func TestIntegrationRunVerdictCompletedResultsArtifactReadsDone(t *testing.T) { slug = "research" ) recPath := groomPath(id, slug) - rec := strings.Replace(groomableChange(id, slug), "trivial: false\n", "trivial: true\n", 1) + rec := withLinkedSpec(groomableChange(id, slug), fixtureSpecPath(slug)) rec = strings.Replace(rec, "type: feat\n", "type: feat\ndeliverable: results-artifact\n", 1) m := planRepoModes()[0] - repo := buildConfiguredRepoWith(t, m, map[string]string{recPath: rec}) + repo := buildConfiguredRepoWith(t, m, map[string]string{recPath: rec, fixtureSpecPath(slug): fixtureSpecFile(id, slug)}) lw := prepareLeakWorkspace(t, repo, m.branch, id, recPath, false) completeLeakWorkspace(t, lw, repo.meta, m.branch, recPath) diff --git a/internal/app/schema_vocab.go b/internal/app/schema_vocab.go index c67234291..f8968dd29 100644 --- a/internal/app/schema_vocab.go +++ b/internal/app/schema_vocab.go @@ -71,7 +71,7 @@ func SchemaVocabularies(effects []string) map[string]Vocabulary { v["section_intents"] = Vocabulary{Members: members(len(render.AllSectionIntents), func(i int) string { return string(render.AllSectionIntents[i]) })} - v["groom_outcomes"] = Vocabulary{Members: []string{string(GroomSpec), string(GroomTrivial), string(GroomRevise), string(GroomAbstain), string(GroomReEnable)}} + v["groom_outcomes"] = Vocabulary{Members: []string{string(GroomSpec), string(GroomRevise), string(GroomAbstain), string(GroomReEnable)}} v["change_types"] = Vocabulary{Pattern: changeTypePattern} v["effects"] = Vocabulary{Members: effects} diff --git a/internal/app/schema_vocab_test.go b/internal/app/schema_vocab_test.go index e532eb6f8..6eff3db4b 100644 --- a/internal/app/schema_vocab_test.go +++ b/internal/app/schema_vocab_test.go @@ -45,7 +45,7 @@ func TestSchemaVocabulariesCore(t *testing.T) { assertVocabMembers(t, v, "priorities", []string{"critical", "high", "medium", "low"}) assertVocabMembers(t, v, "section_intents", []string{"preserve", "replace", "remove"}) - assertVocabMembers(t, v, "groom_outcomes", []string{"spec", "trivial", "revise", "abstain", "re-enable"}) + assertVocabMembers(t, v, "groom_outcomes", []string{"spec", "revise", "abstain", "re-enable"}) assertVocabMembers(t, v, "statuses", []string{ "proposed", "in-progress", "blocked", "deferred", "implemented", "stacked-merged", "done", "killed", diff --git a/internal/app/spec_fixture_test.go b/internal/app/spec_fixture_test.go new file mode 100644 index 000000000..74d825aa1 --- /dev/null +++ b/internal/app/spec_fixture_test.go @@ -0,0 +1,51 @@ +package app + +import ( + "fmt" + "strings" + "testing" +) + +func TestWithLinkedSpecLinksAndRefusesMissingAnchor(t *testing.T) { + got := withLinkedSpec(lifecycleChange(3, "widget", "proposed"), fixtureSpecPath("widget")) + if !strings.Contains(got, "\nspec: 'docs/superpowers/specs/2026-08-01-widget-design.md'\n") { + t.Errorf("record does not link the fixture spec:\n%s", got) + } + if strings.Contains(got, "\nspec:\n") { + t.Errorf("record still carries an empty spec line:\n%s", got) + } + + panicked := func() (p bool) { + defer func() { p = recover() != nil }() + withLinkedSpec("---\nid: 3\n---\n", fixtureSpecPath("widget")) + return false + }() + if !panicked { + t.Errorf("withLinkedSpec on a record with no empty spec line did not panic") + } +} + +// fixtureSpecPath is the spec path a build-ready fixture change links. +func fixtureSpecPath(slug string) string { + return "docs/superpowers/specs/2026-08-01-" + slug + "-design.md" +} + +// withLinkedSpec links specPath on a record's empty spec line, so a proposed +// fixture carries the design every build-ready change needs. It panics when the +// record has no empty spec line, so a fixture can never silently stay spec-less. +func withLinkedSpec(src, specPath string) string { + const anchor = "\nspec:\n" + if !strings.Contains(src, anchor) { + panic("withLinkedSpec: record has no empty \"spec:\" line to link") + } + return strings.Replace(src, anchor, "\nspec: '"+specPath+"'\n", 1) +} + +// fixtureSpecFile is a spec as the metadata branch stores it: a +// docket:backlink block above the authored title. +func fixtureSpecFile(id int, slug string) string { + return "\n" + + "> ↩ **[Change " + fmt.Sprintf("%04d", id) + " — A change](../../changes/active/" + fmt.Sprintf("%04d", id) + "-" + slug + ".md)**\n" + + "\n\n" + + "# Widget: design\n\nBuild the widget.\n" +} diff --git a/internal/app/status_test.go b/internal/app/status_test.go index 6765f5f41..249db5537 100644 --- a/internal/app/status_test.go +++ b/internal/app/status_test.go @@ -712,3 +712,37 @@ func TestStatusReportsHeldChange(t *testing.T) { row.Readiness, row.ReadinessWhy, row.Ready) } } + +// TestStatusLegacyTrivialRecordReadsNeedsGrooming: a legacy record carrying +// trivial: true and no spec is a stub — status reports it needs-grooming and +// keeps it out of the build-ready queue, while a spec'd sibling is ready. +func TestStatusLegacyTrivialRecordReadsNeedsGrooming(t *testing.T) { + fake := &fakeReader{ + pin: docketPin(t), + corpus: []StatusBlob{ + changeBlob(15, "legacy", "feat", "high", "trivial: true\n"), + changeBlob(16, "groomed", "feat", "low", "spec: docs/changes/specs/s16.md\n"), + }, + facts: domain.NewBranchFacts(nil), + artifacts: map[string]bool{"metadata|docs/changes/specs/s16.md": true}, + } + got := Status(context.Background(), fake, StatusOptions{}) + if got.Result != ResultApplied { + t.Fatalf("result = %q, want applied; message=%q", got.Result, got.Message) + } + if len(got.Ready) != 1 || got.Ready[0] != 16 { + t.Errorf("ready = %v, want [16] (the legacy trivial record is not build-ready)", got.Ready) + } + var row *StatusChange + for i := range got.Changes { + if got.Changes[i].ID == 15 { + row = &got.Changes[i] + } + } + if row == nil { + t.Fatalf("no row for legacy change 15: %+v", got.Changes) + } + if row.Readiness != string(domain.ReadyNeedsGrooming) || row.Ready { + t.Errorf("legacy trivial row = readiness %q, ready %v; want needs-grooming, false", row.Readiness, row.Ready) + } +} diff --git a/internal/app/workflow_e2e_test.go b/internal/app/workflow_e2e_test.go index 76ec5b7c5..164bd9b55 100644 --- a/internal/app/workflow_e2e_test.go +++ b/internal/app/workflow_e2e_test.go @@ -2,7 +2,6 @@ package app import ( "context" - "fmt" "github.com/danielhanold/docket/internal/evidence" "github.com/danielhanold/docket/internal/githubcli" "github.com/danielhanold/docket/internal/testsupport" @@ -364,18 +363,15 @@ func buildConfiguredRepoWith(t *testing.T, m planRepoMode, metadata map[string]s } // specLinkedBuildReadyChange is a proposed, build-ready change record whose -// design is the spec at specPath (not a trivial verdict). +// design is the spec at specPath. func specLinkedBuildReadyChange(id int, slug, specPath string) string { - return strings.Replace(groomableChange(id, slug), "spec:\n", "spec: "+specPath+"\n", 1) + return withLinkedSpec(groomableChange(id, slug), specPath) } // workflowMetadataSpec is a spec as the metadata branch stores it: a // docket:backlink block above the authored title. func workflowMetadataSpec(id int, slug string) string { - return "\n" + - "> ↩ **[Change " + fmt.Sprintf("%04d", id) + " — A change](../../changes/active/" + fmt.Sprintf("%04d", id) + "-" + slug + ".md)**\n" + - "\n\n" + - "# Widget: design\n\nBuild the widget.\n" + return fixtureSpecFile(id, slug) } // assertDeferredCapabilityBlocksClaim proves a `.docket.yml` that actively diff --git a/internal/app/workflow_integration_test.go b/internal/app/workflow_integration_test.go index 4432b0033..de13813fb 100644 --- a/internal/app/workflow_integration_test.go +++ b/internal/app/workflow_integration_test.go @@ -397,7 +397,8 @@ func TestIntegrationWorkflowRepoClaimRaceLosesCleanly(t *testing.T) { m := m t.Run(m.name, func(t *testing.T) { repo := m.build(t, map[string]string{ - recPath: buildReadyChange(id, slug), + recPath: buildReadyChange(id, slug), + fixtureSpecPath(slug): fixtureSpecFile(id, slug), }) ctx := context.Background() @@ -494,7 +495,8 @@ func TestIntegrationWorkflowRepoClaimForeignRunContextSameRevisionContends(t *te m := m t.Run(m.name, func(t *testing.T) { repo := m.build(t, map[string]string{ - recPath: buildReadyChange(id, slug), + recPath: buildReadyChange(id, slug), + fixtureSpecPath(slug): fixtureSpecFile(id, slug), }) ctx := context.Background() nodeA := planningDepsFor(t, cloneOrigin(t, repo.origin)) @@ -556,7 +558,8 @@ func TestIntegrationWorkflowRepoClaimRetryAfterLostResponse(t *testing.T) { m := m t.Run(m.name, func(t *testing.T) { repo := m.build(t, map[string]string{ - recPath: buildReadyChange(id, slug), + recPath: buildReadyChange(id, slug), + fixtureSpecPath(slug): fixtureSpecFile(id, slug), }) node := planningDepsFor(t, repo.invocation) ctx := context.Background() @@ -1288,7 +1291,8 @@ func TestIntegrationWorkflowRepoRefreshClaimAppliesWhenBoardReRenderIsUnchanged( m := m t.Run(m.name, func(t *testing.T) { repo := m.build(t, map[string]string{ - recPath: buildReadyChange(id, slug), + recPath: buildReadyChange(id, slug), + fixtureSpecPath(slug): fixtureSpecFile(id, slug), }) ctx := context.Background() @@ -1369,8 +1373,8 @@ func TestIntegrationWorkflowRepoStackedContextClaimWorkspaceFromParentBranch(t * ) parentRec := groomPath(parentID, parentSlug) childRec := groomPath(childID, childSlug) - // The child is proposed + designed (trivial: true stands in for a spec, - // as in buildReadyChange) and stacked on the live parent. + // The child is proposed + designed (it links a spec, as in + // buildReadyChange) and stacked on the live parent. childBody := strings.Replace(buildReadyChange(childID, childSlug), "stacked_on:\n", "stacked_on: 20\n", 1) @@ -1378,8 +1382,9 @@ func TestIntegrationWorkflowRepoStackedContextClaimWorkspaceFromParentBranch(t * m := m t.Run(m.name, func(t *testing.T) { repo := m.build(t, map[string]string{ - parentRec: lifecycleChange(parentID, parentSlug, "in-progress"), - childRec: childBody, + parentRec: lifecycleChange(parentID, parentSlug, "in-progress"), + childRec: childBody, + fixtureSpecPath(childSlug): fixtureSpecFile(childID, childSlug), }) ctx := context.Background() @@ -1764,7 +1769,7 @@ func commitSpecMetadataSpec(body string) string { } // commitSpecRecord is change 31 in-progress, its spec: field set to specPath -// ("" leaves it empty — a trivial change). +// ("" leaves it empty — a change claimed with no spec). func commitSpecRecord(specPath string) string { rec := lifecycleChange(31, "copyme", "in-progress") if specPath != "" { @@ -1932,11 +1937,16 @@ func TestIntegrationWorkflowLifecycleCommitSpecRefreshesRevisedSpec(t *testing.T env.assertClean(t) } -// TestIntegrationWorkflowLifecycleCommitSpecTrivialNoSpec: a change with no -// spec has no copy — a no-op that commits nothing. -func TestIntegrationWorkflowLifecycleCommitSpecTrivialNoSpec(t *testing.T) { +// TestIntegrationWorkflowLifecycleCommitSpecNoSpec: a legacy change claimed +// with no spec (its record still carrying an inert trivial: true line) has no +// copy — it still gets the no-spec no-op, which commits nothing. +func TestIntegrationWorkflowLifecycleCommitSpecNoSpec(t *testing.T) { + legacy := strings.Replace(commitSpecRecord(""), "\ntrivial: false\n", "\ntrivial: true\n", 1) + if !strings.Contains(legacy, "\ntrivial: true\n") { + t.Fatal("legacy fixture lacks its trivial: true line") + } env := newCommitSpecEnv(t, nil, map[string]string{ - groomPath(31, "copyme"): commitSpecRecord(""), + groomPath(31, "copyme"): legacy, }) before := env.head(t) res := env.commitSpec(t) diff --git a/internal/app/workspace_spec.go b/internal/app/workspace_spec.go index e451d50f9..43ab69842 100644 --- a/internal/app/workspace_spec.go +++ b/internal/app/workspace_spec.go @@ -42,8 +42,8 @@ const ( SpecCopyRefreshed = "refreshed" // SpecCopyCurrent: the feature head already carries the exact copy (no-op). SpecCopyCurrent = "current" - // SpecCopyNoSpec: the change links no spec (a trivial change), so there is - // no copy (no-op). + // SpecCopyNoSpec: the change links no spec (a legacy record claimed with + // none), so there is no copy (no-op). SpecCopyNoSpec = "no-spec" ) diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index 8f7e535ad..c5c14ef72 100644 --- a/internal/assets/embedded/manifest.json +++ b/internal/assets/embedded/manifest.json @@ -1,7 +1,7 @@ { "format_version": 1, "asset_protocol": 1, - "asset_set_id": "sha256:9655f89087fb84ac2de7852c2c09408ec7636be9f76c084c4708e905c8947dce", + "asset_set_id": "sha256:98ddce21935afa973ca1337ad84abbb3386c6ccd1a1cff03e2693392c1d83fe0", "entries": [ { "path": ".docket.example.yml", @@ -21,15 +21,15 @@ "path": "agents/docket-auto-groom-critic.md", "role": "agent-source", "mode": 420, - "size": 1591, - "sha256": "3d28f51fbf68cc9a7b0c28cb328f2f21e2778642abe0ae96847cc9887ec83590" + "size": 1572, + "sha256": "c6e0c63df61fc936c4986981c7b28c8bfa8416151c139844725e75e44209267e" }, { "path": "agents/docket-auto-groom.md", "role": "agent-source", "mode": 420, - "size": 929, - "sha256": "528ec497eb05e8bb10f5619eea927822a849fbfad67f83d5c1e12672f4c43182" + "size": 909, + "sha256": "e499c9749dffeed5b25d8d1c605ed7ea9cc153edefe1342bab617cf2724a55d7" }, { "path": "agents/docket-brainstorm-consultant.md", @@ -154,8 +154,8 @@ "path": "cursor-rules/dispatch/docket-auto-groom-critic.md", "role": "dispatch", "mode": 420, - "size": 864, - "sha256": "1374525b1c5cd7098e67e6b741b4baad43c3aa223d98c73ea88a25e89d08bb43" + "size": 827, + "sha256": "3823486506ccaa9280a06ff586356508870271c67088b340126c08425f4196f1" }, { "path": "cursor-rules/dispatch/docket-auto-groom.md", @@ -280,8 +280,8 @@ "path": "skills/docket-auto-groom/SKILL.md", "role": "skill", "mode": 420, - "size": 11651, - "sha256": "94ba139f727b8d5adb50f378b41be03d400c3d04cd172a736e0c7ae69fca1d0b" + "size": 11011, + "sha256": "825a46b20f871f0d1ad6ed53c33fa7c9533657e938519a5d39b4d26b43677cce" }, { "path": "skills/docket-brainstorm/SKILL.md", @@ -322,8 +322,8 @@ "path": "skills/docket-convention/SKILL.md", "role": "skill", "mode": 420, - "size": 53753, - "sha256": "46f39cae61f74ff14a8fdc5a5878c3d7fe8a6f9ade4e43e57817c23ee76b8cfe" + "size": 53532, + "sha256": "c53fb6037c675224b506f99373c8a71571b41af9b2ad9c79912b9d8c4d04ca66" }, { "path": "skills/docket-convention/references/agent-layer.md", @@ -371,15 +371,15 @@ "path": "skills/docket-groom-next/SKILL.md", "role": "skill", "mode": 420, - "size": 16352, - "sha256": "3fc4bb2d3d8c6d1def93d24b18e15f70d7792d7514060cb2ace588c0e5b4bfb3" + "size": 15820, + "sha256": "4e5665aab5d649f74d16c66ba610801bb150cb612753dca9dcdd2b10f9a8d8b3" }, { "path": "skills/docket-implement-next/SKILL.md", "role": "skill", "mode": 420, - "size": 59470, - "sha256": "4fa089cb4628311bad6750288b0cae3a84b6ba63911992c08979c9df08e389aa" + "size": 59299, + "sha256": "15b342ac83767c92a1a73c105e14fbedd03a47951b357b37dd87b54a02aad144" }, { "path": "skills/docket-implement-next/references/edge-paths.md", @@ -399,36 +399,36 @@ "path": "skills/docket-implement-next/references/results-artifact.md", "role": "skill", "mode": 420, - "size": 5131, - "sha256": "abd74f4dca159ae60d5bcd2aefb4ba16d2e0deffeeabce09b650d69110820aad" + "size": 5071, + "sha256": "b7112b747ec1d24ed5d6a83ff4e537a507be4f60bab28679e540a744ca041937" }, { "path": "skills/docket-implement-next/results-template.md", "role": "skill", "mode": 420, - "size": 3760, - "sha256": "a5f1d87a0d63f764551c6e3301e019886c83b541507b22eb0e935ebc881bed8c" + "size": 3741, + "sha256": "c633d7c6e9ebe1540282f4361eedee0aac082b3f9897c0668a7aec2a275bc0a3" }, { "path": "skills/docket-new-change/SKILL.md", "role": "skill", "mode": 420, - "size": 11385, - "sha256": "dd38825949fa7a25427f4a2ef4baaf06b8664365f21bf5506fb9207d4d8d5cdd" + "size": 10669, + "sha256": "f95cab6bec123d39473d206be294f1d667a89bcb442a5f7beccaedb38db4757d" }, { "path": "skills/docket-review/SKILL.md", "role": "skill", "mode": 420, - "size": 6489, - "sha256": "1e7dcfa45df8283824cc76eb2aa64d37ab04e6c10f60f458454114b3a1e835d1" + "size": 6460, + "sha256": "2589c88417c7af5d25b7b807270c549f98982b519f0545ba7b8c2f72dda4cb62" }, { "path": "skills/docket-status/SKILL.md", "role": "skill", "mode": 420, - "size": 20143, - "sha256": "891b4ed127a7d48e7579790e226c7f1c1feff4351dfc318b23b99dcc72c1516c" + "size": 20121, + "sha256": "6a72745f574d8f2d5c2f868f9abc3d22ac9b4c77efe85586abfb164d487c4280" } ] } diff --git a/internal/assets/embedded/tree/agents/docket-auto-groom-critic.md b/internal/assets/embedded/tree/agents/docket-auto-groom-critic.md index 14d19dd38..b4d0bce05 100644 --- a/internal/assets/embedded/tree/agents/docket-auto-groom-critic.md +++ b/internal/assets/embedded/tree/agents/docket-auto-groom-critic.md @@ -1,6 +1,6 @@ --- name: docket-auto-groom-critic -description: Adversarial reviewer of an auto-groom draft spec or trivial verdict — attacks it, never improves it, and returns exactly one verdict per the dispatching skill's protocol. +description: Adversarial reviewer of an auto-groom draft spec — attacks it, never improves it, and returns exactly one verdict per the dispatching skill's protocol. skills: [docket-convention] worktree-scope: metadata --- diff --git a/internal/assets/embedded/tree/agents/docket-auto-groom.md b/internal/assets/embedded/tree/agents/docket-auto-groom.md index 2b7c4907b..e7243a89d 100644 --- a/internal/assets/embedded/tree/agents/docket-auto-groom.md +++ b/internal/assets/embedded/tree/agents/docket-auto-groom.md @@ -1,6 +1,6 @@ --- name: docket-auto-groom -description: Use when individual stubs opted into autonomous grooming (their `auto_groomable` is `true`) and you want the auto-groomable needs-grooming queue drained with no human — selecting each auto-groomable stub deterministically and designing it via a default-biased self-brainstorm gated by an adversarial critic, exiting each stub with a linked spec, a trivial verdict, or an abstain back to the human queue. Kill and defer are never autonomous. Writes markdown only — never branches, worktrees, or code. +description: Use when individual stubs opted into autonomous grooming (their `auto_groomable` is `true`) and you want the auto-groomable needs-grooming queue drained with no human — selecting each auto-groomable stub deterministically and designing it via a default-biased self-brainstorm gated by an adversarial critic, exiting each stub with a linked spec or an abstain back to the human queue. Kill and defer are never autonomous. Writes markdown only — never branches, worktrees, or code. skills: [docket-auto-groom, docket-convention] worktree-scope: metadata launch: root-coordinator diff --git a/internal/assets/embedded/tree/cursor-rules/dispatch/docket-auto-groom-critic.md b/internal/assets/embedded/tree/cursor-rules/dispatch/docket-auto-groom-critic.md index 195c80164..42b7ca10d 100644 --- a/internal/assets/embedded/tree/cursor-rules/dispatch/docket-auto-groom-critic.md +++ b/internal/assets/embedded/tree/cursor-rules/dispatch/docket-auto-groom-critic.md @@ -1,11 +1,11 @@ ## docket-auto-groom-critic — dispatch only This agent wraps no skill and is normally dispatched **by** docket-auto-groom as its adversarial gate, -not invoked directly. If you are asked to adversarially review an auto-groom draft spec or trivial -verdict, dispatch it rather than reviewing inline. +not invoked directly. If you are asked to adversarially review an auto-groom draft spec, dispatch it +rather than reviewing inline. Dispatch to the subagent `docket-auto-groom-critic`, foreground, using this mode's subagent-launch -mechanism. The prompt must include the draft spec / trivial verdict under review and the dispatching +mechanism. The prompt must include the draft spec under review and the dispatching skill's verdict protocol. Do NOT let it improve the draft — it only attacks and returns exactly one verdict. 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 7f3ccd763..d8cbaf6aa 100644 --- a/internal/assets/embedded/tree/skills/docket-auto-groom/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-auto-groom/SKILL.md @@ -1,6 +1,6 @@ --- name: docket-auto-groom -description: Use when individual stubs opted into autonomous grooming (their `auto_groomable` is `true`) and you want the auto-groomable needs-grooming queue drained with no human — selecting each auto-groomable stub deterministically and designing it via a default-biased self-brainstorm gated by an adversarial critic, exiting each stub with a linked spec, a trivial verdict, or an abstain back to the human queue. Kill and defer are never autonomous. Writes markdown only — never branches, worktrees, or code. +description: Use when individual stubs opted into autonomous grooming (their `auto_groomable` is `true`) and you want the auto-groomable needs-grooming queue drained with no human — selecting each auto-groomable stub deterministically and designing it via a default-biased self-brainstorm gated by an adversarial critic, exiting each stub with a linked spec or an abstain back to the human queue. Kill and defer are never autonomous. Writes markdown only — never branches, worktrees, or code. context: fork agent: docket-auto-groom --- @@ -32,24 +32,23 @@ Sync the metadata working tree (the startup-check `repository.prepare` operation ### Step 2 — Designer pass -Read the stub body, its `related`/`depends_on` neighbours (active + recently archived), the ADR index, and the relevant code. Read the learnings index `/learnings/README.md` and pull any findings whose hook bears on the stub, so the self-brainstorm is informed by past lessons (skipped entirely when `learnings.enabled` is `false`). Enumerate the decision points an interactive brainstorm would raise. For each, weigh 2–3 approaches and COMMIT to the conservative / recommended default — do NOT invoke `superpowers:brainstorming` with a simulated human answerer (a subagent picking "the recommended option" is the model agreeing with itself while faking an approval gate; rejected at design time). Draft the spec in session scratch space — never inside the metadata worktree — as the Markdown body that Step 4 sends as `spec_markdown` in the `change.groom` request file, with an `## Assumptions` block: every decision, the chosen default, the rejected alternatives, and why — the human's deferred audit trail. In a private repository the spec ships with the PR, so its body follows the private-repository writing rule: no `Change #N, groomed …` line, no change or ADR numbers, no backlog references. If the stub is genuinely mechanical (no real design questions), the draft verdict is *trivial* instead of a spec, with the reasoning written for the critic. +Read the stub body, its `related`/`depends_on` neighbours (active + recently archived), the ADR index, and the relevant code. Read the learnings index `/learnings/README.md` and pull any findings whose hook bears on the stub, so the self-brainstorm is informed by past lessons (skipped entirely when `learnings.enabled` is `false`). Enumerate the decision points an interactive brainstorm would raise. For each, weigh 2–3 approaches and COMMIT to the conservative / recommended default — do NOT invoke `superpowers:brainstorming` with a simulated human answerer (a subagent picking "the recommended option" is the model agreeing with itself while faking an approval gate; rejected at design time). Draft the spec in session scratch space — never inside the metadata worktree — as the Markdown body that Step 4 sends as `spec_markdown` in the `change.groom` request file, with an `## Assumptions` block: every decision, the chosen default, the rejected alternatives, and why — the human's deferred audit trail. In a private repository the spec ships with the PR, so its body follows the private-repository writing rule: no `Change #N, groomed …` line, no change or ADR numbers, no backlog references. A mechanical stub gets a short spec with its `## Assumptions` block like any other. ### 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 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. +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 spec. 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. **No-verdict posture (bounded — two steps, then out).** If the dispatch returns no legible verdict — a malformed return, pre-yield prose, or a backgrounded child's bare completion — make **one collect attempt** (read the child's completed final report where the harness surfaces it), and failing that **one fresh foreground re-dispatch** of the critic over the same draft, issued through whatever mechanism makes the parent block on the return — if none does, that leg would only repeat the first, so skip it straight to `abstain`. Still no verdict ⇒ treat it as a failed dispatch attempt under the convention's *Dispatch-capability resolution*: **`abstain`**, so the groom **abstains** for this stub (→ Step 4's **Abstain** exit in full, the `auto_groomable: false` flip included — left armed, the stub stays auto-groomable and the drain re-selects it, forfeiting *Termination & concurrency*), recording the return-channel diagnostic in the `blocked_note`, the human's re-enable cue. Never a third dispatch; never an indefinite wait. Re-dispatching a critic is safe where a build worker is not — it is read-only over prose, holds no worktree, and writes no git state, so `yielded-worker-return-closes-every-door`'s closed-doors analysis does not bind here. -### Step 4 — Exit (one of three) +### Step 4 — Exit (one of two) 1. **Spec** — every assumption survived: apply one atomic transaction — the `change.groom` operation with `--repo-dir --request ` — carrying the change id, the pinned `path` + `revision` from Step 1, `outcome: spec`, the drafted `spec_markdown` (the settled design plus its `## Assumptions` block), the owned proposal-section rewrites (proposal altitude, resolved `## Open questions` removed), and the desired `depends_on`/`related`/`adrs`/`discovered_from`/`stacked_on`. In one metadata commit it writes the spec file, sets `spec:` + `updated:`, stamps the spec's `docket:backlink` block, and re-renders the `## Artifacts` block and inline board; a typed refusal (not-groomable, spec-path-taken, malformed markers, revision mismatch) writes nothing. Build-ready. -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. +2. **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. +**Hold.** When the emitted spec 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. @@ -59,8 +58,8 @@ 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 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. +Summarize the drain: groomed N, 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 -Every exit shrinks the queue (spec/trivial ⇒ no longer needs-grooming; abstain ⇒ no longer auto-groomable), so the drain visits each stub at most once and provably terminates. No claim is taken — ADR-0004's conflict-checked final-push stance, adopted for the autonomous case: its human-attended rationale does not apply here, but the load-bearing half does — each stub's writes land in a single final commit, so a late collision wastes minutes, not hours, and the post-rebase re-read is the arbiter. +Every exit shrinks the queue (spec ⇒ no longer needs-grooming; abstain ⇒ no longer auto-groomable), so the drain visits each stub at most once and provably terminates. No claim is taken — ADR-0004's conflict-checked final-push stance, adopted for the autonomous case: its human-attended rationale does not apply here, but the load-bearing half does — each stub's writes land in a single final commit, so a late collision wastes minutes, not hours, and the post-rebase re-read is the arbiter. diff --git a/internal/assets/embedded/tree/skills/docket-convention/SKILL.md b/internal/assets/embedded/tree/skills/docket-convention/SKILL.md index 32de42c90..f67b32524 100644 --- a/internal/assets/embedded/tree/skills/docket-convention/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-convention/SKILL.md @@ -154,7 +154,7 @@ docket's workflow steps are **roles**, each done by one fixed skill: / # default docs/adrs/ — flat; ADRs are NEVER archived -.md # immutable once Accepted (only its status: line ever changes) README.md # generated ADR index -/ # default docs/results/ — required close-out artifacts (one per implemented change, trivial included) (on the metadata branch; NEVER archived) +/ # default docs/results/ — required close-out artifacts (one per implemented change) (on the metadata branch; NEVER archived) --results.md ``` @@ -162,7 +162,7 @@ The `archive/` filename date prefix is **UTC**: the merge date for a merged chan All of the above lives on the metadata branch, written through the persistent **metadata worktree**: `/.docket/` in a shared repository (gitignored, deliberately not under `.worktrees/` — slug collisions, prune blast radius), or a checkout outside the clone in a private one; skills always use `metadata_worktree_path` (see *Branch model*). -**Results artifact shape and lifecycle.** The results file is a required close-out artifact for every implemented change, trivial included. Its template opens with a required `**Human action:**` statement immediately after the title (a settled assessment at finalization) and carries a required `## Outcome` section plus the conditional sections `## Human actions and testing` (items labeled Important or Optional; optional walkthroughs may cover automated behavior), `## Verification performed`, and `## Known issues and follow-ups` — omit any conditional section, subsections and all, when it would hold no substantive content, and never pad one with `None`/`N/A` filler. The results **file** lives on the metadata branch at `/--results.md`; the `change.attach-results` operation writes the file and the `results:` **field** together, in one commit. The coordinator captures findings at defined checkpoints during implementation (docket-implement-next's Step 6.5 is normative), not in a single final pass. Follow-ups recorded here hold out-of-scope work for human triage — the run checks proposed and deferred changes and names any match, but never mints a change, issue, ADR, or learning automatically. +**Results artifact shape and lifecycle.** The results file is a required close-out artifact for every implemented change. Its template opens with a required `**Human action:**` statement immediately after the title (a settled assessment at finalization) and carries a required `## Outcome` section plus the conditional sections `## Human actions and testing` (items labeled Important or Optional; optional walkthroughs may cover automated behavior), `## Verification performed`, and `## Known issues and follow-ups` — omit any conditional section, subsections and all, when it would hold no substantive content, and never pad one with `None`/`N/A` filler. The results **file** lives on the metadata branch at `/--results.md`; the `change.attach-results` operation writes the file and the `results:` **field** together, in one commit. The coordinator captures findings at defined checkpoints during implementation (docket-implement-next's Step 6.5 is normative), not in a single final pass. Follow-ups recorded here hold out-of-scope work for human triage — the run checks proposed and deferred changes and names any match, but never mints a change, issue, ADR, or learning automatically. ### Change manifest (frontmatter at the top of each change file) @@ -187,7 +187,6 @@ adrs: [24] # ADRs this change cites or produces spec: # superpowers design doc path; set at brainstorm (propose) time, on the metadata branch plan: # plan FILE on the metadata branch; FILE and FIELD written together by change.attach-plan at build time results: # results FILE on the metadata branch; FILE and FIELD written together by change.attach-results at the first checkpoint, required before the implemented transition -trivial: false # true = no spec needed (small mechanical change); still build-ready auto_groomable: # `true` makes a stub auto-groomable; unset or `false` means not hold: # `true` keeps a groomed change out of autonomous build selection; naming it still builds it branch_prefix: # optional one unqualified branch-path component; overrides at mint, consumed only at claim, inert once branch: is populated, survives reclaim @@ -288,13 +287,13 @@ An `Accepted` ADR is immutable except its `status:` line; a non-reversing contex ### Build-readiness & selection (shared definition) -A change is **build-ready** — eligible for `docket-implement-next` — only when it is `proposed`, has a `spec:` **or** `trivial: true`, and all `depends_on` are satisfied (`done`). A `proposed` change with neither a spec nor `trivial: true` is **needs-grooming** (not build-ready). A change carrying `stacked_on:` is additionally build-ready only when the binary resolves its **effective base**; until then its readiness is `stack-base-unresolved` and the board reads *waiting on #A — stack base not built* (*stack parent #A killed — re-parent, un-stack, or kill* when an ancestor was killed). Stacking adds this eligibility condition only — never a ranking one. The implementer's deterministic selection order is `priority` (`critical` > `high` > `medium` > `low`) → age (`created`) → **lowest `id`**. A `created:` that is missing or malformed (not a well-formed `YYYY-MM-DD`) sorts last within its priority band — unknown age never preempts dated work. A held change (`hold: true`) that would be build-ready reads `on-hold`: autonomous selection never picks it, and naming it builds it. +A change is **build-ready** — eligible for `docket-implement-next` — only when it is `proposed`, has a `spec:`, and all `depends_on` are satisfied (`done`). A `proposed` change with no spec is **needs-grooming** (not build-ready). A change carrying `stacked_on:` is additionally build-ready only when the binary resolves its **effective base**; until then its readiness is `stack-base-unresolved` and the board reads *waiting on #A — stack base not built* (*stack parent #A killed — re-parent, un-stack, or kill* when an ancestor was killed). Stacking adds this eligibility condition only — never a ranking one. The implementer's deterministic selection order is `priority` (`critical` > `high` > `medium` > `low`) → age (`created`) → **lowest `id`**. A `created:` that is missing or malformed (not a well-formed `YYYY-MM-DD`) sorts last within its priority band — unknown age never preempts dated work. A held change (`hold: true`) that would be build-ready reads `on-hold`: autonomous selection never picks it, and naming it builds it. ### Autonomous grooming (shared definition) -A change is opted into autonomous grooming only by its own `auto_groomable: true`; unset or `false` means not. The field is human input with one exception: `docket-auto-groom`'s abstain is the single agent write (`change.groom` `outcome: abstain` sets it to `false`). Likewise `hold` is human input except the auto-groomer's `hold: true` on a spec or trivial verdict that needs a person's step. +A change is opted into autonomous grooming only by its own `auto_groomable: true`; unset or `false` means not. The field is human input with one exception: `docket-auto-groom`'s abstain is the single agent write (`change.groom` `outcome: abstain` sets it to `false`). Likewise `hold` is human input except the auto-groomer's `hold: true` on a spec that needs a person's step. -A stub is **auto-groomable** — selectable by `docket-auto-groom` — when it is needs-grooming (`proposed`, no `spec:`, not `trivial: true`) AND it carries `auto_groomable: true`. Unsatisfied `depends_on` does NOT exclude it (the same design-ahead rule as interactive grooming; the implementer's reconcile re-validates at build time). Ranking is the same deterministic selection order as build-ready selection. +A stub is **auto-groomable** — selectable by `docket-auto-groom` — when it is needs-grooming (`proposed`, no `spec:`) AND it carries `auto_groomable: true`. Unsatisfied `depends_on` does NOT exclude it (the same design-ahead rule as interactive grooming; the implementer's reconcile re-validates at build time). Ranking is the same deterministic selection order as build-ready selection. **Abstain rule.** When autonomous grooming cannot safely default a decision, it emits NO spec; it applies `change.groom` with `outcome: abstain`, which flips `auto_groomable: false`, appends a dated entry to the `## Auto-groom blocked` body section, and re-renders the board in one commit. The stub stays needs-grooming — out of the autonomous queue, still in the interactive one. Re-enable = a human supplies the missing context and applies `change.groom` with `outcome: re-enable` (optionally with owned-section edits carrying that context): it sets the flag back to `true` and removes the `## Auto-groom blocked` section in the same commit — never a hand edit (git history keeps the section; its presence drives the board's needs-you cell, so a stale one would mislabel a re-enabled stub). Kill and defer are never autonomous: they surface inside the blocked section as recommendations. diff --git a/internal/assets/embedded/tree/skills/docket-groom-next/SKILL.md b/internal/assets/embedded/tree/skills/docket-groom-next/SKILL.md index 9c4bf1022..e62af2310 100644 --- a/internal/assets/embedded/tree/skills/docket-groom-next/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-groom-next/SKILL.md @@ -1,6 +1,6 @@ --- name: docket-groom-next -description: Use when stubs are sitting at needs-grooming on the docket board and you want the next one designed — selecting the next needs-grooming change (proposed, no spec, not trivial) deterministically and grooming it to build-ready through an interactive brainstorm with the human, exiting with a linked spec, a trivial verdict, a kill, a defer, or a re-enable — or revising a proposed change by explicit id (an already-groomed one, or a stub to edit rather than groom). Selection is autonomous; the design conversation is not. Writes markdown only — never branches, worktrees, or code. +description: Use when stubs are sitting at needs-grooming on the docket board and you want the next one designed — selecting the next needs-grooming change (proposed, no spec) deterministically and grooming it to build-ready through an interactive brainstorm with the human, exiting with a linked spec, a kill, a defer, or a re-enable — or revising a proposed change by explicit id (an already-groomed one, or a stub to edit rather than groom). Selection is autonomous; the design conversation is not. Writes markdown only — never branches, worktrees, or code. --- # docket-groom-next — the groomer (interactive) @@ -13,7 +13,7 @@ description: Use when stubs are sitting at needs-grooming on the docket board an - Stubs show as needs-grooming on the board and you want to design the next one, or a specific one (pass its id explicitly to skip selection). - Do NOT use to capture a brand-new idea — that is `docket-new-change`'s job; this skill never mints ids. -- An explicit id naming an already-groomed `proposed` change (has `spec:` or `trivial: true`) is NOT an error — it routes to the revise flow (Step 4, exit 5): adjust the existing spec and owned sections through `change.groom` with `outcome: revise`. An explicit id with a request to *edit* (not groom) a needs-grooming stub routes there too. Drift against current reality at build time remains the reconcile pass's job in `docket-implement-next`. +- An explicit id naming an already-groomed `proposed` change (has `spec:`) is NOT an error — it routes to the revise flow (Step 4, exit 4): adjust the existing spec and owned sections through `change.groom` with `outcome: revise`. An explicit id with a request to *edit* (not groom) a needs-grooming stub routes there too. Drift against current reality at build time remains the reconcile pass's job in `docket-implement-next`. ## Convention (load first — blocking) @@ -23,7 +23,7 @@ Invoke the `docket-convention` skill via the Skill tool first — unless already ### Step 1 — Select -Sync the metadata working tree (the startup-check `repository.prepare` operation), then rank every needs-grooming change in `active/` — `status: proposed`, no `spec:`, not `trivial: true` — by the convention's deterministic selection order (the same ranking `docket-implement-next` uses). Pick the top, or accept an explicit id from the caller. An explicit id naming an already-groomed `proposed` change (has `spec:` or `trivial: true`) routes to the **revise** flow — recap what is there today (the linked spec's body, or the trivial rationale, and the owned sections), run the resolved brainstorm skill seeded with the current design framed as "what would you like to adjust," and exit via Step 4's revise exit. When the human asks to *edit* a needs-grooming stub rather than groom it, skip the brainstorm and apply Step 4's revise exit directly with the requested owned-section, `title`, `priority`, or relationship edits — the stub stays needs-grooming. Any other explicit id that is not needs-grooming is an error to report, never a silent re-pick. Empty queue → report that nothing needs grooming and stop. Read the selected stub's exact **record path** and opaque **record revision** (the blob object id) from the `status` operation (with `--json`) — the Step-4 groom/defer transactions pin the record with those, and re-reading them after a mid-run re-sync is a fresh `status` read. +Sync the metadata working tree (the startup-check `repository.prepare` operation), then rank every needs-grooming change in `active/` — `status: proposed`, no `spec:` — by the convention's deterministic selection order (the same ranking `docket-implement-next` uses). Pick the top, or accept an explicit id from the caller. An explicit id naming an already-groomed `proposed` change (has `spec:`) routes to the **revise** flow — recap what is there today (the linked spec's body and the owned sections), run the resolved brainstorm skill seeded with the current design framed as "what would you like to adjust," and exit via Step 4's revise exit. When the human asks to *edit* a needs-grooming stub rather than groom it, skip the brainstorm and apply Step 4's revise exit directly with the requested owned-section, `title`, `priority`, or relationship edits — the stub stays needs-grooming. Any other explicit id that is not needs-grooming is an error to report, never a silent re-pick. Empty queue → report that nothing needs grooming and stop. Read the selected stub's exact **record path** and opaque **record revision** (the blob object id) from the `status` operation (with `--json`) — the Step-4 groom/defer transactions pin the record with those, and re-reading them after a mid-run re-sync is a fresh `status` read. When autonomous grooming is in play (see the convention's *Autonomous grooming* shared definition), rank in **selection bands** — the human's attention goes first to stubs that need a human: (1) abstained stubs (a `## Auto-groom blocked` section is present), then (2) `auto_groomable` unset or `false` stubs, then (3) `auto_groomable: true` stubs, each flagged "#NNNN is auto-groomable — docket-auto-groom will handle it unless you want it now." Within each band, the deterministic order applies unchanged. Every needs-grooming stub stays selectable — bands reorder, they never exclude; an explicit id still overrides everything. @@ -46,32 +46,31 @@ Open with a **recap of the selected stub**, written for a reader with no prior c When the design settles on building this stub atop another change's **unmerged** branch, set `stacked_on: ` at the spec exit and **read [`../docket-convention/references/stacked-changes.md`](../docket-convention/references/stacked-changes.md) now (blocking)** first — stacking changes how the change is built, merged, and closed out. -The recap is an introduction, not a confirmation gate — flow straight into the brainstorm, where the human redirects. Then invoke `superpowers:brainstorming` WITH THE HUMAN, seeded with the stub's body and its `## Open questions` — the open questions are the session's starting agenda. When `superpowers:brainstorming` cannot be invoked, run the brainstorm inline with the human, warning prominently — the artifact is unchanged: a spec, then stop. If the human asks for a consultant-written spec, invoke `docket-brainstorm` for this run instead — human steering of an interactive session always wins (see the README's consultant-brainstorm section). STOP AT THE SPEC — do NOT continue to `superpowers:writing-plans` (planning is build-time, owned by `docket-implement-next`). +The recap is an introduction, not a confirmation gate — flow straight into the brainstorm, where the human redirects. Then invoke `superpowers:brainstorming` WITH THE HUMAN, seeded with the stub's body and its `## Open questions` — the open questions are the session's starting agenda. Tell it the artifact is always a written spec, sized to the change: a small change gets a short spec, and it never concludes that a change needs no written design. When `superpowers:brainstorming` cannot be invoked, run the brainstorm inline with the human, warning prominently — the artifact is unchanged: a spec, then stop. If the human asks for a consultant-written spec, invoke `docket-brainstorm` for this run instead — human steering of an interactive session always wins (see the README's consultant-brainstorm section). STOP AT THE SPEC — do NOT continue to `superpowers:writing-plans` (planning is build-time, owned by `docket-implement-next`). -### Step 4 — Exit (one of six; the human confirms which) +### Step 4 — Exit (one of five; the human confirms which) -All six exits reuse existing transitions — this skill introduces no new lifecycle status: +All five exits reuse existing transitions — this skill introduces no new lifecycle status: 1. **Spec** (the normal exit): **author** the settled design as the spec's Markdown body, and any owned proposal-section rewrites (proposal altitude, resolved `## Open questions` removed). Apply it with one atomic transaction — the `change.groom` operation with `--repo-dir --request ` — carrying the change id, the pinned record `path` + `revision` from Step 1, `outcome: spec`, the `spec_markdown`, the owned-section edits, and the desired `depends_on`/`related`/`adrs`/`discovered_from`/`stacked_on` (authored Markdown travels in the request file, never a shell-escaped flag). In a private repository the spec ships with the PR, so its body follows the private-repository writing rule: no `Change #N, groomed …` line, no change or ADR numbers, no backlog references. In one metadata commit it writes the spec file, sets `spec:` + `updated:`, stamps the spec's `docket:backlink` block, and re-renders the `## Artifacts` block and inline board — so there is no separate render, back-link, or Board pass. A typed refusal (not-groomable, spec-path-taken, malformed markers, revision mismatch) writes nothing — surface it. The change is now build-ready. -2. **Trivial verdict**: the brainstorm concludes there is no real design question — 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 as the trivial rationale. The transaction sets `trivial: true` + `updated:`, re-renders the `## Artifacts` block, and re-renders the inline board atomically — no spec file, no separate Board pass. Also build-ready. -3. **Kill**: the stub is obsolete, a duplicate, or decided against — follow the proposed-kill sub-path in `docket-new-change` (it owns the kill mechanics; do not restate them here). -4. **Defer**: right idea, wrong time — apply the `change.defer` operation with `--repo-dir --request ` with the pinned `path` + `revision` and the authored `why_deferred` section body. The transaction sets `status: deferred`, splices the `## Why deferred` section, sets `updated:`, and re-renders the inline board atomically. -5. **Revise** (explicit-id route only): the human wants a `proposed` change adjusted without changing its groom state — apply the `change.groom` operation with `--repo-dir --request ` with `outcome: revise`, the pinned `path` + `revision`, and whichever of `spec_markdown` (a whole-body replace of the *existing* linked spec, minus its `docket:backlink` block, which the transaction re-stamps; it never mints a new path) and owned-section `sections` edits the adjustment touched, plus any relationship-field updates. With `spec_markdown`, also send `spec_revision`, the linked spec's blob object id read by `git -C rev-parse HEAD:` (`` is the record's `spec:` value) — a concurrent spec edit then contends instead of being overwritten. It never sets `spec:`, `trivial:`, or `auto_groomable:`. Repeatable while the change stays `proposed`. A typed refusal (`not-revisable`, `spec-not-linked` — also the answer to `spec_markdown` on a needs-grooming stub, which has no spec — `spec-file-missing`, `empty-revise`, `empty-spec_revision`, `invalid-section-heading` for an edit naming `## Auto-groom blocked`, revision mismatch) writes nothing — surface it. The change keeps its groom state. -6. **Re-enable** (abstained or opted-out stubs): the human supplied the context an abstain asked for and wants `docket-auto-groom` to take the stub — apply the `change.groom` operation with `--repo-dir --request ` with `outcome: re-enable`, the pinned `path` + `revision`, and any owned-section `sections` edits carrying the new context. The transaction sets `auto_groomable: true`, removes the `## Auto-groom blocked` section, and re-renders the inline board atomically, returning the stub to the autonomous queue. A `nothing-to-re-enable` refusal (no blocked section, already `true`) writes nothing. A spec or trivial groom of an abstained stub needs no re-enable. +2. **Kill**: the stub is obsolete, a duplicate, or decided against — follow the proposed-kill sub-path in `docket-new-change` (it owns the kill mechanics; do not restate them here). +3. **Defer**: right idea, wrong time — apply the `change.defer` operation with `--repo-dir --request ` with the pinned `path` + `revision` and the authored `why_deferred` section body. The transaction sets `status: deferred`, splices the `## Why deferred` section, sets `updated:`, and re-renders the inline board atomically. +4. **Revise** (explicit-id route only): the human wants a `proposed` change adjusted without changing its groom state — apply the `change.groom` operation with `--repo-dir --request ` with `outcome: revise`, the pinned `path` + `revision`, and whichever of `spec_markdown` (a whole-body replace of the *existing* linked spec, minus its `docket:backlink` block, which the transaction re-stamps; it never mints a new path) and owned-section `sections` edits the adjustment touched, plus any relationship-field updates. With `spec_markdown`, also send `spec_revision`, the linked spec's blob object id read by `git -C rev-parse HEAD:` (`` is the record's `spec:` value) — a concurrent spec edit then contends instead of being overwritten. It never sets `spec:` or `auto_groomable:`. Repeatable while the change stays `proposed`. A typed refusal (`not-revisable`, `spec-not-linked` — also the answer to `spec_markdown` on a needs-grooming stub, which has no spec — `spec-file-missing`, `empty-revise`, `empty-spec_revision`, `invalid-section-heading` for an edit naming `## Auto-groom blocked`, revision mismatch) writes nothing — surface it. The change keeps its groom state. +5. **Re-enable** (abstained or opted-out stubs): the human supplied the context an abstain asked for and wants `docket-auto-groom` to take the stub — apply the `change.groom` operation with `--repo-dir --request ` with `outcome: re-enable`, the pinned `path` + `revision`, and any owned-section `sections` edits carrying the new context. The transaction sets `auto_groomable: true`, removes the `## Auto-groom blocked` section, and re-renders the inline board atomically, returning the stub to the autonomous queue. A `nothing-to-re-enable` refusal (no blocked section, already `true`) writes nothing. A spec groom of an abstained stub needs no re-enable. -**Retitle.** When the settled design renamed the change, exits 1 (spec), 2 (trivial), 5 (revise), and 6 (re-enable) also carry `title` in the same `change.groom` request. The transaction rewrites `title:` through the writer, re-renders the board and the `## Artifacts` block, and re-stamps the linked spec's `docket:backlink` line; a `title` alone is a valid revise. The slug, record filename, spec path, and branch never change — a retitle renames nothing. A typed refusal (`invalid-title`, `empty-title`, `not-retitleable`, `spec-backlink-missing`, `spec-backlink-malformed`) writes nothing — surface it. +**Retitle.** When the settled design renamed the change, exits 1 (spec), 4 (revise), and 5 (re-enable) also carry `title` in the same `change.groom` request. The transaction rewrites `title:` through the writer, re-renders the board and the `## Artifacts` block, and re-stamps the linked spec's `docket:backlink` line; a `title` alone is a valid revise. The slug, record filename, spec path, and branch never change — a retitle renames nothing. A typed refusal (`invalid-title`, `empty-title`, `not-retitleable`, `spec-backlink-missing`, `spec-backlink-malformed`) writes nothing — surface it. -**Reprioritize.** The same four exits may also carry `priority` (`critical`, `high`, `medium`, or `low`) in the same `change.groom` request; the transaction rewrites `priority:` and re-renders the board and the `## Artifacts` block, and a `priority` alone is a valid revise. Abstain refuses it (`invalid-priority`) and an unknown value refuses with `unknown-priority`; either writes nothing — surface it. A deferred change is revived before it can be re-prioritized. +**Reprioritize.** The same three exits may also carry `priority` (`critical`, `high`, `medium`, or `low`) in the same `change.groom` request; the transaction rewrites `priority:` and re-renders the board and the `## Artifacts` block, and a `priority` alone is a valid revise. Abstain refuses it (`invalid-priority`) and an unknown value refuses with `unknown-priority`; either writes nothing — surface it. A deferred change is revived before it can be re-prioritized. -**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. +**Deliverable, type, and branch prefix.** The same three 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. +**Hold.** When the settled design needs a step a person must carry out, suggest a hold before the spec exit; the person decides. The same three 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. +**Stacking.** The same three 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) -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. +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:`). 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 e8fef5d33..068061db5 100644 --- a/internal/assets/embedded/tree/skills/docket-implement-next/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-implement-next/SKILL.md @@ -54,7 +54,7 @@ A claim of a `proposed` record that still carries a `## Run halted` section remo ### Step 3 — Reconcile ⭐ -Re-read the step-1 bundle's change + spec bytes against `related` + recently-archived changes, cited + recent ADRs, and CURRENT code, and decide NON-INTERACTIVELY what is true NOW (drop work done elsewhere, adjust scope, fold in new constraints). That judgment is yours; the write is a transaction. **Author** a reconcile request — structured replacement text for the owned proposal sections and still-mutable linked-spec content, the complete desired relations (`depends_on`/`stacked_on`/`related`/`adrs`/`discovered_from`) when reality requires them, and one dated `## Reconcile log` entry — and apply it with the `change.reconcile` operation with `--input ` (the request file carries `id`, the pinned `revision`, and the authored Markdown — never a shell-escaped flag). The transaction checks the exact revision and legal `in-progress` status, sets `reconciled: true`, refreshes the claim, rerenders backlinks/`## Artifacts` block/inline board, validates the whole repository, and commits atomically on the metadata branch, pushed to the metadata remote; unknown frontmatter, unlisted authored sections, line endings, and unrelated files stay byte-identical, and a request naming a non-owned field/section is a typed refusal that writes nothing. A trivial change has no spec — patch the body only. If fresh origin state diverges incompatibly, the operation returns `contended` and writes nothing — never a text-merge; re-read fresh context and re-author. +Re-read the step-1 bundle's change + spec bytes against `related` + recently-archived changes, cited + recent ADRs, and CURRENT code, and decide NON-INTERACTIVELY what is true NOW (drop work done elsewhere, adjust scope, fold in new constraints). That judgment is yours; the write is a transaction. **Author** a reconcile request — structured replacement text for the owned proposal sections and still-mutable linked-spec content, the complete desired relations (`depends_on`/`stacked_on`/`related`/`adrs`/`discovered_from`) when reality requires them, and one dated `## Reconcile log` entry — and apply it with the `change.reconcile` operation with `--input ` (the request file carries `id`, the pinned `revision`, and the authored Markdown — never a shell-escaped flag). The transaction checks the exact revision and legal `in-progress` status, sets `reconciled: true`, refreshes the claim, rerenders backlinks/`## Artifacts` block/inline board, validates the whole repository, and commits atomically on the metadata branch, pushed to the metadata remote; unknown frontmatter, unlisted authored sections, line endings, and unrelated files stay byte-identical, and a request naming a non-owned field/section is a typed refusal that writes nothing. If fresh origin state diverges incompatibly, the operation returns `contended` and writes nothing — never a text-merge; re-read fresh context and re-author. Adjacent follow-up work this pass surfaces is **noted for the final report** — nothing is minted automatically; a human captures reported work deliberately with `docket change create`, guided by the backlog verdict final consolidation attaches (Step 6.5 *Backlog match*). @@ -77,7 +77,7 @@ The `workspace.prepare` operation reloads the authoritative snapshot, resolves t the metadata branch only receives bookkeeping commits — it NEVER determines where code branches start; the feature branch is cut from the resolved effective base (`origin/` in the ordinary case). -**Preparation (parent).** The reconciled **spec is read from the metadata working tree** (**re-sync the metadata worktree immediately before reading it**). Then run the `workspace.commit-spec` operation with `--id `: it commits the spec copy as the branch's first commit (a trivial change reports `no-spec`); a `spec-path-occupied` or `workspace-not-ready` refusal halts. Confirm the worktree is clean and record its HEAD as the **pre-dispatch HEAD**. Resolve nothing new: learnings enablement and every repo path come from the startup-check prepared context. Immediately before the long plan dispatch, **refresh the claim** — the `change.refresh-claim` operation with `--id --revision ` re-stamps `claimed_at` (only) and returns the new revision; a refresh `contended` means a newer record owns the change, so it **stops a NEW dispatch** but **never cancels** a child already running whose outcome must still be inspected. +**Preparation (parent).** The reconciled **spec is read from the metadata working tree** (**re-sync the metadata worktree immediately before reading it**). Then run the `workspace.commit-spec` operation with `--id `: it commits the spec copy as the branch's first commit; a `spec-path-occupied` or `workspace-not-ready` refusal halts. Confirm the worktree is clean and record its HEAD as the **pre-dispatch HEAD**. Resolve nothing new: learnings enablement and every repo path come from the startup-check prepared context. Immediately before the long plan dispatch, **refresh the claim** — the `change.refresh-claim` operation with `--id --revision ` re-stamps `claimed_at` (only) and returns the new revision; a refresh `contended` means a newer record owns the change, so it **stops a NEW dispatch** but **never cancels** a child already running whose outcome must still be inspected. **Plan authoring (dispatched).** The parent stays the orchestrator. @@ -113,7 +113,7 @@ It also contains the branch and base ref, change title and scope, relevant learn ### Step 6.5 — Results (required) -The results artifact is **required for every change, trivial included** — there is no skip and no close-out condition to weigh. Author `/--results.md` from `results-template.md` in a scratch file outside both worktrees; it is written on the metadata branch, never the feature branch. The path is chosen **once per change and reused on every resume** even when the authoring date has since changed (a changed date never mints a second file). Immediately after the H1 title, a **`**Human action:**` statement** says whether human action is needed — during implementation it may say the assessment is pending, but final results give a settled assessment consistent with the rest of the artifact, and the implemented boundary refuses a missing or empty statement. `## Outcome` is required; every other section is **conditional** — omit an empty heading and its subsections rather than filling it, and never write a `None`/`N/A`/`not applicable` body (whole-section filler refuses at the implemented boundary). The `docket:backlink` block above the title is owned by the `change.attach-results` operation — never hand-author its markers. +The results artifact is **required for every implemented change** — there is no skip and no close-out condition to weigh. Author `/--results.md` from `results-template.md` in a scratch file outside both worktrees; it is written on the metadata branch, never the feature branch. The path is chosen **once per change and reused on every resume** even when the authoring date has since changed (a changed date never mints a second file). Immediately after the H1 title, a **`**Human action:**` statement** says whether human action is needed — during implementation it may say the assessment is pending, but final results give a settled assessment consistent with the rest of the artifact, and the implemented boundary refuses a missing or empty statement. `## Outcome` is required; every other section is **conditional** — omit an empty heading and its subsections rather than filling it, and never write a `None`/`N/A`/`not applicable` body (whole-section filler refuses at the implemented boundary). The `docket:backlink` block above the title is owned by the `change.attach-results` operation — never hand-author its markers. **Human actions and testing** labels every item **Important** or **Optional**, written for a mid-level engineer with little knowledge of Docket internals. An **Important** item marks a meaningful verification gap or necessary human judgment (never a new automated merge requirement) — give the reason, when the action matters, and what remains uncertain if skipped. An Optional walkthrough MAY exercise behavior automated tests already cover — a routine suite rerun is not a functional walkthrough. Every item carries prerequisites and setup, concrete steps with observable expected results, and cleanup when it changes persistent state — complete enough to run without reconstructing missing commands. Do not infer coverage from a green suite: inspect the relevant tests and evidence, and where coverage is genuinely uncertain report that uncertainty under Known issues and follow-ups or Verification performed rather than authoring a speculative checklist. The section holds only what a human should do or check — never a record of what the run already checked, which belongs under Verification performed. @@ -146,7 +146,7 @@ The results artifact is **required for every change, trivial included** — ther **Leak check (private repositories).** `workspace.publish` and `pr.publish` refuse `leak-detected` (`blocked`) when anything they would expose carries a docket fingerprint; the result's `leaks` list names each hit (source, commit, file, line, rule, matched text). Nothing was pushed or opened. End the run `halted`: write the hit list into the `change.halt` report — never reword, amend, rebase, or force-push to get past it, and never retry. `leak-check-unverified` (`external-failed`) means the check could not run; treat it as any external failure. `metadata-on-shared-remote` warnings go in the run report only. -**Mark implemented.** The `change.mark-implemented` operation with `--id --revision --head --pr --evidence ` is the final mutation in this scope. Before its transaction it reprobes Git and GitHub and proves: the change is still the exact `in-progress` revision, `reconciled: true`, linked to the verified plan; local and remote feature heads equal the supplied head; valid evidence names that head and a passed gate; exactly one verified PR for the feature branch targets the resolved effective-base branch and names that head; and a results artifact is attached, read from the metadata branch, and satisfies the final content contract and its artifact identity (missing, invalid, or unattached results — trivial changes included — refuse the transition). It then applies the landed transition atomically — `status: implemented` + `pr:` + updated date + the verified evidence as the record's `## Build evidence` section + `## Artifacts` block + inline board + audit receipt (letting the sweep read `pr:`), rendering the board inside that transaction, so no separate Board pass runs. It does NOT clear the claim, delete the branch/workspace, merge, archive, or close descendants. A retry against an already-`implemented` change with matching PR/head returns the prior applied outcome, never a duplicate transition. +**Mark implemented.** The `change.mark-implemented` operation with `--id --revision --head --pr --evidence ` is the final mutation in this scope. Before its transaction it reprobes Git and GitHub and proves: the change is still the exact `in-progress` revision, `reconciled: true`, linked to the verified plan; local and remote feature heads equal the supplied head; valid evidence names that head and a passed gate; exactly one verified PR for the feature branch targets the resolved effective-base branch and names that head; and a results artifact is attached, read from the metadata branch, and satisfies the final content contract and its artifact identity (missing, invalid, or unattached results refuse the transition). It then applies the landed transition atomically — `status: implemented` + `pr:` + updated date + the verified evidence as the record's `## Build evidence` section + `## Artifacts` block + inline board + audit receipt (letting the sweep read `pr:`), rendering the board inside that transaction, so no separate Board pass runs. It does NOT clear the claim, delete the branch/workspace, merge, archive, or close descendants. A retry against an already-`implemented` change with matching PR/head returns the prior applied outcome, never a duplicate transition. **Verify the run.** The `run.verify` operation with `--id ` is read-only: it reports one closed verdict — `run-complete` / `run-unclaimed` / `run-incomplete` / `run-halted` / `run-waiting` — and enumerates every unmet condition with its stable reason and observed identity. Automation keys on the typed verdict, **never** the exit code (all verdicts exit 0). `run-complete` is the receipt that Step 7's postcondition (or the results-artifact ending's) holds; `run-halted` is the closed verdict for a change carrying a `## Run halted` marker — a human is needed, and an attributed caller re-dispatches it through the resume path (the `change.resume-halted` operation with `--acknowledge-quiescent`, Step 2), never a fresh claim. `run-waiting ` is the closed verdict for a change whose gate stopped at a safe, resumable continuation — neither complete nor failed: an attributed caller resumes that exact handoff rather than drawing another change or re-dispatching a fresh run, and precedence is completed-run postconditions first, then a valid `run-waiting`, then ordinary `run-incomplete`; a persisted `run-halted` stays terminal. A run **dispatched with an explicit change id, continuation id, and run key resumes, not restarts**: its FIRST act is the `run.continue` operation with ` `, claiming the recovered drive **before any other work**; it never launches a replacement test, and this is a **continuation, not `run-retry-once`** — the key stays active until a true terminal disposition. Each `run-retry-once` authorizes exactly one next dispatch; the run tracker may grant another on a later eligible attempt while the configured `run.max_attempts` budget allows, and a continuation consumes none of that budget. A gated parent's prompt may also carry a **run context** token; pass it, always as `--run-context`, into every build-owned `gate.drive.start` (`--owner build` — Step 6's evidence re-mint and re-gates, the build role's final suite gate, and each post-repair attempt the build role starts) this run performs — each invoked with `--json` per the shared capture requirement and each always carrying `--change-id ` — and into the Step-2 claim, omitting it only when the prompt carried none (a `run-untracked` or ungated run). Build-task workers never receive it: they run their tests directly and call no gate operation. @@ -160,7 +160,7 @@ Each step below is complete only when its row holds — read from **git**, never |---|---| | 2 Claim | `status: in-progress` + `branch:` + `updated:` + `claimed_at:` committed on the metadata branch **and landed** (local tip == remote tip). | | 3 Reconcile | `reconciled: true` and a dated `## Reconcile log` entry landed on the metadata branch — or, on the kill path, the change archived. | -| 4 Worktree + plan | Step 3's push SHA-confirmed **before** the branch is cut; then the spec copy committed as the first commit on `/` (non-trivial changes), then `plan:` and the plan file with its backlink landed on the metadata branch, the feature HEAD unchanged by planning. | +| 4 Worktree + plan | Step 3's push SHA-confirmed **before** the branch is cut; then the spec copy committed as the first commit on `/`, then `plan:` and the plan file with its backlink landed on the metadata branch, the feature HEAD unchanged by planning. | | 5 Build | the executed plan committed on `/`, with a build-evidence record at `result: green` (or `skipped` / `build-gate-off` under `build.gate: off`) whose `head_sha` **equals branch HEAD**. | | 6 Review + ADRs | that record still present at `head_sha` == HEAD **after** any fix commits, and every ADR the run produced landed in `adrs:`. Known-weak row: on a clean review this reduces to Step 5's, because whether a reviewer ran is not a fact about git. | | 7 PR + stop | the branch pushed (`origin//` resolves), the PR open, and `status: implemented` + `pr:` landed on the metadata branch; `results:` set and the final results file with its backlink on the metadata branch, and the record's `## Build evidence` section naming the PR head. | @@ -201,7 +201,7 @@ A change is drafted against a *snapshot* of the codebase, ADRs, and other in-fli `reconciled: false` at birth; set to `true` only after the reconcile pass completes and commits. It is **(1) an audit signal** — paired with the dated `## Reconcile log` entry, it proves the change was freshened against current reality; **(2) a resume-safety guard** — on any resume of an `in-progress` change, **read `references/edge-paths.md` now (blocking)** for the resume rules. -`reconciled` is **NOT a selection criterion** — build-readiness is `spec:`-or-`trivial: true` plus satisfied `depends_on`; a change sitting at `reconciled: false` is still build-ready, and reconcile happens in step 3, after selection and claim. +`reconciled` is **NOT a selection criterion** — build-readiness is `spec:` plus satisfied `depends_on`; a change sitting at `reconciled: false` is still build-ready, and reconcile happens in step 3, after selection and claim. ## Branch & metadata discipline diff --git a/internal/assets/embedded/tree/skills/docket-implement-next/references/results-artifact.md b/internal/assets/embedded/tree/skills/docket-implement-next/references/results-artifact.md index e7c316b10..0ff999f80 100644 --- a/internal/assets/embedded/tree/skills/docket-implement-next/references/results-artifact.md +++ b/internal/assets/embedded/tree/skills/docket-implement-next/references/results-artifact.md @@ -11,7 +11,7 @@ skill. No plan, no build, no PR. Skip `workspace.commit-spec` — the branch must keep no commits of its own, or cleanup keeps it — plus the plan-writer dispatch, the build role, the build gate, evidence records, the branch diff review, `workspace.publish`, `pr.publish`, and `change.mark-implemented` -(it refuses a `results-artifact` change). The spec, or a trivial change's body, is the plan. +(it refuses a `results-artifact` change). The spec is the plan. **Refresh the claim** (the `change.refresh-claim` operation, at a revision re-read after a re-sync) at each phase boundary below, as the `pr` path does: before the work, before review, and before @@ -52,7 +52,7 @@ so everything it reads travels inline. Dispatch `docket-review-standard` foreground — the default tier when there is no build record — and tell it to review in its results-artifact mode, then stop. Its dispatch payload contains: Feature worktree: -It also contains, inline, the spec body (or the trivial change's body), the results artifact's text, the change title and scope, and the relevant learnings hooks. When the `docket-review` skill is missing, apply the convention's missing-skill rule: review the results inline against the same checks, warning prominently, and dispatch no reviewer. An undispatchable review tier — established only per the convention's *Dispatch-capability resolution* — makes the run **`halt`**. +It also contains, inline, the spec body, the results artifact's text, the change title and scope, and the relevant learnings hooks. When the `docket-review` skill is missing, apply the convention's missing-skill rule: review the results inline against the same checks, warning prominently, and dispatch no reviewer. An undispatchable review tier — established only per the convention's *Dispatch-capability resolution* — makes the run **`halt`**. ## 5. Fix pass diff --git a/internal/assets/embedded/tree/skills/docket-implement-next/results-template.md b/internal/assets/embedded/tree/skills/docket-implement-next/results-template.md index 57069d009..11070f1d1 100644 --- a/internal/assets/embedded/tree/skills/docket-implement-next/results-template.md +++ b/internal/assets/embedded/tree/skills/docket-implement-next/results-template.md @@ -1,5 +1,5 @@ - " edge per depends_on entry // (padded), or a bare " " node when it has none — then every archived @@ -140,8 +135,8 @@ type BoardUnrenderable struct { // BoardSection is one rendered board group — a set of allowed values deliberately // distinct from the lifecycle statuses a change carries (change 0367). A change // is classified into exactly one section; the mapping is not one-to-one with -// status (finalize-blocked implemented changes render Blocked, spec-backed -// build-ready proposals render Groomed). +// status (finalize-blocked implemented changes render Blocked, build-ready +// proposals render Groomed). type BoardSection string const ( @@ -283,13 +278,10 @@ func boardClassify(in BoardInput, c domain.Change) (BoardSection, error) { return BoardSectionBuilt, nil case domain.StatusProposed: // Groomed means build-ready (or held, which is build-ready but for the - // hold) AND spec-backed: a trivial build-ready change with an empty - // spec stays Proposed. - if c.Spec().Value != "" { - switch domain.EvaluateReadiness(in.Snapshot, c, in.Facts).Kind { - case domain.ReadyBuildReady, domain.ReadyOnHold: - return BoardSectionGroomed, nil - } + // hold); readiness already requires a spec. + switch domain.EvaluateReadiness(in.Snapshot, c, in.Facts).Kind { + case domain.ReadyBuildReady, domain.ReadyOnHold: + return BoardSectionGroomed, nil } return BoardSectionProposed, nil case domain.StatusDeferred: @@ -737,18 +729,6 @@ func boardGroomedReadinessCell(in BoardInput, c domain.Change) (string, error) { func boardReadinessCell(in BoardInput, c domain.Change) (string, error) { r := domain.EvaluateReadiness(in.Snapshot, c, in.Facts) switch r.Kind { - case domain.ReadyBuildReady: - // The only build-ready row that reaches Proposed is trivial-without-spec - // (spec-backed build-ready is Groomed); mark it so the reader sees why it - // skipped grooming. - if c.Trivial() { - return "build-ready (trivial)", nil - } - return "build-ready", nil - case domain.ReadyOnHold: - // Only a held trivial-without-spec change reaches Proposed with this - // kind (a held spec-backed change is Groomed). - return "on hold", nil case domain.ReadyNeedsGrooming: return "needs-grooming", nil case domain.ReadyAutoGroomBlocked: @@ -762,7 +742,8 @@ func boardReadinessCell(in BoardInput, c domain.Change) (string, error) { } return fmt.Sprintf("⏳ waiting on #%04d — stack base not built", int(c.StackedOn().Value)), nil default: - // A proposed row never reaches here for a well-formed corpus: readiness + // A proposed row never reaches here for a well-formed corpus: a + // build-ready or on-hold change classifies as Groomed, readiness // reports not-proposed only for a non-proposed change, and invalid only // for a duplicate/negative id or an unusable slug. A corpus carrying such // an unrelated defect is still rendered (change 0449), so this is a diff --git a/internal/render/board_test.go b/internal/render/board_test.go index 5b8bc5def..a2103e1d0 100644 --- a/internal/render/board_test.go +++ b/internal/render/board_test.go @@ -151,8 +151,8 @@ func boardWith(t *testing.T, pres render.BoardPresentation, facts domain.BranchF // TestBoardClassifyEveryBucket pins boardClassify's precedence: exactly one // rendered section per active change, including the two precedence edges -// (finalize-blocked implemented → Blocked over Built; spec-backed build-ready → -// Groomed while trivial-build-ready-without-spec stays Proposed). +// (finalize-blocked implemented → Blocked over Built; build-ready → Groomed +// over Proposed). func TestBoardClassifyEveryBucket(t *testing.T) { blocked := domain.NewChange(domain.ChangeSpec{ ID: 1, Slug: "blk", Title: "Blocked", Status: domain.StatusBlocked, @@ -198,12 +198,6 @@ func TestBoardClassifyEveryBucket(t *testing.T) { stackChildSpec.StackedOn = domain.OptionalInt{State: domain.FieldPresent, Value: 9} stackChild := domain.NewChange(stackChildSpec) - // proposed + trivial, no spec (build-ready) → proposed, because the groomed - // label means build-ready AND spec-backed. - trivialSpec := proposedChange(10, "triv", "Trivial") - trivialSpec.Trivial = true - trivial := domain.NewChange(trivialSpec) - needsGrooming := domain.NewChange(proposedChange(11, "needs", "Needs grooming")) // proposed + spec + held → Groomed (a hold is selection-only, not a demotion). @@ -236,7 +230,6 @@ func TestBoardClassifyEveryBucket(t *testing.T) { {"proposed spec held", held, nil, render.BoardSectionGroomed}, {"proposed spec unmet dependency", waiter, []domain.Change{depTarget}, render.BoardSectionProposed}, {"proposed spec unresolved stack base", stackChild, []domain.Change{parent}, render.BoardSectionProposed}, - {"proposed trivial no spec", trivial, nil, render.BoardSectionProposed}, {"proposed needs-grooming", needsGrooming, nil, render.BoardSectionProposed}, {"proposed auto-groom-blocked", agBlocked, nil, render.BoardSectionProposed}, {"deferred lifecycle", deferred, nil, render.BoardSectionDeferred}, @@ -352,7 +345,7 @@ func TestBoardReadinessNeedsMerge(t *testing.T) { // retained auto-groom-blocked marker reports the human call to action. func TestBoardReadinessAutoGroomBlocked(t *testing.T) { c := proposedChange(7, "blocked-groom", "Blocked groom") - c.HasAutoGroomBlocked = true // no spec, not trivial + c.HasAutoGroomBlocked = true // no spec out := string(boardFrom(t, domain.NewChange(c))) if !strings.Contains(out, "| Blocked groom | `` | `untyped` | auto-groom blocked — needs you |") { t.Fatalf("auto-groom-blocked cell not rendered:\n%s", out) @@ -461,25 +454,6 @@ func TestBoardGroomedReadinessCells(t *testing.T) { assertNoRepairNotice(t, out) } -// TestBoardHeldTrivialStaysProposed: a held trivial change without a spec stays -// in Proposed and states "on hold", never "build-ready (trivial)". -func TestBoardHeldTrivialStaysProposed(t *testing.T) { - spec := proposedChange(22, "held-triv", "Held trivial") - spec.Trivial = true - spec.Hold = heldTrue - out := string(boardFrom(t, domain.NewChange(spec))) - if !strings.Contains(out, "## 🟡 Proposed (1)") { - t.Fatalf("held trivial change must render under Proposed:\n%s", out) - } - if !strings.Contains(out, "| [0022](active/0022-held-triv.md) | Held trivial | `` | `untyped` | on hold |\n") { - t.Fatalf("held trivial cell must read on hold:\n%s", out) - } - if strings.Contains(out, "build-ready (trivial)") { - t.Fatalf("held trivial change must not read build-ready (trivial):\n%s", out) - } - assertNoRepairNotice(t, out) -} - // TestBoardHeldWaitingChangeShowsWaitingCell: a held change with an unmet // dependency keeps its earlier readiness, so the board shows the waiting cell // in Proposed, not "on hold". @@ -602,28 +576,17 @@ func killedStackParent(id int, slug string) domain.Change { } // TestBoardReadinessKilledStackParent pins the plain killed-parent cell for a -// spec'd and a trivial proposal stacked on a killed parent. +// spec'd proposal stacked on a killed parent. func TestBoardReadinessKilledStackParent(t *testing.T) { - for _, tc := range []struct { - name string - trivial bool - }{{"spec", false}, {"trivial", true}} { - t.Run(tc.name, func(t *testing.T) { - child := proposedChange(9, "child", "Child") - if tc.trivial { - child.Trivial = true - } else { - child.Spec = optString("docs/superpowers/specs/child-design.md") - } - child.StackedOn = domain.OptionalInt{State: domain.FieldPresent, Value: 8} - out := string(boardFromFacts(t, domain.BranchFacts{}, killedStackParent(8, "parent"), domain.NewChange(child))) - if !strings.Contains(out, "stack parent #0008 killed — re-parent, un-stack, or kill") { - t.Fatalf("killed-parent cell not rendered:\n%s", out) - } - if strings.Contains(out, "waiting on #0008") { - t.Fatalf("killed parent still rendered as waiting:\n%s", out) - } - }) + child := proposedChange(9, "child", "Child") + child.Spec = optString("docs/superpowers/specs/child-design.md") + child.StackedOn = domain.OptionalInt{State: domain.FieldPresent, Value: 8} + out := string(boardFromFacts(t, domain.BranchFacts{}, killedStackParent(8, "parent"), domain.NewChange(child))) + if !strings.Contains(out, "stack parent #0008 killed — re-parent, un-stack, or kill") { + t.Fatalf("killed-parent cell not rendered:\n%s", out) + } + if strings.Contains(out, "waiting on #0008") { + t.Fatalf("killed parent still rendered as waiting:\n%s", out) } } @@ -1228,21 +1191,6 @@ func TestBoardRepeatRenderByteStable(t *testing.T) { } } -// TestBoardProposedTrivialBuildReadyCell pins that a trivial, spec-less -// build-ready proposal renders "build-ready (trivial)" under Proposed (the only -// build-ready row that reaches Proposed — spec-backed build-ready is Groomed). -func TestBoardProposedTrivialBuildReadyCell(t *testing.T) { - spec := proposedChange(10, "triv", "Trivial") - spec.Trivial = true - out := string(boardFrom(t, domain.NewChange(spec))) - if !strings.Contains(out, "## 🟡 Proposed (1)") { - t.Fatalf("Proposed section missing:\n%s", out) - } - if !strings.Contains(out, "| build-ready (trivial) |") { - t.Fatalf("trivial build-ready cell missing:\n%s", out) - } -} - // permutedPresentation differs from the default on BOTH presentation axes: the // section order is reversed AND every section sorts id/asc instead of the // built-in updated/desc. It is the "the presentation genuinely changed" fixture diff --git a/internal/render/record.go b/internal/render/record.go index 6f374f6b2..c7b2399ce 100644 --- a/internal/render/record.go +++ b/internal/render/record.go @@ -66,7 +66,6 @@ func ChangeRecord(r NewChangeRecord) ([]byte, error) { {Name: "spec", Value: document.Null()}, {Name: "plan", Value: document.Null()}, {Name: "results", Value: document.Null()}, - {Name: "trivial", Value: document.Bool(false)}, {Name: "auto_groomable", Value: optionalBoolValue(r.AutoGroomable)}, {Name: "hold", Value: holdValue(r.Hold)}, {Name: "branch_prefix", Value: optionalStringValue(r.BranchPrefix)}, diff --git a/internal/render/record_test.go b/internal/render/record_test.go index 9a3d59442..409ec2a54 100644 --- a/internal/render/record_test.go +++ b/internal/render/record_test.go @@ -63,6 +63,32 @@ func TestChangeRecordMatchesGolden(t *testing.T) { } } +// TestChangeRecordHasNoTrivialKey proves a new change record writes no +// trivial: frontmatter line. +func TestChangeRecordHasNoTrivialKey(t *testing.T) { + got, err := render.ChangeRecord(render.NewChangeRecord{ + ID: 312, Slug: "add-planning-mutations", Title: "Add planning mutations: board and ADRs", + Type: "feat", Priority: "medium", Created: goldenDate, + Why: "w", WhatChanges: "wc", OutOfScope: "oos", + }) + if err != nil { + t.Fatalf("ChangeRecord: %v", err) + } + lines := strings.Split(string(got), "\n") + if len(lines) == 0 || lines[0] != "---" { + t.Fatalf("record does not open with frontmatter:\n%s", got) + } + for _, line := range lines[1:] { + if line == "---" { + return + } + if strings.HasPrefix(line, "trivial:") { + t.Fatalf("new change record carries %q", line) + } + } + t.Fatalf("frontmatter never closed:\n%s", got) +} + // TestLearningRecordMatchesGolden pins the canonical learning shape. func TestLearningRecordMatchesGolden(t *testing.T) { got, err := render.LearningRecord(render.NewLearningRecord{ diff --git a/internal/render/testdata/board/PROVENANCE.md b/internal/render/testdata/board/PROVENANCE.md index 7b1e255f4..0903daf9e 100644 --- a/internal/render/testdata/board/PROVENANCE.md +++ b/internal/render/testdata/board/PROVENANCE.md @@ -53,7 +53,7 @@ Sections and rows: - **Proposed** — two readiness bands, sorted `updated desc`: - id 4 (updated 2026-08-04) waiting `⏳ waiting on #3 — not yet built` (dep on a non-built change); - - id 3 (updated 2026-08-03) `needs-grooming` (no spec, not trivial). + - id 3 (updated 2026-08-03) `needs-grooming` (no spec). - **Deferred** — id 6. - **Archive `
`** — id 9 (`done`) and id 10 (`killed`); summary emoji + `done + killed` label; Merged date from the archive filename prefix. @@ -71,17 +71,15 @@ directly instead: - the dated `## Run halted — ` variant NOT lighting the State cell (whole-line decode contract — `TestBoardRunHaltedWholeLineContract`); - the Groomed `on hold` Readiness cell for a held spec-backed change - (`TestBoardGroomedReadinessCells`) and the Proposed `on hold` cell for a held - trivial change (`TestBoardHeldTrivialStaysProposed`); + (`TestBoardGroomedReadinessCells`); - the classification precedence edges (finalize-blocked implemented → Blocked; - spec-backed build-ready → Groomed vs trivial-without-spec → Proposed); + spec-backed build-ready → Groomed); - the Blocked `finalize blocked — needs you` Reason cell; - the Built `merged into #NNNN` State cell for a stacked-merged change; - proposed `⏳ … — needs your merge` (dependency on an `implemented` change); - proposed `auto-groom blocked — needs you`; - proposed `⏳ waiting on #NNNN — stack base not built`; - proposed `stack parent #NNNN killed — re-parent, un-stack, or kill`; -- proposed `build-ready (trivial)` (trivial, spec-less build-ready); - non-default section orders and per-section sort keys, same-date id-desc ties, and the unknown-date band; - the empty-priority / `untyped`-type cells; diff --git a/internal/render/testdata/records/change.golden.md b/internal/render/testdata/records/change.golden.md index 53cf6b5f7..1967c10f9 100644 --- a/internal/render/testdata/records/change.golden.md +++ b/internal/render/testdata/records/change.golden.md @@ -16,7 +16,6 @@ adrs: [] spec: plan: results: -trivial: false auto_groomable: hold: branch_prefix: diff --git a/internal/repoguard/budgets_test.go b/internal/repoguard/budgets_test.go index 31288c65f..395c86890 100644 --- a/internal/repoguard/budgets_test.go +++ b/internal/repoguard/budgets_test.go @@ -101,7 +101,7 @@ type skillBudget struct { // // Change 0410 re-baselined the required-results workflow surfaces upward once to // hold the durable-results contract prose (results are now a REQUIRED close-out -// artifact for every implemented change, trivial included; the mandatory Step 6.5 +// artifact for every implemented change; the mandatory Step 6.5 // checkpoint lifecycle; and the build/review capture-ownership boundaries): // docket-build/SKILL.md (390/3907 -> 404/4054), docket-convention/SKILL.md (word // 7807 -> 7969), docket-implement-next/SKILL.md (180/6991 -> 201/7530), @@ -190,7 +190,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", 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-auto-groom/SKILL.md", 65, 1608}, // 0573: trivial retired; exits are spec or abstain (66/1695 -> 65/1608); 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 @@ -199,7 +199,7 @@ var skillBudgets = []skillBudget{ {"docket-build/references/gate-driver.md", 138, 1552}, // 0502 review: the raw-verb section names finalize's repaired-head re-gate (137/1546 -> 138/1552); 0502: "loop" means /loop only (137/1550 -> 137/1546); 0502: finalize's repaired-head re-gate is a direct caller (136/1523 -> 137/1550); 0502: the gate-execution intro reference is deleted (138/1555 -> 136/1523); 0502: renamed from gate-caller-loop.md; 0497: +halted-gate tree-survives finding relay (134/1510 -> 138/1555); 0491: the run id is retired (134/1513 -> 134/1510); 0490: the admission section describes the supervisor-held worktree lock; launch-unconfirmed is no longer a refusal (136/1511 -> 134/1513); 0488 review fix: finalize reaches the driver only through finalize.rebase; task-era handoff clauses dropped (word ceiling 1504 -> 1511); 0488 review: start row carries --change-id (word ceiling 1491 -> 1504); 0488: worker-scope/takeover/acknowledge rows and the parent-takeover section removed; callers are the full-suite gates (175/1872 -> 136/1491); 0467: +prepare-scope --run-id and scope-inherited start run id (word ceiling 1826 -> 1872); 0375: +worktree-admission section (word ceiling 1750 -> 1826) {"docket-build/references/task-routing.md", 50, 500}, {"docket-build-task/SKILL.md", 173, 1695}, // 0532: the private-repository writing rule and visibility hand-off (168/1640 -> 173/1695); 0531: the metadata worktree and remote come from the repository.prepare context (168/1637 -> 168/1640); 0488: scoped drive protocol replaced by direct foreground tests under timeout; three outcomes (211/2235 -> 168/1637); 0467 review fix: +the repair re-run run-id exception (206/2183 -> 211/2235); 0467: +the run id rides on the scope, never the bundle (204/2151 -> 206/2183); 0459: +post-handoff continuation never acknowledges or reuses the transferred scope (188/1964 -> 204/2151); 0405: sequential-drive receipt and acknowledgement; 0420: shell-safe capture; 0375: worktree-busy-not-a-retry rule (179/1842 -> 188/1964) - {"docket-convention/SKILL.md", 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) + {"docket-convention/SKILL.md", 361, 7381}, // 0573: trivial retired (362/7411 -> 361/7381); 0560: the hold manifest field, its selection rule, the ## Why on hold section, and the auto-groomer's hold write (360/7331 -> 362/7411); 0565: a kill refuses on built stacked descendants; the killed-parent board text and exits table (360/7317 -> 360/7331); 0568: deferred is entered only from proposed (363/7317 -> 360/7317); 0559: the manifest lists deliverable; done means a merged PR or a completed results artifact; archive dates and change.complete (361/7276 -> 363/7317); 0533: editing visibility never moves a repository; repository.set-visibility does (361/7263 -> 361/7276); 0532: the private-repository writing rule and visibility hand-off (359/7160 -> 361/7263); 0531 review: skills say "the metadata branch", naming `docket` once for shared mode (359/7155 -> 359/7160); 0531: the metadata worktree and remote come from the repository.prepare context (357/7062 -> 359/7155); 0530: plan, results, and build evidence live on the docket branch — the plan-writer's one metadata operation, the attach operations as file-backlink writers, relative same-branch links, and the new ## Build evidence record section (357/7026 -> 357/7062); 0529 review: the backlink block names its PR-body writers beside artifact.backlink, one shared renderer (357/7004 -> 357/7026); 0515: the repair sign-off is retired; a green repair merges (357/7007 -> 357/7004); 0502 rebase onto 0510: kept the backlog-match follow-up clause in the results-artifact paragraph (357/7004 -> 357/7007); 0502 review: the review-tier dispatch is the controller's own (357/6995 -> 357/7004); 0502: configuration read paths corrected — operations read .docket.yml from origin's default-branch tip, the repository setup operations from the primary worktree (357/6959 -> 357/6995); 0502: "loop" means /loop only (357/7036 -> 357/7037); 0502: one metadata layout — the docket branch and the .docket/ worktree (357/7035 -> 357/7036); 0502: agent layer names user-level wrappers and global-only pins (357/7024 -> 357/7035); 0502: typed operations replace the Bash-era script names; ## Run halted facts corrected (359/7092 -> 357/7024); 0502: terminal publish, the learnings cap, and the repository auto_groom default are deleted (362/7256 -> 359/7092); 0502: the auto-capture export paragraph is deleted (370/7334 -> 362/7256); 0502: the configuration contract rewritten from the schema (371/7488 -> 370/7334); 0502: fixed role skills; halt posture (372/7660 -> 371/7488); 0502: record blocks mirror the renderers (367/7619 -> 372/7660); 0502: the dummy-mode shared definition is deleted (390/7848 -> 367/7619); 0410: +required-results lifecycle prose; 0399: +schema request/result contract prose; 0388: +sync-integration prose (see note above); 0502: drop change citations and Go v1 narration (357/7037 -> 357/6958); 0502: the harness adapter is named without a docket source path (357/6958 -> 357/6959) // 0154: docket-convention/github-board-mirror.md removed — the GitHub mirror is // retired (unsupported, mutation-blocking); its budget row is deleted with it. {"docket-convention/references/agent-layer.md", 214, 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) @@ -208,15 +208,15 @@ var skillBudgets = []skillBudget{ {"docket-convention/references/stacked-changes.md", 227, 2290}, // 0571: a root carries exactly the children merged into it, stacked-merged or implemented; any other child never blocks it (223/2217 -> 227/2290); 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", 242, 6269}, // 0571: the children-retarget-required closeout bullet is deleted; root-archived names who is carried (243/6254 -> 242/6269); 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, 2107}, // 0571: the children-retarget-required closeout halt is deleted (162/2111 -> 162/2107); 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, 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, 8637}, // 0570: the --selection claim sentence and the run-next driver rule (218/8555 -> 218/8637); 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-groom-next/SKILL.md", 77, 2310}, // 0573: trivial retired; the brainstorm is told the artifact is always a spec (78/2377 -> 77/2310); 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, 8612}, // 0573: trivial retired (218/8637 -> 218/8612); 0570: the --selection claim sentence and the run-next driver rule (218/8555 -> 218/8637); 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, 1276}, // 0571: the stack-base refusal names its true reason (109/1265 -> 109/1276); 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, 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) + {"docket-implement-next/references/results-artifact.md", 79, 765}, // 0573: trivial retired (79/775 -> 79/765); 0559: new — the results-artifact ending (no plan, build, or PR; review, complete, clean up) + {"docket-implement-next/results-template.md", 70, 543}, // 0573: trivial retired (70/545 -> 70/543); 0502 rebase onto 0510: carried the backlog verdict and next action in the Known issues placeholder (68/506 -> 70/545); 0502: inline review replaces the custom review skill (68/511 -> 68/510); 0498: +whole-branch review summary line in Verification performed (64/446 -> 68/511); 0440: reader-first template — action statement + merged Known issues (see note above); 0502: drop change citations and Go v1 narration (68/510 -> 68/506) + {"docket-review/SKILL.md", 127, 1054}, // 0573: trivial retired (127/1059 -> 127/1054); 0559: the results-artifact mode (114/966 -> 127/1049); 0559: Inputs and evidence sections defer to results-artifact mode (127/1049 -> 127/1059); 0531: the metadata worktree and remote come from the repository.prepare context (114/965 -> 114/966); 0502: the evidence rule keys on the payload's build.gate value; gate-off skipped records are expected (110/913 -> 114/965); 0410: +findings-return capture contract (see note above) + {"docket-new-change/SKILL.md", 48, 1538}, // 0573: trivial retired; the trivial path is deleted and the brainstorm is told the artifact is always a spec (53/1636 -> 48/1538); 0560: suggest a hold; it rides change.create or change.groom (53/1598 -> 53/1636); 0559: the create request carries deliverable: results-artifact for findings-only work (57/1635 -> 53/1598); 0532: the private-repository writing rule and visibility hand-off (57/1603 -> 57/1635); 0531: the metadata worktree and remote come from the repository.prepare context (57/1596 -> 57/1603); 0502 review: omitted draft-time scalars are described exactly (57/1591 -> 57/1596); 0502: "loop" means /loop only (57/1593 -> 57/1591); 0502: one metadata layout — the docket branch and the .docket/ worktree (57/1590 -> 57/1593); 0502: terminal-publication narration and the repository auto_groom default are deleted (57/1609 -> 57/1590); 0502: invoke superpowers:brainstorming by name (57/1636 -> 57/1609); 0502: the dummy-mode pointer is deleted (59/1674 -> 57/1636); 0445: +pointer to the docket-groom-next revise path after landing (word ceiling 1700 -> 1706); 0382: draft-time scalars moved into change.create (ceiling 1706 -> 1675) + {"docket-status/SKILL.md", 126, 2990}, // 0573: trivial retired (126/2993 -> 126/2990); 0560: a held change shows on hold (126/2983 -> 126/2993); 0539: derived-view drift is named by family and each finding's own remedy is relayed instead of a code list (126/2923 -> 126/2983); 0531: the metadata worktree and remote come from the repository.prepare context (126/2921 -> 126/2923); 0530: artifact-missing names where a plan or results file may live — the docket branch, or the integration branch for a record closed before the move (126/2904 -> 126/2921); 0529 review: full-scope cleanup retries also repoint stale merged-PR description backlinks; repair --pr-backlinks previews them (126/2880 -> 126/2904); 0502: one metadata layout — the docket branch and the .docket/ worktree (126/2876 -> 126/2880); 0502: findings named as the binary emits them (126/2852 -> 126/2876); 0502: deferred learnings and publication narration is deleted (127/2956 -> 126/2852); 0502: the dummy-mode pointer is deleted (129/2985 -> 127/2956); 0388: +sync-integration prose (see note above) } // 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 19d7849cf..fac0ec36e 100644 --- a/internal/repoguard/prose_contracts_test.go +++ b/internal/repoguard/prose_contracts_test.go @@ -286,19 +286,34 @@ var proseContracts = []proseContract{ {sentinel: "change_0410_implement_next_results", file: "skills/docket-implement-next/SKILL.md", present: []string{ "Step 6.5 — Results (required)", - "required for every change, trivial included", + "required for every implemented change", "never commit or move HEAD beneath a live gate, a running worker, or a transferred drive", }, - absent: []string{"Results close-out (optional)"}}, + absent: []string{"Results close-out (optional)", "trivial included"}}, // change 0410 — the convention now describes results as a REQUIRED close-out // artifact in both the directory-map row and the lifecycle paragraph. (The // existing frozen-records row above — sentinel test_results_artifact — is left // untouched and still pins "Closed-out plans and results are frozen build records.") {sentinel: "change_0410_convention_results", file: "skills/docket-convention/SKILL.md", present: []string{ - "required close-out artifacts (one per implemented change, trivial included)", - "required close-out artifact for every implemented change, trivial included.", - }}, + "required close-out artifacts (one per implemented change)", + "required close-out artifact for every implemented change.", + }, + absent: []string{"trivial included"}}, + // change 0573 — build-readiness is a spec plus satisfied dependencies; the + // convention no longer names a trivial flag anywhere. + {sentinel: "change_0573_convention_spec_required", file: "skills/docket-convention/SKILL.md", + present: []string{"has a `spec:`, and all `depends_on` are satisfied"}, + absent: []string{"trivial: true", "trivial:"}}, + // change 0573 — every groom that makes a change build-ready writes a spec: + // the brainstorm is told so. That no trivial exit or verdict survives is + // guarded by shape, not by spelling — TestGroomSkillsNeverSayTrivial. + {sentinel: "change_0573_spec_always", file: "skills/docket-groom-next/SKILL.md", + present: []string{"always a written spec, sized to the change"}}, + {sentinel: "change_0573_spec_always", file: "skills/docket-new-change/SKILL.md", + present: []string{"always a written spec, sized to the change"}}, + {sentinel: "change_0573_auto_groom_spec_or_abstain", file: "skills/docket-auto-groom/SKILL.md", + present: []string{"Exit (one of two)"}}, // change 0410 — docket-build's end-of-build capture ownership: the controller // may checkpoint on the coordinator's behalf, but task workers never write the // results file and a checkpoint never independently launches tests (each an @@ -557,6 +572,47 @@ func TestProseContracts(t *testing.T) { }) } +// trivialWord matches the whole word "trivial" in any case, so every spelling of +// the retired exit ("a trivial verdict", "**Trivial** —", "(spec/trivial") is +// caught without enumerating them; "trivially" is a different word and passes. +var trivialWord = regexp.MustCompile(`(?i)\btrivial\b`) + +// change 0573 — the grooming skills no longer offer a trivial exit, so none of +// them may use the word at all. +var noTrivialGroomSkills = []string{ + "skills/docket-groom-next/SKILL.md", + "skills/docket-new-change/SKILL.md", + "skills/docket-auto-groom/SKILL.md", +} + +func TestGroomSkillsNeverSayTrivial(t *testing.T) { + root := guardRoot(t) + for _, rel := range noTrivialGroomSkills { + b, err := os.ReadFile(filepath.Join(root, filepath.FromSlash(rel))) + if err != nil { + t.Fatalf("read %s: %v (fail closed)", rel, err) + } + for i, line := range strings.Split(string(b), "\n") { + if trivialWord.MatchString(line) { + t.Errorf("%s: line %d uses the retired word \"trivial\": %q", rel, i+1, line) + } + } + } + + t.Run("non_vacuity", func(t *testing.T) { + for _, hit := range []string{"a trivial verdict", "**Trivial** —", "(spec/trivial", "TRIVIAL path"} { + if !trivialWord.MatchString(hit) { + t.Errorf("trivialWord missed %q", hit) + } + } + for _, miss := range []string{"trivially small", "nontrivial"} { + if trivialWord.MatchString(miss) { + t.Errorf("trivialWord flagged %q", miss) + } + } + }) +} + // docSectionContract binds one or more load-bearing clauses to BOTH a named // section heading AND the heading that terminates it, so the assertion is "this // clause is present inside THIS section" — not the weaker "somewhere in the diff --git a/internal/repository/decode.go b/internal/repository/decode.go index a61d0c9b1..fc927ba8d 100644 --- a/internal/repository/decode.go +++ b/internal/repository/decode.go @@ -122,7 +122,6 @@ type changeWire struct { Spec scalar `yaml:"spec"` Plan scalar `yaml:"plan"` Results scalar `yaml:"results"` - Trivial scalar `yaml:"trivial"` AutoGroomable scalar `yaml:"auto_groomable"` Hold scalar `yaml:"hold"` BranchPrefix scalar `yaml:"branch_prefix"` @@ -576,7 +575,6 @@ func decodeChange(in InputDocument) (domain.Change, []domain.Finding) { spec.Spec = d.optionalString("spec", wire.Spec) spec.Plan = d.optionalString("plan", wire.Plan) spec.Results = d.optionalString("results", wire.Results) - spec.Trivial = d.boolean("trivial", wire.Trivial) spec.AutoGroomable = d.optionalBool("auto_groomable", wire.AutoGroomable) spec.Hold = d.optionalBool("hold", wire.Hold) spec.BranchPrefix = d.optionalString("branch_prefix", wire.BranchPrefix) diff --git a/internal/repository/decode_test.go b/internal/repository/decode_test.go index d507e4c6a..c8fd3d308 100644 --- a/internal/repository/decode_test.go +++ b/internal/repository/decode_test.go @@ -136,9 +136,6 @@ func TestDecodeChangeHappyPath(t *testing.T) { if got := change.Results(); got.State != domain.FieldEmpty { t.Errorf("Results = %+v", got) } - if change.Trivial() { - t.Error("Trivial = true, want false") - } if got := change.Branch(); got.State != domain.FieldPresent || got.Value != "feat/domain-snapshot-validation-graphs-and-selection" { t.Errorf("Branch = %+v", got) @@ -788,19 +785,35 @@ func TestDecodeChangeIDMalformed(t *testing.T) { } } -// TestDecodeChangeBooleanMalformed — trivial/reconciled are booleans; a -// non-boolean is a finding, not a silent false. +// TestDecodeChangeBooleanMalformed — reconciled is a boolean; a non-boolean is +// a finding, not a silent false. func TestDecodeChangeBooleanMalformed(t *testing.T) { - const source = "---\nid: 1\nslug: s\ntrivial: maybe\nreconciled: true\n---\n\nbody\n" + const source = "---\nid: 1\nslug: s\nreconciled: maybe\n---\n\nbody\n" change, findings := decodeChange(input(t, KindChange, LocationActive, "docs/changes/active/0001-s.md", source)) - if change.Trivial() { - t.Error("Trivial = true for a malformed value") + if change.Reconciled() { + t.Error("Reconciled = true for a malformed value") } - if !change.Reconciled() { - t.Error("Reconciled = false, want true") + if !hasFinding(findings, CodeFieldMalformed, "reconciled") { + t.Errorf("no field-malformed finding for reconciled: %v", findingCodes(findings)) } - if !hasFinding(findings, CodeFieldMalformed, "trivial") { - t.Errorf("no field-malformed finding for trivial: %v", findingCodes(findings)) +} + +// TestDecodeLegacyTrivialKeyIsInert — a legacy trivial: line is unread data: +// trivial: true with an empty spec: still needs design, and a malformed +// trivial: value produces no finding. +func TestDecodeLegacyTrivialKeyIsInert(t *testing.T) { + const legacy = "---\nid: 1\nslug: s\nstatus: proposed\nspec:\ntrivial: true\n---\n\nbody\n" + change, findings := decodeChange(input(t, KindChange, LocationActive, "docs/changes/active/0001-s.md", legacy)) + if len(findings) != 0 { + t.Fatalf("legacy trivial: true produced findings: %v", findingCodes(findings)) + } + if !domain.NeedsDesign(change) { + t.Errorf("legacy trivial: true with no spec must need design; spec = %+v", change.Spec()) + } + + const malformed = "---\nid: 1\nslug: s\nstatus: proposed\ntrivial: maybe\n---\n\nbody\n" + if _, findings := decodeChange(input(t, KindChange, LocationActive, "docs/changes/active/0001-s.md", malformed)); len(findings) != 0 { + t.Errorf("malformed legacy trivial: produced findings: %v", findingCodes(findings)) } } diff --git a/skills/docket-auto-groom/SKILL.md b/skills/docket-auto-groom/SKILL.md index 7f3ccd763..d8cbaf6aa 100644 --- a/skills/docket-auto-groom/SKILL.md +++ b/skills/docket-auto-groom/SKILL.md @@ -1,6 +1,6 @@ --- name: docket-auto-groom -description: Use when individual stubs opted into autonomous grooming (their `auto_groomable` is `true`) and you want the auto-groomable needs-grooming queue drained with no human — selecting each auto-groomable stub deterministically and designing it via a default-biased self-brainstorm gated by an adversarial critic, exiting each stub with a linked spec, a trivial verdict, or an abstain back to the human queue. Kill and defer are never autonomous. Writes markdown only — never branches, worktrees, or code. +description: Use when individual stubs opted into autonomous grooming (their `auto_groomable` is `true`) and you want the auto-groomable needs-grooming queue drained with no human — selecting each auto-groomable stub deterministically and designing it via a default-biased self-brainstorm gated by an adversarial critic, exiting each stub with a linked spec or an abstain back to the human queue. Kill and defer are never autonomous. Writes markdown only — never branches, worktrees, or code. context: fork agent: docket-auto-groom --- @@ -32,24 +32,23 @@ Sync the metadata working tree (the startup-check `repository.prepare` operation ### Step 2 — Designer pass -Read the stub body, its `related`/`depends_on` neighbours (active + recently archived), the ADR index, and the relevant code. Read the learnings index `/learnings/README.md` and pull any findings whose hook bears on the stub, so the self-brainstorm is informed by past lessons (skipped entirely when `learnings.enabled` is `false`). Enumerate the decision points an interactive brainstorm would raise. For each, weigh 2–3 approaches and COMMIT to the conservative / recommended default — do NOT invoke `superpowers:brainstorming` with a simulated human answerer (a subagent picking "the recommended option" is the model agreeing with itself while faking an approval gate; rejected at design time). Draft the spec in session scratch space — never inside the metadata worktree — as the Markdown body that Step 4 sends as `spec_markdown` in the `change.groom` request file, with an `## Assumptions` block: every decision, the chosen default, the rejected alternatives, and why — the human's deferred audit trail. In a private repository the spec ships with the PR, so its body follows the private-repository writing rule: no `Change #N, groomed …` line, no change or ADR numbers, no backlog references. If the stub is genuinely mechanical (no real design questions), the draft verdict is *trivial* instead of a spec, with the reasoning written for the critic. +Read the stub body, its `related`/`depends_on` neighbours (active + recently archived), the ADR index, and the relevant code. Read the learnings index `/learnings/README.md` and pull any findings whose hook bears on the stub, so the self-brainstorm is informed by past lessons (skipped entirely when `learnings.enabled` is `false`). Enumerate the decision points an interactive brainstorm would raise. For each, weigh 2–3 approaches and COMMIT to the conservative / recommended default — do NOT invoke `superpowers:brainstorming` with a simulated human answerer (a subagent picking "the recommended option" is the model agreeing with itself while faking an approval gate; rejected at design time). Draft the spec in session scratch space — never inside the metadata worktree — as the Markdown body that Step 4 sends as `spec_markdown` in the `change.groom` request file, with an `## Assumptions` block: every decision, the chosen default, the rejected alternatives, and why — the human's deferred audit trail. In a private repository the spec ships with the PR, so its body follows the private-repository writing rule: no `Change #N, groomed …` line, no change or ADR numbers, no backlog references. A mechanical stub gets a short spec with its `## Assumptions` block like any other. ### 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 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. +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 spec. 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. **No-verdict posture (bounded — two steps, then out).** If the dispatch returns no legible verdict — a malformed return, pre-yield prose, or a backgrounded child's bare completion — make **one collect attempt** (read the child's completed final report where the harness surfaces it), and failing that **one fresh foreground re-dispatch** of the critic over the same draft, issued through whatever mechanism makes the parent block on the return — if none does, that leg would only repeat the first, so skip it straight to `abstain`. Still no verdict ⇒ treat it as a failed dispatch attempt under the convention's *Dispatch-capability resolution*: **`abstain`**, so the groom **abstains** for this stub (→ Step 4's **Abstain** exit in full, the `auto_groomable: false` flip included — left armed, the stub stays auto-groomable and the drain re-selects it, forfeiting *Termination & concurrency*), recording the return-channel diagnostic in the `blocked_note`, the human's re-enable cue. Never a third dispatch; never an indefinite wait. Re-dispatching a critic is safe where a build worker is not — it is read-only over prose, holds no worktree, and writes no git state, so `yielded-worker-return-closes-every-door`'s closed-doors analysis does not bind here. -### Step 4 — Exit (one of three) +### Step 4 — Exit (one of two) 1. **Spec** — every assumption survived: apply one atomic transaction — the `change.groom` operation with `--repo-dir --request ` — carrying the change id, the pinned `path` + `revision` from Step 1, `outcome: spec`, the drafted `spec_markdown` (the settled design plus its `## Assumptions` block), the owned proposal-section rewrites (proposal altitude, resolved `## Open questions` removed), and the desired `depends_on`/`related`/`adrs`/`discovered_from`/`stacked_on`. In one metadata commit it writes the spec file, sets `spec:` + `updated:`, stamps the spec's `docket:backlink` block, and re-renders the `## Artifacts` block and inline board; a typed refusal (not-groomable, spec-path-taken, malformed markers, revision mismatch) writes nothing. Build-ready. -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. +2. **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. +**Hold.** When the emitted spec 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. @@ -59,8 +58,8 @@ 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 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. +Summarize the drain: groomed N, 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 -Every exit shrinks the queue (spec/trivial ⇒ no longer needs-grooming; abstain ⇒ no longer auto-groomable), so the drain visits each stub at most once and provably terminates. No claim is taken — ADR-0004's conflict-checked final-push stance, adopted for the autonomous case: its human-attended rationale does not apply here, but the load-bearing half does — each stub's writes land in a single final commit, so a late collision wastes minutes, not hours, and the post-rebase re-read is the arbiter. +Every exit shrinks the queue (spec ⇒ no longer needs-grooming; abstain ⇒ no longer auto-groomable), so the drain visits each stub at most once and provably terminates. No claim is taken — ADR-0004's conflict-checked final-push stance, adopted for the autonomous case: its human-attended rationale does not apply here, but the load-bearing half does — each stub's writes land in a single final commit, so a late collision wastes minutes, not hours, and the post-rebase re-read is the arbiter. diff --git a/skills/docket-convention/SKILL.md b/skills/docket-convention/SKILL.md index 32de42c90..f67b32524 100644 --- a/skills/docket-convention/SKILL.md +++ b/skills/docket-convention/SKILL.md @@ -154,7 +154,7 @@ docket's workflow steps are **roles**, each done by one fixed skill: / # default docs/adrs/ — flat; ADRs are NEVER archived -.md # immutable once Accepted (only its status: line ever changes) README.md # generated ADR index -/ # default docs/results/ — required close-out artifacts (one per implemented change, trivial included) (on the metadata branch; NEVER archived) +/ # default docs/results/ — required close-out artifacts (one per implemented change) (on the metadata branch; NEVER archived) --results.md ``` @@ -162,7 +162,7 @@ The `archive/` filename date prefix is **UTC**: the merge date for a merged chan All of the above lives on the metadata branch, written through the persistent **metadata worktree**: `/.docket/` in a shared repository (gitignored, deliberately not under `.worktrees/` — slug collisions, prune blast radius), or a checkout outside the clone in a private one; skills always use `metadata_worktree_path` (see *Branch model*). -**Results artifact shape and lifecycle.** The results file is a required close-out artifact for every implemented change, trivial included. Its template opens with a required `**Human action:**` statement immediately after the title (a settled assessment at finalization) and carries a required `## Outcome` section plus the conditional sections `## Human actions and testing` (items labeled Important or Optional; optional walkthroughs may cover automated behavior), `## Verification performed`, and `## Known issues and follow-ups` — omit any conditional section, subsections and all, when it would hold no substantive content, and never pad one with `None`/`N/A` filler. The results **file** lives on the metadata branch at `/--results.md`; the `change.attach-results` operation writes the file and the `results:` **field** together, in one commit. The coordinator captures findings at defined checkpoints during implementation (docket-implement-next's Step 6.5 is normative), not in a single final pass. Follow-ups recorded here hold out-of-scope work for human triage — the run checks proposed and deferred changes and names any match, but never mints a change, issue, ADR, or learning automatically. +**Results artifact shape and lifecycle.** The results file is a required close-out artifact for every implemented change. Its template opens with a required `**Human action:**` statement immediately after the title (a settled assessment at finalization) and carries a required `## Outcome` section plus the conditional sections `## Human actions and testing` (items labeled Important or Optional; optional walkthroughs may cover automated behavior), `## Verification performed`, and `## Known issues and follow-ups` — omit any conditional section, subsections and all, when it would hold no substantive content, and never pad one with `None`/`N/A` filler. The results **file** lives on the metadata branch at `/--results.md`; the `change.attach-results` operation writes the file and the `results:` **field** together, in one commit. The coordinator captures findings at defined checkpoints during implementation (docket-implement-next's Step 6.5 is normative), not in a single final pass. Follow-ups recorded here hold out-of-scope work for human triage — the run checks proposed and deferred changes and names any match, but never mints a change, issue, ADR, or learning automatically. ### Change manifest (frontmatter at the top of each change file) @@ -187,7 +187,6 @@ adrs: [24] # ADRs this change cites or produces spec: # superpowers design doc path; set at brainstorm (propose) time, on the metadata branch plan: # plan FILE on the metadata branch; FILE and FIELD written together by change.attach-plan at build time results: # results FILE on the metadata branch; FILE and FIELD written together by change.attach-results at the first checkpoint, required before the implemented transition -trivial: false # true = no spec needed (small mechanical change); still build-ready auto_groomable: # `true` makes a stub auto-groomable; unset or `false` means not hold: # `true` keeps a groomed change out of autonomous build selection; naming it still builds it branch_prefix: # optional one unqualified branch-path component; overrides at mint, consumed only at claim, inert once branch: is populated, survives reclaim @@ -288,13 +287,13 @@ An `Accepted` ADR is immutable except its `status:` line; a non-reversing contex ### Build-readiness & selection (shared definition) -A change is **build-ready** — eligible for `docket-implement-next` — only when it is `proposed`, has a `spec:` **or** `trivial: true`, and all `depends_on` are satisfied (`done`). A `proposed` change with neither a spec nor `trivial: true` is **needs-grooming** (not build-ready). A change carrying `stacked_on:` is additionally build-ready only when the binary resolves its **effective base**; until then its readiness is `stack-base-unresolved` and the board reads *waiting on #A — stack base not built* (*stack parent #A killed — re-parent, un-stack, or kill* when an ancestor was killed). Stacking adds this eligibility condition only — never a ranking one. The implementer's deterministic selection order is `priority` (`critical` > `high` > `medium` > `low`) → age (`created`) → **lowest `id`**. A `created:` that is missing or malformed (not a well-formed `YYYY-MM-DD`) sorts last within its priority band — unknown age never preempts dated work. A held change (`hold: true`) that would be build-ready reads `on-hold`: autonomous selection never picks it, and naming it builds it. +A change is **build-ready** — eligible for `docket-implement-next` — only when it is `proposed`, has a `spec:`, and all `depends_on` are satisfied (`done`). A `proposed` change with no spec is **needs-grooming** (not build-ready). A change carrying `stacked_on:` is additionally build-ready only when the binary resolves its **effective base**; until then its readiness is `stack-base-unresolved` and the board reads *waiting on #A — stack base not built* (*stack parent #A killed — re-parent, un-stack, or kill* when an ancestor was killed). Stacking adds this eligibility condition only — never a ranking one. The implementer's deterministic selection order is `priority` (`critical` > `high` > `medium` > `low`) → age (`created`) → **lowest `id`**. A `created:` that is missing or malformed (not a well-formed `YYYY-MM-DD`) sorts last within its priority band — unknown age never preempts dated work. A held change (`hold: true`) that would be build-ready reads `on-hold`: autonomous selection never picks it, and naming it builds it. ### Autonomous grooming (shared definition) -A change is opted into autonomous grooming only by its own `auto_groomable: true`; unset or `false` means not. The field is human input with one exception: `docket-auto-groom`'s abstain is the single agent write (`change.groom` `outcome: abstain` sets it to `false`). Likewise `hold` is human input except the auto-groomer's `hold: true` on a spec or trivial verdict that needs a person's step. +A change is opted into autonomous grooming only by its own `auto_groomable: true`; unset or `false` means not. The field is human input with one exception: `docket-auto-groom`'s abstain is the single agent write (`change.groom` `outcome: abstain` sets it to `false`). Likewise `hold` is human input except the auto-groomer's `hold: true` on a spec that needs a person's step. -A stub is **auto-groomable** — selectable by `docket-auto-groom` — when it is needs-grooming (`proposed`, no `spec:`, not `trivial: true`) AND it carries `auto_groomable: true`. Unsatisfied `depends_on` does NOT exclude it (the same design-ahead rule as interactive grooming; the implementer's reconcile re-validates at build time). Ranking is the same deterministic selection order as build-ready selection. +A stub is **auto-groomable** — selectable by `docket-auto-groom` — when it is needs-grooming (`proposed`, no `spec:`) AND it carries `auto_groomable: true`. Unsatisfied `depends_on` does NOT exclude it (the same design-ahead rule as interactive grooming; the implementer's reconcile re-validates at build time). Ranking is the same deterministic selection order as build-ready selection. **Abstain rule.** When autonomous grooming cannot safely default a decision, it emits NO spec; it applies `change.groom` with `outcome: abstain`, which flips `auto_groomable: false`, appends a dated entry to the `## Auto-groom blocked` body section, and re-renders the board in one commit. The stub stays needs-grooming — out of the autonomous queue, still in the interactive one. Re-enable = a human supplies the missing context and applies `change.groom` with `outcome: re-enable` (optionally with owned-section edits carrying that context): it sets the flag back to `true` and removes the `## Auto-groom blocked` section in the same commit — never a hand edit (git history keeps the section; its presence drives the board's needs-you cell, so a stale one would mislabel a re-enabled stub). Kill and defer are never autonomous: they surface inside the blocked section as recommendations. diff --git a/skills/docket-groom-next/SKILL.md b/skills/docket-groom-next/SKILL.md index 9c4bf1022..e62af2310 100644 --- a/skills/docket-groom-next/SKILL.md +++ b/skills/docket-groom-next/SKILL.md @@ -1,6 +1,6 @@ --- name: docket-groom-next -description: Use when stubs are sitting at needs-grooming on the docket board and you want the next one designed — selecting the next needs-grooming change (proposed, no spec, not trivial) deterministically and grooming it to build-ready through an interactive brainstorm with the human, exiting with a linked spec, a trivial verdict, a kill, a defer, or a re-enable — or revising a proposed change by explicit id (an already-groomed one, or a stub to edit rather than groom). Selection is autonomous; the design conversation is not. Writes markdown only — never branches, worktrees, or code. +description: Use when stubs are sitting at needs-grooming on the docket board and you want the next one designed — selecting the next needs-grooming change (proposed, no spec) deterministically and grooming it to build-ready through an interactive brainstorm with the human, exiting with a linked spec, a kill, a defer, or a re-enable — or revising a proposed change by explicit id (an already-groomed one, or a stub to edit rather than groom). Selection is autonomous; the design conversation is not. Writes markdown only — never branches, worktrees, or code. --- # docket-groom-next — the groomer (interactive) @@ -13,7 +13,7 @@ description: Use when stubs are sitting at needs-grooming on the docket board an - Stubs show as needs-grooming on the board and you want to design the next one, or a specific one (pass its id explicitly to skip selection). - Do NOT use to capture a brand-new idea — that is `docket-new-change`'s job; this skill never mints ids. -- An explicit id naming an already-groomed `proposed` change (has `spec:` or `trivial: true`) is NOT an error — it routes to the revise flow (Step 4, exit 5): adjust the existing spec and owned sections through `change.groom` with `outcome: revise`. An explicit id with a request to *edit* (not groom) a needs-grooming stub routes there too. Drift against current reality at build time remains the reconcile pass's job in `docket-implement-next`. +- An explicit id naming an already-groomed `proposed` change (has `spec:`) is NOT an error — it routes to the revise flow (Step 4, exit 4): adjust the existing spec and owned sections through `change.groom` with `outcome: revise`. An explicit id with a request to *edit* (not groom) a needs-grooming stub routes there too. Drift against current reality at build time remains the reconcile pass's job in `docket-implement-next`. ## Convention (load first — blocking) @@ -23,7 +23,7 @@ Invoke the `docket-convention` skill via the Skill tool first — unless already ### Step 1 — Select -Sync the metadata working tree (the startup-check `repository.prepare` operation), then rank every needs-grooming change in `active/` — `status: proposed`, no `spec:`, not `trivial: true` — by the convention's deterministic selection order (the same ranking `docket-implement-next` uses). Pick the top, or accept an explicit id from the caller. An explicit id naming an already-groomed `proposed` change (has `spec:` or `trivial: true`) routes to the **revise** flow — recap what is there today (the linked spec's body, or the trivial rationale, and the owned sections), run the resolved brainstorm skill seeded with the current design framed as "what would you like to adjust," and exit via Step 4's revise exit. When the human asks to *edit* a needs-grooming stub rather than groom it, skip the brainstorm and apply Step 4's revise exit directly with the requested owned-section, `title`, `priority`, or relationship edits — the stub stays needs-grooming. Any other explicit id that is not needs-grooming is an error to report, never a silent re-pick. Empty queue → report that nothing needs grooming and stop. Read the selected stub's exact **record path** and opaque **record revision** (the blob object id) from the `status` operation (with `--json`) — the Step-4 groom/defer transactions pin the record with those, and re-reading them after a mid-run re-sync is a fresh `status` read. +Sync the metadata working tree (the startup-check `repository.prepare` operation), then rank every needs-grooming change in `active/` — `status: proposed`, no `spec:` — by the convention's deterministic selection order (the same ranking `docket-implement-next` uses). Pick the top, or accept an explicit id from the caller. An explicit id naming an already-groomed `proposed` change (has `spec:`) routes to the **revise** flow — recap what is there today (the linked spec's body and the owned sections), run the resolved brainstorm skill seeded with the current design framed as "what would you like to adjust," and exit via Step 4's revise exit. When the human asks to *edit* a needs-grooming stub rather than groom it, skip the brainstorm and apply Step 4's revise exit directly with the requested owned-section, `title`, `priority`, or relationship edits — the stub stays needs-grooming. Any other explicit id that is not needs-grooming is an error to report, never a silent re-pick. Empty queue → report that nothing needs grooming and stop. Read the selected stub's exact **record path** and opaque **record revision** (the blob object id) from the `status` operation (with `--json`) — the Step-4 groom/defer transactions pin the record with those, and re-reading them after a mid-run re-sync is a fresh `status` read. When autonomous grooming is in play (see the convention's *Autonomous grooming* shared definition), rank in **selection bands** — the human's attention goes first to stubs that need a human: (1) abstained stubs (a `## Auto-groom blocked` section is present), then (2) `auto_groomable` unset or `false` stubs, then (3) `auto_groomable: true` stubs, each flagged "#NNNN is auto-groomable — docket-auto-groom will handle it unless you want it now." Within each band, the deterministic order applies unchanged. Every needs-grooming stub stays selectable — bands reorder, they never exclude; an explicit id still overrides everything. @@ -46,32 +46,31 @@ Open with a **recap of the selected stub**, written for a reader with no prior c When the design settles on building this stub atop another change's **unmerged** branch, set `stacked_on: ` at the spec exit and **read [`../docket-convention/references/stacked-changes.md`](../docket-convention/references/stacked-changes.md) now (blocking)** first — stacking changes how the change is built, merged, and closed out. -The recap is an introduction, not a confirmation gate — flow straight into the brainstorm, where the human redirects. Then invoke `superpowers:brainstorming` WITH THE HUMAN, seeded with the stub's body and its `## Open questions` — the open questions are the session's starting agenda. When `superpowers:brainstorming` cannot be invoked, run the brainstorm inline with the human, warning prominently — the artifact is unchanged: a spec, then stop. If the human asks for a consultant-written spec, invoke `docket-brainstorm` for this run instead — human steering of an interactive session always wins (see the README's consultant-brainstorm section). STOP AT THE SPEC — do NOT continue to `superpowers:writing-plans` (planning is build-time, owned by `docket-implement-next`). +The recap is an introduction, not a confirmation gate — flow straight into the brainstorm, where the human redirects. Then invoke `superpowers:brainstorming` WITH THE HUMAN, seeded with the stub's body and its `## Open questions` — the open questions are the session's starting agenda. Tell it the artifact is always a written spec, sized to the change: a small change gets a short spec, and it never concludes that a change needs no written design. When `superpowers:brainstorming` cannot be invoked, run the brainstorm inline with the human, warning prominently — the artifact is unchanged: a spec, then stop. If the human asks for a consultant-written spec, invoke `docket-brainstorm` for this run instead — human steering of an interactive session always wins (see the README's consultant-brainstorm section). STOP AT THE SPEC — do NOT continue to `superpowers:writing-plans` (planning is build-time, owned by `docket-implement-next`). -### Step 4 — Exit (one of six; the human confirms which) +### Step 4 — Exit (one of five; the human confirms which) -All six exits reuse existing transitions — this skill introduces no new lifecycle status: +All five exits reuse existing transitions — this skill introduces no new lifecycle status: 1. **Spec** (the normal exit): **author** the settled design as the spec's Markdown body, and any owned proposal-section rewrites (proposal altitude, resolved `## Open questions` removed). Apply it with one atomic transaction — the `change.groom` operation with `--repo-dir --request ` — carrying the change id, the pinned record `path` + `revision` from Step 1, `outcome: spec`, the `spec_markdown`, the owned-section edits, and the desired `depends_on`/`related`/`adrs`/`discovered_from`/`stacked_on` (authored Markdown travels in the request file, never a shell-escaped flag). In a private repository the spec ships with the PR, so its body follows the private-repository writing rule: no `Change #N, groomed …` line, no change or ADR numbers, no backlog references. In one metadata commit it writes the spec file, sets `spec:` + `updated:`, stamps the spec's `docket:backlink` block, and re-renders the `## Artifacts` block and inline board — so there is no separate render, back-link, or Board pass. A typed refusal (not-groomable, spec-path-taken, malformed markers, revision mismatch) writes nothing — surface it. The change is now build-ready. -2. **Trivial verdict**: the brainstorm concludes there is no real design question — 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 as the trivial rationale. The transaction sets `trivial: true` + `updated:`, re-renders the `## Artifacts` block, and re-renders the inline board atomically — no spec file, no separate Board pass. Also build-ready. -3. **Kill**: the stub is obsolete, a duplicate, or decided against — follow the proposed-kill sub-path in `docket-new-change` (it owns the kill mechanics; do not restate them here). -4. **Defer**: right idea, wrong time — apply the `change.defer` operation with `--repo-dir --request ` with the pinned `path` + `revision` and the authored `why_deferred` section body. The transaction sets `status: deferred`, splices the `## Why deferred` section, sets `updated:`, and re-renders the inline board atomically. -5. **Revise** (explicit-id route only): the human wants a `proposed` change adjusted without changing its groom state — apply the `change.groom` operation with `--repo-dir --request ` with `outcome: revise`, the pinned `path` + `revision`, and whichever of `spec_markdown` (a whole-body replace of the *existing* linked spec, minus its `docket:backlink` block, which the transaction re-stamps; it never mints a new path) and owned-section `sections` edits the adjustment touched, plus any relationship-field updates. With `spec_markdown`, also send `spec_revision`, the linked spec's blob object id read by `git -C rev-parse HEAD:` (`` is the record's `spec:` value) — a concurrent spec edit then contends instead of being overwritten. It never sets `spec:`, `trivial:`, or `auto_groomable:`. Repeatable while the change stays `proposed`. A typed refusal (`not-revisable`, `spec-not-linked` — also the answer to `spec_markdown` on a needs-grooming stub, which has no spec — `spec-file-missing`, `empty-revise`, `empty-spec_revision`, `invalid-section-heading` for an edit naming `## Auto-groom blocked`, revision mismatch) writes nothing — surface it. The change keeps its groom state. -6. **Re-enable** (abstained or opted-out stubs): the human supplied the context an abstain asked for and wants `docket-auto-groom` to take the stub — apply the `change.groom` operation with `--repo-dir --request ` with `outcome: re-enable`, the pinned `path` + `revision`, and any owned-section `sections` edits carrying the new context. The transaction sets `auto_groomable: true`, removes the `## Auto-groom blocked` section, and re-renders the inline board atomically, returning the stub to the autonomous queue. A `nothing-to-re-enable` refusal (no blocked section, already `true`) writes nothing. A spec or trivial groom of an abstained stub needs no re-enable. +2. **Kill**: the stub is obsolete, a duplicate, or decided against — follow the proposed-kill sub-path in `docket-new-change` (it owns the kill mechanics; do not restate them here). +3. **Defer**: right idea, wrong time — apply the `change.defer` operation with `--repo-dir --request ` with the pinned `path` + `revision` and the authored `why_deferred` section body. The transaction sets `status: deferred`, splices the `## Why deferred` section, sets `updated:`, and re-renders the inline board atomically. +4. **Revise** (explicit-id route only): the human wants a `proposed` change adjusted without changing its groom state — apply the `change.groom` operation with `--repo-dir --request ` with `outcome: revise`, the pinned `path` + `revision`, and whichever of `spec_markdown` (a whole-body replace of the *existing* linked spec, minus its `docket:backlink` block, which the transaction re-stamps; it never mints a new path) and owned-section `sections` edits the adjustment touched, plus any relationship-field updates. With `spec_markdown`, also send `spec_revision`, the linked spec's blob object id read by `git -C rev-parse HEAD:` (`` is the record's `spec:` value) — a concurrent spec edit then contends instead of being overwritten. It never sets `spec:` or `auto_groomable:`. Repeatable while the change stays `proposed`. A typed refusal (`not-revisable`, `spec-not-linked` — also the answer to `spec_markdown` on a needs-grooming stub, which has no spec — `spec-file-missing`, `empty-revise`, `empty-spec_revision`, `invalid-section-heading` for an edit naming `## Auto-groom blocked`, revision mismatch) writes nothing — surface it. The change keeps its groom state. +5. **Re-enable** (abstained or opted-out stubs): the human supplied the context an abstain asked for and wants `docket-auto-groom` to take the stub — apply the `change.groom` operation with `--repo-dir --request ` with `outcome: re-enable`, the pinned `path` + `revision`, and any owned-section `sections` edits carrying the new context. The transaction sets `auto_groomable: true`, removes the `## Auto-groom blocked` section, and re-renders the inline board atomically, returning the stub to the autonomous queue. A `nothing-to-re-enable` refusal (no blocked section, already `true`) writes nothing. A spec groom of an abstained stub needs no re-enable. -**Retitle.** When the settled design renamed the change, exits 1 (spec), 2 (trivial), 5 (revise), and 6 (re-enable) also carry `title` in the same `change.groom` request. The transaction rewrites `title:` through the writer, re-renders the board and the `## Artifacts` block, and re-stamps the linked spec's `docket:backlink` line; a `title` alone is a valid revise. The slug, record filename, spec path, and branch never change — a retitle renames nothing. A typed refusal (`invalid-title`, `empty-title`, `not-retitleable`, `spec-backlink-missing`, `spec-backlink-malformed`) writes nothing — surface it. +**Retitle.** When the settled design renamed the change, exits 1 (spec), 4 (revise), and 5 (re-enable) also carry `title` in the same `change.groom` request. The transaction rewrites `title:` through the writer, re-renders the board and the `## Artifacts` block, and re-stamps the linked spec's `docket:backlink` line; a `title` alone is a valid revise. The slug, record filename, spec path, and branch never change — a retitle renames nothing. A typed refusal (`invalid-title`, `empty-title`, `not-retitleable`, `spec-backlink-missing`, `spec-backlink-malformed`) writes nothing — surface it. -**Reprioritize.** The same four exits may also carry `priority` (`critical`, `high`, `medium`, or `low`) in the same `change.groom` request; the transaction rewrites `priority:` and re-renders the board and the `## Artifacts` block, and a `priority` alone is a valid revise. Abstain refuses it (`invalid-priority`) and an unknown value refuses with `unknown-priority`; either writes nothing — surface it. A deferred change is revived before it can be re-prioritized. +**Reprioritize.** The same three exits may also carry `priority` (`critical`, `high`, `medium`, or `low`) in the same `change.groom` request; the transaction rewrites `priority:` and re-renders the board and the `## Artifacts` block, and a `priority` alone is a valid revise. Abstain refuses it (`invalid-priority`) and an unknown value refuses with `unknown-priority`; either writes nothing — surface it. A deferred change is revived before it can be re-prioritized. -**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. +**Deliverable, type, and branch prefix.** The same three 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. +**Hold.** When the settled design needs a step a person must carry out, suggest a hold before the spec exit; the person decides. The same three 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. +**Stacking.** The same three 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) -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. +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:`). STOP — grooming never implements. ## Concurrency — no claim diff --git a/skills/docket-implement-next/SKILL.md b/skills/docket-implement-next/SKILL.md index e8fef5d33..068061db5 100644 --- a/skills/docket-implement-next/SKILL.md +++ b/skills/docket-implement-next/SKILL.md @@ -54,7 +54,7 @@ A claim of a `proposed` record that still carries a `## Run halted` section remo ### Step 3 — Reconcile ⭐ -Re-read the step-1 bundle's change + spec bytes against `related` + recently-archived changes, cited + recent ADRs, and CURRENT code, and decide NON-INTERACTIVELY what is true NOW (drop work done elsewhere, adjust scope, fold in new constraints). That judgment is yours; the write is a transaction. **Author** a reconcile request — structured replacement text for the owned proposal sections and still-mutable linked-spec content, the complete desired relations (`depends_on`/`stacked_on`/`related`/`adrs`/`discovered_from`) when reality requires them, and one dated `## Reconcile log` entry — and apply it with the `change.reconcile` operation with `--input ` (the request file carries `id`, the pinned `revision`, and the authored Markdown — never a shell-escaped flag). The transaction checks the exact revision and legal `in-progress` status, sets `reconciled: true`, refreshes the claim, rerenders backlinks/`## Artifacts` block/inline board, validates the whole repository, and commits atomically on the metadata branch, pushed to the metadata remote; unknown frontmatter, unlisted authored sections, line endings, and unrelated files stay byte-identical, and a request naming a non-owned field/section is a typed refusal that writes nothing. A trivial change has no spec — patch the body only. If fresh origin state diverges incompatibly, the operation returns `contended` and writes nothing — never a text-merge; re-read fresh context and re-author. +Re-read the step-1 bundle's change + spec bytes against `related` + recently-archived changes, cited + recent ADRs, and CURRENT code, and decide NON-INTERACTIVELY what is true NOW (drop work done elsewhere, adjust scope, fold in new constraints). That judgment is yours; the write is a transaction. **Author** a reconcile request — structured replacement text for the owned proposal sections and still-mutable linked-spec content, the complete desired relations (`depends_on`/`stacked_on`/`related`/`adrs`/`discovered_from`) when reality requires them, and one dated `## Reconcile log` entry — and apply it with the `change.reconcile` operation with `--input ` (the request file carries `id`, the pinned `revision`, and the authored Markdown — never a shell-escaped flag). The transaction checks the exact revision and legal `in-progress` status, sets `reconciled: true`, refreshes the claim, rerenders backlinks/`## Artifacts` block/inline board, validates the whole repository, and commits atomically on the metadata branch, pushed to the metadata remote; unknown frontmatter, unlisted authored sections, line endings, and unrelated files stay byte-identical, and a request naming a non-owned field/section is a typed refusal that writes nothing. If fresh origin state diverges incompatibly, the operation returns `contended` and writes nothing — never a text-merge; re-read fresh context and re-author. Adjacent follow-up work this pass surfaces is **noted for the final report** — nothing is minted automatically; a human captures reported work deliberately with `docket change create`, guided by the backlog verdict final consolidation attaches (Step 6.5 *Backlog match*). @@ -77,7 +77,7 @@ The `workspace.prepare` operation reloads the authoritative snapshot, resolves t the metadata branch only receives bookkeeping commits — it NEVER determines where code branches start; the feature branch is cut from the resolved effective base (`origin/` in the ordinary case). -**Preparation (parent).** The reconciled **spec is read from the metadata working tree** (**re-sync the metadata worktree immediately before reading it**). Then run the `workspace.commit-spec` operation with `--id `: it commits the spec copy as the branch's first commit (a trivial change reports `no-spec`); a `spec-path-occupied` or `workspace-not-ready` refusal halts. Confirm the worktree is clean and record its HEAD as the **pre-dispatch HEAD**. Resolve nothing new: learnings enablement and every repo path come from the startup-check prepared context. Immediately before the long plan dispatch, **refresh the claim** — the `change.refresh-claim` operation with `--id --revision ` re-stamps `claimed_at` (only) and returns the new revision; a refresh `contended` means a newer record owns the change, so it **stops a NEW dispatch** but **never cancels** a child already running whose outcome must still be inspected. +**Preparation (parent).** The reconciled **spec is read from the metadata working tree** (**re-sync the metadata worktree immediately before reading it**). Then run the `workspace.commit-spec` operation with `--id `: it commits the spec copy as the branch's first commit; a `spec-path-occupied` or `workspace-not-ready` refusal halts. Confirm the worktree is clean and record its HEAD as the **pre-dispatch HEAD**. Resolve nothing new: learnings enablement and every repo path come from the startup-check prepared context. Immediately before the long plan dispatch, **refresh the claim** — the `change.refresh-claim` operation with `--id --revision ` re-stamps `claimed_at` (only) and returns the new revision; a refresh `contended` means a newer record owns the change, so it **stops a NEW dispatch** but **never cancels** a child already running whose outcome must still be inspected. **Plan authoring (dispatched).** The parent stays the orchestrator. @@ -113,7 +113,7 @@ It also contains the branch and base ref, change title and scope, relevant learn ### Step 6.5 — Results (required) -The results artifact is **required for every change, trivial included** — there is no skip and no close-out condition to weigh. Author `/--results.md` from `results-template.md` in a scratch file outside both worktrees; it is written on the metadata branch, never the feature branch. The path is chosen **once per change and reused on every resume** even when the authoring date has since changed (a changed date never mints a second file). Immediately after the H1 title, a **`**Human action:**` statement** says whether human action is needed — during implementation it may say the assessment is pending, but final results give a settled assessment consistent with the rest of the artifact, and the implemented boundary refuses a missing or empty statement. `## Outcome` is required; every other section is **conditional** — omit an empty heading and its subsections rather than filling it, and never write a `None`/`N/A`/`not applicable` body (whole-section filler refuses at the implemented boundary). The `docket:backlink` block above the title is owned by the `change.attach-results` operation — never hand-author its markers. +The results artifact is **required for every implemented change** — there is no skip and no close-out condition to weigh. Author `/--results.md` from `results-template.md` in a scratch file outside both worktrees; it is written on the metadata branch, never the feature branch. The path is chosen **once per change and reused on every resume** even when the authoring date has since changed (a changed date never mints a second file). Immediately after the H1 title, a **`**Human action:**` statement** says whether human action is needed — during implementation it may say the assessment is pending, but final results give a settled assessment consistent with the rest of the artifact, and the implemented boundary refuses a missing or empty statement. `## Outcome` is required; every other section is **conditional** — omit an empty heading and its subsections rather than filling it, and never write a `None`/`N/A`/`not applicable` body (whole-section filler refuses at the implemented boundary). The `docket:backlink` block above the title is owned by the `change.attach-results` operation — never hand-author its markers. **Human actions and testing** labels every item **Important** or **Optional**, written for a mid-level engineer with little knowledge of Docket internals. An **Important** item marks a meaningful verification gap or necessary human judgment (never a new automated merge requirement) — give the reason, when the action matters, and what remains uncertain if skipped. An Optional walkthrough MAY exercise behavior automated tests already cover — a routine suite rerun is not a functional walkthrough. Every item carries prerequisites and setup, concrete steps with observable expected results, and cleanup when it changes persistent state — complete enough to run without reconstructing missing commands. Do not infer coverage from a green suite: inspect the relevant tests and evidence, and where coverage is genuinely uncertain report that uncertainty under Known issues and follow-ups or Verification performed rather than authoring a speculative checklist. The section holds only what a human should do or check — never a record of what the run already checked, which belongs under Verification performed. @@ -146,7 +146,7 @@ The results artifact is **required for every change, trivial included** — ther **Leak check (private repositories).** `workspace.publish` and `pr.publish` refuse `leak-detected` (`blocked`) when anything they would expose carries a docket fingerprint; the result's `leaks` list names each hit (source, commit, file, line, rule, matched text). Nothing was pushed or opened. End the run `halted`: write the hit list into the `change.halt` report — never reword, amend, rebase, or force-push to get past it, and never retry. `leak-check-unverified` (`external-failed`) means the check could not run; treat it as any external failure. `metadata-on-shared-remote` warnings go in the run report only. -**Mark implemented.** The `change.mark-implemented` operation with `--id --revision --head --pr --evidence ` is the final mutation in this scope. Before its transaction it reprobes Git and GitHub and proves: the change is still the exact `in-progress` revision, `reconciled: true`, linked to the verified plan; local and remote feature heads equal the supplied head; valid evidence names that head and a passed gate; exactly one verified PR for the feature branch targets the resolved effective-base branch and names that head; and a results artifact is attached, read from the metadata branch, and satisfies the final content contract and its artifact identity (missing, invalid, or unattached results — trivial changes included — refuse the transition). It then applies the landed transition atomically — `status: implemented` + `pr:` + updated date + the verified evidence as the record's `## Build evidence` section + `## Artifacts` block + inline board + audit receipt (letting the sweep read `pr:`), rendering the board inside that transaction, so no separate Board pass runs. It does NOT clear the claim, delete the branch/workspace, merge, archive, or close descendants. A retry against an already-`implemented` change with matching PR/head returns the prior applied outcome, never a duplicate transition. +**Mark implemented.** The `change.mark-implemented` operation with `--id --revision --head --pr --evidence ` is the final mutation in this scope. Before its transaction it reprobes Git and GitHub and proves: the change is still the exact `in-progress` revision, `reconciled: true`, linked to the verified plan; local and remote feature heads equal the supplied head; valid evidence names that head and a passed gate; exactly one verified PR for the feature branch targets the resolved effective-base branch and names that head; and a results artifact is attached, read from the metadata branch, and satisfies the final content contract and its artifact identity (missing, invalid, or unattached results refuse the transition). It then applies the landed transition atomically — `status: implemented` + `pr:` + updated date + the verified evidence as the record's `## Build evidence` section + `## Artifacts` block + inline board + audit receipt (letting the sweep read `pr:`), rendering the board inside that transaction, so no separate Board pass runs. It does NOT clear the claim, delete the branch/workspace, merge, archive, or close descendants. A retry against an already-`implemented` change with matching PR/head returns the prior applied outcome, never a duplicate transition. **Verify the run.** The `run.verify` operation with `--id ` is read-only: it reports one closed verdict — `run-complete` / `run-unclaimed` / `run-incomplete` / `run-halted` / `run-waiting` — and enumerates every unmet condition with its stable reason and observed identity. Automation keys on the typed verdict, **never** the exit code (all verdicts exit 0). `run-complete` is the receipt that Step 7's postcondition (or the results-artifact ending's) holds; `run-halted` is the closed verdict for a change carrying a `## Run halted` marker — a human is needed, and an attributed caller re-dispatches it through the resume path (the `change.resume-halted` operation with `--acknowledge-quiescent`, Step 2), never a fresh claim. `run-waiting ` is the closed verdict for a change whose gate stopped at a safe, resumable continuation — neither complete nor failed: an attributed caller resumes that exact handoff rather than drawing another change or re-dispatching a fresh run, and precedence is completed-run postconditions first, then a valid `run-waiting`, then ordinary `run-incomplete`; a persisted `run-halted` stays terminal. A run **dispatched with an explicit change id, continuation id, and run key resumes, not restarts**: its FIRST act is the `run.continue` operation with ` `, claiming the recovered drive **before any other work**; it never launches a replacement test, and this is a **continuation, not `run-retry-once`** — the key stays active until a true terminal disposition. Each `run-retry-once` authorizes exactly one next dispatch; the run tracker may grant another on a later eligible attempt while the configured `run.max_attempts` budget allows, and a continuation consumes none of that budget. A gated parent's prompt may also carry a **run context** token; pass it, always as `--run-context`, into every build-owned `gate.drive.start` (`--owner build` — Step 6's evidence re-mint and re-gates, the build role's final suite gate, and each post-repair attempt the build role starts) this run performs — each invoked with `--json` per the shared capture requirement and each always carrying `--change-id ` — and into the Step-2 claim, omitting it only when the prompt carried none (a `run-untracked` or ungated run). Build-task workers never receive it: they run their tests directly and call no gate operation. @@ -160,7 +160,7 @@ Each step below is complete only when its row holds — read from **git**, never |---|---| | 2 Claim | `status: in-progress` + `branch:` + `updated:` + `claimed_at:` committed on the metadata branch **and landed** (local tip == remote tip). | | 3 Reconcile | `reconciled: true` and a dated `## Reconcile log` entry landed on the metadata branch — or, on the kill path, the change archived. | -| 4 Worktree + plan | Step 3's push SHA-confirmed **before** the branch is cut; then the spec copy committed as the first commit on `/` (non-trivial changes), then `plan:` and the plan file with its backlink landed on the metadata branch, the feature HEAD unchanged by planning. | +| 4 Worktree + plan | Step 3's push SHA-confirmed **before** the branch is cut; then the spec copy committed as the first commit on `/`, then `plan:` and the plan file with its backlink landed on the metadata branch, the feature HEAD unchanged by planning. | | 5 Build | the executed plan committed on `/`, with a build-evidence record at `result: green` (or `skipped` / `build-gate-off` under `build.gate: off`) whose `head_sha` **equals branch HEAD**. | | 6 Review + ADRs | that record still present at `head_sha` == HEAD **after** any fix commits, and every ADR the run produced landed in `adrs:`. Known-weak row: on a clean review this reduces to Step 5's, because whether a reviewer ran is not a fact about git. | | 7 PR + stop | the branch pushed (`origin//` resolves), the PR open, and `status: implemented` + `pr:` landed on the metadata branch; `results:` set and the final results file with its backlink on the metadata branch, and the record's `## Build evidence` section naming the PR head. | @@ -201,7 +201,7 @@ A change is drafted against a *snapshot* of the codebase, ADRs, and other in-fli `reconciled: false` at birth; set to `true` only after the reconcile pass completes and commits. It is **(1) an audit signal** — paired with the dated `## Reconcile log` entry, it proves the change was freshened against current reality; **(2) a resume-safety guard** — on any resume of an `in-progress` change, **read `references/edge-paths.md` now (blocking)** for the resume rules. -`reconciled` is **NOT a selection criterion** — build-readiness is `spec:`-or-`trivial: true` plus satisfied `depends_on`; a change sitting at `reconciled: false` is still build-ready, and reconcile happens in step 3, after selection and claim. +`reconciled` is **NOT a selection criterion** — build-readiness is `spec:` plus satisfied `depends_on`; a change sitting at `reconciled: false` is still build-ready, and reconcile happens in step 3, after selection and claim. ## Branch & metadata discipline diff --git a/skills/docket-implement-next/references/results-artifact.md b/skills/docket-implement-next/references/results-artifact.md index e7c316b10..0ff999f80 100644 --- a/skills/docket-implement-next/references/results-artifact.md +++ b/skills/docket-implement-next/references/results-artifact.md @@ -11,7 +11,7 @@ skill. No plan, no build, no PR. Skip `workspace.commit-spec` — the branch must keep no commits of its own, or cleanup keeps it — plus the plan-writer dispatch, the build role, the build gate, evidence records, the branch diff review, `workspace.publish`, `pr.publish`, and `change.mark-implemented` -(it refuses a `results-artifact` change). The spec, or a trivial change's body, is the plan. +(it refuses a `results-artifact` change). The spec is the plan. **Refresh the claim** (the `change.refresh-claim` operation, at a revision re-read after a re-sync) at each phase boundary below, as the `pr` path does: before the work, before review, and before @@ -52,7 +52,7 @@ so everything it reads travels inline. Dispatch `docket-review-standard` foreground — the default tier when there is no build record — and tell it to review in its results-artifact mode, then stop. Its dispatch payload contains: Feature worktree: -It also contains, inline, the spec body (or the trivial change's body), the results artifact's text, the change title and scope, and the relevant learnings hooks. When the `docket-review` skill is missing, apply the convention's missing-skill rule: review the results inline against the same checks, warning prominently, and dispatch no reviewer. An undispatchable review tier — established only per the convention's *Dispatch-capability resolution* — makes the run **`halt`**. +It also contains, inline, the spec body, the results artifact's text, the change title and scope, and the relevant learnings hooks. When the `docket-review` skill is missing, apply the convention's missing-skill rule: review the results inline against the same checks, warning prominently, and dispatch no reviewer. An undispatchable review tier — established only per the convention's *Dispatch-capability resolution* — makes the run **`halt`**. ## 5. Fix pass diff --git a/skills/docket-implement-next/results-template.md b/skills/docket-implement-next/results-template.md index 57069d009..11070f1d1 100644 --- a/skills/docket-implement-next/results-template.md +++ b/skills/docket-implement-next/results-template.md @@ -1,5 +1,5 @@ -