Skip to content
Merged
14 changes: 14 additions & 0 deletions .tiller/events/2026/11/19/EV-2hq1zz.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
id: EV-2hq1zz
type: submit.tweak
at: 2026-11-19T19:03:20.448442Z
contributor: jc
command: submit tweak TW-3eo3s2
targets:
- TW-3eo3s2
before:
status: check
after:
pr: 30
status: in_review
files:
- path: .tiller/tweaks/shelf-merged-review-recovery/tweak.yml
13 changes: 13 additions & 0 deletions .tiller/events/2026/11/19/EV-4lcc6e.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
id: EV-4lcc6e
type: start.tweak
at: 2026-11-19T18:25:40.649925Z
contributor: jc
command: start tweak TW-3eo3s2
targets:
- TW-3eo3s2
before:
status: ready
after:
status: in_progress
files:
- path: .tiller/tweaks/shelf-merged-review-recovery/tweak.yml
14 changes: 14 additions & 0 deletions .tiller/events/2026/11/19/EV-9d65jj.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
id: EV-9d65jj
type: submit.tweak
at: 2026-11-19T19:07:29.203768Z
contributor: jc
command: submit tweak TW-3eo3s2
targets:
- TW-3eo3s2
before:
status: check
after:
pr: 30
status: in_review
files:
- path: .tiller/tweaks/shelf-merged-review-recovery/tweak.yml
14 changes: 14 additions & 0 deletions .tiller/events/2026/11/19/EV-f324bk.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
id: EV-f324bk
type: resume.tweak
at: 2026-11-19T19:03:59.526038Z
contributor: jc
command: resume tweak TW-3eo3s2
targets:
- TW-3eo3s2
before:
status: in_review
after:
reason: merge main after TW-xfjsgw; point the unrecorded-merge warning at shelf recovery
status: in_progress
files:
- path: .tiller/tweaks/shelf-merged-review-recovery/tweak.yml
13 changes: 13 additions & 0 deletions .tiller/events/2026/11/19/EV-vhu7qj.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
id: EV-vhu7qj
type: check.tweak
at: 2026-11-19T19:02:53.824332Z
contributor: jc
command: check tweak TW-3eo3s2
targets:
- TW-3eo3s2
before:
status: in_progress
after:
status: check
files:
- path: .tiller/tweaks/shelf-merged-review-recovery/tweak.yml
11 changes: 11 additions & 0 deletions .tiller/events/2026/11/19/EV-w70svf.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
id: EV-w70svf
type: claim.tweak
at: 2026-11-19T18:25:40.592255Z
contributor: jc
command: claim tweak tweaks/shelf-merged-review-recovery
targets:
- TW-3eo3s2
after:
owner: jc
files:
- path: .tiller/tweaks/shelf-merged-review-recovery/tweak.yml
13 changes: 13 additions & 0 deletions .tiller/events/2026/11/19/EV-zdin4u.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
id: EV-zdin4u
type: check.tweak
at: 2026-11-19T19:07:21.56786Z
contributor: jc
command: check tweak TW-3eo3s2
targets:
- TW-3eo3s2
before:
status: in_progress
after:
status: check
files:
- path: .tiller/tweaks/shelf-merged-review-recovery/tweak.yml
53 changes: 51 additions & 2 deletions .tiller/tweaks/shelf-merged-review-recovery/tweak.yml
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
id: TW-3eo3s2
key: tweaks/shelf-merged-review-recovery
title: A shelf item's already-merged PR cannot be recorded
status: ready
status: in_review
blocked: false
started: false
started: true
owner: jc
proposed_by: jc
accepted_against:
spec:
Expand All @@ -15,3 +16,51 @@ accepted_against:
kind: git_commit
value: git:819abfa
observed_at: 2026-11-19T18:22:26.733787Z
branch: tiller/tweaks/shelf-merged-review-recovery
pr: 30
gates:
build:
required: true
kind: command
status: pass
run_by: jc
run_at: 2026-11-19T19:04:32.433307Z
against:
kind: git_commit
value: git:d302cb7
observed_at: 2026-11-19T19:04:32.3348Z
code: sha256:d029e8e3bd964a6b549df2089de92222c7884846af6b4ea9ad11b86a84dde128
config: sha256:18320c22f2caf93ef8889a10bef882a38b42ed91315ccd9812f0f36b70cd0293
evidence:
- kind: command_output
ref: artifacts/tiller/gates/build-d302cb7-out-7667e0c0b29b6ae418b58ff64e7457afeaca2a3700e6f2b523bc7980446fd6f6.txt
lint:
required: true
kind: command
status: pass
run_by: jc
run_at: 2026-11-19T19:04:32.433307Z
against:
kind: git_commit
value: git:d302cb7
observed_at: 2026-11-19T19:04:32.3348Z
code: sha256:d029e8e3bd964a6b549df2089de92222c7884846af6b4ea9ad11b86a84dde128
config: sha256:3e2200b186b8956fc97ea2649af0d75769e37e0a9be48ccbe6e28938a4fa9120
evidence:
- kind: command_output
ref: artifacts/tiller/gates/lint-d302cb7-out-685d158f951e3eb11749d2e519a64eba4f57dcc93cd562eaee2cc9457f72846e.txt
tests:
required: true
kind: command
status: pass
run_by: jc
run_at: 2026-11-19T19:04:32.433307Z
against:
kind: git_commit
value: git:d302cb7
observed_at: 2026-11-19T19:04:32.3348Z
code: sha256:d029e8e3bd964a6b549df2089de92222c7884846af6b4ea9ad11b86a84dde128
config: sha256:6031ffcd18b874f5607c7dcacb78599ef98ded9055b2ccf545771b8b5135c512
evidence:
- kind: command_output
ref: artifacts/tiller/gates/tests-d302cb7-out-e9e2e579574e67450966d4ac13f0b19be66a9877f602e9a7dcc2b8bfc25f409a.txt
20 changes: 17 additions & 3 deletions docs/spec/artifact-schema.md
Original file line number Diff line number Diff line change
Expand Up @@ -179,7 +179,7 @@ observed_at: "2026-06-23T00:00:00Z"
## The root manifest: `tiller.yml`

