diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 9e347f3b3..825dc9d92 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -59,8 +59,9 @@ Each line is a pointer: the command, what its verbs govern, and where to read th (implemented with a PR, or a completed results artifact); also reset the count of implement-next halts in a row (`docket run reset-halts`). Verbs: `docket run --help`. -- **`docket schema`** — emit request/result payload schemas and allowed values (read-only, - repository-independent). Verbs: `docket schema --help`. +- **`docket schema []`** — emit request/result payload schemas and allowed values (read-only, + repository-independent). Narrow it to one operation by giving its id positionally or via + `--operation`. Verbs: `docket schema --help`. - **`docket status`** — report backlog status, readiness, selection, and repository health (read-only). Verbs: `docket status --help`. - **`docket uninstall`** — remove recorded harness integrations while retaining the CLI and diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index c035ae15e..fad4b9d08 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -527,17 +527,17 @@ docket finalize cleanup --id 412 ### Claim / claim lease / reclaim A **claim** is the moment a change is picked up for building; it records which branch will carry -the work and when it was taken. The **claim lease** is a timestamp on a claim (`claimed_at:`); -when it expires with no branch behind it, the change goes back to the queue. **Reclaim** is that +the work and when it was taken. The **claim lease** is a timestamp on a claim (`claimed_at:`), +stamped at claim and re-stamped at reconcile and resume-halted; when it expires with no branch +behind it, the change goes back to the queue. **Reclaim** is that return trip (`in-progress → proposed`), logged in `## Reclaim log`. **Used for:** making sure an abandoned build never holds a change forever. A claim that already has a feature branch or a workspace (real work) is never reclaimed. Grooming never takes a claim. ```sh -docket change claim --id 412 --revision -docket change refresh-claim --id 412 --revision # extend the lease at a phase boundary -docket change reclaim --id 412 --revision # refuses with lease-not-expired if still live +docket change claim --id 412 --revision +docket change reclaim --id 412 --revision # refuses with lease-not-expired if still live ``` Config: `reclaim.lease_ttl` (hours) and `reclaim.auto`. @@ -848,7 +848,9 @@ The build and finalize gates both run the whole suite. The page that covers them ### Implementation context The read-only bundle implement-next assembles before claiming: the selected change, its readiness, -and what it needs to proceed. +and what it needs to proceed. Read by id, it also serves the run's own `in-progress` change (after +the claim, or on a resume), reporting `claim_eligible: false` with the record's current revision +and recorded branch. ```sh docket context implementation --id 412 --json @@ -2122,7 +2124,7 @@ below. |---|---|---| | `block_dispositions` | `recorded` `already-recorded` `cleared` `nothing-to-clear` `unknown` `contended` `refused` `failed` | `finalize block`, `finalize clear-block` | | `cancel_dispositions` | `cancelled` `already-cancelled` `cancellation-pending` `refused` | `run cancel` | -| `claim_dispositions` | `applied` `already-claimed` `contended` `failed` `run-context-invalid` `run-context-conflict` | `change claim`, `change refresh-claim` | +| `claim_dispositions` | `applied` `already-claimed` `contended` `failed` `run-context-invalid` `run-context-conflict` | `change claim` | | `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` | diff --git a/docs/superpowers/specs/2026-10-20-cut-implement-next-coordination-tax-context-after-claim-sess-design.md b/docs/superpowers/specs/2026-10-20-cut-implement-next-coordination-tax-context-after-claim-sess-design.md new file mode 100644 index 000000000..f3819436b --- /dev/null +++ b/docs/superpowers/specs/2026-10-20-cut-implement-next-coordination-tax-context-after-claim-sess-design.md @@ -0,0 +1,132 @@ +# Stop implement-next tripping over its own bookkeeping — design + +Change 0360 — Stop implement-next tripping over its own bookkeeping + +## Why + +An implement-next run spends a steady share of its turns on bookkeeping between its own writes, not on the change. Change #360's stub (2026-08-27) listed about fifteen such costs. Most were fixed by later changes (see *Already fixed — do not rebuild*). What remains was measured on the last 15 `docket-implement-next` runs (transcripts from 2026-10-17 to 2026-10-20; 14 of them claimed a change): + +- **The revision the agent passes is the wrong one.** Each record write takes `--revision `. The claim's receipt carries `committed_revision`, which is the metadata **commit** id (`res.AppliedCommit`; ADR-0129 defines every `*_revision` result key as a commit id). The skill tells the agent the claim "returns the new record revision", so 13 of 14 claimed runs passed the commit id to `change.reconcile` and got a bare `contended`. +- **The documented way to re-read the revision refuses.** The agent then calls `context.implementation --id `, which refuses every in-progress change: `invalid-state` / `not-ready-not-proposed (state "in-progress")` (14 of 14 runs). `selectContextChange` runs `domain.ClaimEligibility` → `EvaluateReadiness`, which returns `ReadyNotProposed` for any non-`proposed` record. Yet two skill edits from 2026-10-06 (b559fd4d7, 440f16fae) route the post-plan and results-checkpoint re-reads through it. The skill's own named path also lists "a named resume of an in-progress change" as going straight to `context.implementation --id`, so the documented resume entry hits the same refusal. +- **So every write is preceded by a hand-rolled lookup.** Runs settle on `docket repository prepare … >/dev/null; R=$(git -C .docket rev-parse HEAD:)` before each write — 6.7 `repository.prepare` calls per run on average. Since #549 every docket write already fast-forwards the local metadata checkout, and every typed read (`status`, `context.implementation`) fetches and pins origin itself, so nearly all of those re-syncs do nothing. +- **Four claim refreshes protect nothing.** The skill calls `change.refresh-claim` before and after the plan dispatch and the build. The lease's only consumer is reclaim (`domain.EvaluateReclaim`, the sweep's `maintenance.go` worklist, `change.reclaim`), and reclaim refuses whenever the recorded or conventional feature branch exists locally or remotely, or a live workspace or gate run exists. The branch exists from `workspace.prepare` onward, which runs minutes after claim; claim and reconcile both stamp `claimed_at` before that. Nothing else reads `claimed_at` (no board cell, no status field). Only implement-next calls the operation. +- **`evidence.verify` fails in 13 of 15 runs.** The skill says `evidence.record` "returns the immutable typed record" and then to run `evidence.verify --record `; agents save the JSON receipt and pass it, and verify answers `missing-evidence: the record file carries no build-evidence block` (it wants the receipt's `block` text). That call also repeats a check `pr.publish` and `change.mark-implemented` each make themselves (`evidence.Verify(req.EvidenceRecord, req.Head)` in `pr_publish.go` and `change_implemented.go`). +- **Smaller costs:** `docket schema change.reconcile` (no `--operation`) is refused as an unknown command — agents tried that form 10 times in 15 runs; Step 7 loads the 109-line `references/edge-paths.md` on every PR run for its last section only; the review-tier size bump diffs `origin/...HEAD`, so a stacked child counts its parent's lines; nothing says reconcile's log entry is the body only, or what to send when nothing changed; `repository.prepare` returns an always-empty `skills: {}` that nothing reads. + +The point is not to make a run skip safety checks. It is to stop the run failing on its own bookkeeping and re-deriving facts the system already keeps current. + +## Goals + +- A run's writes succeed first time: no self-inflicted `contended`, no `context.implementation` refusal for the run's own claimed change, no failed `evidence.verify`. +- About two `repository.prepare` calls per run instead of about seven. +- The resume entry the skill documents actually works. +- Every skill sentence about receipts, leases, re-syncs, and evidence matches what the binary does. + +## Non-goals and anti-goals + +- **No new receipt field.** Considered and rejected at grooming: the run looks the revision up instead (see 1). A `record_revision` field would save one local read per write, but it adds a new term (the key `revision` already means a commit id in run-tracker results, per ADR-0129) for a protection nothing needs. +- **No conflict checks removed.** Every write keeps its exact-revision check and exact-lease push. Claim eligibility, stacked-base resolution, and "no metadata writes on the feature branch" are unchanged. Accepted at grooming: because the run looks the revision up just before each post-claim write (1), that check guards the moment between the lookup and the write, not everything since the run's previous write. That is what today's runs already do by hand, and nothing else writes an in-progress record without changing its status (which reconcile, halt, and mark-implemented refuse) or moving it (kill), while claim and the run tracker prevent a second run on the same change. +- **No Go `docket implement` driver.** The fixes below remove the busywork a driver was meant to hide. +- **No gate "couldn't run" result.** Exit 126/127 under `/bin/sh -c` still reads `FAILED`. The stub's trigger (agent-supplied gate argv) no longer exists: owners take no argv since #374/#489. Out of scope until it is seen again. +- **No change to the parent's check of the plan-writer's work.** A dispatched agent's "done" is not proof; the check is one read and stays. +- **No change to `docket config --repo-dir`'s local-config lookup** (it reads the given folder, not the main checkout). Not hitting any run today; left out deliberately. +- **No change to selection.** `context.implementation` with no `--id` still selects only build-ready `proposed` changes. + +## Design + +### 1. Revision lookups: read the local copy before each write + +Before every write to its own change record after the claim — `change.reconcile`, `change.halt`, `change.kill` on a reconcile-kill, `workspace.prepare` (which compares `--revision` without writing), the revision handed to the plan-writer for its `change.attach-plan`, the producing-change revision handed to `docket-adr` (see 6a), each `change.attach-results` checkpoint, and `change.mark-implemented` — the run reads the record's current revision from the local metadata checkout, in the same shell call as the write (or immediately before a dispatch that carries it): + +``` +R=$(git -C rev-parse HEAD:) +``` + +`` is the change's `path` from the pre-claim bundle; it does not move while the change is active. The skill states plainly that every receipt's `committed_revision` is the commit id and is never a `--revision` value, and removes the sentences saying claim and refresh "return the new record revision". + +**On `contended`:** re-sync once (`repository.prepare`), look the revision up again, and retry the write once — except `change.reconcile`, which keeps its existing rule (re-read fresh context and re-author the request, since its content depends on the record). A second `contended` follows the step's existing stop rule. This covers the rare case where #549's best-effort follow left the local checkout behind (dirty, ahead, or diverged), and it guards the same lookup-to-write window the non-goals accept. + +The claim itself still uses the revision from the pre-claim bundle, as today. A resume (`change.resume-halted`) uses the revision from the context bundle (see 2). + +### 2. `context.implementation --id` serves the run's in-progress change + +With an explicit `--id` naming an `in-progress` change, `context.implementation` returns the normal bundle instead of refusing: + +- `change` (path, source, revision, summary), `spec`, `related`, `effective_base`, `adrs`, `learnings`, `workflow`, `warnings` — computed as for a proposed change. +- `workflow.feature_branch` carries the recorded `branch:` for an in-progress change (today it is always the branch a claim *would* mint, `domain.MintBranch(type, branch_prefix, slug)`, pinned by `TestContextImplementationFeatureBranchHonorsMintPrefix`; keep that for proposed changes and update the field comment, which says the context is produced before the claim). +- `halt.run_halted` reports the `## Run halted` marker. Today it is readable only on a proposed record carrying a leftover marker (`TestContextImplementationReportsHalt`); the in-progress records that `change.halt` actually marks are refused. +- `readiness` and `claim_eligible: false` with `claim_refusal` carrying today's reason (`not-ready-not-proposed`). A plain named run on an in-progress change therefore reads "not claimable" from the bundle and ends exactly as it does now (surfaced refusal, `drained`); only a resume proceeds. +- Add the record's `claimed_at` and `reconciled` values if the builder finds the resume path needs them from the bundle rather than the source bytes (the source bytes already carry both — builder's call). + +Every other non-`proposed` status (`blocked`, `deferred`, `implemented`, `stacked-merged`, `done`, `killed`) refuses exactly as today, and a `proposed` change keeps today's readiness refusals. No `--id`: unchanged. Update the code comment "The explicit change must be claimable exactly as a claim requires" to state the new rule. + +Skill side: the named path's documented resume entry now works as written; the post-plan and results-checkpoint "re-read via `context.implementation`" sentences become the local lookup from 1 (one rule for every post-claim revision). + +### 3. Delete the claim refreshes and `change.refresh-claim` + +- Remove every `change.refresh-claim` call from `docket-implement-next` (Step 4 before the plan dispatch and after it, Step 5 before and after the build) and from `references/results-artifact.md` ("Refresh the claim … at each phase boundary"). +- Delete the operation: the `docket change refresh-claim` CLI command, its capability-catalog entry, its schema registration, `ChangeRefreshClaim` and the `refresh` branch of `changeClaimOp` in `internal/app/change_claim.go`, their tests, the glossary entry, and any install allow rule naming it (`internal/cli/install.go`). **Keep `domain.RefreshClaim`** (rename it if the builder prefers): `change.reconcile`'s claimed_at patch step and `change.resume-halted` both call it, and that stamping stays. Whole-repo grep for `refresh-claim` / `RefreshClaim` / `refresh_claim`; point-in-time records (archived changes, specs, plans) stay as written. Check `internal/repoguard/retired_vocabulary_test.go` — retire the token there if that guard's pattern calls for it. +- `claimed_at` is still stamped by `change.claim`, `change.reconcile`, and `change.resume-halted`, and cleared on leaving `in-progress`. Fix the wording to match: the convention's manifest comment (`claimed_at: … stamped at claim; refreshed at phase boundaries; …`); the field-write rule's "the transaction re-stamps `claimed_at` … on every mutation" (it does not: attach-* and mark-implemented leave it untouched) and its "the skill also refreshes the claim explicitly … around the long plan and build dispatches" sentence; the paragraph under SKILL.md's *Step postconditions* table saying rows 3, 4, 6 and 7 carry "the `claimed_at` re-stamp" (rows 4 and 7 never re-stamp); and the "stays `in-progress` with `claimed_at` refreshed" halt phrases (SKILL.md Step 5, `references/fix-pass.md`). +- The `reclaim.lease_ttl` key, `change.reclaim`, and the sweep's reclaim are unchanged. +- **Accepted at grooming — the cross-clone case.** `workspace.prepare` creates the feature branch locally; it reaches the remote only at `workspace.publish` (Step 7). From another clone, reclaim therefore sees no branch during plan and build, and only the lease protects the change. Without refreshes the lease runs from the reconcile stamp, so another clone could reclaim a running change only if the run took more than `reclaim.lease_ttl` (72h by default) between reconcile and publishing, and someone ran `change reclaim` there or had `reclaim.auto: true` (off by default). Runs take hours; a build that itself ran past the TTL was already exposed with refreshes. Folding a re-stamp into attach-plan/attach-results was considered and declined. + +### 4. Re-sync only where it matters + +`repository.prepare` runs: + +1. at startup (unchanged), and after `maintenance.preflight` on the selection path (unchanged); +2. once after any dispatched agent that writes the change record returns — the plan-writer (`change.attach-plan`) and `docket-adr` (`adr.record` with the producing change, 6a) — before the parent checks that agent's work from git (one rule for both); +3. once after a `contended` write, per 1; +4. on a contended claim, before re-selecting (unchanged). + +Remove the others: the Step 4 "local metadata tip must equal the remote tip" SHA check after claim (an `applied` receipt already proves the exact-lease push landed — reword postcondition row 2's "landed (local tip == remote tip)" to name the applied receipt), the "re-sync immediately before reading" the spec, the re-syncs around the build, and before each results checkpoint and its re-read of the results file. Typed reads fetch on their own; plain-file reads of `.docket` follow every docket write since #549. Keep one sentence in the skill saying why (so a later edit does not re-add them). + +### 5. Reconcile wording + +Step 3 says: when nothing changed (spec, stack base, related changes, and scope all hold), send `{id, revision, reconcile_log_entry}` with a one-line body such as "Unchanged against ``". Owned sections, spec sections, and relations are included only when reality requires a change. The `reconcile_log_entry` is the **body only** — the operation writes the `### YYYY-MM-DD` heading (`appendReconcileLog`); mirror the halt prose's "section body only" wording. No Go change. + +### 6. Evidence wording + +Step 6: `evidence.record`'s receipt carries the evidence as its `block` field. Write that text to a file; that file is the `--evidence` input for `pr.publish` and `change.mark-implemented`. Delete the standalone `evidence.verify` call after `evidence.record` — the record call already refuses anything but a `PASSED` drive at that head, and both consuming commands re-verify the bytes. "Repeat the record → verify chain" after review fixes becomes "repeat the record step". Keep the *Validate the build evidence* head check at the start of Step 6 as written. + +### 6a. docket-adr records the ADR number on the change itself + +`adr.record` already takes an optional producing change `{id, path, revision}` (`ADRProducingChange` in `internal/app/adr_ops.go`): when supplied, the same transaction checks that exact revision, appends the new id to the change's `adrs:`, and re-renders `## Artifacts`. The `docket-adr` skill already says to supply it from implement-next Step 6; implement-next never does, and instead writes `adrs:` with a second `change.reconcile`. + +Step 6 now looks the revision up (1) and passes `{id, path, revision}` in each `docket-adr` dispatch payload; `docket-adr` passes it through as the request's `change`. Delete the Step 6 "record that number in the change's `adrs:` relation through a `change.reconcile`" write. After the dispatch returns, re-sync once (4.2) and check that the returned number is in `adrs:` (postcondition row 6 is unchanged). A `contended` from `adr.record` is handled by the child's existing refusal posture; the parent re-syncs, looks the revision up again, and re-dispatches once, then follows Step 6's existing stop rule. Several ADRs in one run are dispatched one at a time, each with a fresh lookup. No Go change. + +### 7. Review size bump uses the change's own base + +Step 6's tier modifier ("more than 1500 changed lines … from `git diff --shortstat origin/...HEAD`") diffs against the change's resolved effective base instead: the bundle's `effective_base` — `origin/` for an ordinary change, the parent's branch for a stacked one (the same base `workspace.prepare` cut from). Skill prose only; there is no Go implementation of the rule. + +### 8. Leftovers riding along + +- **Delete `skills` from `repository.prepare`.** Remove `PrepareSkills`, the `Skills` field on `PrepareContext`, and its constructor line. The schema is reflected from `RepositoryPrepareResult` through its single registry row, so the descriptor follows the struct. Update the test that builds a populated `PrepareSkills` to prove the human output redacts it (`internal/cli/repository_test.go`). Nothing reads the field; config refuses every `skills.*` key. Keep that config-side refusal as it is. +- **Move PR-body assembly into Step 7.** Move the *PR-body assembly (Step 7)* section of `references/edge-paths.md` into SKILL.md Step 7 and drop Step 7's "read `references/edge-paths.md` now (blocking)" for it; edge-paths keeps its rare-edge sections and their conditional loads. +- **`docket schema `.** Accept one optional positional argument as the operation id, equivalent to `--operation `; both together must agree or refuse as invalid arguments. Update the catalog signature (`[] [--operation ]` or the house form) and the command help. + +## Already fixed — do not rebuild + +From the stub, now handled elsewhere: named runs skip the maintenance preflight (#448); build and finalize gates run the configured command as one `/bin/sh -c` string and take no argv (#374, #489); `evidence.record` reads the owner's own test command (#517); results land on the metadata branch, so they never stale evidence (#530); operational config reads `.docket.local.yml` from the main checkout; request schemas are authoritative and probes are not the discovery path (#399, #520, #521); dummy-mode, auto-capture, and gate-execution references are gone (#502); prepare output is one JSON line; reconcile never required section rewrites; build-worker prompts are already small (median about 1.1k characters). + +## Proof + +- **Go:** unit and integration tests for `context.implementation --id` on an in-progress change (bundle returned, `claim_eligible: false`, `claim_refusal: not-ready-not-proposed`, `feature_branch` set, `halt.run_halted` true when marked) and that every other non-proposed status still refuses; a mutation check (restore the old refusal → the new test reddens). Tests that `change.refresh-claim` is gone from the CLI, catalog, and schema registry. `repository.prepare` JSON has no `skills` key. `docket schema ` equals `docket schema --operation `, and a mismatch refuses. +- **Skills:** run `go generate ./internal/assets/` so the embedded copies match; existing skill guards stay green. Whole-repo grep shows no remaining `refresh-claim` instruction, no "returns the new record revision" claim, no `evidence.verify` call in implement-next, and no Step 6 `change.reconcile` writing `adrs:`; the `docket-adr` dispatch payload names the producing change. +- **Whole suite** at the build gate, as always. +- **After merge (optional, for the human):** re-run the transcript tally used for this spec on the next several implement-next runs; expect no self-inflicted `contended`, no context refusal, no failed `evidence.verify`, and about two prepares per run. + +## Decisions worth an ADR + +- `context.implementation --id` serves the run's in-progress change; selection stays proposed-only (amends the "claimable exactly as a claim requires" contract). +- The claim lease is stamped only by claim, reconcile, and resume-halted; there is no explicit refresh, because reclaim already refuses while a branch or workspace exists. +- Post-claim revisions are looked up from the local metadata checkout, not carried in receipts; the exact-revision check guards the lookup-to-write window. + +The builder decides which of these need an ADR through the normal Step 6 path. + +## Left to the builder + +- Exact wording and placement of every skill edit, within the rules above. +- Whether `claimed_at`/`reconciled` join the context bundle (2). +- How `docket schema` spells the positional argument in its signature and help. +- Test placement and names. diff --git a/internal/app/adr_ops.go b/internal/app/adr_ops.go index 1a4f761ef..ae114ba2f 100644 --- a/internal/app/adr_ops.go +++ b/internal/app/adr_ops.go @@ -454,7 +454,8 @@ func validateADRReferences(relatesTo []int, snap domain.Snapshot) []domain.Findi Severity: domain.SeverityError, Entity: domain.EntityRef{Kind: domain.EntityADR}, Field: "relates_to", - Detail: map[string]string{"reference": fmt.Sprintf("%d", id)}, + Related: []domain.EntityRef{{Kind: domain.EntityADR, ID: id}}, + Detail: map[string]string{"lookup": "absent"}, }) } } diff --git a/internal/app/adr_ops_test.go b/internal/app/adr_ops_test.go index 6491ab7fd..d8c171f65 100644 --- a/internal/app/adr_ops_test.go +++ b/internal/app/adr_ops_test.go @@ -4,6 +4,7 @@ import ( "context" "encoding/json" "github.com/danielhanold/docket/internal/render" + "github.com/danielhanold/docket/internal/reposetup" "github.com/danielhanold/docket/internal/repository/transaction" "strings" "testing" @@ -185,6 +186,16 @@ func TestADRRecordPlanRefusesDanglingRelatesTo(t *testing.T) { if !hasDomainFindingCode(opRes.Findings, "adr-dangling-reference") { t.Errorf("missing adr-dangling-reference finding: %v", opRes.Findings) } + // The rendered text names the missing ADR, never a placeholder change. + for _, f := range opRes.Findings { + if f.Code != "adr-dangling-reference" { + continue + } + msg := explainValidation(f, reposetup.RecordLocator{Checkout: ".docket"}).Message + if !strings.Contains(msg, "ADR 0999") || strings.Contains(msg, "change 0000") { + t.Errorf("dangling relates_to message does not name ADR 0999: %q", msg) + } + } } func TestADRRecordPlanRecordContent(t *testing.T) { diff --git a/internal/app/change_claim.go b/internal/app/change_claim.go index b385fc867..2ac6b9f86 100644 --- a/internal/app/change_claim.go +++ b/internal/app/change_claim.go @@ -17,13 +17,14 @@ import ( "github.com/danielhanold/docket/internal/repository/transaction" ) -// This file is the `change claim` and `change refresh-claim` planning -// operations: two exact-revision metadata transitions that land a change's claim -// fields and every affected v1-owned derived view (the change record's owned -// lifecycle fields, its refreshed updated date, its re-rendered artifact block, -// and the inline board) as one validated atomic transaction. The domain owns -// legality: domain.Claim and domain.RefreshClaim decide whether the current -// status may take the transition and yield the exact FieldChanges to apply. +// This file is the `change claim` planning operation: an exact-revision +// metadata transition that lands a change's claim fields and every affected +// v1-owned derived view (the change record's owned lifecycle fields, its +// refreshed updated date, its re-rendered artifact block, and the inline board) +// as one validated atomic transaction. The domain owns legality: domain.Claim +// decides whether the current status may take the transition and yields the +// exact FieldChanges to apply. The lease is re-stamped only by claim, +// change.reconcile, and change.resume-halted. // // Claim additionally re-proves eligibility INSIDE the transaction against the // attempt's own fresh snapshot — proposed, uniquely identified, build-ready, @@ -35,17 +36,12 @@ import ( // Claim carries an idempotency key derived from its own (id, revision) request so // a lost response replays the original applied receipt as `already-claimed` // rather than allocating a second claim; a foreign edit that moved the record -// fails the exact-revision expectation as `contended`. Refresh is a small -// non-keyed exact-revision transaction — a revision mismatch is `contended`, which -// instructs the caller to stop, never to overwrite a newer record. Neither -// operation clears or steals an expired claim; reclaim is 0316. +// fails the exact-revision expectation as `contended`. A claim never clears or +// steals an expired claim; reclaim is 0316. -// The operation keys the two claim transitions record in their result envelopes -// and transaction trailers. -const ( - OperationChangeClaim = "change.claim" - OperationChangeRefreshClaim = "change.refresh-claim" -) +// OperationChangeClaim is the operation key the claim transition records in its +// result envelope and transaction trailer. +const OperationChangeClaim = "change.claim" // The closed set of claim dispositions a result may carry. `applied` is a fresh // claim; `already-claimed` is an idempotent replay of this exact request's own @@ -71,9 +67,9 @@ const ( ClaimDispositionRunContextConflict = "run-context-conflict" ) -// ChangeClaimRequest is the closed, caller-supplied request for one claim or -// refresh-claim. ID names the change; Revision pins the exact submitted record -// blob (the revision the authoritative context read reported). +// ChangeClaimRequest is the closed, caller-supplied request for one claim. ID +// names the change; Revision pins the exact submitted record blob (the revision +// the authoritative context read reported). type ChangeClaimRequest struct { ID int `json:"id" docket:"required"` Revision string `json:"revision" docket:"required"` @@ -126,11 +122,11 @@ type claimDigestPayload struct { RunContextHash string `json:"gate_context_hash"` } -// ChangeClaimResult is the protocol-v1 document `change claim` and -// `change refresh-claim` return. It embeds the envelope; the claim fields are -// populated on a successful apply or an idempotent replay, Disposition carries -// the closed claim disposition, and Findings carries every refusal or validation -// diagnostic (marshalled as [] never null). +// ChangeClaimResult is the protocol-v1 document `change claim` returns. It +// embeds the envelope; the claim fields are populated on a successful apply or +// an idempotent replay, Disposition carries the closed claim disposition, and +// Findings carries every refusal or validation diagnostic (marshalled as [] +// never null). type ChangeClaimResult struct { Envelope ID int `json:"id,omitempty"` @@ -326,62 +322,9 @@ func ChangeClaim(ctx context.Context, deps PlanningDeps, repoDir string, req Cha return out } -// ChangeRefreshClaim validates the request, pins authoritative context, and -// drives one small non-keyed exact-revision transaction that re-stamps the -// change's claimed_at (plus its refreshed updated date and derived views) and -// nothing else. It requires the change to still be in-progress at the exact -// submitted revision; a mismatch is `contended`, which stops the run rather than -// overwriting a newer record. -func ChangeRefreshClaim(ctx context.Context, deps PlanningDeps, repoDir string, req ChangeClaimRequest) ChangeClaimResult { - findings := dropFindingCode(validateLifecycleShape("id", req.ID, "", req.Revision), FCEmptyPath) - if len(findings) > 0 { - return newChangeClaimResult(OperationChangeRefreshClaim, ResultInvalidInput, ChangeClaimResult{Findings: findings}) - } - - pin, eff, inline, repo, pre := claimPreflight(ctx, deps, repoDir, OperationChangeRefreshClaim) - if pre != nil { - return *pre - } - - // Resolve the record's current path (the request carries only id + revision). - // Refresh consults no branch facts — it re-proves nothing about readiness — - // so the resolved facts are discarded. - recPath, _, _, terr := resolveClaimTarget(ctx, deps, pin, eff, req.ID, OperationChangeRefreshClaim) - if terr != nil { - return *terr - } - - op := changeClaimOp{ - opKey: OperationChangeRefreshClaim, - changeID: req.ID, - refresh: true, - eff: eff, - clock: deps.Clock, - ttlHours: eff.Reclaim.LeaseTTL.Value, - inline: inline, - link: linkContextOf(pin), - changesDir: eff.ChangesDir.Value, - } - - res, execErr := deps.Engine.Execute(ctx, transaction.Request{ - Repository: repo, - Remote: metadataRemote(pin.Layout), - TargetRef: metadataRef(pin.Layout), - Expected: []transaction.EntityExpectation{{ - Path: gitcli.RepoPath(recPath), - Revision: transaction.ExpectedRevision{Kind: transaction.RevisionBlob, ObjectID: gitcli.ObjectID(req.Revision)}, - }}, - Loader: newPlanningLoader(eff), - Scope: changeScope(req.ID, recPath, false), - Operation: op, - }) - - return claimResultFromOutcome(OperationChangeRefreshClaim, res, execErr) -} - -// claimPreflight performs the shared pre-transaction plumbing both claim -// transitions need: pin context, check the board surface, and discover the -// repository. It returns a non-nil result pointer for any preflight failure. +// claimPreflight performs the pre-transaction plumbing a claim needs: pin +// context, check the board surface, and discover the repository. It returns a +// non-nil result pointer for any preflight failure. func claimPreflight(ctx context.Context, deps PlanningDeps, repoDir, opKey string) ( pin StatusPin, eff config.Effective, inline bool, repo gitcli.Repository, refusal *ChangeClaimResult) { @@ -578,14 +521,13 @@ func decodeChangeClaimReceipt(b []byte) (changeClaimReceipt, bool) { return rec, true } -// changeClaimOp is the SemanticOperation the engine drives per attempt for both -// claim and refresh-claim. Every field is fixed before the transaction; the -// state-dependent work (the eligibility re-proof, the domain gate, field -// patching, rendering) re-runs from the attempt's own fresh state. +// changeClaimOp is the SemanticOperation the engine drives per attempt for a +// claim. Every field is fixed before the transaction; the state-dependent work +// (the eligibility re-proof, the domain gate, field patching, rendering) re-runs +// from the attempt's own fresh state. type changeClaimOp struct { opKey string changeID int - refresh bool facts domain.BranchFacts eff config.Effective clock transaction.Clock @@ -594,18 +536,17 @@ type changeClaimOp struct { link render.LinkContext changesDir string // runContextHash is the hashed run context this claim is bound to ("" - // for an ungated claim or a refresh). It is folded into the committed claim + // for an ungated claim). It is folded into the committed claim // receipt as the durable ownership proof (change 0407); the raw token never // reaches this struct. runContextHash string - // selection is the normalized claim selection ("" = unknown, and always "" - // for a refresh), folded into the committed claim receipt. + // selection is the normalized claim selection ("" = unknown), folded into the committed claim receipt. selection string } func (o changeClaimOp) Key() transaction.OperationKey { return transaction.OperationKey(o.opKey) } -// Plan re-proves eligibility (claim only) against the attempt's fresh snapshot, +// Plan re-proves eligibility against the attempt's fresh snapshot, // gates the transition through the domain action, patches the owned claim fields // plus the refreshed updated date, applies any domain-owned section removals, // re-renders the artifact block, and assembles the closed plan: the mutated @@ -622,26 +563,16 @@ func (o changeClaimOp) Plan(ctx context.Context, st transaction.AttemptState) (t return refuseLifecycle(FindingCode(reason), fmt.Sprintf("change %04d is not a single record in the current corpus", o.changeID)) } - var result domain.ActionResult - if o.refresh { - r, fail := domain.RefreshClaim(c, o.clock.Now()) - if fail != nil { - return refuseLifecyclePolicy(fail) - } - result = r - } else { - // In-transaction re-proof: proposed, uniquely identified, build-ready, and - // a resolved effective base — all from the attempt's own fresh snapshot. - // Stripping this line lets an ineligible change be claimed on stale facts; - // the refusal table mutation-tests exactly that. - if fail := domain.ClaimEligibility(snap, c, o.facts); fail != nil { - return refuseLifecyclePolicy(fail) - } - r, fail := domain.Claim(c, o.clock.Now()) - if fail != nil { - return refuseLifecyclePolicy(fail) - } - result = r + // In-transaction re-proof: proposed, uniquely identified, build-ready, and + // a resolved effective base — all from the attempt's own fresh snapshot. + // Stripping this line lets an ineligible change be claimed on stale facts; + // the refusal table mutation-tests exactly that. + if fail := domain.ClaimEligibility(snap, c, o.facts); fail != nil { + return refuseLifecyclePolicy(fail) + } + result, fail := domain.Claim(c, o.clock.Now()) + if fail != nil { + return refuseLifecyclePolicy(fail) } src, ok := st.State.Sources[c.Path()] @@ -705,10 +636,8 @@ func (o changeClaimOp) Plan(ctx context.Context, st transaction.AttemptState) (t } if o.inline { - // A refresh re-stamps only claimed_at and the updated date — neither is - // board-visible — so includeBoard's declare-only-when-changed shape can - // render byte-identical to the committed board and correctly declare no - // board mutation. + // includeBoard declares a board mutation only when the re-render differs + // from the committed board. boardPath := path.Join(o.changesDir, "BOARD.md") if err := includeBoard(ctx, st.Tree, boardPath, candidate, boardUnrenderable(st.State, o.changesDir), boardPresentation(o.eff), &files); err != nil { return transaction.MutationPlan{}, transaction.OperationResult{}, fmt.Errorf("change claim: %w", err) @@ -731,9 +660,6 @@ func (o changeClaimOp) Plan(ctx context.Context, st transaction.AttemptState) (t } subject := fmt.Sprintf("change %04d claimed", o.changeID) - if o.refresh { - subject = fmt.Sprintf("change %04d claim refreshed", o.changeID) - } return transaction.MutationPlan{ Files: files, CommitSubject: subject, diff --git a/internal/app/change_claim_integration_test.go b/internal/app/change_claim_integration_test.go index 884a106cb..f460e77d7 100644 --- a/internal/app/change_claim_integration_test.go +++ b/internal/app/change_claim_integration_test.go @@ -14,7 +14,6 @@ import ( "path" "strings" "testing" - "time" ) // TestIntegrationRecordOpsClaimTransactionTargetsPinnedMetadataLayout pins the @@ -315,7 +314,6 @@ func TestIntegrationRecordOpsChangeClaimUnrelatedInvalidRecordProgress(t *testin unrelatedBrokenPath: unrelatedBrokenBytes, }) node := planningDepsFor(t, repo.invocation) - later := planningDepsForClock(t, repo.invocation, fixedClock{t: time.Date(2026, 8, 17, 12, 0, 0, 0, time.UTC)}) ctx := context.Background() claim := ChangeClaim(ctx, node.deps, node.dir, ChangeClaimRequest{ID: id, Revision: blobRevisionAt(t, repo.origin, "docket", recPath)}) @@ -342,14 +340,6 @@ func TestIntegrationRecordOpsChangeClaimUnrelatedInvalidRecordProgress(t *testin if !strings.Contains(board, "| `"+unrelatedBrokenPath+"` | unclosed-frontmatter |") { t.Errorf("board lacks the repair notice naming the unrelated record:\n%s", board) } - - refresh := ChangeRefreshClaim(ctx, later.deps, later.dir, ChangeClaimRequest{ID: id, Revision: blobRevisionAt(t, repo.origin, "docket", recPath)}) - if refresh.Result != ResultApplied { - t.Fatalf("refresh-claim beside an unrelated unparseable record = %q (disposition %q findings %v), want applied", - refresh.Result, refresh.Disposition, refresh.Findings) - } - assertAppliedSurfacesUnrelated(t, refresh) - assertUnrelatedBrokenIntact(t, repo) } // TestIntegrationRecordOpsChangeClaimUnrelatedDependentsOfBrokenProgress is the canonical real-world @@ -448,30 +438,6 @@ func TestIntegrationRecordOpsChangeClaimUnrelatedInvalidRecordRefusals(t *testin } } -func TestIntegrationRecordOpsChangeRefreshClaimUnrelatedInvalidRecordRefusals(t *testing.T) { - requireRealGit(t) - const id = 3 - recPath := groomPath(id, "widget") - src := lifecycleChange(id, "widget", "in-progress") - for _, c := range unrelatedRefusalCases(t, id, recPath, src, lifecycleChange(id, "dupe", "in-progress")) { - t.Run(c.name, func(t *testing.T) { - repo := newWorkingRepo(t, c.files) - node := planningDepsFor(t, repo.invocation) - tip := originTip(t, repo.origin, "docket") - - res := ChangeRefreshClaim(context.Background(), node.deps, node.dir, - ChangeClaimRequest{ID: id, Revision: blobRevisionAt(t, repo.origin, "docket", recPath)}) - if res.Result == ResultApplied { - t.Fatalf("refresh-claim applied despite %s; want a refusal", c.name) - } - assertRefusalBeyondUnrelated(t, res.Disposition, res.Findings) - if got := originTip(t, repo.origin, "docket"); got != tip { - t.Errorf("a refused refresh-claim moved the metadata branch %s -> %s", tip, got) - } - }) - } -} - // TestIntegrationRecordOpsClaimResumeContextRefusedBeforeReserve: a `run start --resume` start pre-binds // the resumed change as AttributedID and never gets a claim binding (change 0463). // A claim under that context, for the resumed change itself or for any other change, diff --git a/internal/app/change_claim_test.go b/internal/app/change_claim_test.go index 883bed896..d25f1f9bf 100644 --- a/internal/app/change_claim_test.go +++ b/internal/app/change_claim_test.go @@ -60,81 +60,12 @@ func baseClaimOp(surfaces []string, id int, facts domain.BranchFacts) changeClai } } -func baseRefreshOp(surfaces []string, id int) changeClaimOp { - op := baseClaimOp(surfaces, id, domain.BranchFacts{}) - op.opKey = OperationChangeRefreshClaim - op.refresh = true - return op -} - // --- TestChangeClaimApplies ------------------------------------------------ // --- TestChangeClaimRefusals ----------------------------------------------- // --- TestChangeClaimRetryConvergence --------------------------------------- -// --- TestChangeRefreshClaimStampsOnly -------------------------------------- - -// --- TestChangeRefreshClaimSkipsUnchangedBoard ------------------------------ - -// TestChangeRefreshClaimSkipsUnchangedBoard: a refresh re-stamps only -// claimed_at and updated — neither is board-visible — so its board re-render -// can be byte-identical to the committed BOARD.md. Declaring an unchanged -// path trips the engine's verify-delta guard ("a declared path is not an -// actual change") and fails the whole refresh (change 0335), so the plan must -// declare the board only when it truly changes the tree: absent -> create, -// differing -> replace, byte-identical -> not declared at all. -func TestChangeRefreshClaimSkipsUnchangedBoard(t *testing.T) { - recPath := groomPath(3, "widget") - src := lifecycleChange(3, "widget", "in-progress") - const boardPath = "docs/changes/BOARD.md" - - // Pass 1: no committed board. The refresh must still declare the board as - // a create — and its declared bytes are the canonical render for this - // corpus at the fixed test clock, which seeds the byte-identical case. - plan, opRes := claimPlanFor(t, map[string]string{recPath: src}, baseRefreshOp([]string{"inline"}, 3)) - if opRes.Refused { - t.Fatalf("unexpected refusal: %v", opRes.Findings) - } - assertPlanPaths(t, plan, map[string]transaction.MutationKind{ - recPath: transaction.MutationReplace, - boardPath: transaction.MutationCreate, - }) - var boardBytes []byte - for _, f := range plan.Files { - if string(f.Path) == boardPath { - boardBytes = f.Bytes - } - } - if len(boardBytes) == 0 { - t.Fatal("absent-board refresh declared no board bytes") - } - - t.Run("byte-identical committed board is not declared", func(t *testing.T) { - files := map[string]string{recPath: src, boardPath: string(boardBytes)} - plan, opRes := claimPlanFor(t, files, baseRefreshOp([]string{"inline"}, 3)) - if opRes.Refused { - t.Fatalf("unexpected refusal: %v", opRes.Findings) - } - // Exactly the record — a declared-but-unchanged board is the 0335 bug. - assertPlanPaths(t, plan, map[string]transaction.MutationKind{ - recPath: transaction.MutationReplace, - }) - }) - - t.Run("stale committed board is still declared", func(t *testing.T) { - files := map[string]string{recPath: src, boardPath: "# Backlog\n\nstale\n"} - plan, opRes := claimPlanFor(t, files, baseRefreshOp([]string{"inline"}, 3)) - if opRes.Refused { - t.Fatalf("unexpected refusal: %v", opRes.Findings) - } - assertPlanPaths(t, plan, map[string]transaction.MutationKind{ - recPath: transaction.MutationReplace, - boardPath: transaction.MutationReplace, - }) - }) -} - func TestClaimResultFromOutcomeFailedCarriesCause(t *testing.T) { execErr := &transaction.Failure{ Stage: transaction.StageVerifyDelta, @@ -143,7 +74,7 @@ func TestClaimResultFromOutcomeFailedCarriesCause(t *testing.T) { } res := transaction.Result{Disposition: transaction.DispositionFailed} - out := claimResultFromOutcome(OperationChangeRefreshClaim, res, execErr) + out := claimResultFromOutcome(OperationChangeClaim, res, execErr) if out.Result != ResultInvalidState { t.Fatalf("result = %q, want %q", out.Result, ResultInvalidState) diff --git a/internal/app/change_integration_test.go b/internal/app/change_integration_test.go index 1317974c0..6157c6a6e 100644 --- a/internal/app/change_integration_test.go +++ b/internal/app/change_integration_test.go @@ -2763,77 +2763,6 @@ func TestIntegrationChangeAuthoringReconcileContention(t *testing.T) { }) } -// TestChangeRefreshClaimStampsOnly proves refresh re-stamps claimed_at (and the -// updated date) and nothing else, requires in-progress, and reports a revision -// mismatch as contended — the stop-don't-overwrite instruction. -func TestIntegrationChangeAuthoringRefreshClaimStampsOnly(t *testing.T) { - recPath := groomPath(3, "widget") - - t.Run("stamps claimed_at and updated only", func(t *testing.T) { - // An in-progress record with an older claimed_at and an unknown frontmatter - // key and unknown body section that must both survive untouched. - src := lifecycleChange(3, "widget", "in-progress") - src = strings.Replace(src, "trivial: false\n", "trivial: false\ncustom_field: 'survives'\n", 1) - src += "\n## Custom notes\n\nUnknown section survives.\n" - files := map[string]string{recPath: src} - - plan, opRes := claimPlanFor(t, files, baseRefreshOp(nil, 3)) - if opRes.Refused { - t.Fatalf("unexpected refusal: %v", opRes.Findings) - } - assertPlanPaths(t, plan, map[string]transaction.MutationKind{recPath: transaction.MutationReplace}) - - rec := lifecycleRecordBytes(t, plan, recPath) - if !strings.Contains(rec, "claimed_at: '2026-08-16T12:00:00Z'") { - t.Errorf("claimed_at not re-stamped:\n%s", rec) - } - if !strings.Contains(rec, "updated: '2026-08-16'") { - t.Errorf("updated not stamped:\n%s", rec) - } - // Untouched: status stays in-progress, branch/reconciled unchanged, and the - // unknown key and section survive byte-identically. - if !strings.Contains(rec, "status: in-progress") { - t.Errorf("status must stay in-progress unquoted (untouched):\n%s", rec) - } - if !strings.Contains(rec, "branch: feat/widget") { - t.Errorf("branch must be untouched:\n%s", rec) - } - if !strings.Contains(rec, "custom_field: 'survives'") { - t.Errorf("unknown frontmatter key did not survive:\n%s", rec) - } - if !strings.Contains(rec, "## Custom notes\n\nUnknown section survives.\n") { - t.Errorf("unknown body section did not survive:\n%s", rec) - } - }) - - t.Run("requires in-progress", func(t *testing.T) { - files := map[string]string{recPath: claimableChange(3, "widget")} // proposed - plan, opRes := claimPlanFor(t, files, baseRefreshOp(nil, 3)) - if !opRes.Refused { - t.Fatalf("refresh of a proposed change must refuse") - } - if !hasDomainFindingCode(opRes.Findings, "illegal-source-status") { - t.Errorf("missing illegal-source-status; got %v", opRes.Findings) - } - if len(plan.Files) != 0 { - t.Errorf("a refusal planned %d files, want 0", len(plan.Files)) - } - }) - - t.Run("revision mismatch is contended", func(t *testing.T) { - repoDir := newWorkingRepo(t, nil).invocation - engine := &recordingEngine{result: transaction.Result{Disposition: transaction.DispositionContended}} - reader := &fakeReader{pin: mainModePin([]string{"inline"}), corpus: []StatusBlob{changeBlob(3, "widget", "feat", "high", "")}} - deps := PlanningDeps{Client: newGitClient(t), Engine: engine, Reader: reader, Clock: testClock()} - - res := ChangeRefreshClaim(context.Background(), deps, repoDir, ChangeClaimRequest{ID: 3, Revision: "9999999999999999999999999999999999999999"}) - - if res.Result != ResultContended || res.Disposition != ClaimDispositionContended { - t.Fatalf("result=%q disposition=%q, want contended/contended", res.Result, res.Disposition) - } - }) -} - // TestRelinkAdoptPRHeadPinsExactRevision proves the transaction pins the approved // revision exactly, keying the relink op on the exact record blob. func TestIntegrationChangeRuntimeRelinkAdoptPRHeadPinsExactRevision(t *testing.T) { diff --git a/internal/app/claim_workflow_git_test.go b/internal/app/claim_workflow_git_test.go index aaae49d7c..646fbb495 100644 --- a/internal/app/claim_workflow_git_test.go +++ b/internal/app/claim_workflow_git_test.go @@ -40,12 +40,10 @@ func buildReadyChange(id int, slug string) string { // --- attach-plan lands change record + board in ONE metadata commit ---------- -// --- 0335: refresh-claim succeeds when the re-rendered board is unchanged --- - -// planningDepsForClock is planningDepsFor with an explicit clock, so a refresh -// run can happen at a later wall time than the claim that preceded it against the -// same origin — the record's claimed_at/updated then genuinely change while the -// inline board (which shows none of those fields) re-renders byte-identical. +// planningDepsForClock is planningDepsFor with an explicit clock, so a +// reconcile can run at a later wall time than the claim that preceded it against +// the same origin — the record's claimed_at/updated then genuinely change while +// the inline board (which shows none of those fields) re-renders byte-identical. func planningDepsForClock(t *testing.T, dir string, clock transaction.Clock) realNode { t.Helper() client := newGitClient(t) diff --git a/internal/app/derived_views.go b/internal/app/derived_views.go index b54a324b5..1081666a9 100644 --- a/internal/app/derived_views.go +++ b/internal/app/derived_views.go @@ -150,7 +150,7 @@ func renderCanonicalADRIndex(snap domain.Snapshot, unrenderable []render.BoardUn // kill, lifecycle, mark-implemented, reclaim, relink, closeout) always render a // board that differs from the committed one, so the board is always declared — // as a create when BOARD.md is absent, a replace otherwise. Operations whose -// edits are NOT board-visible (attach, claim refresh, reconcile, clear-block via +// edits are NOT board-visible (attach, reconcile, clear-block via // planInlineBoard) can render a board byte-identical to the committed one; the // transaction engine's verify-delta refuses a declared path that is not an // actual change ("a declared path is not an actual change"), so those must skip diff --git a/internal/app/derived_views_test.go b/internal/app/derived_views_test.go index 767f0fb8a..754df737e 100644 --- a/internal/app/derived_views_test.go +++ b/internal/app/derived_views_test.go @@ -189,7 +189,7 @@ func TestIncludeBoardReplacesWhenBoardPresentAndDiffers(t *testing.T) { // TestIncludeBoardSkipsWhenByteIdentical proves the declare-only-when-changed // shape: when the committed board already equals the canonical render (the -// not-board-visible mutations: attach, claim refresh, reconcile, clear-block), +// not-board-visible mutations: attach, reconcile, clear-block), // no board mutation is declared, so the engine's verify-delta does not refuse. func TestIncludeBoardSkipsWhenByteIdentical(t *testing.T) { snap, boardPath, _, want := derivedViewsSnapshot(t) diff --git a/internal/app/implementation_context.go b/internal/app/implementation_context.go index c16badd3b..37aac7e20 100644 --- a/internal/app/implementation_context.go +++ b/internal/app/implementation_context.go @@ -279,7 +279,7 @@ func ContextImplementation(ctx context.Context, deps PlanningDeps, repoDir strin return newContextResult(result, reason, err.Error(), nil) } - selected, refusal := selectContextChange(snap, facts, req) + selected, claimRefusal, refusal := selectContextChange(snap, facts, req) if refusal != nil { return *refusal } @@ -321,7 +321,8 @@ func ContextImplementation(ctx context.Context, deps PlanningDeps, repoDir strin Spec: specEntity, Related: relatedSummaries(snap, selected), Readiness: string(domain.EvaluateReadiness(snap, selected, facts).Kind), - ClaimEligible: true, + ClaimEligible: claimRefusal == "", + ClaimRefusal: claimRefusal, Halt: ContextHalt{ RunHalted: selected.HasRunHalted(), FinalizeBlocked: selected.HasFinalizeBlocked(), @@ -333,10 +334,7 @@ func ContextImplementation(ctx context.Context, deps PlanningDeps, repoDir strin BuildGate: eff.Build.Gate.Value, BuildTestCommand: eff.Build.TestCommand.Value, Remote: string(originRemote), - // The context is produced BEFORE the claim, so no branch is recorded yet; - // this is the branch the imminent claim will mint and record, through the - // one branch constructor (never a bare slug-derived name). - FeatureBranch: domain.MintBranch(selected.Type(), selected.BranchPrefix(), selected.Slug()), + FeatureBranch: contextFeatureBranch(selected), }, } bundle.Learnings, bundle.Warnings = learningEntries(snap) @@ -344,21 +342,39 @@ func ContextImplementation(ctx context.Context, deps PlanningDeps, repoDir strin return newContextResult(ResultApplied, "", "", bundle) } +// contextFeatureBranch names the change's feature branch. Before the claim no +// branch is recorded yet, so a proposed change previews the branch the imminent +// claim will mint and record, through the one branch constructor (never a bare +// slug-derived name). The run's own in-progress change (served by explicit id +// after its claim, change 0360) reports the branch the claim recorded; a +// malformed in-progress record with no recorded branch falls back to the mint +// rather than an empty name. +func contextFeatureBranch(c domain.Change) string { + if c.Status() == domain.StatusInProgress { + if b := c.Branch(); b.State == domain.FieldPresent && b.Value != "" { + return b.Value + } + } + return domain.MintBranch(c.Type(), c.BranchPrefix(), c.Slug()) +} + // selectContextChange resolves the change the bundle describes: the first // build-ready candidate under the selection policy, or the exact requested id. // A hold is a selection-only exclusion: no-id selection never returns a held // change, while an explicit id accepts one (ClaimEligibility admits on-hold). -// It returns a non-nil result pointer for every typed non-bundle outcome, and a -// claim-eligible change with a nil pointer on success. -func selectContextChange(snap domain.Snapshot, facts domain.BranchFacts, req ImplementationContextRequest) (domain.Change, *ImplementationContextResult) { +// It returns a non-nil result pointer for every typed non-bundle outcome. On +// success the pointer is nil and the middle return is the claim-refusal reason: +// "" for a claim-eligible change, or the ClaimEligibility reason for the run's +// own in-progress change, which an explicit id serves read-only. +func selectContextChange(snap domain.Snapshot, facts domain.BranchFacts, req ImplementationContextRequest) (domain.Change, string, *ImplementationContextResult) { if req.ID <= 0 { queue := domain.SelectQueue(snap, facts, domain.SelectionFilter{}) if len(queue) == 0 { r := newContextResult(ResultNoOp, ReasonContextNoCandidate, "no build-ready change is available to implement", nil) - return domain.Change{}, &r + return domain.Change{}, "", &r } - return queue[0], nil + return queue[0], "", nil } c, out := snap.Change(domain.ChangeID(req.ID)) @@ -366,20 +382,27 @@ func selectContextChange(snap domain.Snapshot, facts domain.BranchFacts, req Imp case domain.LookupAbsent: r := newContextResult(ResultInvalidInput, ReasonContextUnknownChange, fmt.Sprintf("no change %04d is present in the corpus", req.ID), nil) - return domain.Change{}, &r + return domain.Change{}, "", &r case domain.LookupAmbiguous: r := newContextResult(ResultInvalidState, ReasonContextAmbiguousID, fmt.Sprintf("more than one record claims change id %04d; refusing to choose", req.ID), nil) - return domain.Change{}, &r + return domain.Change{}, "", &r } - // The explicit change must be claimable exactly as a claim requires. + // The explicit change must be claimable exactly as a claim requires, with + // one exception: the run's own in-progress change (a resume, or a re-read + // after the claim) is served read-only, reporting claim_eligible: false with + // its ClaimEligibility reason, so the run can read its current record + // revision and recorded branch (change 0360). Every other status refuses. // ClaimEligibility keys on readiness and admits a held (on-hold) // change, since naming it overrides the hold; any other non-ready change // carries its exact reason token: an unusable identity is malformed, and // every other non-ready outcome maps to not-ready- (including // stack-base-unresolved for an unresolved effective base). if fail := domain.ClaimEligibility(snap, c, facts); fail != nil { + if c.Status() == domain.StatusInProgress { + return c, fail.Reason, nil + } reason := fail.Reason if reason == "not-ready-"+string(domain.ReadyInvalid) { reason = ReasonContextMalformed @@ -389,9 +412,9 @@ func selectContextChange(snap domain.Snapshot, facts domain.BranchFacts, req Imp result = ResultInvalidInput } r := newContextResult(result, reason, fail.Error(), nil) - return domain.Change{}, &r + return domain.Change{}, "", &r } - return c, nil + return c, "", nil } // contextBase renders a resolved effective base as the bundle's tagged view. diff --git a/internal/app/implementation_context_test.go b/internal/app/implementation_context_test.go index 80458178f..c4bbd76b8 100644 --- a/internal/app/implementation_context_test.go +++ b/internal/app/implementation_context_test.go @@ -312,6 +312,14 @@ func TestContextImplementationTypedAbsence(t *testing.T) { wantResult: ResultInvalidState, wantReason: "not-ready-" + string(domain.ReadyStackBaseUnresolved), }, + { + name: "in-progress is never auto-selected", + corpus: []StatusBlob{inProgressContextBlob("branch: 'hotfix/alpha'\n", "")}, + artifacts: map[string]StatusArtifact{sourceMetadata + "|" + specA: {Found: true, Data: []byte("x")}}, + req: ImplementationContextRequest{}, + wantResult: ResultNoOp, + wantReason: ReasonContextNoCandidate, + }, } for _, tc := range cases { @@ -677,3 +685,117 @@ func TestContextImplementationExplicitIDBuildsHeldChange(t *testing.T) { t.Errorf("readiness=%q claim_eligible=%v, want on-hold/true", got.Context.Readiness, got.Context.ClaimEligible) } } + +// inProgressContextBlob builds the run's own claimed (in-progress) change 0011 +// "alpha" with a spec at docs/changes/specs/spec-a.md. branchLine carries the +// recorded branch: line (or "" for a malformed record without one); tail is +// appended after the body (e.g. a "## Run halted" section). +func inProgressContextBlob(branchLine, tail string) StatusBlob { + src := "---\nid: 11\nslug: alpha\ntitle: Alpha\nstatus: 'in-progress'\npriority: high\ntype: feat\ncreated: 2026-01-02\nspec: docs/changes/specs/spec-a.md\n" + + branchLine + "claimed_at: '2026-01-03T00:00:00Z'\nreconciled: true\n---\n\nBody.\n" + tail + return StatusBlob{ + Kind: repository.KindChange, Location: repository.LocationActive, + Path: "docs/changes/active/0011-alpha.md", Revision: "v11", Data: []byte(src), + } +} + +// TestContextImplementationServesInProgressChange: an explicit id naming the +// run's own in-progress change (a resume, or a post-claim re-read) is served +// read-only — an applied bundle that reports claim_eligible: false with the +// not-proposed refusal, the current record revision, and the RECORDED feature +// branch rather than a fresh mint (change 0360). +func TestContextImplementationServesInProgressChange(t *testing.T) { + specA := "docs/changes/specs/spec-a.md" + artifacts := map[string]StatusArtifact{sourceMetadata + "|" + specA: {Found: true, Revision: "sa", Data: []byte("spec a\n")}} + run := func(t *testing.T, blob StatusBlob) ImplementationContextResult { + t.Helper() + fake := &fakeReader{pin: docketPin(t), corpus: []StatusBlob{blob}, artifactData: artifacts} + got := ContextImplementation(context.Background(), contextDeps(fake), "", ImplementationContextRequest{ID: 11}) + if got.Result != ResultApplied || got.Context == nil { + t.Fatalf("result=%q reason=%q message=%q", got.Result, got.Reason, got.Message) + } + return got + } + + got := run(t, inProgressContextBlob("branch: 'hotfix/alpha'\n", "")) + c := got.Context + if c.ClaimEligible { + t.Error("ClaimEligible = true, want false for an already-claimed change") + } + if want := "not-ready-" + string(domain.ReadyNotProposed); c.ClaimRefusal != want { + t.Errorf("ClaimRefusal = %q, want %q", c.ClaimRefusal, want) + } + if c.Readiness != string(domain.ReadyNotProposed) { + t.Errorf("Readiness = %q, want %q", c.Readiness, domain.ReadyNotProposed) + } + if c.Change.Revision != "v11" { + t.Errorf("Change.Revision = %q, want v11", c.Change.Revision) + } + if c.Change.Summary == nil || c.Change.Summary.Status != "in-progress" { + t.Errorf("Change.Summary = %+v, want status in-progress", c.Change.Summary) + } + if c.Workflow.FeatureBranch != "hotfix/alpha" { + t.Errorf("FeatureBranch = %q, want the recorded hotfix/alpha (not the mint feat/alpha)", c.Workflow.FeatureBranch) + } + if c.Halt.RunHalted { + t.Error("Halt.RunHalted = true on a record with no run-halted section") + } + + t.Run("run halted marker is readable", func(t *testing.T) { + got := run(t, inProgressContextBlob("branch: 'hotfix/alpha'\n", "\n## Run halted\n\n### 2026-08-14\n\nPaused.\n")) + if !got.Context.Halt.RunHalted { + t.Errorf("Halt.RunHalted = false, want true: %+v", got.Context.Halt) + } + }) + t.Run("no recorded branch falls back to mint", func(t *testing.T) { + got := run(t, inProgressContextBlob("", "")) + if got.Context.Workflow.FeatureBranch != "feat/alpha" { + t.Errorf("FeatureBranch = %q, want the minted feat/alpha", got.Context.Workflow.FeatureBranch) + } + }) +} + +// TestContextImplementationRefusesOtherNonProposedStatuses: serving an explicit +// id read-only is confined to in-progress; every other non-proposed status +// refuses exactly as before — no bundle, not-ready-not-proposed. +func TestContextImplementationRefusesOtherNonProposedStatuses(t *testing.T) { + specA := "docs/changes/specs/spec-a.md" + artifacts := map[string]StatusArtifact{sourceMetadata + "|" + specA: {Found: true, Data: []byte("x")}} + record := func(id int, slug, status, extra string, loc repository.RecordLocation, path string) StatusBlob { + src := fmt.Sprintf("---\nid: %d\nslug: %s\ntitle: Change %d\nstatus: '%s'\npriority: high\ntype: feat\ncreated: 2026-01-02\nspec: %s\n%s---\n\nBody.\n", + id, slug, id, status, specA, extra) + return StatusBlob{Kind: repository.KindChange, Location: loc, Path: path, Revision: fmt.Sprintf("v%d", id), Data: []byte(src)} + } + active := func(id int, slug string) string { return fmt.Sprintf("docs/changes/active/%04d-%s.md", id, slug) } + archived := func(id int, slug string) string { + return fmt.Sprintf("docs/changes/archive/2026-01-05-%04d-%s.md", id, slug) + } + cases := []struct { + name string + id int + blob StatusBlob + }{ + {"blocked", 31, record(31, "blk", "blocked", "blocked_by: 'x'\n", repository.LocationActive, active(31, "blk"))}, + {"deferred", 32, record(32, "dfr", "deferred", "", repository.LocationActive, active(32, "dfr"))}, + {"implemented", 33, record(33, "imp", "implemented", + "branch: 'feat/imp'\nclaimed_at: '2026-01-03T00:00:00Z'\nreconciled: true\nplan: docs/superpowers/plans/p.md\npr: 'https://example.com/pull/1'\n", + repository.LocationActive, active(33, "imp"))}, + {"done", 34, record(34, "dn", "done", "", repository.LocationArchive, archived(34, "dn"))}, + {"killed", 35, record(35, "kld", "killed", "", repository.LocationArchive, archived(35, "kld"))}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + fake := &fakeReader{pin: docketPin(t), corpus: []StatusBlob{tc.blob}, artifactData: artifacts} + got := ContextImplementation(context.Background(), contextDeps(fake), "", ImplementationContextRequest{ID: tc.id}) + if got.Result != ResultInvalidState { + t.Errorf("result = %q, want %q (reason %q)", got.Result, ResultInvalidState, got.Reason) + } + if got.Reason != "not-ready-not-proposed" { + t.Errorf("reason = %q, want not-ready-not-proposed", got.Reason) + } + if got.Context != nil { + t.Errorf("refusal fabricated a bundle: %+v", got.Context) + } + }) + } +} diff --git a/internal/app/repository_prepare.go b/internal/app/repository_prepare.go index 27e05e55b..e7a2c7e95 100644 --- a/internal/app/repository_prepare.go +++ b/internal/app/repository_prepare.go @@ -68,7 +68,6 @@ import ( // supported config.Effective finalize fields) // - supported build gate configuration → PrepareContext.Build (mirrors the // supported config.Effective build fields; independent of finalize — change 0374) -// - resolved workflow skill bindings → PrepareContext.Skills // - configuration diagnostics → PrepareContext.ConfigDiagnostics // OperationRepositoryPrepare is the operation key `repository prepare` records. @@ -124,19 +123,6 @@ type PrepareBuild struct { MaxAttempts int `json:"max_attempts"` } -// PrepareSkills carries the resolved workflow skill-role bindings. In Go v1 the -// skill roles are deferred capabilities: a valid repository leaves them unset, so -// these resolve to their empty defaults today. They are typed (never a generic -// map) so a later resolver fills named fields rather than reintroducing a stringly -// transport blob. -type PrepareSkills struct { - Brainstorm string `json:"brainstorm,omitempty"` - Plan string `json:"plan,omitempty"` - Build string `json:"build,omitempty"` - Review string `json:"review,omitempty"` - Finish string `json:"finish,omitempty"` -} - // PrepareContext is the closed typed context a workflow carries forward (spec // §Structured result). It is a closed struct derived from the consumer inventory: // no generic string map, no DOCKET_* names, and no shell-quoted or eval-shaped @@ -170,7 +156,6 @@ type PrepareContext struct { Finalize PrepareFinalize `json:"finalize"` Build PrepareBuild `json:"build"` - Skills PrepareSkills `json:"skills"` ConfigDiagnostics []string `json:"config_diagnostics,omitempty"` } @@ -568,9 +553,6 @@ func buildPrepareContext(cfg config.Effective, sc setupContext, f reposetup.Fact TestCommand: cfg.Build.TestCommand.Value, MaxAttempts: cfg.Build.MaxAttempts.Value, }, - // Skills roles are deferred capabilities in Go v1; a valid repository leaves - // them unset, so they resolve to their empty defaults today. - Skills: PrepareSkills{}, } } diff --git a/internal/app/runtracker_ownership_integration_test.go b/internal/app/runtracker_ownership_integration_test.go index ca78d1513..6b06244d2 100644 --- a/internal/app/runtracker_ownership_integration_test.go +++ b/internal/app/runtracker_ownership_integration_test.go @@ -239,7 +239,7 @@ func TestIntegrationRunFenceUnrelatedChurnDoesNotMoveOwnership(t *testing.T) { t.Fatalf("baseline verdict = %q, want %q", got, want) } - // Refresh id 3's claimed_at and priority (a real refresh-claim / groom edit + // Refresh id 3's claimed_at and priority (a real reconcile / groom edit // leaves the change complete), and add two sibling in-progress claims — exactly // the churn the pre-0407 before-set/run inference keyed on. refreshed := string(evidenced) diff --git a/internal/app/schema_registry.go b/internal/app/schema_registry.go index 48e6c6bfb..6af66b8f6 100644 --- a/internal/app/schema_registry.go +++ b/internal/app/schema_registry.go @@ -61,7 +61,6 @@ var operationBindings = []OperationBinding{ {ID: "change.mark-implemented", Request: nil, Result: ChangeLifecycleResult{}}, // ChangeMarkImplemented {ID: "change.reclaim", Request: nil, Result: ChangeReclaimResult{}}, // ChangeReclaim {ID: "change.reconcile", Request: ChangeReconcileRequest{}, Result: ChangeReconcileResult{}}, // ChangeReconcile - {ID: "change.refresh-claim", Request: nil, Result: ChangeClaimResult{}}, // ChangeRefreshClaim {ID: "change.relink", Request: nil, Result: RelinkResult{}}, // Relink {ID: "change.resume-halted", Request: nil, Result: HaltResult{}}, // ChangeResumeHalted {ID: "change.revive", Request: ChangeReviveRequest{}, Result: ChangeLifecycleResult{}}, // ChangeRevive diff --git a/internal/app/workflow_integration_test.go b/internal/app/workflow_integration_test.go index de13813fb..0bf942d78 100644 --- a/internal/app/workflow_integration_test.go +++ b/internal/app/workflow_integration_test.go @@ -1264,22 +1264,92 @@ func TestIntegrationWorkflowRepoReconcileIndependentWriterWins(t *testing.T) { } } -// TestRefreshClaimAppliesWhenBoardReRenderIsUnchanged: a refresh re-stamps a -// claimed record's claimed_at and updated fields (a real change to the record) -// and re-renders the inline board. The board's in-progress row shows only -// id/title/priority/type/spec/branch — none of which a refresh touches — so -// the re-render is byte-identical to the board the claim already committed. -// Pre-0335 the plan nonetheless DECLARED the board, and the engine's two-way -// actual-delta guard rejected it as "a declared path is not an actual change" -// (a *Failure at stage verify-delta), silently failing every such lease -// refresh. Post-fix the plan declares only the record, so the refresh applies: -// one metadata commit touching exactly the record, the lease re-stamped, the +// TestIntegrationWorkflowRepoContextServesClaimedChange: after a real claim, a +// fresh clone's context.implementation --id read of the now in-progress change +// is served (change 0360) rather than refused: claim_eligible is false with the +// not-proposed refusal, the bundle revision is exactly the record blob on origin +// (what `git rev-parse HEAD:` prints), and the feature branch is +// the branch: value the claim recorded. +func TestIntegrationWorkflowRepoContextServesClaimedChange(t *testing.T) { + requireRealGit(t) + const ( + id = 3 + slug = "widget" + ) + recPath := groomPath(id, slug) + for _, m := range planRepoModes() { + m := m + t.Run(m.name, func(t *testing.T) { + repo := m.build(t, map[string]string{ + recPath: buildReadyChange(id, slug), + fixtureSpecPath(slug): fixtureSpecFile(id, slug), + }) + ctx := context.Background() + + claimNode := planningDepsFor(t, cloneOrigin(t, repo.origin)) + pre := ContextImplementation(ctx, claimNode.deps, claimNode.dir, ImplementationContextRequest{ID: id}) + if pre.Result != ResultApplied || pre.Context == nil || !pre.Context.ClaimEligible { + t.Fatalf("pre-claim context read = %q (reason %q)", pre.Result, pre.Reason) + } + claim := ChangeClaim(ctx, claimNode.deps, claimNode.dir, ChangeClaimRequest{ID: id, Revision: pre.Context.Change.Revision}) + if claim.Result != ResultApplied || claim.Disposition != ClaimDispositionApplied { + t.Fatalf("claim = (%q, %q), want applied/applied (findings %v)", claim.Result, claim.Disposition, claim.Findings) + } + + readNode := planningDepsFor(t, cloneOrigin(t, repo.origin)) + got := ContextImplementation(ctx, readNode.deps, readNode.dir, ImplementationContextRequest{ID: id}) + if got.Result != ResultApplied || got.Context == nil { + t.Fatalf("post-claim context read = %q (reason %q, message %q), want applied", got.Result, got.Reason, got.Message) + } + c := got.Context + if c.ClaimEligible { + t.Error("post-claim ClaimEligible = true, want false") + } + if c.ClaimRefusal != "not-ready-not-proposed" { + t.Errorf("ClaimRefusal = %q, want not-ready-not-proposed", c.ClaimRefusal) + } + if want := blobRevisionAt(t, repo.origin, m.branch, recPath); c.Change.Revision != want { + t.Errorf("Change.Revision = %q, want the origin record blob %q", c.Change.Revision, want) + } + rec, ok := originFile(t, repo.origin, m.branch, recPath) + if !ok { + t.Fatalf("record %s missing from origin after claim", recPath) + } + recorded := "" + for _, line := range strings.Split(rec, "\n") { + if v, found := strings.CutPrefix(line, "branch: "); found { + recorded = strings.Trim(v, "'\"") + break + } + } + if recorded == "" { + t.Fatalf("claimed record carries no branch: line:\n%s", rec) + } + if c.Workflow.FeatureBranch != recorded { + t.Errorf("FeatureBranch = %q, want the recorded branch %q", c.Workflow.FeatureBranch, recorded) + } + }) + } +} + +// TestIntegrationWorkflowRepoReconcileAppliesWhenBoardReRenderIsUnchanged: a +// reconcile after a claim re-stamps the record's claimed_at and updated fields +// and flips reconciled (a real change to the record) and re-renders the inline +// board. The board's in-progress row shows only id/title/priority/type/spec/ +// branch — none of which a reconcile touches — so the re-render is +// byte-identical to the board the claim already committed. Declaring that +// unchanged board would trip the engine's two-way actual-delta guard ("a +// declared path is not an actual change", a *Failure at stage verify-delta) — +// the change 0335 bug, first seen on the since-deleted refresh-claim operation +// (change 0360 retargeted this test at reconcile, which now owns re-stamping the +// lease). The plan declares only the record, so the reconcile applies: one +// metadata commit touching exactly the record, the lease re-stamped, the // committed board untouched and still matching a fresh render. // -// The refresh runs a day after the claim (advanced clock) so the record +// The reconcile runs a day after the claim (advanced clock) so the record // genuinely changes; that isolates the board as the sole would-be // declared-but-unchanged path. -func TestIntegrationWorkflowRepoRefreshClaimAppliesWhenBoardReRenderIsUnchanged(t *testing.T) { +func TestIntegrationWorkflowRepoReconcileAppliesWhenBoardReRenderIsUnchanged(t *testing.T) { requireRealGit(t) const ( id = 3 @@ -1311,40 +1381,42 @@ func TestIntegrationWorkflowRepoRefreshClaimAppliesWhenBoardReRenderIsUnchanged( claimedRevision := blobRevisionAt(t, repo.origin, m.branch, recPath) - // Refresh a day later: claimed_at/updated genuinely change on the + // Reconcile a day later: claimed_at/updated genuinely change on the // record while the board re-renders byte-identical. - refreshNode := planningDepsForClock(t, cloneOrigin(t, repo.origin), advanced) - res := ChangeRefreshClaim(ctx, refreshNode.deps, refreshNode.dir, ChangeClaimRequest{ID: id, Revision: claimedRevision}) - if res.Result != ResultApplied || res.Disposition != ClaimDispositionApplied { - t.Fatalf("refresh = (%q, %q), want applied/applied (failure %+v, findings %v)", + reconcileNode := planningDepsForClock(t, cloneOrigin(t, repo.origin), advanced) + res := ChangeReconcile(ctx, reconcileNode.deps, reconcileNode.dir, ChangeReconcileRequest{ + ID: id, Revision: claimedRevision, ReconcileLogEntry: "Reconciled against current reality.\n", + }) + if res.Result != ResultApplied { + t.Fatalf("reconcile = (%q, %q), want applied (failure %+v, findings %v)", res.Result, res.Disposition, res.Failure, res.Findings) } if res.Revision == "" { - t.Fatal("applied refresh carried no committed revision") + t.Fatal("applied reconcile carried no committed revision") } - // The refresh commit touches exactly the record — the + // The reconcile commit touches exactly the record — the // byte-identical board was not declared, so it is not in the // commit's changed-path set. got := originCommitPaths(t, repo.origin, res.Revision) if strings.Join(got, ",") != recPath { - t.Errorf("refresh commit changed %v, want exactly [%s] (unchanged board must not be declared)", got, recPath) + t.Errorf("reconcile commit changed %v, want exactly [%s] (unchanged board must not be declared)", got, recPath) } // The lease actually moved to the advanced clock. final, ok := originFile(t, repo.origin, m.branch, recPath) if !ok { - t.Fatalf("record %s missing from origin after refresh", recPath) + t.Fatalf("record %s missing from origin after reconcile", recPath) } if !strings.Contains(final, "claimed_at: '2026-08-17T12:00:00Z'") { - t.Errorf("refresh did not re-stamp claimed_at:\n%s", final) + t.Errorf("reconcile did not re-stamp claimed_at:\n%s", final) } if !strings.Contains(final, "updated: '2026-08-17'") { - t.Errorf("refresh did not re-stamp updated:\n%s", final) + t.Errorf("reconcile did not re-stamp updated:\n%s", final) } // The committed board still matches a fresh render of the corpus. - assertBoardMatchesCommitted(t, repo.origin, m.branch, refreshNode.dir) + assertBoardMatchesCommitted(t, repo.origin, m.branch, reconcileNode.dir) }) } } diff --git a/internal/assets/embedded/manifest.json b/internal/assets/embedded/manifest.json index c5c14ef72..620715422 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:98ddce21935afa973ca1337ad84abbb3386c6ccd1a1cff03e2693392c1d83fe0", + "asset_set_id": "sha256:d89a536023d4ce4c601fe6fb1790ff898a747da0cad14ef4659bbd5fe54a8a40", "entries": [ { "path": ".docket.example.yml", @@ -273,8 +273,8 @@ "path": "skills/docket-adr/SKILL.md", "role": "skill", "mode": 420, - "size": 7758, - "sha256": "7420286e6fbd71001ca612e99a512627154e44af53cbea2e2cd85d144c893e21" + "size": 7871, + "sha256": "3bf888a57c967edb66d5caaddeafb3704b5e73dfd8fd0db70d2ca6169dd2d98e" }, { "path": "skills/docket-auto-groom/SKILL.md", @@ -322,8 +322,8 @@ "path": "skills/docket-convention/SKILL.md", "role": "skill", "mode": 420, - "size": 53532, - "sha256": "c53fb6037c675224b506f99373c8a71571b41af9b2ad9c79912b9d8c4d04ca66" + "size": 53504, + "sha256": "58bac591609e709cebcf9afd598737607924fb3c140351a8eee2e55f69c22f4d" }, { "path": "skills/docket-convention/references/agent-layer.md", @@ -378,29 +378,29 @@ "path": "skills/docket-implement-next/SKILL.md", "role": "skill", "mode": 420, - "size": 59299, - "sha256": "15b342ac83767c92a1a73c105e14fbedd03a47951b357b37dd87b54a02aad144" + "size": 60752, + "sha256": "dc8cf283ada6cfd4d7b00740bd688afad006c9f1183481674b75673303f69221" }, { "path": "skills/docket-implement-next/references/edge-paths.md", "role": "skill", "mode": 420, - "size": 8704, - "sha256": "a83e24ce2559df496643b2c79956cec0115a8b6c00768754335fb39ea168f930" + "size": 7214, + "sha256": "9cae52fff741fff7e0bc0fa9443ccb79018b8d1669f85a8439ae368c0185a7f1" }, { "path": "skills/docket-implement-next/references/fix-pass.md", "role": "skill", "mode": 420, - "size": 12497, - "sha256": "e52c26a900915c8eac7cbdeff9224decd5f9c7fbbe4c14f98a2ade6523c3fd36" + "size": 12416, + "sha256": "40a735e9b05c1ee3529b98751cda9a332c6b8bf4aa11f69051cc0e9b9931613a" }, { "path": "skills/docket-implement-next/references/results-artifact.md", "role": "skill", "mode": 420, - "size": 5071, - "sha256": "b7112b747ec1d24ed5d6a83ff4e537a507be4f60bab28679e540a744ca041937" + "size": 4899, + "sha256": "9581a92f684da771010a23a38f77b826c16e1ba651f4e5600547821c24333b61" }, { "path": "skills/docket-implement-next/results-template.md", diff --git a/internal/assets/embedded/tree/skills/docket-adr/SKILL.md b/internal/assets/embedded/tree/skills/docket-adr/SKILL.md index 9cda4fabb..112840a68 100644 --- a/internal/assets/embedded/tree/skills/docket-adr/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-adr/SKILL.md @@ -25,10 +25,10 @@ Invoke the `docket-convention` skill via the Skill tool first — unless already ### Create -Build the ADR as a JSON request and hand it to the record transaction on stdin: +Hand the record transaction a JSON request on stdin: ``` -adr.record --request - # resolve argv from the capability catalog +adr.record --request - --repo-dir --json # resolve argv from the capability catalog ``` The request object (`ADRRecordRequest`, decoded with `DisallowUnknownFields` — an unknown key is rejected) carries: @@ -37,11 +37,11 @@ The request object (`ADRRecordRequest`, decoded with `DisallowUnknownFields` — - `title` — the decision's title. - `context`, `decision`, `consequences`, `alternatives` — the ADR body sections. - `relates_to` — an array of existing ADR ids this decision relates to (optional; each id must resolve or the transaction refuses with `adr-dangling-reference`). -- `change` — the producing change as `{id, path, revision}` (optional; supply it when a change produces this ADR, e.g. `docket-implement-next` step 6). +- `change` — the producing change as `{id, path, revision}` (optional; supply it when a change produces this ADR). `docket-implement-next` step 6 supplies it in its dispatch payload; pass it through unchanged. One validated transaction lands atomically, in a single metadata commit: the next ADR number allocated (max `id:` + 1, 4-digit zero-pad `0024-…`), the new `-.md` record (`status: Accepted`, today's UTC `date:`, the optional `change:` back-link), graph validation, the re-rendered `/README.md` index, and — when `change` is supplied — that change's `adrs:` append and re-rendered `## Artifacts` block. There is **no** separate index commit and **no** hand-allocation, template-write, or manual conflict-checked-rename step: a typed conflict or refusal returns without writing anything, so re-read and retry the operation rather than patching the tree by hand. -**Return the number** — read the allocated ADR id from the operation's result envelope so the caller (e.g. `docket-implement-next` step 6) can cite it in the change's `adrs:` field. +**Return the number** — read the allocated ADR id from the operation's result envelope and return it. When `change` was supplied, the transaction has already appended the number to that change's `adrs:` — the caller only verifies it. **Where an ADR lives** — the ADR and its index live on the metadata branch; no ADR, change-tied or standalone, is copied to the integration branch. @@ -50,10 +50,10 @@ One validated transaction lands atomically, in a single metadata commit: the nex Never edit an `Accepted` ADR's body. To replace a decision, hand the replace transaction a JSON request on stdin: ``` -adr.supersede --request - # resolve argv from the capability catalog +adr.supersede --request - --repo-dir --json # resolve argv from the capability catalog ``` -(or the `adr.reverse` operation with `--request -` to reverse rather than supersede). The request object (`ADRReplaceRequest`, `DisallowUnknownFields`) carries: +(or `adr.reverse`, same flags, to reverse rather than supersede). The request object (`ADRReplaceRequest`, `DisallowUnknownFields`) carries: - `request_id` — the caller-chosen idempotency key (the outer key governs; the `successor`'s own `request_id` is ignored). - `target` — the ADR being replaced, as `{id, path, revision}`. The target must be `Accepted`, else the transaction refuses. diff --git a/internal/assets/embedded/tree/skills/docket-convention/SKILL.md b/internal/assets/embedded/tree/skills/docket-convention/SKILL.md index f67b32524..1deed7316 100644 --- a/internal/assets/embedded/tree/skills/docket-convention/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-convention/SKILL.md @@ -95,7 +95,7 @@ When dispatch is genuinely unavailable the kinds are **not** equivalent, so the |---|---|---| | **`inline` — deterministic** | the `docket-status` and `docket-adr` composition dispatches | Run the same work **inline** — a **first-class equivalent path**, neither a degradation nor a warning, because the contract is git state on the metadata branch, not an in-context return. Every obligation holds unchanged: re-sync before reading, derive from fresh origin, never adopt or commit another agent's uncommitted files. | | **`abstain` — adversarial** | the `docket-auto-groom-critic` gate | **Abstain**, per *Autonomous grooming*. Self-critique by the agent that drafted the spec is not an adversarial gate, and the abstain is a path that skill already owns. | -| **`halt` — discipline** | the **plan-writer dispatch**, the `build` role skill's required nested dispatches, the controller's own review-tier dispatch (the `docket-review` skill itself never dispatches), and the in-branch fix workers (which run the `build` role's own contract) | **`halt`** — the run stops: the change stays `in-progress` with `claimed_at` refreshed and the halt reason recorded through `change.halt`. **No new status, no new field** — the reclaim lease self-heals an abandoned claim. | +| **`halt` — discipline** | the **plan-writer dispatch**, the `build` role skill's required nested dispatches, the controller's own review-tier dispatch (the `docket-review` skill itself never dispatches), and the in-branch fix workers (which run the `build` role's own contract) | **`halt`** — the run stops: the change stays `in-progress` with the halt reason recorded through `change.halt`. **No new status, no new field** — the reclaim lease self-heals an abandoned claim. | **Outside the table — `no-fallback`.** `docket-finalize-change`'s two finalize-gate dispatches — `docket-rebase-resolver` and `docket-integration-repair` — sit **outside** this table rather than in a row of it, because their contract is an **in-context report** gating the merge, not git state on the metadata branch. Neither fallback can be borrowed for them: `inline`'s first-class-equivalent path presupposes a git-state transition to reproduce, and `halt` belongs to the workflow roles, and these dispatches are not a role. When dispatch is genuinely unavailable for either — established per the resolution rule above, never from a tool name — the posture is finalize's own pre-existing **abort-and-report**: the gate stops, the PR stays open, the change stays `implemented`, and the reason is recorded through the three channels `docket-finalize-change`'s failure reference owns. **Inline substitution is forbidden** for both, and that is the point of `no-fallback` rather than a table row: reconciling the conflict, or authoring the repair, inside the very agent that would then merge that work is the same self-approval shape `abstain` exists to avoid for the critic. @@ -194,7 +194,7 @@ branch: # minted / (or /) nam pr: # set when the PR is opened blocked_by: # free text; set only when status: blocked reconciled: false # set true after the just-in-time reconcile pass -claimed_at: # UTC ISO-8601 claim lease (YYYY-MM-DDTHH:MM:SSZ); stamped at claim; refreshed at phase boundaries; cleared on leaving in-progress +claimed_at: # UTC ISO-8601 claim lease (YYYY-MM-DDTHH:MM:SSZ); stamped by claim, reconcile, and resume-halted; cleared on leaving in-progress --- ``` 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 068061db5..d295618d6 100644 --- a/internal/assets/embedded/tree/skills/docket-implement-next/SKILL.md +++ b/internal/assets/embedded/tree/skills/docket-implement-next/SKILL.md @@ -26,7 +26,7 @@ Before anything else in this skill, invoke the `docket-convention` skill via the Run the convention's **startup check** (load the convention; run the capability bootstrap; run the `repository.prepare` operation with `--repo-dir --json` as its own Bash call; validate the protocol-v1 envelope and carry its typed context values forward as literals; act on the disposition). All bookkeeping in this skill (claim, reconcile, `status`, `pr:`, `plan:`, `adrs:`, the plan and results files, build evidence) lands in the metadata worktree (`metadata_worktree_path` in the `repository.prepare` context) on the metadata branch, pushed to the metadata remote (`metadata_remote`) immediately; only the spec copy and the code land on the feature branch. -**Named invocation — no maintenance preflight.** When this run was invoked with exactly **one explicit change id** — an initial named call, an attributed retry carrying the id, or a named resume of an in-progress change — skip the implementation preflight and Step 1's status-digest certification entirely: after the `repository.prepare` operation succeeds, go **directly** to the authoritative `context.implementation` operation with `--id ` and the existing claim/resume path. The named path never runs `maintenance.preflight` or any maintenance sweep first — another change's failing closeout, cleanup, or reclaim can never halt this change before its own claim/gate; anyone who wants those maintenance outcomes runs the explicit `maintenance.preflight` or `maintenance.sweep` operation deliberately, where every problem stays visible. Every local check for the named change is kept — readiness, record revision, dependencies, effective base, claim eligibility, run context, and resume/cancellation. A held change (`on-hold`) is built when named. So a malformed, absent, not-ready, or improperly resumed id returns its existing typed refusal, reported with its reason exactly as a scoped-id skip is (ending `drained` when nothing else is in scope); a named request **never falls back to selecting another change**, and shared repository/configuration/transport failures keep the `halted` posture. +**Named invocation — no maintenance preflight.** When this run was invoked with exactly **one explicit change id** — an initial named call, an attributed retry carrying the id, or a named resume of an in-progress change — skip the implementation preflight and Step 1's status-digest certification entirely: after the `repository.prepare` operation succeeds, go **directly** to the authoritative `context.implementation` operation with `--id ` and the existing claim/resume path. The named path never runs `maintenance.preflight` or any maintenance sweep first — another change's failing closeout, cleanup, or reclaim can never halt this change before its own claim/gate; anyone who wants those maintenance outcomes runs the explicit `maintenance.preflight` or `maintenance.sweep` operation deliberately, where every problem stays visible. Every local check for the named change is kept — readiness, record revision, dependencies, effective base, claim eligibility, run context, and resume/cancellation; an `in-progress` id is served only to its own resume (Step 1). A held change (`on-hold`) is built when named. So a malformed, absent, not-ready, or improperly resumed id returns its existing typed refusal, reported with its reason exactly as a scoped-id skip is (ending `drained` when nothing else is in scope); a named request **never falls back to selecting another change**, and shared repository/configuration/transport failures keep the `halted` posture. **The named change's own merged dependencies.** Skipping the sweep never declares a dependency satisfied. When the named path's `context.implementation` read refuses `not-ready-waiting-dependency`, **read `references/edge-paths.md` now (blocking)** for the bounded closeout of the named change's own `implemented` dependencies — never any other change's. @@ -38,7 +38,7 @@ Build-readiness and ranking are defined by the convention's **Build-readiness & **Acquisition.** Run the `status` operation with `--json` — a write-free read; on the selection path, only AFTER Step 0's `maintenance.preflight` run and metadata re-sync (the snapshot is taken pre-sweep otherwise and would list already-merged changes). A named invocation takes no ready-queue digest — it arrives here already holding Step 0's directive to read the explicit-id bundle below. Validate the envelope before trusting it: `protocol_version` MUST be `1` and `operation` MUST be `status`. The top-level `ready` array IS the build-ready queue, already in the convention's deterministic order — final tie-break LOWEST `id`, so concurrent implementers converge on one winner. Per-change skip reasons come from each `changes[]` entry's `readiness` / `readiness_reason` fields (`readiness` vocabulary: `build-ready`, `on-hold`, `needs-grooming`, `waiting-dependency`, `stack-base-unresolved`, `not-proposed`, `auto-groom-blocked`, `invalid`; `readiness_reason` carries the human-readable phrase). -The digest is an **accelerator, not the sole channel**: the authoritative read is the `context.implementation` operation with `--id ` (no `--id` applies the same selection policy; an attributed retry passes the id). It loads ONE fresh snapshot and returns the change's source bytes, exact opaque **record revision**, readiness, claim-eligibility, resolved effective base, integration branch, and workflow config — the single bundle the claim and every later operation key on, so no step re-reads the change file. **Judgment on that bundle stays yours.** CONFIRM build-readiness (on the named path `on-hold` also qualifies) before claiming — a stale digest costs a re-pick, never a bad build; a typed no-candidate/absent-id/duplicate-id/not-ready/unsupported-config outcome is surfaced, never overridden. If the bundle disagrees with the digest, drop that candidate, take the next, and REPORT it; on the selection path a bundle reporting `on-hold` is dropped and reported the same way. **The exit status and the envelope's shape together govern the disposition.** A **non-zero exit**, or stdout that will not parse as a JSON envelope, **is a hard error** (config export failure, refused bootstrap guard, missing metadata worktree, failed render, or malformed output) — surface its stderr diagnostic and STOP with the **`halted`** disposition; never fall back to `active/` for a hard error, and never report `drained` for one. On **exit 0** with a valid envelope, an **empty `ready` array** (`ready: []`) means the queue is genuinely empty → `drained`. A parseable envelope that is **missing the `ready` key altogether** is malformed machine output — **reject it and STOP with `halted`**, exactly as for a hard error: the typed contract always carries `ready`, so there is no walk-`active/`-yourself degradation. Likewise a failed `protocol_version`/`operation` check. +The digest is an **accelerator, not the sole channel**: the authoritative read is the `context.implementation` operation with `--id ` (no `--id` applies the same selection policy; an attributed retry passes the id). It loads ONE fresh snapshot and returns the change's source bytes, exact opaque **record revision**, readiness, claim-eligibility, resolved effective base, integration branch, and workflow config — the single bundle the claim and every later operation key on, so no step re-reads the change file. For the run's own `in-progress` change (a named resume) it returns the bundle with `claim_eligible: false`, the recorded branch, and a readable `halt.run_halted`; a plain named run that reads `claim_eligible: false` surfaces the refusal and ends `drained`, never claiming or building — only a resume proceeds. **Judgment on that bundle stays yours.** CONFIRM build-readiness (on the named path `on-hold` also qualifies) before claiming — a stale digest costs a re-pick, never a bad build; a typed no-candidate/absent-id/duplicate-id/not-ready/unsupported-config outcome is surfaced, never overridden. If the bundle disagrees with the digest, drop that candidate, take the next, and REPORT it; on the selection path a bundle reporting `on-hold` is dropped and reported the same way. **The exit status and the envelope's shape together govern the disposition.** A **non-zero exit**, or stdout that will not parse as a JSON envelope, **is a hard error** (config export failure, refused bootstrap guard, missing metadata worktree, failed render, or malformed output) — surface its stderr diagnostic and STOP with the **`halted`** disposition; never fall back to `active/` for a hard error, and never report `drained` for one. On **exit 0** with a valid envelope, an **empty `ready` array** (`ready: []`) means the queue is genuinely empty → `drained`. A parseable envelope that is **missing the `ready` key altogether** is malformed machine output — **reject it and STOP with `halted`**, exactly as for a hard error: the typed contract always carries `ready`, so there is no walk-`active/`-yourself degradation. Likewise a failed `protocol_version`/`operation` check. **Scope (id allowlist).** With no argument the candidate set is the whole `ready` queue. A caller may pass an **id allowlist** of two or more ids — `docket-implement-next 90,92,94` — and selection is then **restricted to that set**, preserving the queue's order *within* it. (A **single explicit id** is not an allowlist: it is a named invocation and takes Step 0's named branch, never this filter.) The allowlist is a filter, **never a dependency override**: a scoped id that is not currently build-ready+claimable — needs-grooming, on hold, already `in-progress`, or waiting on an unmerged `depends_on` — is **skipped with its reason** (read it off that id's `changes[]` entry — a non-`proposed` `status` there is skipped for that status — or from the change file if it has none — already archived, or no such id), never force-built, and never aborts the run. @@ -46,7 +46,9 @@ The digest is an **accelerator, not the sole channel**: the authoritative read i ### Step 2 — Claim (conflict-checked write) -Claim by transaction: the `change.claim` operation with `--id --revision ` (the exact revision from the step-1 bundle). When the dispatch prompt carried a **run context** token, pass it to the claim as --run-context : the claim validates it against the started run, records durable proof binding this dispatch to its successful claim, and the parent's keyed verdict resolves ownership from that proof; an invalid or conflicting run context is a typed refusal that writes nothing — never retried as an ungated claim. A claim without the token stays supported for ungated invocations. Also pass `--selection queue` on the selection path and `--selection named` on the named path: the run tracker counts a halt toward a loop's halt limit only for a change picked from the queue. In the **metadata working tree** the operation reloads fresh origin, re-proves the change is still `proposed`, uniquely identified, build-ready, and has a resolved effective base, then applies the landed claim (`status: in-progress` + `branch: /` + `updated:` + `claimed_at:` — the lease the `change.reclaim` operation and the maintenance sweep's reclaim key on) and updates the change record, `## Artifacts` block, and inline board **together in one metadata commit** on the metadata branch, pushed to the metadata remote. It returns the new record revision, feature branch, lease classification, and a closed disposition; a wrong revision or a not-`proposed`/not-build-ready/duplicate/unresolved-base change returns `contended`/a typed refusal that **writes nothing and creates no workspace**. A lost-response retry converges by re-reading authority — an already-held matching claim returns the applied receipt or a typed `already-claimed`, a foreign claim returns `contended`; never adopt a branch or workspace as proof the claim landed. A `contended` result is the **`contended`** disposition (see *Terminal disposition*): a lost conflict-checked claim race is a normal, continue-able outcome a driver re-selects past, **never `halted`** — re-sync (re-run the `repository.prepare` operation) and re-select. No worktree yet. +Claim by transaction: the `change.claim` operation with `--id --revision ` (the exact revision from the step-1 bundle). When the dispatch prompt carried a **run context** token, pass it to the claim as --run-context : the claim validates it against the started run, records durable proof binding this dispatch to its successful claim, and the parent's keyed verdict resolves ownership from that proof; an invalid or conflicting run context is a typed refusal that writes nothing — never retried as an ungated claim. A claim without the token stays supported for ungated invocations. Also pass `--selection queue` on the selection path and `--selection named` on the named path: the run tracker counts a halt toward a loop's halt limit only for a change picked from the queue. In the **metadata working tree** the operation reloads fresh origin, re-proves the change is still `proposed`, uniquely identified, build-ready, and has a resolved effective base, then applies the landed claim (`status: in-progress` + `branch: /` + `updated:` + `claimed_at:` — the lease the `change.reclaim` operation and the maintenance sweep's reclaim key on) and updates the change record, `## Artifacts` block, and inline board **together in one metadata commit** on the metadata branch, pushed to the metadata remote. It returns the feature branch, lease classification, and a closed disposition; a wrong revision or a not-`proposed`/not-build-ready/duplicate/unresolved-base change returns `contended`/a typed refusal that **writes nothing and creates no workspace**. A lost-response retry converges by re-reading authority — an already-held matching claim returns the applied receipt or a typed `already-claimed`, a foreign claim returns `contended`; never adopt a branch or workspace as proof the claim landed. A `contended` result is the **`contended`** disposition (see *Terminal disposition*): a lost conflict-checked claim race is a normal, continue-able outcome a driver re-selects past, **never `halted`** — re-sync (re-run the `repository.prepare` operation) and re-select. No worktree yet. + +**Revision lookups.** The claim pins the pre-claim bundle's revision and `change.resume-halted` the context bundle's. Before every later write to its own record — `change.reconcile`, `change.halt`, a reconcile-kill's `change.kill`, `workspace.prepare`, the revision handed to the plan-writer, the producing-change revision handed to `docket-adr`, each `change.attach-results`, and `change.mark-implemented` — the run reads the revision from the local metadata checkout in the same shell call as the write (or immediately before the dispatch carrying it): `R=$(git -C rev-parse HEAD:)`, `` being the bundle's `change.path`, which does not move while the change is active. A receipt's `committed_revision` is the commit id, never a `--revision` value. On `contended`, re-sync once (the `repository.prepare` operation), look the revision up again, and retry the write once — except `change.reconcile`, which keeps its re-read-and-re-author rule (Step 3); a second `contended` follows the step's existing stop rule. A claim of a `proposed` record that still carries a `## Run halted` section removes that section in the same transaction. **Resuming a halted in-progress change** — one the caller re-dispatches by id after a `run.verify` verdict of **`run-halted`** — goes through the `change.resume-halted` operation with `--id --revision --acknowledge-quiescent`, never a fresh claim: it requires the exact marked record and the explicit `--acknowledge-quiescent` acknowledgement that the prior worker is quiescent, reprobes the branch/workspace/live gate, refreshes the claim, and removes exactly the `## Run halted` marker section while preserving every other byte and checkpoint — it never resets or adopts a workspace whose writer may be live. It refuses (writing nothing) without the acknowledgement, on revision drift (`contended`), or on a live gate lock. A change that instead reached `proposed` through the `change.reclaim` operation carries no live claim, so it re-enters through the ordinary claim above. The claim and resume both render the inline board in their own transaction, so no separate Board pass runs here. Starting the resume also passes through the run tracker, which refuses a second run over one that has not verifiably stopped — **read `references/edge-paths.md` now (blocking)** for those run-tracker resume refusals and their remedies. @@ -54,7 +56,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. 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 `reconcile_log_entry` is the **section body only** — the operation writes the `### YYYY-MM-DD` heading. When nothing changed (spec, stack base, related changes, and scope all hold), send just `{id, revision, reconcile_log_entry}` with a one-line body such as "Unchanged against ``"; sections and relations go in only when reality requires a change. 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*). @@ -65,7 +67,7 @@ Two escape hatches: ### Step 4 — Worktree + plan -CONFIRM the step-3 reconcile push has landed on the **metadata branch** before continuing — by **SHA-compare**, not "the push exited 0": after a re-sync, the local metadata tip must equal the remote tip (re-run the `repository.prepare` operation, assert `git -C rev-parse HEAD` equals `git -C rev-parse `). If they differ (a concurrent writer rejected the push): re-sync, re-push — repeat until the SHAs match, so the build never reads bytes older than origin. Then prepare the owned feature workspace: +Step 3's `applied` reconcile receipt proves its exact-lease push landed on the metadata branch. Prepare the owned feature workspace: ``` workspace.prepare --id --revision # resolve argv from the capability catalog @@ -77,7 +79,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 `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**. The `repository.prepare` operation runs at startup, after a dispatched agent writes the change, once after a `contended` write, and on a contended claim. Typed reads fetch on their own, and plain-file reads of the metadata checkout follow every docket write, so no other re-sync is needed. 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. **Plan authoring (dispatched).** The parent stays the orchestrator. @@ -89,24 +91,24 @@ It also supplies the change id, title, exact record revision, synchronized chang **Verification (parent).** The returned path is a **claim, not proof**. Re-sync the metadata worktree (the `repository.prepare` operation), then verify from git on the metadata branch that `plan:` equals the returned path, the file exists at the metadata tip under `docs/superpowers/plans/` with a backlink to this change, and that the feature worktree is clean with HEAD equal to the pre-dispatch HEAD. On a malformed return, a missing or mismatched `plan:`, a missing file or backlink, a dirty worktree, or a moved HEAD: **halt** (`## Run halted` + the `halted` disposition) — **never adopt**, repair, or commit the child's output, and never retry with the parent or a weaker model. The attach refuses an unsafe path, an unbalanced backlink, an unresolved placeholder, a `plan:` naming another path (`artifact-path-mismatch`), or a path holding another change's file (`artifact-path-occupied`), writing nothing; a lost-response retry with the same bytes replays its applied receipt. -**Continue.** After the dispatch returns, a `PLAN_PATH` return MUST be verified; the child's attach moved the record, so on the re-synced tree re-read its revision (the `context.implementation` operation with `--id `) and **refresh the claim again** with it (the `change.refresh-claim` operation) to stamp the plan→build seam, then the parent MUST proceed into Step 5 — `PLAN_PATH` is a sub-step receipt, **never** a terminal disposition, and neither the child's return nor Step 4's postcondition may be reported as `advanced`. **Dispatch fallback (`halt`):** plan-writer dispatch unavailable — established only per the convention's *Dispatch-capability resolution*, never from a tool name — is **`halt`**: the change stays `in-progress` with `claimed_at` refreshed and the halt reason recorded. Build workers and reviewers read the plan from the metadata worktree (`/`, after a re-sync); the archive transaction retargets every metadata backlink in its own commit. +**Continue.** After the dispatch returns, a `PLAN_PATH` return MUST be verified; the child's attach moved the record, so every later write looks its revision up again (*Revision lookups*, Step 2); then the parent MUST proceed into Step 5 — `PLAN_PATH` is a sub-step receipt, **never** a terminal disposition, and neither the child's return nor Step 4's postcondition may be reported as `advanced`. **Dispatch fallback (`halt`):** plan-writer dispatch unavailable — established only per the convention's *Dispatch-capability resolution*, never from a tool name — is **`halt`**: the change stays `in-progress` with the halt reason recorded. Build workers and reviewers read the plan from the metadata worktree (`/`); the archive transaction retargets every metadata backlink in its own commit. ### Step 5 — Build -**Refresh the claim** (the `change.refresh-claim` operation) immediately before this long **build-role invocation** and again when it returns, at a revision re-read after a re-sync (a build checkpoint moves the record) — a refresh `contended` stops a new invocation but never cancels a build already running. The build role — `docket-build` — is invoked **DIRECTED to:** execute the plan task-by-task and stop at the executed plan, carrying the prepare context's `visibility` so every worker payload names its `Visibility`. `docket-build` is a skill to invoke, never a same-name agent to dispatch (convention, *Skill layer*): the invoked skill directs the controller to dispatch one named build-tier worker per plan task and gates on one full-suite run. A rejected attempt to dispatch a same-name `docket-build` agent is the wrong operation, never capability evidence — resume at the skill invocation; no metadata or worktree state changed because that probe was refused. **Proceed through the build — the deliverable is the executed plan, never the decision about how to execute it.** Separately, and without ever relaxing the first: answer any choice it poses from resolved config, surface none, and log one line naming the role and skill if you suppressed a hand-off. Emitting that log line discharges the suppression obligation only; the step is not complete until its git-state postcondition holds — see *Step postconditions*. When `docket-build` cannot be invoked, apply the convention's missing-skill rule: execute the plan inline on the feature branch, warning prominently — the artifact is the executed plan. If the invoked skill's **required nested dispatch** — a build-tier worker — is unavailable (established only per the convention's *Dispatch-capability resolution* — never from a tool name), the build role is **`halt`**: the change stays `in-progress` with `claimed_at` refreshed and the halt reason recorded. When the build role returns `halted`, the `## Run halted` report carries its halt report's gate evidence verbatim, a `tree-survives` finding included — information for the human, never a different disposition. +The build role — `docket-build` — is invoked **DIRECTED to:** execute the plan task-by-task and stop at the executed plan, carrying the prepare context's `visibility` so every worker payload names its `Visibility`. `docket-build` is a skill to invoke, never a same-name agent to dispatch (convention, *Skill layer*): the invoked skill directs the controller to dispatch one named build-tier worker per plan task and gates on one full-suite run. A rejected attempt to dispatch a same-name `docket-build` agent is the wrong operation, never capability evidence — resume at the skill invocation; no metadata or worktree state changed because that probe was refused. **Proceed through the build — the deliverable is the executed plan, never the decision about how to execute it.** Separately, and without ever relaxing the first: answer any choice it poses from resolved config, surface none, and log one line naming the role and skill if you suppressed a hand-off. Emitting that log line discharges the suppression obligation only; the step is not complete until its git-state postcondition holds — see *Step postconditions*. When `docket-build` cannot be invoked, apply the convention's missing-skill rule: execute the plan inline on the feature branch, warning prominently — the artifact is the executed plan. If the invoked skill's **required nested dispatch** — a build-tier worker — is unavailable (established only per the convention's *Dispatch-capability resolution* — never from a tool name), the build role is **`halt`**: the change stays `in-progress` with the halt reason recorded. When the build role returns `halted`, the `## Run halted` report carries its halt report's gate evidence verbatim, a `tree-survives` finding included — information for the human, never a different disposition. ### Step 6 — Review + ADRs **Validate the build evidence.** Read the build-evidence record step 5's gate emitted — it must be present, its `head_sha` equal to the branch HEAD, and its `result` either `green` or `skipped` (the repo set `build.gate: off`, carrying `reason: build-gate-off`, no command). Missing, malformed, or stale is a build-contract violation — never review an uncertified branch. Re-mint once yourself: under `build.gate: off`, the `evidence.record` operation with `--id --head ` and no run dir mints the skipped record; under a local gate, **drive** the native gate — never author a launch/observe/sleep sequence of your own: the `gate.drive.start` operation with `--repo-dir --run-root --owner build --change-id --run-context --json` (`--owner build` resolves the build-owned command; no suite argv; `--change-id` always, so the attempt is charged and the run tracker can find the drive; `--run-context` carries your dispatch prompt's value, omitted only when it carried none) — capture that first JSON response into `gate_reply` and the drive id and owner generation from it, its exit code (if needed) into `gate_rc`, never a zsh read-only special parameter such as `status` (the shared JSON-capture requirement; human text omits the generation) — then the `gate.drive.advance` operation with `--drive-id --owner-gen ` — one slice per call — under docket-build's bounded gate-run posture until a terminal disposition. The typed disposition vocabulary lives in `docket-build`'s `references/gate-driver.md`; only a **`PASSED`** disposition at the current head exposes the raw run dir that feeds the recording below — `FAILED`/`HALTED`/`WAITING` never do. -**Create the durable evidence.** Under a local gate, only from a **`PASSED`** drive disposition whose head equals the current feature head: the `evidence.record` operation with `--id --run --head ` reads the outcome from the run directory that disposition exposed and the gate command from the build configuration (`build.test_command`) — **no agent-supplied `passed` boolean** — and returns the immutable typed record; a `FAILED`/`HALTED`/`WAITING` or head-mismatched drive produces none. Then the `evidence.verify` operation with `--record --head ` re-checks its bytes against the head. Any review fix below changes HEAD and **invalidates this evidence** — repeat the record → verify chain before publishing. +**Create the durable evidence.** Under a local gate, only from a **`PASSED`** drive disposition whose head equals the current feature head: the `evidence.record` operation with `--id --run --head ` reads the outcome from the run directory that disposition exposed and the gate command from the build configuration (`build.test_command`) — **no agent-supplied `passed` boolean** — and returns the immutable typed record; a `FAILED`/`HALTED`/`WAITING` or head-mismatched drive produces none. Write the receipt's `block` field to a file: that file is the `--evidence` input for `pr.publish` and `change.mark-implemented`, which each re-verify it against the head. Any review fix below changes HEAD and **invalidates this evidence** — repeat the record step before publishing. -For the `docket-review` role, **select the review tier** deterministically from the build record — take the **highest tier any task routed or escalated to** (an escalation counts as the tier escalated *to*), then map `economy` to `docket-review-lean`, `standard` to `docket-review-standard`, and `premium` or `max` to `docket-review-deep`. When the build emits **no build record** (for example, it ran inline under the missing-skill rule), the tier defaults to `docket-review-standard`, matching the uncertainty sink `standard` is in docket-build's own routing. One modifier: a whole-branch diff of more than **1500 changed lines** — insertions + deletions from `git diff --shortstat origin/...HEAD` — bumps the tier one step, capped at deep — the only selection signal independent of the build's own self-assessment. Log the chosen tier and its reason as one line. Selection is a rule over the build record, never model judgment. +For the `docket-review` role, **select the review tier** deterministically from the build record — take the **highest tier any task routed or escalated to** (an escalation counts as the tier escalated *to*), then map `economy` to `docket-review-lean`, `standard` to `docket-review-standard`, and `premium` or `max` to `docket-review-deep`. When the build emits **no build record** (for example, it ran inline under the missing-skill rule), the tier defaults to `docket-review-standard`, matching the uncertainty sink `standard` is in docket-build's own routing. One modifier: a whole-branch diff of more than **1500 changed lines** — insertions + deletions from `git diff --shortstat ...HEAD`, the bundle's `effective_base` (`origin/`, or the parent's branch for a stacked change — the base `workspace.prepare` cut from) — bumps the tier one step, capped at deep — the only selection signal independent of the build's own self-assessment. Log the chosen tier and its reason as one line. Selection is a rule over the build record, never model judgment. The review role — `docket-review` — is invoked **DIRECTED to:** review the whole branch against its base and return its findings, then stop, answering any choice it poses from resolved config and never surfacing one — log one line naming the role and skill if you suppressed a hand-off. `docket-review` is a skill, never a same-name agent to dispatch, and the skill itself dispatches nothing: you — the controller — dispatch the selected tier wrapper — `docket-review-lean`, `docket-review-standard`, or `docket-review-deep` — foreground, and that wrapper preloads the `docket-review` skill. Its dispatch payload contains: Feature worktree: -It also contains the branch and base ref, change title and scope, relevant learnings hooks, the evidence record, and the resolved `build.gate` value (from the startup-check prepared context's `build` block). When the `docket-review` skill is missing, apply the convention's missing-skill rule: review the whole branch inline before the PR opens, warning prominently, and dispatch no reviewer. Re-read the learnings index `/learnings/README.md` first and pull the findings relevant to what this change touched (skipped entirely when `learnings.enabled` is `false`). For any non-obvious decision made during implementation, **dispatch the `docket-adr` subagent** (foreground, at the model/effort its wrapper resolves) — once per decision; it assigns the number, updates the index, commits the ADR on the metadata remote, and **returns the number**. After re-syncing the metadata worktree, record that number in the change's `adrs:` relation through a `change.reconcile` operation relations update — the transaction re-checks the exact revision and re-renders the `## Artifacts` block and inline board atomically, so the skill never hand-renders a derived view. Review findings that are distinct follow-up work — not this change's own fixes — are **reported as follow-up work in the final report**; nothing is minted automatically, and a human captures reported work deliberately with `docket change create`. On unavailable dispatch — established only per the convention's *Dispatch-capability resolution*, never from a tool name, and never from a rejected same-name role-agent attempt — an undispatchable review tier makes the review role **`halt`** on the same terms as step 5; the `docket-adr` dispatch falls back **`inline`**, with its git-state contract unchanged. +It also contains the branch and base ref, change title and scope, relevant learnings hooks, the evidence record, and the resolved `build.gate` value (from the startup-check prepared context's `build` block). When the `docket-review` skill is missing, apply the convention's missing-skill rule: review the whole branch inline before the PR opens, warning prominently, and dispatch no reviewer. Re-read the learnings index `/learnings/README.md` first and pull the findings relevant to what this change touched (skipped entirely when `learnings.enabled` is `false`). For any non-obvious decision made during implementation, **dispatch the `docket-adr` subagent** (foreground, at the model/effort its wrapper resolves) — once per decision. Each payload passes the producing change as `{id, path, revision}` (path from the bundle, revision from *Revision lookups*, Step 2); `docket-adr` passes it through as the request's `change`, so `adr.record` assigns the number, updates the index, appends it to `adrs:`, and re-renders `## Artifacts` in one metadata commit, then **returns the number**. Several ADRs go one at a time, each with a fresh lookup. After each returns, re-sync once (the `repository.prepare` operation) and check from git that the number is in `adrs:`. A `contended` from `adr.record`: re-sync, look the revision up again, and re-dispatch once; a second `contended` is a hard error that ends the run `halted`. Review findings that are distinct follow-up work — not this change's own fixes — are **reported as follow-up work in the final report**; nothing is minted automatically, and a human captures reported work deliberately with `docket change create`. On unavailable dispatch — established only per the convention's *Dispatch-capability resolution*, never from a tool name, and never from a rejected same-name role-agent attempt — an undispatchable review tier makes the review role **`halt`** on the same terms as step 5; the `docket-adr` dispatch falls back **`inline`**, with its git-state contract unchanged. **Triage the returned findings, then FIX them in-branch.** Findings are repaired on the open branch before the PR opens — a bounded **fix pass**, not a stub for every one. `review.min_fix_severity` (read through the `diagnostic.config` operation; `minor` by default) is the lowest severity that enters it, and blockers are fixed regardless of it. Routing is by the fix's CHARACTER via the shared rubric, never by its severity, and never reaches the `max` tier; every fix runs the `docket-build-task` contract. Before dispatching the first fix task, **read `references/fix-pass.md` now (blocking)** — it owns the routing table, the non-blocker task cap, the per-finding and batched task shapes, the revert-and-record suite gate (bounded at two runs; still-red halts), and the PR-body disposition table. The reviewer's `unverified-build-state` blocker is the one exception you resolve yourself, by re-running the suite — or, under `build.gate: off`, by re-minting the skipped record. A finding that is genuinely distinct beyond-the-branch work is reported as follow-up work in the final report, carrying the backlog verdict final consolidation attaches; a finding about this branch's own diff never is. There is **no re-review** round after fixes — remediation is carried by the worker's own self-review, the suite re-run, and the human reading every fix in the PR diff. @@ -122,9 +124,9 @@ The results artifact is **required for every implemented change** — there is n **Per-checkpoint mechanics** (in order): 1. Verify ownership and quiescence — no live gate, running worker, or transferred drive. -2. Read and **preserve** the prior results content — after a re-sync, from `/` when `results:` is set; a checkpoint updates it, never truncates it — except final consolidation, which condenses the review findings (*Review findings* below). +2. Read and **preserve** the prior results content — from `/` when `results:` is set; a checkpoint updates it, never truncates it — except final consolidation, which condenses the review findings (*Review findings* below). 3. Write the update into the scratch file. -4. Attach it: the `change.attach-results` operation with `--id --revision --path --markdown `, at a revision re-read after a re-sync (the `context.implementation` operation with `--id `) because the claim refresh, plan attach, and every earlier checkpoint move the record, writes the file with its backlink and sets `results:` in one metadata commit that never moves the feature head; later checkpoints keep the **same path**. +4. Attach it: the `change.attach-results` operation with `--id --revision --path --markdown `, at a freshly looked-up revision (*Revision lookups*, Step 2), writes the file with its backlink and sets `results:` in one metadata commit that never moves the feature head; later checkpoints keep the **same path**. **Evidence sequencing.** Results prose is **never gate evidence**, and a results checkpoint never moves HEAD, so it never stales evidence. Obtain gate evidence for the final code head through the gate driver; any code commit (a fix) still invalidates it. **Never** rewrite results solely to paste the final gate's SHA or timestamp. A new material finding surfaced by the final gate is preserved in results, the fix/halt policy applies, and evidence is re-established after any commit. @@ -140,9 +142,15 @@ The results artifact is **required for every implemented change** — there is n **Publish the feature head.** The `workspace.publish` operation with `--id --head ` inspects the owned workspace and pushes the exact head through the landed non-forcing publication, returning the verified remote head. It refuses when the reinspected head differs from `--head`; a divergent remote ref is `contended`, unknown post-effect state is `unknown` (reprobe on retry) — neither forces, and no PR opens here. -**PR-body assembly.** The authored PR body carries the best-effort `#` reference (never `Closes #N`), and the review disposition table; `pr.publish` adds the back-link line and the plan/results links block. The PR body carries no build-evidence block. In a private repository the authored title and body follow the private-repository writing rule: no `#` reference, no change id in the title, and `pr.publish` publishes the body verbatim. Before assembling it, **read `references/edge-paths.md` now (blocking)** — it owns the mechanics. +**PR-body assembly.** The PR body carries no build-evidence block. In a private repository the authored title and body follow the private-repository writing rule: no `#` reference, no change id in the title, and `pr.publish` publishes the body verbatim, with no back-link line and no links block. + +**Best-effort PR→issue reference.** If the change carries an `issue:` value, add a plain `#` reference to the PR body — but **never `Closes #N`**, so merging the PR never auto-closes the referenced issue. Skip silently when `issue:` is unset — the reference is a one-time courtesy, not a build gate. + +**PR-body back-link.** `pr.publish` renders and upserts a **back-link line** pointing home to the change on the metadata branch — a first body line of the shape `↩ Change — ` linking to the change file on `docket` (built with the same blob-or-bare-path logic) — plus a Docket-owned links block pointing at the plan and results files on the metadata branch; never author either in the body. + +**Review outcome.** The authored body names the reviewing tier and carries the **findings disposition table**: one row per finding, marked fixed (with its commit SHA), deferred, reverted, recorded, or reported — the states `references/fix-pass.md` defines. -**Publish the PR.** With the authored title+body and the verified evidence bytes each in a request file, the `pr.publish` operation with `--id <id> --head <feature head> --body <request-file> --evidence <evidence request-file>` reparses the evidence (never a prior result) and verifies local HEAD == published remote head == evidence head == requested head, and that the feature branch, effective-base branch, and repository identity agree, BEFORE calling the landed GitHub adapter; it then inserts or replaces ONLY the Docket-owned backlink and plan/results links blocks (authored prose byte-preserved) and returns the canonical PR reference, URL, number, head, base, and disposition. `unknown` stays `unknown` — reprobe, never a duplicate PR — and the result redacts the body bytes. It refuses `record-invalid` (`invalid-state`) before any GitHub call when the change, a `depends_on` target, or a stack ancestor carries a validation error (associative links are never checked): no PR was created or edited — repair exactly the records the result's `findings` name, then re-publish; the run keeps its existing halt posture for a typed refusal. +**Publish the PR.** With the authored title+body and the Step 6 evidence file (the `evidence.record` receipt's `block` text) each in a request file, the `pr.publish` operation with `--id <id> --head <feature head> --body <request-file> --evidence <evidence request-file>` reparses the evidence (never a prior result) and verifies local HEAD == published remote head == evidence head == requested head, and that the feature branch, effective-base branch, and repository identity agree, BEFORE calling the landed GitHub adapter; it then inserts or replaces ONLY the Docket-owned backlink and plan/results links blocks (authored prose byte-preserved) and returns the canonical PR reference, URL, number, head, base, and disposition. `unknown` stays `unknown` — reprobe, never a duplicate PR — and the result redacts the body bytes. It refuses `record-invalid` (`invalid-state`) before any GitHub call when the change, a `depends_on` target, or a stack ancestor carries a validation error (associative links are never checked): no PR was created or edited — repair exactly the records the result's `findings` name, then re-publish; the run keeps its existing halt posture for a typed refusal. **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. @@ -158,15 +166,15 @@ Each step below is complete only when its row holds — read from **git**, never | Step | Complete only when | |---|---| -| 2 Claim | `status: in-progress` + `branch:` + `updated:` + `claimed_at:` committed on the metadata branch **and landed** (local tip == remote tip). | +| 2 Claim | `status: in-progress` + `branch:` + `updated:` + `claimed_at:` committed on the metadata branch **and landed** (an `applied` claim receipt). | | 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 `<type>/<slug>`, then `plan:` and the plan file with its backlink landed on the metadata branch, the feature HEAD unchanged by planning. | +| 4 Worktree + plan | the spec copy committed as the first commit on `<type>/<slug>`, 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 `<type>/<slug>`, 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/<type>/<slug>` 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. | | Results-artifact ending | the change `done` and archived on the metadata branch, `results:` set, and the final results file with its backlink on the metadata branch. | -Rows 3, 4, 6 and 7 each carry, in addition, the **field-write rule**'s conditions on every metadata commit they name: the `claimed_at` re-stamp, and — for any link-bearing field write — the regenerated `## Artifacts` block in the same commit. +Rows 3, 4, 6 and 7 each carry, in addition, the **field-write rule**'s link-bearing condition on every metadata commit they name: the regenerated `## Artifacts` block in the same commit. Steps 0, 1 and 6.5 get no row: 0 produces nothing scoped to this change, 1 is a pure read, and 6.5's artifact is certified by Step 7's results condition or the results-artifact ending's. @@ -207,7 +215,7 @@ A change is drafted against a *snapshot* of the codebase, ADRs, and other in-fli ### The field-write rule -Every change-file field write in this run (claim's `status:`/`branch:`, reconcile, `plan:`, `adrs:`, `results:`, `pr:` + `status: implemented`) lands through a **`change.*` / attach / mark-implemented transaction** in the metadata worktree on the metadata branch — never a hand-edit, never in the feature worktree — which reloads fresh origin, checks the exact record revision, and commits and pushes atomically. The skill **never invokes a facade renderer and never hand-writes a derived view**: the transaction re-stamps `claimed_at: <UTC ISO-8601 now>` on every mutation and, for any **link-bearing field** (`spec:`/`plan:`/`adrs:`/`pr:`/`results:`), regenerates the `## Artifacts` block and inline board in the same commit; the skill also refreshes the claim explicitly (the `change.refresh-claim` operation) around the long plan and build dispatches, stamping the plan→build seam where a stopped run is otherwise invisible. The halt-path authored sections also land through transactions, never a hand-edit: the `change.halt` operation writes the `## Run halted` section (Step 3) and the `change.resume-halted` operation removes it on resume (Step 2), each an exact-revision transaction that renders the inline board in its own commit. The skill authors the halt report as a request file and hands it across; it never edits the section bytes itself. **Stage by explicit path** — that tree is shared, so a bare `add -A` commits another agent's staged work under your message. +Every change-file field write in this run (claim's `status:`/`branch:`, reconcile, `plan:`, `adrs:`, `results:`, `pr:` + `status: implemented`) lands through a **`change.*` / attach / mark-implemented transaction** in the metadata worktree on the metadata branch — never a hand-edit, never in the feature worktree — which reloads fresh origin, checks the exact record revision, and commits and pushes atomically. The skill **never invokes a facade renderer and never hand-writes a derived view**: for any **link-bearing field** (`spec:`/`plan:`/`adrs:`/`pr:`/`results:`), the transaction regenerates the `## Artifacts` block and inline board in the same commit; `claimed_at` is stamped only by the claim, reconcile, and resume-halted transactions. The halt-path authored sections also land through transactions, never a hand-edit: the `change.halt` operation writes the `## Run halted` section (Step 3) and the `change.resume-halted` operation removes it on resume (Step 2), each an exact-revision transaction that renders the inline board in its own commit. The skill authors the halt report as a request file and hands it across; it never edits the section bytes itself. **Stage by explicit path** — that tree is shared, so a bare `add -A` commits another agent's staged work under your message. ### Feature branch invariants diff --git a/internal/assets/embedded/tree/skills/docket-implement-next/references/edge-paths.md b/internal/assets/embedded/tree/skills/docket-implement-next/references/edge-paths.md index 1f1804122..40b85d961 100644 --- a/internal/assets/embedded/tree/skills/docket-implement-next/references/edge-paths.md +++ b/internal/assets/embedded/tree/skills/docket-implement-next/references/edge-paths.md @@ -1,8 +1,8 @@ # edge-paths — the implementer's rare edges The rare edges of `docket-implement-next` — read at the trigger moment named in SKILL.md (a named -invocation waiting on its own dependency, a reconcile-kill, a resume of an `in-progress` change, or -Step 7's PR-body assembly). Loaded on demand; sibling files are not auto-loaded with the skill. +invocation waiting on its own dependency, a reconcile-kill, or a resume of an `in-progress` +change). Loaded on demand; sibling files are not auto-loaded with the skill. ## Named invocation's own merged dependencies (Step 0, bounded closeout) @@ -85,7 +85,7 @@ refreshes the copy; otherwise it is a no-op. **The results seam.** The results artifact is required for every change, so a resume must not lose it. On resume, **load the attached results from the metadata worktree (`metadata_worktree_path` in the `repository.prepare` context) at -`<metadata_worktree_path>/<results path>`, after a re-sync, before starting new work**, and +`<metadata_worktree_path>/<results path>` before starting new work**, and reuse the `results:` path whenever it is set — a changed authoring date **never mints a second file**; the canonical path is chosen once and reused. **Never overwrite newer remote work** — a resume that finds the remote ahead re-reads authority rather than force-writing its local view. @@ -97,13 +97,3 @@ or the continuation it was already going to take) and **reports the capture limi existing halt/continuation channel** — no fabricated results path, no stolen lease, and no delayed gate handoff to make room for a write. The missing capture is a reported limitation, never a reason to force a workspace, a commit, or a HEAD move. - -## PR-body assembly (Step 7) - -**Best-effort PR→issue reference.** If the change carries an `issue:` value, add a plain `#<issue>` reference to the PR body — but **never `Closes #N`**, so merging the PR never auto-closes the referenced issue. Skip silently when `issue:` is unset — the reference is a one-time courtesy, not a build gate. None in a private repository (private-repository writing rule); the body is published verbatim. - -**PR-body back-link.** `pr.publish` renders and upserts a **back-link line** pointing home to the change on the metadata branch — a first body line of the shape `↩ Change <padded-id> — <title>` linking to the change file on `docket` (built with the same blob-or-bare-path logic) — plus the plan/results links block; never author either in the body. None in a private repository (private-repository writing rule); the body is published verbatim. - -**Review outcome.** The authored body names the tier that reviewed and carries the **findings disposition table**: one row per finding, each marked fixed (with its commit SHA), deferred, reverted, recorded, or reported. The table's states are defined in `fix-pass.md`; do not redefine them here. - -**Plan/results links.** `pr.publish` adds a Docket-owned links block pointing at the plan and results files on the metadata branch; never author it by hand. None in a private repository (private-repository writing rule); the body is published verbatim. diff --git a/internal/assets/embedded/tree/skills/docket-implement-next/references/fix-pass.md b/internal/assets/embedded/tree/skills/docket-implement-next/references/fix-pass.md index cdda517fc..d2e8d0b92 100644 --- a/internal/assets/embedded/tree/skills/docket-implement-next/references/fix-pass.md +++ b/internal/assets/embedded/tree/skills/docket-implement-next/references/fix-pass.md @@ -43,7 +43,7 @@ character routing at or above `standard` is untouched, and the never-`max` ceili The rubric therefore doubles as the size ceiling; there is no separate knob for "too big to fix in-branch". A **max-character blocker halts** — abort-and-report, the change stays `in-progress` -with `claimed_at` refreshed and the reason recorded. A **max-character important or minor** — rare +with the reason recorded. A **max-character important or minor** — rare by construction, since unresolved architecture flagged as minor essentially does not occur — becomes a line in the PR body for the human's merge-time judgment, **not** a follow-up change. @@ -89,8 +89,8 @@ private-repository writing rule. A fix worker that returns without a schema-valid outcome may still be **running**: never discard the worktree and dispatch a fresh worker for that finding, however dead the first one looks. Halt -instead — abort-and-report, the change staying `in-progress` with `claimed_at` refreshed and the -reason recorded, the worktree left exactly as it stands. The trigger is the malformed return you +instead — abort-and-report, the change staying `in-progress` with the reason +recorded, the worktree left exactly as it stands. The trigger is the malformed return you observed, never elapsed time; a blocked foreground controller has no clock. **If tier dispatch is unavailable** — established only per the convention's @@ -139,7 +139,7 @@ docket-build's gate uses, and refresh the build-evidence record from the result. fixes stay: the run cannot proceed without them. They are the branch's tail by the dispatch order above, so the revert applies cleanly. **Should one conflict anyway** → **halt**: restore the worktree to its pre-revert state first, then abort-and-report, the change staying - `in-progress` with `claimed_at` refreshed and the reason recorded. A half-applied revert in a + `in-progress` with the reason recorded. A half-applied revert in a shared worktree is the one outcome worse than the red branch — the human must arrive at a coherent branch to inspect. 2. **Re-run the suite once**, refreshing the build-evidence record from this run — the record must 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 0ff999f80..31e08a76c 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 @@ -13,10 +13,6 @@ own, or cleanup keeps it — plus the plan-writer dispatch, the build role, the records, the branch diff review, `workspace.publish`, `pr.publish`, and `change.mark-implemented` (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 -completion. A refresh `contended` stops new work. - ## 1. Do the work Do what the spec describes, in the feature worktree. **Never commit** to the branch, never publish @@ -67,7 +63,8 @@ and how its findings ended. ## 6. Complete, then clean up 1. Run the `change.complete` operation with a request file holding `{change_id, path, revision}`, - pinned from the `status` operation's `--json` output after a re-sync. `completed` (or + `path` from the bundle and `revision` looked up locally (`git -C <metadata_worktree_path> + rev-parse HEAD:<record path>`, as for every write). `completed` (or `already-completed` on a lost-response retry) means the change is `done` and archived; any refusal halts, naming its reason. 2. Run the `finalize.cleanup` operation with `--id <id>`. It removes a clean worktree and a local diff --git a/internal/cli/change.go b/internal/cli/change.go index cf942a729..bbf14ce4d 100644 --- a/internal/cli/change.go +++ b/internal/cli/change.go @@ -106,12 +106,6 @@ func newChangeCommand(setResult func(app.OperationResult)) *cobra.Command { claim.Flags().String("run-context", "", "run-context `token` from run start, binding this claim to its started run (optional; omitted for an untracked claim)") claim.Flags().String("selection", "", "how this change was chosen: `mode` queue (picked from the build-ready queue) or named (the run named it); any other value is recorded as unknown") - refreshClaim := changeIDRevisionSubcommand("refresh-claim", - "Re-stamp an in-progress change's claim lease at an exact revision", - func(c *cobra.Command, deps app.PlanningDeps, repoDir string, req app.ChangeClaimRequest) { - setResult(app.ChangeRefreshClaim(c.Context(), deps, repoDir, req)) - }, EffectMetadataWrite) - reconcile := changeInputSubcommand("reconcile", "Reconcile an in-progress change against current reality from a JSON request", func(c *cobra.Command, deps app.PlanningDeps, repoDir string, req app.ChangeReconcileRequest) { @@ -152,7 +146,7 @@ func newChangeCommand(setResult func(app.OperationResult)) *cobra.Command { relink := newRelinkSubcommand(setResult) - changeCmd.AddCommand(create, groom, block, deferCmd, unblock, revive, kill, complete, claim, refreshClaim, reconcile, attachPlan, attachResults, halt, resumeHalted, reclaim, markImplemented, relink) + changeCmd.AddCommand(create, groom, block, deferCmd, unblock, revive, kill, complete, claim, reconcile, attachPlan, attachResults, halt, resumeHalted, reclaim, markImplemented, relink) return changeCmd } diff --git a/internal/cli/change_test.go b/internal/cli/change_test.go index bfc8ea72f..7e0e1443e 100644 --- a/internal/cli/change_test.go +++ b/internal/cli/change_test.go @@ -139,19 +139,19 @@ func TestChangeRequestFileMissing(t *testing.T) { // never installed assets), so they are not refused on a machine with no // installation. func TestChangeCommandsAssetIndependent(t *testing.T) { - for _, key := range []string{"change", "change create", "change groom", "change block", "change defer", "change unblock", "change revive", "change kill", "change complete", "change claim", "change refresh-claim", "change reconcile"} { + for _, key := range []string{"change", "change create", "change groom", "change block", "change defer", "change unblock", "change revive", "change kill", "change complete", "change claim", "change reconcile"} { if !assetIndependent[key] { t.Errorf("%q is not registered asset-independent", key) } } } -// TestChangeClaimCommandsRegistered proves claim and refresh-claim are wired as -// change subcommands carrying the scalar --id/--revision flags (no --request: -// they carry no authored Markdown). +// TestChangeClaimCommandsRegistered proves claim is wired as a change +// subcommand carrying the scalar --id/--revision flags (no --request: it +// carries no authored Markdown). func TestChangeClaimCommandsRegistered(t *testing.T) { root := captureTree(t) - for _, sub := range []string{"claim", "refresh-claim"} { + for _, sub := range []string{"claim"} { cmd, _, err := root.Find([]string{"change", sub}) if err != nil || cmd == nil || cmd.Name() != sub { t.Fatalf("change %s not registered: cmd=%v err=%v", sub, cmd, err) @@ -166,7 +166,7 @@ func TestChangeClaimCommandsRegistered(t *testing.T) { } // TestChangeClaimRunContextFlag: claim registers the optional --run-context -// flag and refresh-claim does NOT (refresh re-proves nothing about ownership). +// flag. func TestChangeClaimRunContextFlag(t *testing.T) { root := captureTree(t) claimCmd, _, err := root.Find([]string{"change", "claim"}) @@ -176,12 +176,35 @@ func TestChangeClaimRunContextFlag(t *testing.T) { if claimCmd.Flags().Lookup("run-context") == nil { t.Fatalf("change claim must register --run-context") } - refreshCmd, _, err := root.Find([]string{"change", "refresh-claim"}) +} + +// TestChangeRefreshClaimRetired pins the deletion of change.refresh-claim +// (change 0360): no command, no catalog entry, no schema binding — while +// change.claim stays, so the catalog probe is not vacuous. The lease is stamped +// only by claim, reconcile, and resume-halted. +func TestChangeRefreshClaimRetired(t *testing.T) { + root := productionRootForTest(t) + if c, _, err := root.Find([]string{"change", "refresh-claim"}); err == nil && c != nil && c.Name() == "refresh-claim" { + t.Fatal("change refresh-claim is still registered") + } + entries, err := collectCapabilities(root) if err != nil { - t.Fatalf("find refresh-claim: %v", err) + t.Fatalf("collectCapabilities: %v", err) + } + if _, ok := entryByID(entries, "change.refresh-claim"); ok { + t.Fatal("catalog still lists change.refresh-claim") + } + if _, ok := entryByID(entries, "change.claim"); !ok { + t.Fatal("non-vacuity: change.claim missing from catalog") + } + if _, ok, _ := app.SchemaFor("change.refresh-claim", []string{"write"}); ok { + t.Fatal("schema registry still binds change.refresh-claim") + } + if _, ok, _ := app.SchemaFor("change.claim", []string{"write"}); !ok { + t.Fatal("non-vacuity: schema registry lost change.claim") } - if refreshCmd.Flags().Lookup("run-context") != nil { - t.Fatalf("refresh-claim must not register --run-context") + if _, _, code := runCLI(t, "change", "refresh-claim", "--id", "1", "--revision", "x", "--json"); code != 2 { + t.Fatalf("change refresh-claim exit = %d, want 2 (unknown command)", code) } } @@ -277,14 +300,13 @@ func TestChangeClaimFlagsRequired(t *testing.T) { } } -// TestChangeClaimCommandsReachOperation proves both claim commands decode their +// TestChangeClaimCommandsReachOperation proves the claim command decodes its // flags and reach the operation, which returns exactly one protocol-v1 document // naming it. A bare tempdir is no docket repo, so the operation fails past its // shape check — but only after naming itself. func TestChangeClaimCommandsReachOperation(t *testing.T) { cases := []struct{ sub, op string }{ {"claim", "change.claim"}, - {"refresh-claim", "change.refresh-claim"}, } for _, c := range cases { out, errS, code := runCLI(t, "change", c.sub, diff --git a/internal/cli/install.go b/internal/cli/install.go index 6e849f84e..07609c91c 100644 --- a/internal/cli/install.go +++ b/internal/cli/install.go @@ -45,7 +45,6 @@ var assetIndependent = map[string]bool{ "change kill": true, "change complete": true, "change claim": true, - "change refresh-claim": true, "change reconcile": true, "change attach-plan": true, "change attach-results": true, diff --git a/internal/cli/repository_test.go b/internal/cli/repository_test.go index 56a6b219a..dc00a9825 100644 --- a/internal/cli/repository_test.go +++ b/internal/cli/repository_test.go @@ -2,6 +2,7 @@ package cli import ( "context" + "encoding/json" "errors" "strings" "testing" @@ -252,8 +253,8 @@ func TestRepositoryPrepareJSONEnvelope(t *testing.T) { // TestRepositoryPrepareHumanSummaryRedacted proves the non-JSON path presents a // one-line summary through the result's HumanText and never dumps the full -// context: neither the origin URL credentials nor the resolved skills map reach -// human stdout, even when the returned context carries both. +// context: the origin URL credentials never reach human stdout, even when the +// returned context carries them. func TestRepositoryPrepareHumanSummaryRedacted(t *testing.T) { old := repositoryPrepareRunner repositoryPrepareRunner = func(ctx context.Context, d app.SetupDeps, o app.PrepareOptions) app.OperationResult { @@ -264,7 +265,6 @@ func TestRepositoryPrepareHumanSummaryRedacted(t *testing.T) { Context: &app.PrepareContext{ RepoRoot: "/repo", OriginURL: "https://user:s3cr3ttoken@github.com/acme/docket.git", - Skills: app.PrepareSkills{Brainstorm: "docket-brainstorm-secret", Plan: "docket-plan", Build: "docket-build"}, }, } } @@ -280,8 +280,58 @@ func TestRepositoryPrepareHumanSummaryRedacted(t *testing.T) { if strings.Contains(out, "s3cr3ttoken") { t.Errorf("human output leaked origin URL credentials: %q", out) } - if strings.Contains(out, "docket-brainstorm-secret") { - t.Errorf("human output dumped the resolved skills map: %q", out) +} + +// TestRepositoryPrepareJSONHasNoSkillsKey proves the prepare context carries no +// `skills` key — neither in the emitted JSON nor in the published schema — while +// sibling keys decoded through the same path are present (non-vacuity). +func TestRepositoryPrepareJSONHasNoSkillsKey(t *testing.T) { + old := repositoryPrepareRunner + repositoryPrepareRunner = func(ctx context.Context, d app.SetupDeps, o app.PrepareOptions) app.OperationResult { + return app.RepositoryPrepareResult{ + Envelope: app.NewEnvelope(app.OperationRepositoryPrepare, app.ResultApplied), + Disposition: app.PrepareDispositionApplied, + RepositoryState: "healthy", + Context: &app.PrepareContext{RepoRoot: "/repo"}, + } + } + defer func() { repositoryPrepareRunner = old }() + + out, _, code := runCLI(t, "repository", "prepare", "--json") + if code != 0 { + t.Fatalf("exit = %d, want 0", code) + } + var doc struct { + Context map[string]json.RawMessage `json:"context"` + } + if err := json.Unmarshal([]byte(out), &doc); err != nil { + t.Fatalf("decode prepare JSON: %v\n%s", err, out) + } + if _, ok := doc.Context["repo_root"]; !ok { + t.Fatalf("context is missing repo_root (vacuous decode?): %s", out) + } + if _, ok := doc.Context["skills"]; ok { + t.Errorf("context still carries the dead skills key: %s", out) + } + + sch, ok, err := app.SchemaFor("repository.prepare", []string{"read"}) + if err != nil || !ok || len(sch.Operations) != 1 { + t.Fatalf("SchemaFor(repository.prepare): ok=%v err=%v", ok, err) + } + keys := map[string]bool{} + var walk func([]app.FieldDescriptor) + walk = func(fs []app.FieldDescriptor) { + for _, f := range fs { + keys[f.Key] = true + walk(f.Fields) + } + } + walk(sch.Operations[0].Result.Fields) + if !keys["metadata_worktree_path"] { + t.Fatalf("schema is missing metadata_worktree_path (vacuous walk?): %v", keys) + } + if keys["skills"] { + t.Errorf("schema still publishes a skills field for repository.prepare") } } diff --git a/internal/cli/revision_rename_test.go b/internal/cli/revision_rename_test.go index 6e4db092e..363f60e9f 100644 --- a/internal/cli/revision_rename_test.go +++ b/internal/cli/revision_rename_test.go @@ -60,7 +60,7 @@ func TestRetiredRevisionRequestKeysRefused(t *testing.T) { // the record revision on a flag. var revisionFlagOps = [][]string{ {"change", "attach-plan"}, {"change", "attach-results"}, {"change", "claim"}, {"change", "halt"}, - {"change", "mark-implemented"}, {"change", "reclaim"}, {"change", "refresh-claim"}, {"change", "resume-halted"}, + {"change", "mark-implemented"}, {"change", "reclaim"}, {"change", "resume-halted"}, {"finalize", "block"}, {"finalize", "clear-block"}, {"finalize", "merge"}, {"finalize", "rebase"}, {"finalize", "retarget-children"}, {"workspace", "prepare"}, } @@ -181,7 +181,6 @@ func TestRevisionFlagReachesRequest(t *testing.T) { args []string }{ {"", []string{"change", "claim", "--id", "1"}}, - {"", []string{"change", "refresh-claim", "--id", "1"}}, {"", []string{"change", "reclaim", "--id", "1"}}, {"", []string{"change", "resume-halted", "--id", "1"}}, {"# Plan\n\nSteps.\n", []string{"change", "attach-plan", "--id", "1", "--path", "p.md", "--markdown", "-"}}, diff --git a/internal/cli/schema.go b/internal/cli/schema.go index 58330d893..7dc240c52 100644 --- a/internal/cli/schema.go +++ b/internal/cli/schema.go @@ -17,12 +17,21 @@ import ( // which reflects the operation-schema registry. func newSchemaCommand(setResult func(app.OperationResult)) *cobra.Command { cmd := &cobra.Command{ - Use: "schema", - Short: "Emit request/result payload schemas and allowed values (read-only, repository-independent)", - Args: cobra.NoArgs, + Use: "schema [<id>]", + Short: "Emit request/result payload schemas and allowed values; one operation by positional <id> or --operation (read-only, repository-independent)", + Args: cobra.MaximumNArgs(1), Annotations: capability("schema", EffectRead), - RunE: func(c *cobra.Command, _ []string) error { + RunE: func(c *cobra.Command, args []string) error { op, _ := c.Flags().GetString("operation") + // The operation id may be given positionally or via --operation + // (change 0360). Both at once must agree: a disagreement refuses as + // invalid arguments rather than silently picking one. + if len(args) == 1 { + if op != "" && op != args[0] { + return fmt.Errorf("schema: positional id %q and --operation %q disagree", args[0], op) + } + op = args[0] + } effects := sortedEffectStrings() if op == "" { doc, err := app.Schema(effects) @@ -44,7 +53,7 @@ func newSchemaCommand(setResult func(app.OperationResult)) *cobra.Command { return nil }, } - cmd.Flags().String("operation", "", "emit only this operation `id` (e.g. change.create)") + cmd.Flags().String("operation", "", "emit only this operation `id` (e.g. change.create); same as the positional <id>") return cmd } diff --git a/internal/cli/schema_command_test.go b/internal/cli/schema_command_test.go index 657bcc72a..a45f1071b 100644 --- a/internal/cli/schema_command_test.go +++ b/internal/cli/schema_command_test.go @@ -142,3 +142,77 @@ func TestSchemaCapabilityAnnotation(t *testing.T) { t.Errorf("schema effects = %v, want [read]", e.Effects) } } + +// TestSchemaCommandPositionalOperation pins the positional form (change 0360): +// `docket schema <id>` is byte-identical to `--operation <id>`, an agreeing +// pair is accepted, and a disagreeing pair or two positionals refuse as invalid +// arguments rather than silently picking one. +func TestSchemaCommandPositionalOperation(t *testing.T) { + a, errA, ca := runCLI(t, "schema", "change.create", "--json") + b, _, cb := runCLI(t, "schema", "--operation", "change.create", "--json") + if ca != 0 || cb != 0 { + t.Fatalf("positional exit=%d, flag exit=%d; want 0/0\n%s\n%s", ca, cb, a, errA) + } + if a != b { + t.Errorf("positional output differs from --operation output:\n%s\n---\n%s", a, b) + } + + both, _, cboth := runCLI(t, "schema", "change.create", "--operation", "change.create", "--json") + if cboth != 0 || both != a { + t.Errorf("agreeing positional + --operation: exit=%d, same bytes=%v; want 0/true\n%s", cboth, both == a, both) + } + + type refusal struct { + Result string `json:"result"` + Reason string `json:"reason"` + } + mis, _, cmis := runCLI(t, "schema", "change.create", "--operation", "change.claim", "--json") + if cmis != 2 { + t.Fatalf("disagreeing positional + --operation exit = %d, want 2\n%s", cmis, mis) + } + var r refusal + if err := json.Unmarshal([]byte(mis), &r); err != nil { + t.Fatalf("mismatch refusal is not valid JSON: %v\n%s", err, mis) + } + if r.Result != "invalid-input" || r.Reason != "invalid-arguments" { + t.Errorf("mismatch refusal = %+v, want invalid-input/invalid-arguments", r) + } + + if two, _, ctwo := runCLI(t, "schema", "change.create", "change.claim", "--json"); ctwo != 2 { + t.Errorf("two positionals exit = %d, want 2\n%s", ctwo, two) + } + + bad, _, cbad := runCLI(t, "schema", "no.such.operation", "--json") + if cbad != 2 { + t.Fatalf("unknown positional exit = %d, want 2\n%s", cbad, bad) + } + var badDoc struct { + Findings []struct { + Code string `json:"code"` + } `json:"findings"` + } + if err := json.Unmarshal([]byte(bad), &badDoc); err != nil { + t.Fatalf("unknown-operation refusal is not valid JSON: %v\n%s", err, bad) + } + found := false + for _, f := range badDoc.Findings { + if f.Code == "unknown-operation" { + found = true + } + } + if !found { + t.Errorf("unknown positional refusal missing finding code unknown-operation: %v", badDoc.Findings) + } + + entries, err := collectCapabilities(productionRootForTest(t)) + if err != nil { + t.Fatal(err) + } + e, ok := entryByID(entries, "schema") + if !ok { + t.Fatal("schema is absent from the capability catalog") + } + if want := "[<id>] [--operation <id>]"; e.Signature != want { + t.Errorf("schema signature = %q, want %q", e.Signature, want) + } +} diff --git a/internal/domain/actions.go b/internal/domain/actions.go index 0a66d0555..a09aa3202 100644 --- a/internal/domain/actions.go +++ b/internal/domain/actions.go @@ -171,7 +171,7 @@ func Claim(c Change, now time.Time) (ActionResult, *PolicyFailure) { } // RefreshClaim re-stamps an in-progress change's lease without changing any -// other field. +// other field. Its callers are change.reconcile and change.resume-halted. func RefreshClaim(c Change, now time.Time) (ActionResult, *PolicyFailure) { if fail := requireStatus(c, "refresh-claim", StatusInProgress); fail != nil { return ActionResult{}, fail diff --git a/internal/repoguard/budgets_test.go b/internal/repoguard/budgets_test.go index 395c86890..adfdf6e3b 100644 --- a/internal/repoguard/budgets_test.go +++ b/internal/repoguard/budgets_test.go @@ -189,7 +189,7 @@ type skillBudget struct { // lock, and launch-unconfirmed is no longer an admission refusal. Pinned at the // 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-adr/SKILL.md", 86, 1161}, // 0360: the producing change is passed through and adr.record appends the number to adrs:, so the caller only verifies it; the raise states that ownership (86/1143 -> 86/1161); 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", 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) @@ -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", 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) + {"docket-convention/SKILL.md", 361, 7377}, // 0360: claimed_at is stamped by claim, reconcile, and resume-halted; a halt no longer claims a refreshed lease (361/7381 -> 361/7377); 0573: trivial retired (362/7411 -> 361/7381); 0560: the hold manifest field, its selection rule, the ## Why on hold section, and the auto-groomer's hold write (360/7331 -> 362/7411); 0565: a kill refuses on built stacked descendants; the killed-parent board text and exits table (360/7317 -> 360/7331); 0568: deferred is entered only from proposed (363/7317 -> 360/7317); 0559: the manifest lists deliverable; done means a merged PR or a completed results artifact; archive dates and change.complete (361/7276 -> 363/7317); 0533: editing visibility never moves a repository; repository.set-visibility does (361/7263 -> 361/7276); 0532: the private-repository writing rule and visibility hand-off (359/7160 -> 361/7263); 0531 review: skills say "the metadata branch", naming `docket` once for shared mode (359/7155 -> 359/7160); 0531: the metadata worktree and remote come from the repository.prepare context (357/7062 -> 359/7155); 0530: plan, results, and build evidence live on the docket branch — the plan-writer's one metadata operation, the attach operations as file-backlink writers, relative same-branch links, and the new ## Build evidence record section (357/7026 -> 357/7062); 0529 review: the backlink block names its PR-body writers beside artifact.backlink, one shared renderer (357/7004 -> 357/7026); 0515: the repair sign-off is retired; a green repair merges (357/7007 -> 357/7004); 0502 rebase onto 0510: kept the backlog-match follow-up clause in the results-artifact paragraph (357/7004 -> 357/7007); 0502 review: the review-tier dispatch is the controller's own (357/6995 -> 357/7004); 0502: configuration read paths corrected — operations read .docket.yml from origin's default-branch tip, the repository setup operations from the primary worktree (357/6959 -> 357/6995); 0502: "loop" means /loop only (357/7036 -> 357/7037); 0502: one metadata layout — the docket branch and the .docket/ worktree (357/7035 -> 357/7036); 0502: agent layer names user-level wrappers and global-only pins (357/7024 -> 357/7035); 0502: typed operations replace the Bash-era script names; ## Run halted facts corrected (359/7092 -> 357/7024); 0502: terminal publish, the learnings cap, and the repository auto_groom default are deleted (362/7256 -> 359/7092); 0502: the auto-capture export paragraph is deleted (370/7334 -> 362/7256); 0502: the configuration contract rewritten from the schema (371/7488 -> 370/7334); 0502: fixed role skills; halt posture (372/7660 -> 371/7488); 0502: record blocks mirror the renderers (367/7619 -> 372/7660); 0502: the dummy-mode shared definition is deleted (390/7848 -> 367/7619); 0410: +required-results lifecycle prose; 0399: +schema request/result contract prose; 0388: +sync-integration prose (see note above); 0502: drop change citations and Go v1 narration (357/7037 -> 357/6958); 0502: the harness adapter is named without a docket source path (357/6958 -> 357/6959) // 0154: docket-convention/github-board-mirror.md removed — the GitHub mirror is // retired (unsupported, mutation-blocking); its budget row is deleted with it. {"docket-convention/references/agent-layer.md", 214, 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) @@ -209,10 +209,10 @@ var skillBudgets = []skillBudget{ {"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", 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, 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/SKILL.md", 226, 8841}, // review: Step 7 names the Step 6 evidence file instead of verified bytes (226/8835 -> 226/8841); 0360 step wording: the PR-body rules moved in from edge-paths.md (which fell 222 words) plus the minimal reconcile request, evidence block file, and ADR producing-change pass-through; the raise is that moved text, compressed (220/8590 -> 226/8835); 0360: local revision lookups, no claim refreshes, fewer re-syncs; the line raise is the new standalone Revision lookups paragraph every post-claim write keys on, words fell (218/8612 -> 220/8590); 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", 99, 1051}, // 0360: the PR-body assembly section moved into SKILL.md Step 7 (109/1273 -> 99/1051); 0360: the resume results load needs no extra re-sync (109/1276 -> 109/1273); 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, 1954}, // 0360: halts no longer claim a refreshed lease (189/1963 -> 189/1954); 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", 76, 737}, // 0360: no claim refreshes; change.complete pins a locally looked-up revision (79/765 -> 76/737); 0573: trivial retired (79/775 -> 79/765); 0559: new — the results-artifact ending (no plan, build, or PR; review, complete, clean up) {"docket-implement-next/results-template.md", 70, 543}, // 0573: trivial retired (70/545 -> 70/543); 0502 rebase onto 0510: carried the backlog verdict and next action in the Known issues placeholder (68/506 -> 70/545); 0502: inline review replaces the custom review skill (68/511 -> 68/510); 0498: +whole-branch review summary line in Verification performed (64/446 -> 68/511); 0440: reader-first template — action statement + merged Known issues (see note above); 0502: drop change citations and Go v1 narration (68/510 -> 68/506) {"docket-review/SKILL.md", 127, 1054}, // 0573: trivial retired (127/1059 -> 127/1054); 0559: the results-artifact mode (114/966 -> 127/1049); 0559: Inputs and evidence sections defer to results-artifact mode (127/1049 -> 127/1059); 0531: the metadata worktree and remote come from the repository.prepare context (114/965 -> 114/966); 0502: the evidence rule keys on the payload's build.gate value; gate-off skipped records are expected (110/913 -> 114/965); 0410: +findings-return capture contract (see note above) {"docket-new-change/SKILL.md", 48, 1538}, // 0573: trivial retired; the trivial path is deleted and the brainstorm is told the artifact is always a spec (53/1636 -> 48/1538); 0560: suggest a hold; it rides change.create or change.groom (53/1598 -> 53/1636); 0559: the create request carries deliverable: results-artifact for findings-only work (57/1635 -> 53/1598); 0532: the private-repository writing rule and visibility hand-off (57/1603 -> 57/1635); 0531: the metadata worktree and remote come from the repository.prepare context (57/1596 -> 57/1603); 0502 review: omitted draft-time scalars are described exactly (57/1591 -> 57/1596); 0502: "loop" means /loop only (57/1593 -> 57/1591); 0502: one metadata layout — the docket branch and the .docket/ worktree (57/1590 -> 57/1593); 0502: terminal-publication narration and the repository auto_groom default are deleted (57/1609 -> 57/1590); 0502: invoke superpowers:brainstorming by name (57/1636 -> 57/1609); 0502: the dummy-mode pointer is deleted (59/1674 -> 57/1636); 0445: +pointer to the docket-groom-next revise path after landing (word ceiling 1700 -> 1706); 0382: draft-time scalars moved into change.create (ceiling 1706 -> 1675) diff --git a/internal/repoguard/private_writing_rule_test.go b/internal/repoguard/private_writing_rule_test.go index 2260f362e..ad06766f5 100644 --- a/internal/repoguard/private_writing_rule_test.go +++ b/internal/repoguard/private_writing_rule_test.go @@ -33,7 +33,6 @@ var privateRuleWriters = []string{ "skills/docket-build/SKILL.md", "skills/docket-implement-next/SKILL.md", "skills/docket-implement-next/references/fix-pass.md", - "skills/docket-implement-next/references/edge-paths.md", "skills/docket-new-change/SKILL.md", "skills/docket-groom-next/SKILL.md", "skills/docket-auto-groom/SKILL.md", @@ -90,8 +89,11 @@ func TestPrivateWritingRuleReachesEveryWriter(t *testing.T) { } } - if len(privateRuleWriters) < 10 { - t.Fatalf("writer table shrank to %d rows, floor is 10", len(privateRuleWriters)) + // Floor 9: change 0360 moved the PR-body rules (and their private-rule + // clauses) from edge-paths.md into docket-implement-next/SKILL.md, which is + // still a writer row, so edge-paths.md left the table. + if len(privateRuleWriters) < 9 { + t.Fatalf("writer table shrank to %d rows, floor is 9", len(privateRuleWriters)) } for _, rel := range privateRuleWriters { if !strings.Contains(normalizeProse(readRepoFile(t, rel)), privateRulePhrase) { diff --git a/internal/repoguard/prose_contracts_test.go b/internal/repoguard/prose_contracts_test.go index fac0ec36e..8bfca0540 100644 --- a/internal/repoguard/prose_contracts_test.go +++ b/internal/repoguard/prose_contracts_test.go @@ -500,6 +500,65 @@ var proseContracts = []proseContract{ }}, {sentinel: "change_0560_hold", file: "skills/docket-status/SKILL.md", present: []string{"a held change that would be build-ready shows **on hold**"}}, + // change 0360 — the run looks its own record revision up locally before each + // post-claim write, re-syncs only where a docket write it did not make could + // have moved the record, and no longer refreshes the claim lease around long + // dispatches (claimed_at is stamped by claim, reconcile, and resume-halted). + {sentinel: "change_0360_revision_lookup", file: "skills/docket-implement-next/SKILL.md", + present: []string{ + "R=$(git -C <metadata_worktree_path> rev-parse HEAD:<record path>)", + "is the commit id, never a `--revision` value", + "re-sync once (the `repository.prepare` operation), look the revision up again, and retry the write once", + "Typed reads fetch on their own", + "reads `claim_eligible: false`", + }, + absent: []string{ + "change.refresh-claim", + "returns the new record revision", + "local tip == remote tip", + "re-sync the metadata worktree immediately before reading it", + "the claim refresh, plan attach, and every earlier checkpoint move the record", + "the `claimed_at` re-stamp", + "`claimed_at` refreshed", + "re-stamps `claimed_at: <UTC ISO-8601 now>` on every mutation", + }}, + {sentinel: "change_0360_revision_lookup", file: "skills/docket-implement-next/references/results-artifact.md", + present: []string{"rev-parse HEAD:<record path>"}, + absent: []string{"change.refresh-claim"}}, + {sentinel: "change_0360_revision_lookup", file: "skills/docket-implement-next/references/fix-pass.md", + present: []string{"the reason recorded"}, + absent: []string{"`claimed_at` refreshed"}}, + {sentinel: "change_0360_revision_lookup", file: "skills/docket-convention/SKILL.md", + present: []string{"stamped by claim, reconcile, and resume-halted"}, + absent: []string{"refreshed at phase boundaries"}}, + // change 0360 — Step 3 sends a minimal reconcile request when nothing + // changed (the operation writes the dated heading); Step 6 writes the + // evidence.record receipt's block to a file instead of a separate verify + // call, passes the producing change to docket-adr so adr.record appends the + // ADR number itself, and sizes the review against the effective base; the + // PR-body rules move from edge-paths.md into Step 7. + {sentinel: "change_0360_step_wording", file: "skills/docket-implement-next/SKILL.md", + present: []string{ + "the operation writes the `### YYYY-MM-DD` heading", + "Unchanged against `<integration tip>`", + "the receipt's `block` field", + "passes the producing change as `{id, path, revision}`", + "one at a time, each with a fresh lookup", + "`git diff --shortstat <effective base>...HEAD`", + "**Best-effort PR→issue reference.**", + "**PR-body back-link.**", + }, + absent: []string{ + "the `evidence.verify` operation", + "repeat the record → verify chain", + "record that number in the change's `adrs:` relation through a `change.reconcile`", + "git diff --shortstat origin/<integration_branch>...HEAD", + "Before assembling it, **read `references/edge-paths.md` now (blocking)**", + }}, + {sentinel: "change_0360_step_wording", file: "skills/docket-implement-next/references/edge-paths.md", + absent: []string{"## PR-body assembly (Step 7)", "Step 7's PR-body assembly"}}, + {sentinel: "change_0360_step_wording", file: "skills/docket-adr/SKILL.md", + present: []string{"has already appended the number to that change's `adrs:`"}}, } // scanProse checks one file's content against a contract, returning a violation diff --git a/internal/repoguard/retired_vocabulary_test.go b/internal/repoguard/retired_vocabulary_test.go index 5b99be2e1..c39b4c165 100644 --- a/internal/repoguard/retired_vocabulary_test.go +++ b/internal/repoguard/retired_vocabulary_test.go @@ -521,8 +521,9 @@ func catalogOpRefs() (*regexp.Regexp, int, error) { opRefErr = fmt.Errorf("capabilities listed no operation references") return } - // Longest first: Go's alternation is leftmost-first, so change.refresh-claim - // must be tried before any shorter reference it contains. + // Longest first: Go's alternation is leftmost-first, so + // finalize.rebase-continue must be tried before the shorter finalize.rebase + // it contains. sort.Slice(alts, func(i, j int) bool { return len(alts[i]) > len(alts[j]) }) opRefRe = regexp.MustCompile(`(?:^|[^A-Za-z0-9_.-])(` + strings.Join(alts, "|") + `)(?:[^A-Za-z0-9_-]|$)`) }) diff --git a/skills/docket-adr/SKILL.md b/skills/docket-adr/SKILL.md index 9cda4fabb..112840a68 100644 --- a/skills/docket-adr/SKILL.md +++ b/skills/docket-adr/SKILL.md @@ -25,10 +25,10 @@ Invoke the `docket-convention` skill via the Skill tool first — unless already ### Create -Build the ADR as a JSON request and hand it to the record transaction on stdin: +Hand the record transaction a JSON request on stdin: ``` -adr.record --request - # resolve argv from the capability catalog +adr.record --request - --repo-dir <dir> --json # resolve argv from the capability catalog ``` The request object (`ADRRecordRequest`, decoded with `DisallowUnknownFields` — an unknown key is rejected) carries: @@ -37,11 +37,11 @@ The request object (`ADRRecordRequest`, decoded with `DisallowUnknownFields` — - `title` — the decision's title. - `context`, `decision`, `consequences`, `alternatives` — the ADR body sections. - `relates_to` — an array of existing ADR ids this decision relates to (optional; each id must resolve or the transaction refuses with `adr-dangling-reference`). -- `change` — the producing change as `{id, path, revision}` (optional; supply it when a change produces this ADR, e.g. `docket-implement-next` step 6). +- `change` — the producing change as `{id, path, revision}` (optional; supply it when a change produces this ADR). `docket-implement-next` step 6 supplies it in its dispatch payload; pass it through unchanged. One validated transaction lands atomically, in a single metadata commit: the next ADR number allocated (max `id:` + 1, 4-digit zero-pad `0024-…`), the new `<NNNN>-<slug>.md` record (`status: Accepted`, today's UTC `date:`, the optional `change:` back-link), graph validation, the re-rendered `<adrs_dir>/README.md` index, and — when `change` is supplied — that change's `adrs:` append and re-rendered `## Artifacts` block. There is **no** separate index commit and **no** hand-allocation, template-write, or manual conflict-checked-rename step: a typed conflict or refusal returns without writing anything, so re-read and retry the operation rather than patching the tree by hand. -**Return the number** — read the allocated ADR id from the operation's result envelope so the caller (e.g. `docket-implement-next` step 6) can cite it in the change's `adrs:` field. +**Return the number** — read the allocated ADR id from the operation's result envelope and return it. When `change` was supplied, the transaction has already appended the number to that change's `adrs:` — the caller only verifies it. **Where an ADR lives** — the ADR and its index live on the metadata branch; no ADR, change-tied or standalone, is copied to the integration branch. @@ -50,10 +50,10 @@ One validated transaction lands atomically, in a single metadata commit: the nex Never edit an `Accepted` ADR's body. To replace a decision, hand the replace transaction a JSON request on stdin: ``` -adr.supersede --request - # resolve argv from the capability catalog +adr.supersede --request - --repo-dir <dir> --json # resolve argv from the capability catalog ``` -(or the `adr.reverse` operation with `--request -` to reverse rather than supersede). The request object (`ADRReplaceRequest`, `DisallowUnknownFields`) carries: +(or `adr.reverse`, same flags, to reverse rather than supersede). The request object (`ADRReplaceRequest`, `DisallowUnknownFields`) carries: - `request_id` — the caller-chosen idempotency key (the outer key governs; the `successor`'s own `request_id` is ignored). - `target` — the ADR being replaced, as `{id, path, revision}`. The target must be `Accepted`, else the transaction refuses. diff --git a/skills/docket-convention/SKILL.md b/skills/docket-convention/SKILL.md index f67b32524..1deed7316 100644 --- a/skills/docket-convention/SKILL.md +++ b/skills/docket-convention/SKILL.md @@ -95,7 +95,7 @@ When dispatch is genuinely unavailable the kinds are **not** equivalent, so the |---|---|---| | **`inline` — deterministic** | the `docket-status` and `docket-adr` composition dispatches | Run the same work **inline** — a **first-class equivalent path**, neither a degradation nor a warning, because the contract is git state on the metadata branch, not an in-context return. Every obligation holds unchanged: re-sync before reading, derive from fresh origin, never adopt or commit another agent's uncommitted files. | | **`abstain` — adversarial** | the `docket-auto-groom-critic` gate | **Abstain**, per *Autonomous grooming*. Self-critique by the agent that drafted the spec is not an adversarial gate, and the abstain is a path that skill already owns. | -| **`halt` — discipline** | the **plan-writer dispatch**, the `build` role skill's required nested dispatches, the controller's own review-tier dispatch (the `docket-review` skill itself never dispatches), and the in-branch fix workers (which run the `build` role's own contract) | **`halt`** — the run stops: the change stays `in-progress` with `claimed_at` refreshed and the halt reason recorded through `change.halt`. **No new status, no new field** — the reclaim lease self-heals an abandoned claim. | +| **`halt` — discipline** | the **plan-writer dispatch**, the `build` role skill's required nested dispatches, the controller's own review-tier dispatch (the `docket-review` skill itself never dispatches), and the in-branch fix workers (which run the `build` role's own contract) | **`halt`** — the run stops: the change stays `in-progress` with the halt reason recorded through `change.halt`. **No new status, no new field** — the reclaim lease self-heals an abandoned claim. | **Outside the table — `no-fallback`.** `docket-finalize-change`'s two finalize-gate dispatches — `docket-rebase-resolver` and `docket-integration-repair` — sit **outside** this table rather than in a row of it, because their contract is an **in-context report** gating the merge, not git state on the metadata branch. Neither fallback can be borrowed for them: `inline`'s first-class-equivalent path presupposes a git-state transition to reproduce, and `halt` belongs to the workflow roles, and these dispatches are not a role. When dispatch is genuinely unavailable for either — established per the resolution rule above, never from a tool name — the posture is finalize's own pre-existing **abort-and-report**: the gate stops, the PR stays open, the change stays `implemented`, and the reason is recorded through the three channels `docket-finalize-change`'s failure reference owns. **Inline substitution is forbidden** for both, and that is the point of `no-fallback` rather than a table row: reconciling the conflict, or authoring the repair, inside the very agent that would then merge that work is the same self-approval shape `abstain` exists to avoid for the critic. @@ -194,7 +194,7 @@ branch: # minted <type>/<slug> (or <branch_prefix>/<slug>) nam pr: # set when the PR is opened blocked_by: # free text; set only when status: blocked reconciled: false # set true after the just-in-time reconcile pass -claimed_at: # UTC ISO-8601 claim lease (YYYY-MM-DDTHH:MM:SSZ); stamped at claim; refreshed at phase boundaries; cleared on leaving in-progress +claimed_at: # UTC ISO-8601 claim lease (YYYY-MM-DDTHH:MM:SSZ); stamped by claim, reconcile, and resume-halted; cleared on leaving in-progress --- ``` diff --git a/skills/docket-implement-next/SKILL.md b/skills/docket-implement-next/SKILL.md index 068061db5..d295618d6 100644 --- a/skills/docket-implement-next/SKILL.md +++ b/skills/docket-implement-next/SKILL.md @@ -26,7 +26,7 @@ Before anything else in this skill, invoke the `docket-convention` skill via the Run the convention's **startup check** (load the convention; run the capability bootstrap; run the `repository.prepare` operation with `--repo-dir <dir> --json` as its own Bash call; validate the protocol-v1 envelope and carry its typed context values forward as literals; act on the disposition). All bookkeeping in this skill (claim, reconcile, `status`, `pr:`, `plan:`, `adrs:`, the plan and results files, build evidence) lands in the metadata worktree (`metadata_worktree_path` in the `repository.prepare` context) on the metadata branch, pushed to the metadata remote (`metadata_remote`) immediately; only the spec copy and the code land on the feature branch. -**Named invocation — no maintenance preflight.** When this run was invoked with exactly **one explicit change id** — an initial named call, an attributed retry carrying the id, or a named resume of an in-progress change — skip the implementation preflight and Step 1's status-digest certification entirely: after the `repository.prepare` operation succeeds, go **directly** to the authoritative `context.implementation` operation with `--id <id>` and the existing claim/resume path. The named path never runs `maintenance.preflight` or any maintenance sweep first — another change's failing closeout, cleanup, or reclaim can never halt this change before its own claim/gate; anyone who wants those maintenance outcomes runs the explicit `maintenance.preflight` or `maintenance.sweep` operation deliberately, where every problem stays visible. Every local check for the named change is kept — readiness, record revision, dependencies, effective base, claim eligibility, run context, and resume/cancellation. A held change (`on-hold`) is built when named. So a malformed, absent, not-ready, or improperly resumed id returns its existing typed refusal, reported with its reason exactly as a scoped-id skip is (ending `drained` when nothing else is in scope); a named request **never falls back to selecting another change**, and shared repository/configuration/transport failures keep the `halted` posture. +**Named invocation — no maintenance preflight.** When this run was invoked with exactly **one explicit change id** — an initial named call, an attributed retry carrying the id, or a named resume of an in-progress change — skip the implementation preflight and Step 1's status-digest certification entirely: after the `repository.prepare` operation succeeds, go **directly** to the authoritative `context.implementation` operation with `--id <id>` and the existing claim/resume path. The named path never runs `maintenance.preflight` or any maintenance sweep first — another change's failing closeout, cleanup, or reclaim can never halt this change before its own claim/gate; anyone who wants those maintenance outcomes runs the explicit `maintenance.preflight` or `maintenance.sweep` operation deliberately, where every problem stays visible. Every local check for the named change is kept — readiness, record revision, dependencies, effective base, claim eligibility, run context, and resume/cancellation; an `in-progress` id is served only to its own resume (Step 1). A held change (`on-hold`) is built when named. So a malformed, absent, not-ready, or improperly resumed id returns its existing typed refusal, reported with its reason exactly as a scoped-id skip is (ending `drained` when nothing else is in scope); a named request **never falls back to selecting another change**, and shared repository/configuration/transport failures keep the `halted` posture. **The named change's own merged dependencies.** Skipping the sweep never declares a dependency satisfied. When the named path's `context.implementation` read refuses `not-ready-waiting-dependency`, **read `references/edge-paths.md` now (blocking)** for the bounded closeout of the named change's own `implemented` dependencies — never any other change's. @@ -38,7 +38,7 @@ Build-readiness and ranking are defined by the convention's **Build-readiness & **Acquisition.** Run the `status` operation with `--json` — a write-free read; on the selection path, only AFTER Step 0's `maintenance.preflight` run and metadata re-sync (the snapshot is taken pre-sweep otherwise and would list already-merged changes). A named invocation takes no ready-queue digest — it arrives here already holding Step 0's directive to read the explicit-id bundle below. Validate the envelope before trusting it: `protocol_version` MUST be `1` and `operation` MUST be `status`. The top-level `ready` array IS the build-ready queue, already in the convention's deterministic order — final tie-break LOWEST `id`, so concurrent implementers converge on one winner. Per-change skip reasons come from each `changes[]` entry's `readiness` / `readiness_reason` fields (`readiness` vocabulary: `build-ready`, `on-hold`, `needs-grooming`, `waiting-dependency`, `stack-base-unresolved`, `not-proposed`, `auto-groom-blocked`, `invalid`; `readiness_reason` carries the human-readable phrase). -The digest is an **accelerator, not the sole channel**: the authoritative read is the `context.implementation` operation with `--id <id>` (no `--id` applies the same selection policy; an attributed retry passes the id). It loads ONE fresh snapshot and returns the change's source bytes, exact opaque **record revision**, readiness, claim-eligibility, resolved effective base, integration branch, and workflow config — the single bundle the claim and every later operation key on, so no step re-reads the change file. **Judgment on that bundle stays yours.** CONFIRM build-readiness (on the named path `on-hold` also qualifies) before claiming — a stale digest costs a re-pick, never a bad build; a typed no-candidate/absent-id/duplicate-id/not-ready/unsupported-config outcome is surfaced, never overridden. If the bundle disagrees with the digest, drop that candidate, take the next, and REPORT it; on the selection path a bundle reporting `on-hold` is dropped and reported the same way. **The exit status and the envelope's shape together govern the disposition.** A **non-zero exit**, or stdout that will not parse as a JSON envelope, **is a hard error** (config export failure, refused bootstrap guard, missing metadata worktree, failed render, or malformed output) — surface its stderr diagnostic and STOP with the **`halted`** disposition; never fall back to `active/` for a hard error, and never report `drained` for one. On **exit 0** with a valid envelope, an **empty `ready` array** (`ready: []`) means the queue is genuinely empty → `drained`. A parseable envelope that is **missing the `ready` key altogether** is malformed machine output — **reject it and STOP with `halted`**, exactly as for a hard error: the typed contract always carries `ready`, so there is no walk-`active/`-yourself degradation. Likewise a failed `protocol_version`/`operation` check. +The digest is an **accelerator, not the sole channel**: the authoritative read is the `context.implementation` operation with `--id <id>` (no `--id` applies the same selection policy; an attributed retry passes the id). It loads ONE fresh snapshot and returns the change's source bytes, exact opaque **record revision**, readiness, claim-eligibility, resolved effective base, integration branch, and workflow config — the single bundle the claim and every later operation key on, so no step re-reads the change file. For the run's own `in-progress` change (a named resume) it returns the bundle with `claim_eligible: false`, the recorded branch, and a readable `halt.run_halted`; a plain named run that reads `claim_eligible: false` surfaces the refusal and ends `drained`, never claiming or building — only a resume proceeds. **Judgment on that bundle stays yours.** CONFIRM build-readiness (on the named path `on-hold` also qualifies) before claiming — a stale digest costs a re-pick, never a bad build; a typed no-candidate/absent-id/duplicate-id/not-ready/unsupported-config outcome is surfaced, never overridden. If the bundle disagrees with the digest, drop that candidate, take the next, and REPORT it; on the selection path a bundle reporting `on-hold` is dropped and reported the same way. **The exit status and the envelope's shape together govern the disposition.** A **non-zero exit**, or stdout that will not parse as a JSON envelope, **is a hard error** (config export failure, refused bootstrap guard, missing metadata worktree, failed render, or malformed output) — surface its stderr diagnostic and STOP with the **`halted`** disposition; never fall back to `active/` for a hard error, and never report `drained` for one. On **exit 0** with a valid envelope, an **empty `ready` array** (`ready: []`) means the queue is genuinely empty → `drained`. A parseable envelope that is **missing the `ready` key altogether** is malformed machine output — **reject it and STOP with `halted`**, exactly as for a hard error: the typed contract always carries `ready`, so there is no walk-`active/`-yourself degradation. Likewise a failed `protocol_version`/`operation` check. **Scope (id allowlist).** With no argument the candidate set is the whole `ready` queue. A caller may pass an **id allowlist** of two or more ids — `docket-implement-next 90,92,94` — and selection is then **restricted to that set**, preserving the queue's order *within* it. (A **single explicit id** is not an allowlist: it is a named invocation and takes Step 0's named branch, never this filter.) The allowlist is a filter, **never a dependency override**: a scoped id that is not currently build-ready+claimable — needs-grooming, on hold, already `in-progress`, or waiting on an unmerged `depends_on` — is **skipped with its reason** (read it off that id's `changes[]` entry — a non-`proposed` `status` there is skipped for that status — or from the change file if it has none — already archived, or no such id), never force-built, and never aborts the run. @@ -46,7 +46,9 @@ The digest is an **accelerator, not the sole channel**: the authoritative read i ### Step 2 — Claim (conflict-checked write) -Claim by transaction: the `change.claim` operation with `--id <id> --revision <revision>` (the exact revision from the step-1 bundle). When the dispatch prompt carried a **run context** token, pass it to the claim as --run-context <token>: the claim validates it against the started run, records durable proof binding this dispatch to its successful claim, and the parent's keyed verdict resolves ownership from that proof; an invalid or conflicting run context is a typed refusal that writes nothing — never retried as an ungated claim. A claim without the token stays supported for ungated invocations. Also pass `--selection queue` on the selection path and `--selection named` on the named path: the run tracker counts a halt toward a loop's halt limit only for a change picked from the queue. In the **metadata working tree** the operation reloads fresh origin, re-proves the change is still `proposed`, uniquely identified, build-ready, and has a resolved effective base, then applies the landed claim (`status: in-progress` + `branch: <type>/<slug>` + `updated:` + `claimed_at:` — the lease the `change.reclaim` operation and the maintenance sweep's reclaim key on) and updates the change record, `## Artifacts` block, and inline board **together in one metadata commit** on the metadata branch, pushed to the metadata remote. It returns the new record revision, feature branch, lease classification, and a closed disposition; a wrong revision or a not-`proposed`/not-build-ready/duplicate/unresolved-base change returns `contended`/a typed refusal that **writes nothing and creates no workspace**. A lost-response retry converges by re-reading authority — an already-held matching claim returns the applied receipt or a typed `already-claimed`, a foreign claim returns `contended`; never adopt a branch or workspace as proof the claim landed. A `contended` result is the **`contended`** disposition (see *Terminal disposition*): a lost conflict-checked claim race is a normal, continue-able outcome a driver re-selects past, **never `halted`** — re-sync (re-run the `repository.prepare` operation) and re-select. No worktree yet. +Claim by transaction: the `change.claim` operation with `--id <id> --revision <revision>` (the exact revision from the step-1 bundle). When the dispatch prompt carried a **run context** token, pass it to the claim as --run-context <token>: the claim validates it against the started run, records durable proof binding this dispatch to its successful claim, and the parent's keyed verdict resolves ownership from that proof; an invalid or conflicting run context is a typed refusal that writes nothing — never retried as an ungated claim. A claim without the token stays supported for ungated invocations. Also pass `--selection queue` on the selection path and `--selection named` on the named path: the run tracker counts a halt toward a loop's halt limit only for a change picked from the queue. In the **metadata working tree** the operation reloads fresh origin, re-proves the change is still `proposed`, uniquely identified, build-ready, and has a resolved effective base, then applies the landed claim (`status: in-progress` + `branch: <type>/<slug>` + `updated:` + `claimed_at:` — the lease the `change.reclaim` operation and the maintenance sweep's reclaim key on) and updates the change record, `## Artifacts` block, and inline board **together in one metadata commit** on the metadata branch, pushed to the metadata remote. It returns the feature branch, lease classification, and a closed disposition; a wrong revision or a not-`proposed`/not-build-ready/duplicate/unresolved-base change returns `contended`/a typed refusal that **writes nothing and creates no workspace**. A lost-response retry converges by re-reading authority — an already-held matching claim returns the applied receipt or a typed `already-claimed`, a foreign claim returns `contended`; never adopt a branch or workspace as proof the claim landed. A `contended` result is the **`contended`** disposition (see *Terminal disposition*): a lost conflict-checked claim race is a normal, continue-able outcome a driver re-selects past, **never `halted`** — re-sync (re-run the `repository.prepare` operation) and re-select. No worktree yet. + +**Revision lookups.** The claim pins the pre-claim bundle's revision and `change.resume-halted` the context bundle's. Before every later write to its own record — `change.reconcile`, `change.halt`, a reconcile-kill's `change.kill`, `workspace.prepare`, the revision handed to the plan-writer, the producing-change revision handed to `docket-adr`, each `change.attach-results`, and `change.mark-implemented` — the run reads the revision from the local metadata checkout in the same shell call as the write (or immediately before the dispatch carrying it): `R=$(git -C <metadata_worktree_path> rev-parse HEAD:<record path>)`, `<record path>` being the bundle's `change.path`, which does not move while the change is active. A receipt's `committed_revision` is the commit id, never a `--revision` value. On `contended`, re-sync once (the `repository.prepare` operation), look the revision up again, and retry the write once — except `change.reconcile`, which keeps its re-read-and-re-author rule (Step 3); a second `contended` follows the step's existing stop rule. A claim of a `proposed` record that still carries a `## Run halted` section removes that section in the same transaction. **Resuming a halted in-progress change** — one the caller re-dispatches by id after a `run.verify` verdict of **`run-halted`** — goes through the `change.resume-halted` operation with `--id <id> --revision <revision> --acknowledge-quiescent`, never a fresh claim: it requires the exact marked record and the explicit `--acknowledge-quiescent` acknowledgement that the prior worker is quiescent, reprobes the branch/workspace/live gate, refreshes the claim, and removes exactly the `## Run halted` marker section while preserving every other byte and checkpoint — it never resets or adopts a workspace whose writer may be live. It refuses (writing nothing) without the acknowledgement, on revision drift (`contended`), or on a live gate lock. A change that instead reached `proposed` through the `change.reclaim` operation carries no live claim, so it re-enters through the ordinary claim above. The claim and resume both render the inline board in their own transaction, so no separate Board pass runs here. Starting the resume also passes through the run tracker, which refuses a second run over one that has not verifiably stopped — **read `references/edge-paths.md` now (blocking)** for those run-tracker resume refusals and their remedies. @@ -54,7 +56,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 <request-file>` (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. +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 <request-file>` (the request file carries `id`, the pinned `revision`, and the authored Markdown — never a shell-escaped flag). The `reconcile_log_entry` is the **section body only** — the operation writes the `### YYYY-MM-DD` heading. When nothing changed (spec, stack base, related changes, and scope all hold), send just `{id, revision, reconcile_log_entry}` with a one-line body such as "Unchanged against `<integration tip>`"; sections and relations go in only when reality requires a change. 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*). @@ -65,7 +67,7 @@ Two escape hatches: ### Step 4 — Worktree + plan -CONFIRM the step-3 reconcile push has landed on the **metadata branch** before continuing — by **SHA-compare**, not "the push exited 0": after a re-sync, the local metadata tip must equal the remote tip (re-run the `repository.prepare` operation, assert `git -C <metadata_worktree_path> rev-parse HEAD` equals `git -C <metadata_worktree_path> rev-parse <metadata_tracking_ref>`). If they differ (a concurrent writer rejected the push): re-sync, re-push — repeat until the SHAs match, so the build never reads bytes older than origin. Then prepare the owned feature workspace: +Step 3's `applied` reconcile receipt proves its exact-lease push landed on the metadata branch. Prepare the owned feature workspace: ``` workspace.prepare --id <id> --revision <revision> # resolve argv from the capability catalog @@ -77,7 +79,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/<integration_branch>` 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 <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 <id> --revision <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**. The `repository.prepare` operation runs at startup, after a dispatched agent writes the change, once after a `contended` write, and on a contended claim. Typed reads fetch on their own, and plain-file reads of the metadata checkout follow every docket write, so no other re-sync is needed. Then run the `workspace.commit-spec` operation with `--id <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. <!-- docket:feature-dispatch:start targets=docket-plan-writer --> **Plan authoring (dispatched).** The parent stays the orchestrator. @@ -89,24 +91,24 @@ It also supplies the change id, title, exact record revision, synchronized chang **Verification (parent).** The returned path is a **claim, not proof**. Re-sync the metadata worktree (the `repository.prepare` operation), then verify from git on the metadata branch that `plan:` equals the returned path, the file exists at the metadata tip under `docs/superpowers/plans/` with a backlink to this change, and that the feature worktree is clean with HEAD equal to the pre-dispatch HEAD. On a malformed return, a missing or mismatched `plan:`, a missing file or backlink, a dirty worktree, or a moved HEAD: **halt** (`## Run halted` + the `halted` disposition) — **never adopt**, repair, or commit the child's output, and never retry with the parent or a weaker model. The attach refuses an unsafe path, an unbalanced backlink, an unresolved placeholder, a `plan:` naming another path (`artifact-path-mismatch`), or a path holding another change's file (`artifact-path-occupied`), writing nothing; a lost-response retry with the same bytes replays its applied receipt. -**Continue.** After the dispatch returns, a `PLAN_PATH` return MUST be verified; the child's attach moved the record, so on the re-synced tree re-read its revision (the `context.implementation` operation with `--id <id>`) and **refresh the claim again** with it (the `change.refresh-claim` operation) to stamp the plan→build seam, then the parent MUST proceed into Step 5 — `PLAN_PATH` is a sub-step receipt, **never** a terminal disposition, and neither the child's return nor Step 4's postcondition may be reported as `advanced`. **Dispatch fallback (`halt`):** plan-writer dispatch unavailable — established only per the convention's *Dispatch-capability resolution*, never from a tool name — is **`halt`**: the change stays `in-progress` with `claimed_at` refreshed and the halt reason recorded. Build workers and reviewers read the plan from the metadata worktree (`<metadata_worktree_path>/<plan path>`, after a re-sync); the archive transaction retargets every metadata backlink in its own commit. +**Continue.** After the dispatch returns, a `PLAN_PATH` return MUST be verified; the child's attach moved the record, so every later write looks its revision up again (*Revision lookups*, Step 2); then the parent MUST proceed into Step 5 — `PLAN_PATH` is a sub-step receipt, **never** a terminal disposition, and neither the child's return nor Step 4's postcondition may be reported as `advanced`. **Dispatch fallback (`halt`):** plan-writer dispatch unavailable — established only per the convention's *Dispatch-capability resolution*, never from a tool name — is **`halt`**: the change stays `in-progress` with the halt reason recorded. Build workers and reviewers read the plan from the metadata worktree (`<metadata_worktree_path>/<plan path>`); the archive transaction retargets every metadata backlink in its own commit. ### Step 5 — Build -**Refresh the claim** (the `change.refresh-claim` operation) immediately before this long **build-role invocation** and again when it returns, at a revision re-read after a re-sync (a build checkpoint moves the record) — a refresh `contended` stops a new invocation but never cancels a build already running. The build role — `docket-build` — is invoked **DIRECTED to:** execute the plan task-by-task and stop at the executed plan, carrying the prepare context's `visibility` so every worker payload names its `Visibility`. `docket-build` is a skill to invoke, never a same-name agent to dispatch (convention, *Skill layer*): the invoked skill directs the controller to dispatch one named build-tier worker per plan task and gates on one full-suite run. A rejected attempt to dispatch a same-name `docket-build` agent is the wrong operation, never capability evidence — resume at the skill invocation; no metadata or worktree state changed because that probe was refused. **Proceed through the build — the deliverable is the executed plan, never the decision about how to execute it.** Separately, and without ever relaxing the first: answer any choice it poses from resolved config, surface none, and log one line naming the role and skill if you suppressed a hand-off. Emitting that log line discharges the suppression obligation only; the step is not complete until its git-state postcondition holds — see *Step postconditions*. When `docket-build` cannot be invoked, apply the convention's missing-skill rule: execute the plan inline on the feature branch, warning prominently — the artifact is the executed plan. If the invoked skill's **required nested dispatch** — a build-tier worker — is unavailable (established only per the convention's *Dispatch-capability resolution* — never from a tool name), the build role is **`halt`**: the change stays `in-progress` with `claimed_at` refreshed and the halt reason recorded. When the build role returns `halted`, the `## Run halted` report carries its halt report's gate evidence verbatim, a `tree-survives` finding included — information for the human, never a different disposition. +The build role — `docket-build` — is invoked **DIRECTED to:** execute the plan task-by-task and stop at the executed plan, carrying the prepare context's `visibility` so every worker payload names its `Visibility`. `docket-build` is a skill to invoke, never a same-name agent to dispatch (convention, *Skill layer*): the invoked skill directs the controller to dispatch one named build-tier worker per plan task and gates on one full-suite run. A rejected attempt to dispatch a same-name `docket-build` agent is the wrong operation, never capability evidence — resume at the skill invocation; no metadata or worktree state changed because that probe was refused. **Proceed through the build — the deliverable is the executed plan, never the decision about how to execute it.** Separately, and without ever relaxing the first: answer any choice it poses from resolved config, surface none, and log one line naming the role and skill if you suppressed a hand-off. Emitting that log line discharges the suppression obligation only; the step is not complete until its git-state postcondition holds — see *Step postconditions*. When `docket-build` cannot be invoked, apply the convention's missing-skill rule: execute the plan inline on the feature branch, warning prominently — the artifact is the executed plan. If the invoked skill's **required nested dispatch** — a build-tier worker — is unavailable (established only per the convention's *Dispatch-capability resolution* — never from a tool name), the build role is **`halt`**: the change stays `in-progress` with the halt reason recorded. When the build role returns `halted`, the `## Run halted` report carries its halt report's gate evidence verbatim, a `tree-survives` finding included — information for the human, never a different disposition. ### Step 6 — Review + ADRs **Validate the build evidence.** Read the build-evidence record step 5's gate emitted — it must be present, its `head_sha` equal to the branch HEAD, and its `result` either `green` or `skipped` (the repo set `build.gate: off`, carrying `reason: build-gate-off`, no command). Missing, malformed, or stale is a build-contract violation — never review an uncertified branch. Re-mint once yourself: under `build.gate: off`, the `evidence.record` operation with `--id <id> --head <feature head>` and no run dir mints the skipped record; under a local gate, **drive** the native gate — never author a launch/observe/sleep sequence of your own: the `gate.drive.start` operation with `--repo-dir <absolute-feature-worktree> --run-root <absolute-run-root> --owner build --change-id <id> --run-context <token> --json` (`--owner build` resolves the build-owned command; no suite argv; `--change-id` always, so the attempt is charged and the run tracker can find the drive; `--run-context` carries your dispatch prompt's value, omitted only when it carried none) — capture that first JSON response into `gate_reply` and the drive id and owner generation from it, its exit code (if needed) into `gate_rc`, never a zsh read-only special parameter such as `status` (the shared JSON-capture requirement; human text omits the generation) — then the `gate.drive.advance` operation with `--drive-id <id> --owner-gen <gen>` — one slice per call — under docket-build's bounded gate-run posture until a terminal disposition. The typed disposition vocabulary lives in `docket-build`'s `references/gate-driver.md`; only a **`PASSED`** disposition at the current head exposes the raw run dir that feeds the recording below — `FAILED`/`HALTED`/`WAITING` never do. -**Create the durable evidence.** Under a local gate, only from a **`PASSED`** drive disposition whose head equals the current feature head: the `evidence.record` operation with `--id <id> --run <absolute run-dir> --head <feature head>` reads the outcome from the run directory that disposition exposed and the gate command from the build configuration (`build.test_command`) — **no agent-supplied `passed` boolean** — and returns the immutable typed record; a `FAILED`/`HALTED`/`WAITING` or head-mismatched drive produces none. Then the `evidence.verify` operation with `--record <request-file> --head <feature head>` re-checks its bytes against the head. Any review fix below changes HEAD and **invalidates this evidence** — repeat the record → verify chain before publishing. +**Create the durable evidence.** Under a local gate, only from a **`PASSED`** drive disposition whose head equals the current feature head: the `evidence.record` operation with `--id <id> --run <absolute run-dir> --head <feature head>` reads the outcome from the run directory that disposition exposed and the gate command from the build configuration (`build.test_command`) — **no agent-supplied `passed` boolean** — and returns the immutable typed record; a `FAILED`/`HALTED`/`WAITING` or head-mismatched drive produces none. Write the receipt's `block` field to a file: that file is the `--evidence` input for `pr.publish` and `change.mark-implemented`, which each re-verify it against the head. Any review fix below changes HEAD and **invalidates this evidence** — repeat the record step before publishing. -For the `docket-review` role, **select the review tier** deterministically from the build record — take the **highest tier any task routed or escalated to** (an escalation counts as the tier escalated *to*), then map `economy` to `docket-review-lean`, `standard` to `docket-review-standard`, and `premium` or `max` to `docket-review-deep`. When the build emits **no build record** (for example, it ran inline under the missing-skill rule), the tier defaults to `docket-review-standard`, matching the uncertainty sink `standard` is in docket-build's own routing. One modifier: a whole-branch diff of more than **1500 changed lines** — insertions + deletions from `git diff --shortstat origin/<integration_branch>...HEAD` — bumps the tier one step, capped at deep — the only selection signal independent of the build's own self-assessment. Log the chosen tier and its reason as one line. Selection is a rule over the build record, never model judgment. +For the `docket-review` role, **select the review tier** deterministically from the build record — take the **highest tier any task routed or escalated to** (an escalation counts as the tier escalated *to*), then map `economy` to `docket-review-lean`, `standard` to `docket-review-standard`, and `premium` or `max` to `docket-review-deep`. When the build emits **no build record** (for example, it ran inline under the missing-skill rule), the tier defaults to `docket-review-standard`, matching the uncertainty sink `standard` is in docket-build's own routing. One modifier: a whole-branch diff of more than **1500 changed lines** — insertions + deletions from `git diff --shortstat <effective base>...HEAD`, the bundle's `effective_base` (`origin/<integration_branch>`, or the parent's branch for a stacked change — the base `workspace.prepare` cut from) — bumps the tier one step, capped at deep — the only selection signal independent of the build's own self-assessment. Log the chosen tier and its reason as one line. Selection is a rule over the build record, never model judgment. <!-- docket:feature-dispatch:start targets=docket-review-deep,docket-review-lean,docket-review-standard --> The review role — `docket-review` — is invoked **DIRECTED to:** review the whole branch against its base and return its findings, then stop, answering any choice it poses from resolved config and never surfacing one — log one line naming the role and skill if you suppressed a hand-off. `docket-review` is a skill, never a same-name agent to dispatch, and the skill itself dispatches nothing: you — the controller — dispatch the selected tier wrapper — `docket-review-lean`, `docket-review-standard`, or `docket-review-deep` — foreground, and that wrapper preloads the `docket-review` skill. Its dispatch payload contains: Feature worktree: <absolute canonical feature-worktree root> -It also contains the branch and base ref, change title and scope, relevant learnings hooks, the evidence record, and the resolved `build.gate` value (from the startup-check prepared context's `build` block). When the `docket-review` skill is missing, apply the convention's missing-skill rule: review the whole branch inline before the PR opens, warning prominently, and dispatch no reviewer. Re-read the learnings index `<changes_dir>/learnings/README.md` first and pull the findings relevant to what this change touched (skipped entirely when `learnings.enabled` is `false`). For any non-obvious decision made during implementation, **dispatch the `docket-adr` subagent** (foreground, at the model/effort its wrapper resolves) — once per decision; it assigns the number, updates the index, commits the ADR on the metadata remote, and **returns the number**. After re-syncing the metadata worktree, record that number in the change's `adrs:` relation through a `change.reconcile` operation relations update — the transaction re-checks the exact revision and re-renders the `## Artifacts` block and inline board atomically, so the skill never hand-renders a derived view. Review findings that are distinct follow-up work — not this change's own fixes — are **reported as follow-up work in the final report**; nothing is minted automatically, and a human captures reported work deliberately with `docket change create`. On unavailable dispatch — established only per the convention's *Dispatch-capability resolution*, never from a tool name, and never from a rejected same-name role-agent attempt — an undispatchable review tier makes the review role **`halt`** on the same terms as step 5; the `docket-adr` dispatch falls back **`inline`**, with its git-state contract unchanged. +It also contains the branch and base ref, change title and scope, relevant learnings hooks, the evidence record, and the resolved `build.gate` value (from the startup-check prepared context's `build` block). When the `docket-review` skill is missing, apply the convention's missing-skill rule: review the whole branch inline before the PR opens, warning prominently, and dispatch no reviewer. Re-read the learnings index `<changes_dir>/learnings/README.md` first and pull the findings relevant to what this change touched (skipped entirely when `learnings.enabled` is `false`). For any non-obvious decision made during implementation, **dispatch the `docket-adr` subagent** (foreground, at the model/effort its wrapper resolves) — once per decision. Each payload passes the producing change as `{id, path, revision}` (path from the bundle, revision from *Revision lookups*, Step 2); `docket-adr` passes it through as the request's `change`, so `adr.record` assigns the number, updates the index, appends it to `adrs:`, and re-renders `## Artifacts` in one metadata commit, then **returns the number**. Several ADRs go one at a time, each with a fresh lookup. After each returns, re-sync once (the `repository.prepare` operation) and check from git that the number is in `adrs:`. A `contended` from `adr.record`: re-sync, look the revision up again, and re-dispatch once; a second `contended` is a hard error that ends the run `halted`. Review findings that are distinct follow-up work — not this change's own fixes — are **reported as follow-up work in the final report**; nothing is minted automatically, and a human captures reported work deliberately with `docket change create`. On unavailable dispatch — established only per the convention's *Dispatch-capability resolution*, never from a tool name, and never from a rejected same-name role-agent attempt — an undispatchable review tier makes the review role **`halt`** on the same terms as step 5; the `docket-adr` dispatch falls back **`inline`**, with its git-state contract unchanged. <!-- docket:feature-dispatch:end --> **Triage the returned findings, then FIX them in-branch.** Findings are repaired on the open branch before the PR opens — a bounded **fix pass**, not a stub for every one. `review.min_fix_severity` (read through the `diagnostic.config` operation; `minor` by default) is the lowest severity that enters it, and blockers are fixed regardless of it. Routing is by the fix's CHARACTER via the shared rubric, never by its severity, and never reaches the `max` tier; every fix runs the `docket-build-task` contract. Before dispatching the first fix task, **read `references/fix-pass.md` now (blocking)** — it owns the routing table, the non-blocker task cap, the per-finding and batched task shapes, the revert-and-record suite gate (bounded at two runs; still-red halts), and the PR-body disposition table. The reviewer's `unverified-build-state` blocker is the one exception you resolve yourself, by re-running the suite — or, under `build.gate: off`, by re-minting the skipped record. A finding that is genuinely distinct beyond-the-branch work is reported as follow-up work in the final report, carrying the backlog verdict final consolidation attaches; a finding about this branch's own diff never is. There is **no re-review** round after fixes — remediation is carried by the worker's own self-review, the suite re-run, and the human reading every fix in the PR diff. @@ -122,9 +124,9 @@ The results artifact is **required for every implemented change** — there is n **Per-checkpoint mechanics** (in order): 1. Verify ownership and quiescence — no live gate, running worker, or transferred drive. -2. Read and **preserve** the prior results content — after a re-sync, from `<metadata_worktree_path>/<results path>` when `results:` is set; a checkpoint updates it, never truncates it — except final consolidation, which condenses the review findings (*Review findings* below). +2. Read and **preserve** the prior results content — from `<metadata_worktree_path>/<results path>` when `results:` is set; a checkpoint updates it, never truncates it — except final consolidation, which condenses the review findings (*Review findings* below). 3. Write the update into the scratch file. -4. Attach it: the `change.attach-results` operation with `--id <id> --revision <revision> --path <results path> --markdown <file>`, at a revision re-read after a re-sync (the `context.implementation` operation with `--id <id>`) because the claim refresh, plan attach, and every earlier checkpoint move the record, writes the file with its backlink and sets `results:` in one metadata commit that never moves the feature head; later checkpoints keep the **same path**. +4. Attach it: the `change.attach-results` operation with `--id <id> --revision <revision> --path <results path> --markdown <file>`, at a freshly looked-up revision (*Revision lookups*, Step 2), writes the file with its backlink and sets `results:` in one metadata commit that never moves the feature head; later checkpoints keep the **same path**. **Evidence sequencing.** Results prose is **never gate evidence**, and a results checkpoint never moves HEAD, so it never stales evidence. Obtain gate evidence for the final code head through the gate driver; any code commit (a fix) still invalidates it. **Never** rewrite results solely to paste the final gate's SHA or timestamp. A new material finding surfaced by the final gate is preserved in results, the fix/halt policy applies, and evidence is re-established after any commit. @@ -140,9 +142,15 @@ The results artifact is **required for every implemented change** — there is n **Publish the feature head.** The `workspace.publish` operation with `--id <id> --head <feature head>` inspects the owned workspace and pushes the exact head through the landed non-forcing publication, returning the verified remote head. It refuses when the reinspected head differs from `--head`; a divergent remote ref is `contended`, unknown post-effect state is `unknown` (reprobe on retry) — neither forces, and no PR opens here. -**PR-body assembly.** The authored PR body carries the best-effort `#<issue>` reference (never `Closes #N`), and the review disposition table; `pr.publish` adds the back-link line and the plan/results links block. The PR body carries no build-evidence block. In a private repository the authored title and body follow the private-repository writing rule: no `#<issue>` reference, no change id in the title, and `pr.publish` publishes the body verbatim. Before assembling it, **read `references/edge-paths.md` now (blocking)** — it owns the mechanics. +**PR-body assembly.** The PR body carries no build-evidence block. In a private repository the authored title and body follow the private-repository writing rule: no `#<issue>` reference, no change id in the title, and `pr.publish` publishes the body verbatim, with no back-link line and no links block. + +**Best-effort PR→issue reference.** If the change carries an `issue:` value, add a plain `#<issue>` reference to the PR body — but **never `Closes #N`**, so merging the PR never auto-closes the referenced issue. Skip silently when `issue:` is unset — the reference is a one-time courtesy, not a build gate. + +**PR-body back-link.** `pr.publish` renders and upserts a **back-link line** pointing home to the change on the metadata branch — a first body line of the shape `↩ Change <padded-id> — <title>` linking to the change file on `docket` (built with the same blob-or-bare-path logic) — plus a Docket-owned links block pointing at the plan and results files on the metadata branch; never author either in the body. + +**Review outcome.** The authored body names the reviewing tier and carries the **findings disposition table**: one row per finding, marked fixed (with its commit SHA), deferred, reverted, recorded, or reported — the states `references/fix-pass.md` defines. -**Publish the PR.** With the authored title+body and the verified evidence bytes each in a request file, the `pr.publish` operation with `--id <id> --head <feature head> --body <request-file> --evidence <evidence request-file>` reparses the evidence (never a prior result) and verifies local HEAD == published remote head == evidence head == requested head, and that the feature branch, effective-base branch, and repository identity agree, BEFORE calling the landed GitHub adapter; it then inserts or replaces ONLY the Docket-owned backlink and plan/results links blocks (authored prose byte-preserved) and returns the canonical PR reference, URL, number, head, base, and disposition. `unknown` stays `unknown` — reprobe, never a duplicate PR — and the result redacts the body bytes. It refuses `record-invalid` (`invalid-state`) before any GitHub call when the change, a `depends_on` target, or a stack ancestor carries a validation error (associative links are never checked): no PR was created or edited — repair exactly the records the result's `findings` name, then re-publish; the run keeps its existing halt posture for a typed refusal. +**Publish the PR.** With the authored title+body and the Step 6 evidence file (the `evidence.record` receipt's `block` text) each in a request file, the `pr.publish` operation with `--id <id> --head <feature head> --body <request-file> --evidence <evidence request-file>` reparses the evidence (never a prior result) and verifies local HEAD == published remote head == evidence head == requested head, and that the feature branch, effective-base branch, and repository identity agree, BEFORE calling the landed GitHub adapter; it then inserts or replaces ONLY the Docket-owned backlink and plan/results links blocks (authored prose byte-preserved) and returns the canonical PR reference, URL, number, head, base, and disposition. `unknown` stays `unknown` — reprobe, never a duplicate PR — and the result redacts the body bytes. It refuses `record-invalid` (`invalid-state`) before any GitHub call when the change, a `depends_on` target, or a stack ancestor carries a validation error (associative links are never checked): no PR was created or edited — repair exactly the records the result's `findings` name, then re-publish; the run keeps its existing halt posture for a typed refusal. **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. @@ -158,15 +166,15 @@ Each step below is complete only when its row holds — read from **git**, never | Step | Complete only when | |---|---| -| 2 Claim | `status: in-progress` + `branch:` + `updated:` + `claimed_at:` committed on the metadata branch **and landed** (local tip == remote tip). | +| 2 Claim | `status: in-progress` + `branch:` + `updated:` + `claimed_at:` committed on the metadata branch **and landed** (an `applied` claim receipt). | | 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 `<type>/<slug>`, then `plan:` and the plan file with its backlink landed on the metadata branch, the feature HEAD unchanged by planning. | +| 4 Worktree + plan | the spec copy committed as the first commit on `<type>/<slug>`, 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 `<type>/<slug>`, 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/<type>/<slug>` 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. | | Results-artifact ending | the change `done` and archived on the metadata branch, `results:` set, and the final results file with its backlink on the metadata branch. | -Rows 3, 4, 6 and 7 each carry, in addition, the **field-write rule**'s conditions on every metadata commit they name: the `claimed_at` re-stamp, and — for any link-bearing field write — the regenerated `## Artifacts` block in the same commit. +Rows 3, 4, 6 and 7 each carry, in addition, the **field-write rule**'s link-bearing condition on every metadata commit they name: the regenerated `## Artifacts` block in the same commit. Steps 0, 1 and 6.5 get no row: 0 produces nothing scoped to this change, 1 is a pure read, and 6.5's artifact is certified by Step 7's results condition or the results-artifact ending's. @@ -207,7 +215,7 @@ A change is drafted against a *snapshot* of the codebase, ADRs, and other in-fli ### The field-write rule -Every change-file field write in this run (claim's `status:`/`branch:`, reconcile, `plan:`, `adrs:`, `results:`, `pr:` + `status: implemented`) lands through a **`change.*` / attach / mark-implemented transaction** in the metadata worktree on the metadata branch — never a hand-edit, never in the feature worktree — which reloads fresh origin, checks the exact record revision, and commits and pushes atomically. The skill **never invokes a facade renderer and never hand-writes a derived view**: the transaction re-stamps `claimed_at: <UTC ISO-8601 now>` on every mutation and, for any **link-bearing field** (`spec:`/`plan:`/`adrs:`/`pr:`/`results:`), regenerates the `## Artifacts` block and inline board in the same commit; the skill also refreshes the claim explicitly (the `change.refresh-claim` operation) around the long plan and build dispatches, stamping the plan→build seam where a stopped run is otherwise invisible. The halt-path authored sections also land through transactions, never a hand-edit: the `change.halt` operation writes the `## Run halted` section (Step 3) and the `change.resume-halted` operation removes it on resume (Step 2), each an exact-revision transaction that renders the inline board in its own commit. The skill authors the halt report as a request file and hands it across; it never edits the section bytes itself. **Stage by explicit path** — that tree is shared, so a bare `add -A` commits another agent's staged work under your message. +Every change-file field write in this run (claim's `status:`/`branch:`, reconcile, `plan:`, `adrs:`, `results:`, `pr:` + `status: implemented`) lands through a **`change.*` / attach / mark-implemented transaction** in the metadata worktree on the metadata branch — never a hand-edit, never in the feature worktree — which reloads fresh origin, checks the exact record revision, and commits and pushes atomically. The skill **never invokes a facade renderer and never hand-writes a derived view**: for any **link-bearing field** (`spec:`/`plan:`/`adrs:`/`pr:`/`results:`), the transaction regenerates the `## Artifacts` block and inline board in the same commit; `claimed_at` is stamped only by the claim, reconcile, and resume-halted transactions. The halt-path authored sections also land through transactions, never a hand-edit: the `change.halt` operation writes the `## Run halted` section (Step 3) and the `change.resume-halted` operation removes it on resume (Step 2), each an exact-revision transaction that renders the inline board in its own commit. The skill authors the halt report as a request file and hands it across; it never edits the section bytes itself. **Stage by explicit path** — that tree is shared, so a bare `add -A` commits another agent's staged work under your message. ### Feature branch invariants diff --git a/skills/docket-implement-next/references/edge-paths.md b/skills/docket-implement-next/references/edge-paths.md index 1f1804122..40b85d961 100644 --- a/skills/docket-implement-next/references/edge-paths.md +++ b/skills/docket-implement-next/references/edge-paths.md @@ -1,8 +1,8 @@ # edge-paths — the implementer's rare edges The rare edges of `docket-implement-next` — read at the trigger moment named in SKILL.md (a named -invocation waiting on its own dependency, a reconcile-kill, a resume of an `in-progress` change, or -Step 7's PR-body assembly). Loaded on demand; sibling files are not auto-loaded with the skill. +invocation waiting on its own dependency, a reconcile-kill, or a resume of an `in-progress` +change). Loaded on demand; sibling files are not auto-loaded with the skill. ## Named invocation's own merged dependencies (Step 0, bounded closeout) @@ -85,7 +85,7 @@ refreshes the copy; otherwise it is a no-op. **The results seam.** The results artifact is required for every change, so a resume must not lose it. On resume, **load the attached results from the metadata worktree (`metadata_worktree_path` in the `repository.prepare` context) at -`<metadata_worktree_path>/<results path>`, after a re-sync, before starting new work**, and +`<metadata_worktree_path>/<results path>` before starting new work**, and reuse the `results:` path whenever it is set — a changed authoring date **never mints a second file**; the canonical path is chosen once and reused. **Never overwrite newer remote work** — a resume that finds the remote ahead re-reads authority rather than force-writing its local view. @@ -97,13 +97,3 @@ or the continuation it was already going to take) and **reports the capture limi existing halt/continuation channel** — no fabricated results path, no stolen lease, and no delayed gate handoff to make room for a write. The missing capture is a reported limitation, never a reason to force a workspace, a commit, or a HEAD move. - -## PR-body assembly (Step 7) - -**Best-effort PR→issue reference.** If the change carries an `issue:` value, add a plain `#<issue>` reference to the PR body — but **never `Closes #N`**, so merging the PR never auto-closes the referenced issue. Skip silently when `issue:` is unset — the reference is a one-time courtesy, not a build gate. None in a private repository (private-repository writing rule); the body is published verbatim. - -**PR-body back-link.** `pr.publish` renders and upserts a **back-link line** pointing home to the change on the metadata branch — a first body line of the shape `↩ Change <padded-id> — <title>` linking to the change file on `docket` (built with the same blob-or-bare-path logic) — plus the plan/results links block; never author either in the body. None in a private repository (private-repository writing rule); the body is published verbatim. - -**Review outcome.** The authored body names the tier that reviewed and carries the **findings disposition table**: one row per finding, each marked fixed (with its commit SHA), deferred, reverted, recorded, or reported. The table's states are defined in `fix-pass.md`; do not redefine them here. - -**Plan/results links.** `pr.publish` adds a Docket-owned links block pointing at the plan and results files on the metadata branch; never author it by hand. None in a private repository (private-repository writing rule); the body is published verbatim. diff --git a/skills/docket-implement-next/references/fix-pass.md b/skills/docket-implement-next/references/fix-pass.md index cdda517fc..d2e8d0b92 100644 --- a/skills/docket-implement-next/references/fix-pass.md +++ b/skills/docket-implement-next/references/fix-pass.md @@ -43,7 +43,7 @@ character routing at or above `standard` is untouched, and the never-`max` ceili The rubric therefore doubles as the size ceiling; there is no separate knob for "too big to fix in-branch". A **max-character blocker halts** — abort-and-report, the change stays `in-progress` -with `claimed_at` refreshed and the reason recorded. A **max-character important or minor** — rare +with the reason recorded. A **max-character important or minor** — rare by construction, since unresolved architecture flagged as minor essentially does not occur — becomes a line in the PR body for the human's merge-time judgment, **not** a follow-up change. @@ -89,8 +89,8 @@ private-repository writing rule. A fix worker that returns without a schema-valid outcome may still be **running**: never discard the worktree and dispatch a fresh worker for that finding, however dead the first one looks. Halt -instead — abort-and-report, the change staying `in-progress` with `claimed_at` refreshed and the -reason recorded, the worktree left exactly as it stands. The trigger is the malformed return you +instead — abort-and-report, the change staying `in-progress` with the reason +recorded, the worktree left exactly as it stands. The trigger is the malformed return you observed, never elapsed time; a blocked foreground controller has no clock. **If tier dispatch is unavailable** — established only per the convention's @@ -139,7 +139,7 @@ docket-build's gate uses, and refresh the build-evidence record from the result. fixes stay: the run cannot proceed without them. They are the branch's tail by the dispatch order above, so the revert applies cleanly. **Should one conflict anyway** → **halt**: restore the worktree to its pre-revert state first, then abort-and-report, the change staying - `in-progress` with `claimed_at` refreshed and the reason recorded. A half-applied revert in a + `in-progress` with the reason recorded. A half-applied revert in a shared worktree is the one outcome worse than the red branch — the human must arrive at a coherent branch to inspect. 2. **Re-run the suite once**, refreshing the build-evidence record from this run — the record must diff --git a/skills/docket-implement-next/references/results-artifact.md b/skills/docket-implement-next/references/results-artifact.md index 0ff999f80..31e08a76c 100644 --- a/skills/docket-implement-next/references/results-artifact.md +++ b/skills/docket-implement-next/references/results-artifact.md @@ -13,10 +13,6 @@ own, or cleanup keeps it — plus the plan-writer dispatch, the build role, the records, the branch diff review, `workspace.publish`, `pr.publish`, and `change.mark-implemented` (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 -completion. A refresh `contended` stops new work. - ## 1. Do the work Do what the spec describes, in the feature worktree. **Never commit** to the branch, never publish @@ -67,7 +63,8 @@ and how its findings ended. ## 6. Complete, then clean up 1. Run the `change.complete` operation with a request file holding `{change_id, path, revision}`, - pinned from the `status` operation's `--json` output after a re-sync. `completed` (or + `path` from the bundle and `revision` looked up locally (`git -C <metadata_worktree_path> + rev-parse HEAD:<record path>`, as for every write). `completed` (or `already-completed` on a lost-response retry) means the change is `done` and archived; any refusal halts, naming its reason. 2. Run the `finalize.cleanup` operation with `--id <id>`. It removes a clean worktree and a local