```yaml
schema_version: 15 # current on-disk format version; moved forward by reviewed `tiller migrate`
schema_version: 16 # current on-disk format version; moved forward by reviewed `tiller migrate`
schema_epoch: initial # changed only by Class 3 migrations; used as the branch fence

project:
Expand Down Expand Up @@ -639,7 +639,8 @@ gates: {} # same shape as task.yml gates, written by `tiller ch
branch: null # tiller/bugs/certification-form-blank-on-reload once started; cut from the integration branch
pr: null
review_ref: null
done_basis: null # ancestry | content | human_attested | carried
recovered_review: null # optional immutable historical binding; see Merged shelf review recovery
done_basis: null # ancestry | content | human_attested | carried | recovered
supersedes: [] # same-noun transferred predecessor IDs
superseded_by: null # reciprocal successor ID, at most one
policy_violations: []
Expand All @@ -653,11 +654,17 @@ It touches nothing else: not the branch, not the review grain, not claims, routi

Fixed by its own PR is the ordinary case: `done`, basis `ancestry` or `content`, observed. Fixed by other work in the tree uses `resolved_by`, a live carrier pointer to the epic, feature, or task whose merge fixes the bug, set by `tiller resolve`. The bug keeps its stored state, takes the derived display phase `carried`, and drops out of the queue; in the same run that records the carrier's `done`, `sync` crosses the bug `done` with `done_basis: carried`. A cancelled or archived carrier is refused at the moment it is named, since its merge will never come, and a carrier cancelled afterwards returns the bug to the queue rather than letting it vanish, as `resolve --clear` also does. Closing a bug the day its feature is minted is refused for the same reason: a promise is not a fix, and `carried` recomputes on the carrier's fate the way a rollup `done` recomputes. That recompute has a name of its own. A `resolved_by` whose carrier is cancelled, archived, or no longer in the tree derives the phase `carrier_cancelled` instead of `carried`, rendered beside the node's status as "carrier cancelled" the same way a feature's rollup phases are; `sync` then treats the node as having no carrier at all, so an `in_review` one is observed on its own branch and listed as awaiting again. The pointer itself stays on the record: clearing or re-pointing it is `tiller resolve --clear` or `--by`, a human judgment, not something a read or an observation pass decides. A terminal bug refuses `resolve` outright, there being nothing left to carry.

Fixed by a merge Tiller never recorded is the third case, described under Merged shelf review recovery below: a human-authorized `recovered_review` record, and a crossing whose basis is `recovered`.

Not a fix is `cancel` with `--resolution wontfix | invalid | duplicate`, which a shelf node requires and no other noun accepts, and `duplicate` additionally requires `--duplicate-of` naming another node of the same noun. Duplicates are a cancel resolution rather than a carrier because "tracked over there" is a human ruling and the survivor's fate is visible on the survivor; letting duplicates ride carriers invites cascades. A regression of a `done` bug is a new bug; whether it records the earlier one is one of the bug-specific fields left to drift.

**Queue and dependencies.** The queue is a soft order at shelf grain and nothing more, `.tiller/bugs/order.yml`, `.tiller/chores/order.yml`, and `.tiller/tweaks/order.yml`, written only by `tiller order bug`, `tiller order chore`, and `tiller order tweak`, with the precedence every other order carries: recorded `depends_on` edges first, then the list, then canonical key ascending for the unlisted, and it never gates. No `priority` enum ships in v1, since an ordered list is a priority, and a bug's `severity` never enters this order. Dependencies stay inside the shelves: a bug may `depends_on` other bugs, chores, and tweaks only, and no tree node may depend on one, because a cross-graph edge would let the frontier be gated by the queue. "The feature must wait for this fix" is a question with `blocks`, which already exists.

**States, and who drives them.** `proposed` (captured) → `ready` (triaged) → `in_progress` → `check` → `in_review` → `done`, plus `ready → proposed` on return, `in_review → in_progress` on resume, and `cancelled` with a resolution. `done` arrives by the node's own observed merge (basis `ancestry`, `content`, or `human_attested`) or by its carrier's (`carried`), and `sync` writes it either way.
**States, and who drives them.** `proposed` (captured) → `ready` (triaged) → `in_progress` → `check` → `in_review` → `done`, plus `ready → proposed` on return, `in_review → in_progress` on resume, and `cancelled` with a resolution. `done` arrives by the node's own observed merge (basis `ancestry`, `content`, or `human_attested`), by its carrier's (`carried`), or by a recovered review's (`recovered`), and `sync` writes it every way.

**Merged shelf review recovery.** A bug, chore, or tweak carries an optional typed `recovered_review`, written by `submit bug|chore|tweak --recover-merged` when the node's fix merged before any submission was recorded. It holds the same evidence and provenance fields as an aggregate's record, `head`, `merge_commit`, `integration_branch`, `basis`, `recovered_by`, `recovered_at`, and `reason`, and no `tasks` or `policy_snapshots`, because a shelf node has no riders and no acceptance contract. `branch` is the node's recorded working branch and is absent when the fix merged before the node ever started. Load validates the record's shape as strictly as an aggregate's: an unknown field, a missing one, an abbreviated commit, or an explicit null refuses instead of leaving the node to ordinary observation. The caller-supplied PR number is stored in the node's own `pr`.

The record moves no status. `sync` validates it against configured integration and writes `done` with `done_basis: recovered`, directly, the way a carried crossing is written, since the node may never have started and the lifecycle has no row from `ready` to `done`. The crossing event's `evidence` names what the crossing rested on (`ancestry`, `content`, or `human_attested`), and required gates without a recorded pass become `policy_violations`, because recovery approves none. A recovered node needs no `started: true`: its PR and its done crossing belong to work that happened outside Tiller's record, as a carried crossing does. The record stays on the node after `done` as its audit trail, alongside one `recover_review.<noun>` event. While the node is unfinished it takes the derived display phase `recovered` and drops out of the queue.

**Severity.** A bug may carry `severity`, one of `blocker`, `important`, `medium`, or `minor`, stored lowercase and graded by impact, never by the size of the fix (the scale's meanings live in the capture skill). It is optional while the bug is `proposed`, because impact is often unknown when a bug is filed, and `approve bug` refuses an unrated bug with `severity_required`. Three writers set it: `add bug --severity`, `approve bug --severity` (which grades or regrades a `proposed` bug at triage, since triage is the human's call; on a bug past `proposed` it refuses with `severity_not_triage` and the change goes through `grade`), and `grade bug`, open to any contributor from `proposed` through `in_review` and refused on a done or cancelled bug, whose grade is part of the closed record. There is no clearing a grade. `grade` records one `grade.bug` event with the old and new severity in `before` and `after`; an unchanged level writes nothing. Transfer copies the original's severity onto its replacement. Severity is bug only: a `chore.yml` or `tweak.yml` carrying one is a parse error, and any write that would set one refuses with `severity applies to bugs`. No migration writes a severity nobody chose, so a bug already past `proposed` when schema 13 arrived stays unrated until someone grades it. Severity never routes: `tiller next`, the readout, and the approve queue keep the shelf's soft order, and only the console's Fix board sorts or filters by it.

Expand Down Expand Up @@ -1196,6 +1203,13 @@ For one door for documents, settled 2026-11-11 to 2026-11-12:
- Amendments staged before schema 15 keep the old approval rule, and a staged question stays staged until approval. (JC)
- Schema 15 is stamp-only: an add operation gains a node id, a source may name a folder, and an amendment gains the `draft` status, all additive; the stamp keeps an older binary from approving a held draft on its own.

For merged shelf review recovery, settled 2026-11-19:

- A bug, chore, or tweak whose fix merged before its submission was recorded is closed by the aggregate recovery command and evidence rules, not a second mechanism: `submit <noun> --recover-merged`, then ordinary sync.
- The shelf record carries evidence and provenance only. It has no riders and no policy snapshots, and its branch is the node's own recorded branch or nothing, never a name Tiller would have chosen.
- Sync records the crossing with basis `recovered`, with the Git evidence in the record and on the crossing event. Recovery approves no gate, and a missing pass is a policy violation at the crossing.
- Schema 16 is stamp-only: shelf nodes gain the optional `recovered_review` field and the `recovered` done basis. The stamp keeps an older binary from rewriting a recovered node and dropping its record.

---

## What's next
Expand Down
Loading