Skip to content

ADR: work-package windows are recorded at the opening transition

Work-package windows are recorded at the opening transition

Status: Accepted (2026-11-10). The operator ratified it as written on PR #7490, including the interpretation that a review rejection back to planned keeps the window and only a rewind from in-progress resets it.

Date: 2026-11-08

Deciders: Stijn Dejongh (operator).

Amends:

  • 2026-10-04-5-approval-stamp-bounds-the-approved-claim (the approval stamp stays the closing edge of the window and the fallback bound; the lane’s own approval stamps stop exempting its commits on the window path).
  • 2026-09-29-1-closed-world-refuse-on-mixed-lanes (the closed-world anchors are read from one frozen anchor set on resume; the lane anchor stays a named window variant).

Technical Story:

  • #7403: this Mission (consolidation window provenance and reconciliation split).
  • #7358: parent sub-epic.
  • #5721: the commit-between-two-approvals residual this ADR closes.
  • #5048: the deletion-inference defect (fail-open history read), fixed in the same Mission.
  • spec-kitty/spec-kitty-events#229: the cross-repository writer issue (FR-006), a context citation, not a gate.
  • Follow-up: see #7359 (interrupted-run recovery and teardown honesty), #7362 (the forecast evaluating every verify-side check), #5703 (lane-id rebuild orphans recorded windows).

Reader: a maintainer who changes a consolidation check, the status transition pipeline, or the forecast, and an agent doing either. It assumes you know the approval-stamp bound (2026-10-04-5-approval-stamp-bounds-the-approved-claim) and the closed-world rule (2026-09-29-1-closed-world-refuse-on-mixed-lanes).

Context and Problem Statement

The consolidation gate rebuilds each work package’s span of work from branch history after the fact. Every check keeps its own idea of that span. Nine base or window notions exist on main (see the table under Decision Outcome), and a fix to one check has repeatedly had to reason about the others. Of the 57 commits that touched consolidation/reconciliation.py on main before this Mission, 43 carry a fix subject (git log --oneline main -- src/specify_cli/consolidation/reconciliation.py).

Three problems follow:

  1. No recorded window. The gate never knows where a work package’s work began. It infers the window from stamps and branch history, so each check infers it differently.
  2. Different inputs per mode. spec-kitty consolidate --dry-run (the forecast), a fresh run and spec-kitty consolidate --resume call the same claim builder, build_approved_wp_set, with different inputs. The forecast passes no excluded canceled work packages and a live coordination base name; a resume reads some anchors from saved state and others from live branches. The three can disagree on the same repository state.
  3. An unreviewed commit lands with exit 0. A lane carries two work packages. WP01 is approved, someone commits to the lane, WP02 opens and is approved. WP02’s approval stamp reaches the stray commit, and the approval-stamp bound exempts everything an approval stamp of the lane reaches. The gate accepts the commit (#5721, residual “a commit between two approvals on one lane”).

consolidate here is lane consolidation: the local landing of approved lane work onto the local target branch. It never publishes to a remote. “Primary” is not used in this record.

Decision Drivers

  • The status event log is the only provenance authority (C-001). No second file, sidecar or store.
  • The status package stays git-free (C-002). It reads git only through an injected probe.
  • A missing window must never refuse a Mission by itself, and no refusal code is added (C-010).
  • Missions in flight when this ships keep the verdict they would have had (user story 3).
  • One recorded rule: every later change to a consolidation check follows the same window model.
  • Forecast, fresh run and resume must feed the gate the same inputs, so an operator can trust a forecast.

Considered Options

For where the window is recorded (research R-01):

  • A. Derive the window from existing lane_head stamps only, with no new key.
  • B. A separate provenance file or sidecar.
  • C. A new canonical event type that records the window.
  • D. Write the key only on the first opening move, with the status shell reading history to decide.
  • E. A namespaced key on the status transition event, written on every non-migration move into claimed or in_progress, with the reader picking the window opener.

For how far to unify the nine notions (R-02):

  • F. One WindowLedger substrate for all nine notions now.
  • G. One window model, plus a table that maps every other notion to it or to a named window variant.

For a work package with no recorded window (R-03):

  • H. Refuse, with an operator attestation as the escape hatch (what single_branch did).
  • I. Fall back to the approval-stamp bound and report the gap.

For the shape of the split of the reconciliation module (R-06), which this ADR constrains but does not describe:

  • J. A subpackage. K. Flat sibling modules behind a re-exporting facade.

Decision Outcome

Chosen options: E, G, I and K.

1. Where the window-open SHA is recorded

On every non-migration move of a lane-mapped work package into claimed or in_progress, the status shells write policy_metadata.wp_window on the transition event. The value comes from the same lane-head reading that produces lane_head (status/lane_head.py: read_lane_head returns a LaneHeadReading), so recording adds no extra git read. The status transition pipeline (status/transition_pipeline.py) stays git-free: the reading comes from the injected reader.

The wire shape and the writer and reader rules (W-1 to W-7, R-1 to R-7) live in the contract kitty-specs/consolidation-window-provenance-01M6Y84D/contracts/status-event-wp-window.md. This record does not copy the JSON Schema. In prose, the writer rules are:

  • Write only for a non-migration actor, a move into claimed or in_progress, and a work package mapped to a non-planning execution lane (or a single_branch Mission with a minted Mission branch). blocked opens nothing.
  • Take the value from the one lane-head reading. When both keys are written, open_sha equals lane_head.
  • A reading with a SHA writes open_sha. A reading of a mapped work package whose lane branch does not exist writes the gap lane_branch_missing. Any other failed reading writes the gap capture_failed with a cause of git_error or probe_error. A reading that does not apply (planning lane, unassigned work package, no lanes.json) writes nothing.
  • Never refuse, delay or retry a move because of the key. Never change another key. Never backfill past rows (the log is append-only).
  • A second writer, the Java write service, must write the same shape or preserve the key verbatim. spec-kitty/spec-kitty-events#229 asks for that. A writer that drops the key turns later windows into “not recorded” gaps, which is a weaker check and never a refusal.

The key is additive. An event that does not qualify is byte-identical to today’s row.

2. The typed window gap

A window gap is the explicit, typed absence of a usable window for a work package. Four reasons exist:

ReasonOriginMeaning
capture_failed (with cause)writtenThe lane branch exists but the head could not be read (git_error or probe_error).
lane_branch_missingwrittenThe lane branch did not exist at the opening move. This is normal before implement creates the lane.
not_recordedreader onlyThe window opener carries no key (written before the upgrade, or by a writer that drops it), or the key is malformed.
not_on_lanereader onlyThe recorded SHA is not an ancestor of the lane tip (a rewritten lane), or does not resolve in this clone (another clone, a collected object) (FR-022). Never a probe error; a git failure on a SHA that is in the clone is one, and the bound refuses on it (pre-PR fold M2).

The gap is a fact about what the writer observed (written reasons) or about the log and the lane at read time (reader-only reasons). A missing approval stamp is not a window gap: APPROVAL_STAMP_MISSING and APPROVAL_STAMP_NOT_ON_LANE keep their meaning and remedies.

3. The window opener (FR-021)

The recorded window binds to the window opener, found by one shared selector:

  1. The cycle starts after the work package’s last non-migration move to planned from a non-review lane. Moves out of for_review, in_review, approved and done are review rejections and do not reset the cycle (the genesis seed counts as a start).
  2. The candidates are the cycle’s non-migration moves into claimed or in_progress, in event-log order.
  3. Leading candidates that recorded lane_branch_missing are skipped: they prove no lane commit existed at that instant.
  4. If the first remaining candidate has no usable value, that is the gap. An unrecorded opener is never replaced by a later recorded one. Otherwise, among the SHA-bearing candidates, the topologically earliest wins (the SHA that is an ancestor of every other), and event-log order decides when the SHAs are unrelated.
  5. If only skipped candidates exist, the gap is lane_branch_missing. With no candidate at all, the gap is not_recorded.

Interpretation recorded for review. The operator ruling (Decision Moment 01M6YAG16WDVMM37HCJCHAC5YW) says the window opens after the work package “last returned to planned”. This ADR reads a review rejection as rework, not as a return: review rejections move a work package in_review -> planned today, and resetting the window there would put the work package’s own earlier commits outside its window, refused with no attestation route. A move to planned out of for_review, in_review, approved or done is therefore rework. Any other move to planned (today in_progress -> planned) is a rewind and starts a new cycle. The force flag is not read: a forced approved -> planned or done -> planned is rework like its unforced twin, and a forced move to planned out of any other lane is a rewind. The operator can overturn this reading in review.

Clarification 2026-11-10 (operator ruling). An unforced unclaim (in_progress -> planned, and blocked -> planned) is a rewind: it starts a new cycle, so commits from the abandoned cycle that are still on the lane are refused (“precedes approvals”). No attestation lifts that refusal. The recovery is to take those commits off the lane, or not to unclaim work you mean to keep.

The same selector (consolidation/wp_attribution.py: window_opener_events, window_open_of) serves the single_branch derivation when no window is recorded, with its legacy first-claim rule (cycle=False). The opener rule lives once. The review-rejection reading above stays an interpretation the operator may overturn; the shipped selector implements it and tests/status/test_window_opener.py pins it.

4. The window and its exemption anchors

The work-package window is (window-open SHA, newest approval stamp]. A work package with a gap gets a degraded window, (claim base, approval stamp], which is exactly today’s approval-stamp coverage for it.

On a code lane with at least one recorded window, a lane commit that lies in no window and is reached by no exemption anchor is refused with LANE_MOVED_AFTER_APPROVAL, naming the commit and the work package approved before it. The stamp refusals come first, as today, and merge commits and bookkeeping-only commits are dropped exactly as today.

The exemption anchors on the window path (Decision Moment 01M6YAFYHT0RMVZB03THW1WWSE) are the closed-world anchors (the dependency-lane tips of lanes that are not fully canceled, and the target’s pre-consolidation tip) plus the approval stamps of other bounded lanes. A lane’s own approval stamps are not anchors on this path: the windows replace them. That is what makes the commit-between-two-approvals refusal possible.

Dependency-chain exception. A commit another lane’s approval stamp reaches is content inside that lane’s reviewed tip, so it stays exempt. If lane B depends on lane A, merged lane A’s tip with a stray commit, and B’s work package was then approved, the stray commit is exempt on lane A. The exception is deliberate and pinned by a dependency-chain fixture. The own-lane variant, where the stray commit is reachable only from the lane’s own stamp, refuses.

Two tiers. The lane check runs in two tiers (consolidation/write_branch_bound.py: bind_lane_predicates, classify_windows, check_lane_windows). Tier 1 is today’s approval-stamp check, check_lane, unchanged and first: the stamp refusals and content after a lane’s own approval stamps keep today’s whole-lane text. Tier 2 runs only when tier 1 passed and refuses each content commit in claim base..tip that no window covers and no exemption anchor reaches, one refusal per commit, with the new per-commit text (render_lane_window_refusals), printed after every lane’s tier-1 refusals. So the new text appears only for commits tier 1 cannot see (between two approvals, or work abandoned before a rewind); a claim with no tier-2 refusal renders byte-identical to today. The exempt set is computed once per lane and handed to both tiers.

Canceled work packages (operator ruling 2026-11-09). A canceled work package gets no window, so its commits on a lane with recorded windows would otherwise refuse in tier 2 although the mixed-lane rules already judge them. The commits the mixed-lane resolution attributed to the lane’s canceled work packages are therefore exempt from tier 2 (reconciliation_bound._canceled_window_exempt); the mixed-lane and canceled-content rules are their only judge. Tier 1 is unchanged: a canceled work package’s commit after an approval stamp still refuses (#5720). The orchestrator-api door (approved_bound_refusal) runs neither the mixed-lane nor the canceled-content checks, so it exempts no canceled commit: the strict window rule judges them there.

Declared dependency refs (pre-PR fold M9). A lane can carry content inherited before its first window: an external ref merged into it before the work package’s claim, or a lane cut from another ref. Before windows were recorded, the lane’s own approval stamp exempted that content; with a recorded window it lies before the window. The commits of the operator’s declared, pinned --dependency-ref refs (#6771; exactly the verified set the closed world exempts) are therefore exempt from tier 2 as well, so such a lane keeps its pre-window verdict. Tier 1 still never reads the declaration, the single_branch Mission-branch check is unchanged, and an undeclared external commit before the window still refuses. Corpus cell fresh|single_lane|...|dependency_ref_merged_before_window pins it.

Refusal text (pre-PR fold M8). The tier-2 line names the commit and the work package approved before it, and the recovery is to send that work package back for review and approve it again: its window keeps its start and the new approval stamp moves its end past the commit. A commit that no work package’s newest approval precedes (it lies before the named work package’s window, for example work abandoned before a rewind) gets its own text and recovery: approving again moves a window’s end, never its start, so no approval covers it and it has to come off the branch. A revert is never advised: it is new content of its own and clears no window refusal.

All-gap lane. A lane on which every approved work package has a gap runs today’s approval-stamp check (check_lane) unchanged, with today’s anchors, own stamps included. Its verdict and refusal text are byte-identical to today’s (FR-023).

5. Claim inputs and their three sources

ClaimInputs is one frozen value (consolidation/claim_inputs.py), built by one constructor (build_claim), consumed by claim building and by the gate. Its source is a ClaimInputSource. Its fields are: the target base, the coordination base, the frozen lane tips, the frozen dependency anchors, the dependency refs and their pins, the excluded canceled work packages, the strategy, the status directory read, and its source.

SourceModeMeaning
LIVEforecast (--dry-run)Every value read from live branches.
LIVE_THEN_SAVEDfresh runRead live, then saved to state.json (ConsolidationState) at claim capture.
SAVEDresume (--resume)Read from the saved record. A value that was saved is never re-read live.

Equality compares refs by the SHA they resolve to, and the status directory by its resolved path and the digest of its event log. Phase 2 of the Mission keeps every per-mode quirk exactly. Phase 4 aligns the forecast’s excluded canceled work packages and its coordination base (resolved to a SHA) with the fresh run’s (FR-013). The forecast keeps the status read door; it resolves the same status directory as the fresh run’s write accessor on every topology the corpus builds, so no status directory change was needed (one residual, below).

6. Durability horizon

A recorded SHA is valid for one consolidation attempt: the forecast, a fresh run, a resume and the teardown. It is branch-relative provenance, consistent with 2026-11-07-1-dossier-commit-shas-are-branch-relative-provenance. After a rebase landing it may not resolve, and no reader after the landing may require it. The key policy_metadata.wp_window.open_sha is classified BRANCH_RELATIVE in DOSSIER_SHA_FIELDS (tests/architectural/test_dossier_sha_provenance.py).

7. Missing-window fallback

A work package with a window gap is judged by the approval-stamp bound with the degraded window and is never refused for the gap alone. No refusal code is added, and existing codes, remedies and attestation flags keep their meaning. Every work package judged by the fallback is listed in the gap report with its reason. APPROVAL_STAMP_MISSING is unchanged. Missions in flight at upgrade therefore reach the verdict they would have reached before it.

Gap-report surfaces: the fresh run, the resume and the forecast (a human block headed “Window gaps (judged by the approval-stamp bound)”, and window_gaps in the dry-run JSON, also on a refusal). Each entry is a GapEntry (consolidation/wp_attribution.py), rendered by consolidation/window_gap_report.py; the block prints before a claim-time refusal. The orchestrator-api envelope is unchanged (no contract version change); see the residual below.

The forecast reports the approved-bound refusals (research R-09, settled by the corpus). consolidate --dry-run builds the full claim, so a post-approval commit is forecast as CLAIM_REFUSED_FORECAST naming LANE_MOVED_AFTER_APPROVAL (cell forecast|single_lane|post_approval_commit), and a missing or rewritten stamp as APPROVAL_STAMP_MISSING or APPROVAL_STAMP_NOT_ON_LANE. The window refusals reach it the same way.

8. The frozen anchor set on resume

On --resume, one frozen claim-time anchor set, built from the dependency-lane tips frozen at claim capture, feeds every consumer of the closed-world anchors (Decision Moment 01M6YAFZVZAYR4G20Q2X4PN0FT). There are four consumers:

  1. the mixed-lane resolver;
  2. the approved bound;
  3. the fully-canceled lane’s own commits;
  4. the approved-reviewed attestation check.

A dependency lane that moved after the interruption no longer widens what is exempt on any axis. A dependency lane rewound to an ancestor after the interrupted run keeps the frozen (wider) tip, matching what that run’s claim already judged. A fresh run reads live tips, which equal what the claim freezes on an unmutated state, so its verdict is unchanged. A dependency lane the record froze no tip for is read live, listed in ClaimInputs.degraded_dependency_anchors, and named in a note on the resume. Only the coordination topology freezes lane tips, so a resume of a LANES or single_branch Mission with a dependency lane always prints that note.

9. The two recording tiers

TierWhat it recordsWhere
Work-package transitionthe window-open SHA or the gap, the approval stampthe status event log
Run claimthe claim inputs: bases, frozen lane tips, pins, excluded set, strategystate.json (ConsolidationState)

ClaimInputs is run-level provenance. It never writes to the event log and never touches the rollback snapshot. Rollback is out of scope: no module gains a rollback or branch-restore caller outside the existing rollback authority (Follow-up: see #7359).

10. The nine base and window notions

Every notion on main maps to the one window model or to a named window variant. Homes are module and symbol names after the split of reconciliation.py (now a re-exporting facade); line numbers drift.

#NotionHomeDisposition in the window model
1Coordination base (the lane-tip range base)consolidation/phase_claim.py, coord_base_refClaimInputs.coord_base.
2Excluded window base (the target’s pre-mutation tip)consolidation/phase_claim.py, excluded_window_baseClaimInputs.target_base (a claim-base input).
3The bound’s claim baseconsolidation/reconciliation_bound.py, _bound_claim_baseDerived from 1 and 2, unchanged. It is the degraded window’s opening edge.
4Presence lane basesconsolidation/wp_attribution.py, first_governed_open_stampNamed variant “lane anchor”: blocked counts as an opener. Kept, because unifying it would change closed-world verdicts.
5Implementation and review windowsconsolidation/wp_attribution.py, WorkWindowNamed variant “canceled-content windows”: class-change windows of mixed lanes. Unchanged.
6The approval stampconsolidation/approved_bound.py, approval_stampThe window’s closing edge, and the fallback bound.
7The owned-file evidence window (planning_commit_sha..tip)consolidation/wp_evidence.pyNamed variant “owned-file evidence”: not stamp-based. Unchanged.
8The single_branch authorship window (merge-base(target, mission)..mission)lanes/single_branch_landing.pyNamed variant “single_branch authorship window”, unchanged. single_branch approval windows read the recorded window-open SHA when present (FR-011) and keep today’s derivation, reported as a gap, when absent.
9The closed-world anchors (dependency-lane tips and the target base)consolidation/reconciliation_kernel.py, _closed_world_anchorsAnchor SHAs come from ClaimInputs. Frozen on resume (decision 8).

The blocked asymmetry is a named window variant, not drift: the approval-window opener ignores blocked, the closed-world lane anchor counts it. Neither verdict changes.

11. Named residuals

These are accepted and named, so a later reader does not rediscover them:

  • Parallel claims on one lane, and a claim parked without returning to planned: the window opens early and also covers the other work package’s commits and any stray commit between them. Over-wide window, pinned as a strict xfail.
  • A review rejection to planned followed by another work package on the same lane. WP01 is rejected to planned (rework: its cycle continues), WP02 is claimed, worked and approved on the same lane, then WP01 is claimed again and approved. WP01’s window still opens at its first opener, so it covers WP02’s commits and any stray commit made between them. Over-wide window, a consequence of reading a review rejection as rework (section 3).
  • The rewind boundary is found in event-log order. Clock skew across the boundary itself is not topology-corrected. (Skew between openers inside a cycle is corrected by topology order.)
  • Degraded anchors on resume. A record written before the upgrade has no frozen tip for a dependency lane, and a record whose status surface did not resolve at capture froze no tip. Both keep today’s live read.
  • A full-restore re-baseline (#6770) drops the frozen tips on LANES and single_branch, so the next resume is a fresh capture by design.
  • A canceled set that changes between capture and resume only refuses or drops anchors, both safe.
  • The forecast before the first status seed (FR-013). A Mission whose coordination branch holds no status.events.jsonl yet: the forecast reads the log through the read door’s pre-seed fallback (the write checkout), while the fresh run seeds the coordination worktree and measures its claim from that seed commit. Same log bytes, excluded set, lane tips and target base, but a different status directory and coordination SHA. Pinned as the strict xfail test_pre_seed_forecast_status_dir_and_coord_base_equal_fresh_run (tests/consolidation/test_forecast_fresh_run_parity.py).
  • The presence scope reads canceled lanes live on resume. reconciliation_authorship._presence_scope is not one of the four frozen-anchor consumers. Its live read can only shrink the subtracted canceled set, which makes the presence axis stricter, never looser.
  • Compound refusals exempt no canceled commit. The canceled-dependency compound refusal evaluates the bound before the mixed lanes are resolved, so the bound text it appends exempts no canceled work package’s commit from tier 2. A canceled work package that is unattributable, attested (--attest-canceled-superseded) or not, exempts nothing either. Both fail closed.
  • The window downgrade is invisible on orchestrator-api. The envelope carries no gap report, so a second writer that drops the key, or any other downgrade, is not visible to an orchestrator until a later contract version carries the gap report.

12. Limits

  • Lane-id rebuild. Recorded windows rely on the lane id to lane branch binding that 2026-10-04-2-started-work-package-lane-membership-is-frozen guarantees. A lane-id rebuild after execution began orphans recorded windows (Follow-up: see #5703).
  • The Java writer must write or preserve the key (spec-kitty/spec-kitty-events#229). Until it does, work packages opened through it have no window.

Consequences

Positive

  • A commit made between two approvals on a lane with recorded windows is refused before any branch moves (closes the #5721 residual).
  • Every consolidation check has one place to ask where a work package’s window begins.
  • Forecast, fresh run and resume build the claim from one construction point, so the forecast and the fresh run can be compared on the same state.
  • In-flight Missions are never refused for lacking a window, and the operator can see exactly which work packages got the weaker check.
  • The status package stays git-free, and recording adds no git read.

Negative

  • The accepted dependency-chain exception. A stray commit that a dependent lane merged before its own approval stays exempt on the source lane.
  • A weaker check for a gap work package. A gap work package’s degraded window covers a stray commit between an earlier recorded work package’s approval and its own opening. The run passes and the gap report names it. A gap work package followed by a recorded one, with a stray commit between them, is newly refused.
  • A rewound window can still be over-wide (residuals above).
  • A second writer can silently downgrade windows until it writes the key and the envelope carries the gap report.
  • One more key on every opening event, and one more reader rule to keep in step with the Java writer.

Neutral

  • No refusal code, allowlist entry, suppression or orchestrator-api contract version is added.
  • The split of the reconciliation module follows this record but is behaviour-preserving, and the only verdict changes are the named, red-first ones in the Mission.

Confirmation

The characterization corpus, the refusal-precedence matrix and the surface pin landed first and stayed unchanged across the split. Each behaviour change in this Mission is a named corpus cell (NFR-002) with a test committed failing before its fix and passing after. As landed:

  • (a), (b): a commit between two approvals refuses, naming the commit and the work package approved before it (WP19). (c): a rewound work package’s window opens after the rewind, on lanes (WP19) and single_branch (WP20).
  • (d): a history-read error in the authored-content walk refuses the claim instead of counting the path as deleted (#5048(b), WP16).
  • (e), (f): on resume the closed world and the approved bound read the frozen anchors (WP18). On the corpus (e) shape the new refusal is carried by the approved bound, because the closed world walks only the non-merge commits of the first-parent spine and the dependency commit sits behind a merge; the closed world’s own read of the frozen set is pinned by test_resume_closed_world_does_not_exempt_a_post_interrupt_dependency_commit.
  • (g): recorded unreachable. A fully-canceled lane has no frozen tip and is never an anchor, so any route that brings its advance into the claim reaches a dependency lane after that lane’s approval stamp, which the approved bound refuses with live or frozen anchors alike. test_resume_fully_canceled_lane_flip_is_unreachable pins the reachable consequence.
  • (h): the forecast excludes the fresh run’s canceled work packages (verdict-visible) and resolves the coordination base to a SHA (field-level only) (WP17).

The evidence: tests/status/test_wp_window_capture.py, tests/status/test_window_opener.py, test_claim_inputs_parity.py, test_forecast_fresh_run_parity.py, test_lane_approval_windows.py, test_refusal_precedence_matrix_windows.py, test_lane_window_query_count.py, test_window_gap_report.py, test_window_gap_report_entry_points.py, test_authored_walk_read_error.py and test_resume_frozen_anchors.py (all under tests/consolidation/ unless named), and tests/integration/test_single_branch_approval_windows.py.

Landing note (2026-11-10, operator ruling on #7490): the characterization corpus, the seeded-mutation harness, the facade surface pin and the intended-verdict ledger were refactor scaffolding. They are retired at landing, after an independent AST comparison showed every moved definition byte-identical apart from the named verdict changes. The two intended-verdict checks no other test asserted moved into test_resume_frozen_anchors.py (the merge-commit variant of (e)) and test_lane_approval_windows.py (the naming line of (b)); each behaviour above is now carried by the dedicated tests listed.

Pros and Cons of the Options

A. Derive from lane_head stamps only

Pros:

  • No new key.

Cons:

  • It cannot express a typed gap, so “capture failed” and “never recorded” look the same.
  • The lane path would re-derive an opening from older stamps, which the operator ruled out.

B. A separate file or sidecar

Pros:

  • Free-form shape.

Cons:

  • A second authority and a second read door. Already rejected twice (ADRs 2026-09-29-1-closed-world-refuse-on-mixed-lanes and 2026-10-04-5-approval-stamp-bounds-the-approved-claim).

C. A new canonical event type

Pros:

  • A typed, versioned record.

Cons:

  • It duplicates the transition, adds an atomicity obligation, and is blocked on a spec-kitty-events release.

D. Write on the first opening move only

Pros:

  • One row carries the key.

Cons:

  • The shell must read history on every move, which moves window logic into the shell.

E. A namespaced key on every opening move (chosen)

Pros:

  • Ships from core alone: policy_metadata is an open mapping in the events payload.
  • Reuses the lane-head reading already taken, so no extra git read.
  • The reader, not the writer, decides which opener binds, so the status pipeline stays history-free.

Cons:

  • Several rows can carry the key, so the reader must choose (the window opener rule).

F. A full WindowLedger now

Pros:

  • The right end state for all nine notions.

Cons:

  • It would turn a behaviour-preserving split into a redesign. Deferred.

G. One model plus named variants (chosen)

Pros:

  • Every notion is mapped, and no variant’s verdict changes outside the named lane change.

Cons:

  • Variants remain, including the blocked asymmetry.

H. Refuse with attestation

Pros:

  • A missing window is never silent.

Cons:

  • It would strand every Mission in flight at upgrade.

I. Fall back and report (chosen)

Pros:

  • Missions in flight keep their verdict, and the gap is named in the output.

Cons:

  • The fallback is a weaker check.

J. A subpackage

Cons:

  • It cannot share a name with the facade module, and a new __init__.py brings in the version-bump rule.

K. Flat sibling modules (chosen)

Pros:

  • No new package, and module ownership by directory glob stays unchanged.

Amendment 2026-11-12 (#7578): commit-to-target single_branch Missions record their window points

Status: Accepted (operator rulings Q3 and Q8, 2026-11-12).

What changes. A commit-to-target single_branch Mission is one whose write branch is its target branch: a Mission created with --commit-to-target, or created with an explicit --topology single_branch on an unprotected target, where no Mission branch is minted. A Mission created without --topology is not one: it mints a topic branch on every target (core/mission_creation.py, FR-051). A Mission whose minted branch has landed reads as one too: the landing’s teardown (consolidation/phase_teardown.py::_clear_landed_single_branch_mission_branch) clears meta.mission_branch, so its later transitions are stamped at the target head; consolidation has finished by then. Until now such a Mission recorded nothing: its transitions carried no lane_head and its opening moves no wp_window. It now records both, taken at the head of the target branch (status/lane_head.py::_single_branch_write_branch). The opening move (claimed / in_progress) records wp_window.open_sha; every lifecycle move records lane_head. A missing target branch or a git failure is a typed gap, never a refused move. The planning lane of a lanes or lanes_with_coord Mission still records nothing, and a Mission with an unlanded minted Mission branch is unchanged. Its work package’s review range is derived from its committed status events (operator ruling Q10) only where those events are committed on the branch its work is written to: on a lanes Mission, and on a lanes_with_coord Mission whose coordination branch is the planning lane’s write branch (a Mission created without --topology that settled lanes_with_coord, before its landing). On any other lanes_with_coord Mission the events sit on the coordination branch, apart from the work, and the range is unavailable.

Why. The review range of a work package (#7578) reads a recorded window on every topology instead of guessing one from branch history (ruling Q3).

Consolidation verdicts do not change (ruling Q8). Such a Mission stays unbounded in consolidation: reconciliation_bound._bound_write_branch returns None for it (it reads minted_mission_branch), and approved_bound._approval_is_bounded excludes it. The new stamps would still have reached three other readers. We measured each one on a real commit-to-target Mission, before and with the stamps, and without a guard:

ReaderBefore the stampsWith the stamps, no guard
Canceled-work attribution on the planning lane (reconciliation_canceled._mixed_lanes, resolve_canceled_wp): WP01 approved, WP02 implemented then canceledrefused at claim time, exit 1: “canceled WP02 cannot be attributed … carry no commit attribution”exit 0: the attribution came back empty and WP02’s committed content stayed on the target
--dependency-ref guard (_recorded_lane_heads)exit 0, no recorded stampsexit 0, 12 recorded stamps
--attest-approved-reviewed (_has_review_approval_stamp)exit 0, attestation recordedexit 1: “WP01 already has one. Move it back for review instead.”
Approved-only consolidate / acceptexit 0 PASS / accept blocked by path conventionsunchanged
A commit after the last approvalexit 0, not refusedunchanged

The operator ruled to keep the stamps and keep every verdict as it was. One predicate decides whether a Mission is commit-to-target: lanes/single_branch_landing.py::is_commit_to_target_meta, which checks a stored single_branch topology whose write branch equals the recorded target (single_branch_branches, the reading the lane-head stamp also uses); consolidation/commit_to_target_stamps.py::is_commit_to_target_mission calls it over a Mission’s meta.json. For such a Mission, consolidation_events removes lane_head and wp_window from the status events that three seams read:

  • the claim’s event log, reconciliation_kernel._ClaimEventLog.read (canceled-work attribution, the canceled-dependency checks and the compound refusal);
  • the --dependency-ref guard, reconciliation_closed_world._recorded_lane_heads;
  • the attestation validation, approved_attestation.plan_approved_attestations.

With the guard, all five rows above give the same verdict and the same text as before the stamps (tests/consolidation/test_commit_to_target_stamp_characterization.py, STAMPED = True). The status log keeps the stamps; only consolidation ignores them.

Corrections.

  • Ruling Q3 named write_branch_bound.check_write_branch_windows as the consolidation mechanism these stamps feed. For a commit-to-target Mission that check is never reached (_bound_write_branch returns None). The rest of the ruling stands.
  • Nothing refuses a commit-to-target Mission’s late commit today. The test that records this, test_commit_to_target_unbounded_residual, is a strict xfail: its exit 1 assertion fails, so the residual (FR-078) stays open, and the stamps do not close it.

Amendment 2026-11-18 (#7726): the bulk-edit review gate reads the review range

Status: Accepted (operator rulings A and B, 2026-11-18).

What changes. The bulk-edit review gate (agent action review, cli/commands/agent/workflow.py::_enforce_bulk_edit_diff_compliance) diffs from the work package’s review range, review/wp_range.py::resolve_wp_review_range, on every topology. It no longer derives its own base (lanes.json mission_branch) and head (the review workspace branch). On single_branch those two named the same branch, so the gate diffed X..X and passed having checked nothing.

Head. On single_branch the gate judges up to the submission. Commits past it can be another work package’s, so they are named as not judged; re-submitting judges them. On a lane topology it judges up to the lane’s live head, as the gate did before, so a commit added to a lane after its submission is still judged. The diff leaves out only the Mission’s own status files and task index (review/wp_range.py::mission_bookkeeping_pathspecs: the kitty-specs/<mission>/ entries of lanes/for_review_gate.py::status_only_excluded_prefixes, namely status.*, issue-matrix.*, meta.json, tasks/, lanes.json, acceptance-matrix.json, analysis-report.md, decisions/, decisions.events.jsonl and traces/, plus tasks.md), so a ticked task file never blocks the Mission’s own review. It does not leave out .kittify/: the range counts .kittify/ as bookkeeping when it lists commits (WpReviewRange.bookkeeping_pathspecs, which BULK_EDIT_REVIEW_RANGE_EMPTY reads), but the gate still judges a .kittify/ edit the occurrence map forbids, as it did on a lane before #7726.

Planning lane in ruling Q10’s case. A planning-lane work package of a lanes_with_coord Mission whose coordination branch is not its planning branch has no review range: its status events sit apart from its work. The gate judges it from its recorded claim base (refs/spec-kitty/wp-base/<mission>/<wp>) to the head of its planning branch, named from meta.json (review.wp_range.planning_branch_apart_from_status), never the reviewer’s checkout. It applies only in that case (gap not_recorded, no lane stamp, branches apart); every other missing range keeps the range owner’s refusal. A missing claim base refuses: a claim base exists only in the clone that claimed the work package, and no wider base stands in for it. The review context keeps ruling Q10 and shows no range.

Branches others commit to (ruling B). On a commit-to-target single_branch Mission and in the planning-lane window, the gate judges only the paths that the window’s first-parent chain changed itself, each with its net change over the window (bulk_edit/gate.py::_first_parent_paths, through kernel.git.listing.log_paths(first_parent=True, remerge_merges=True)). Renames are split, so a moved file’s old path stays judged. A merge on the chain contributes only what its own resolution introduced (its diff against git’s automatic re-merge), never the commits it brought in. A foreign commit that a rebase or a fast-forward puts on the first-parent chain cannot be told apart from the work package’s own commits, so it is judged (fail-closed). When every changed path came in only through merges, nothing the work package committed itself can be judged, and the gate refuses BULK_EDIT_REVIEW_RANGE_EMPTY.

Refusals (bulk_edit/gate.py::review_range_refusal, workflow.py::_planning_lane_window), none of them a pass:

  • BULK_EDIT_REVIEW_RANGE_UNAVAILABLE: an UNAVAILABLE range, with its gap and a remedy, or a commit listing that failed, or a planning-lane window without a claim base or planning branch;
  • BULK_EDIT_REVIEW_RANGE_EMPTY: no commit outside Mission bookkeeping;
  • BULK_EDIT_REVIEW_TIP_REWRITTEN: the submitted tip is no longer on its branch.

A window that holds commits but no net change (for example a forbidden edit committed and then reverted inside the window) passes: the gate judges what the work package would land, and an empty net diff lands nothing, so there is nothing for the occurrence map to refuse. _EMPTY refuses only a window with no commit outside bookkeeping, where the work package submitted no work at all.

Status moves need the local Mission branch (ruling A). A minted single_branch Mission writes its status to its Mission branch, so a status move without that branch locally refuses DESTINATION_REF_NOT_FOUND (status routing, ADR 2026-11-06-2, unchanged). That refusal now prints the command that restores the branch: git fetch origin <b>:<b> when this clone’s view of origin holds it (refs/remotes/origin/<b>; the pre-flight contacts no remote), else git branch <b> <commit holding the work>. Move-task’s SINGLE_BRANCH_IMPLEMENTATION_UNREADABLE prints the git branch form. Recreating the branch is safe now, because the gate judges the work. Fetching it automatically, through kernel.git.remote, is #7730.

Residuals.

  • The ruling named a work package’s own merge commit as a fail-open edge (the approved bound’s “content inside a merge commit”, ADR 2026-10-04-5). The remerge diff closes it for a two-parent merge: an edit folded into the merge is judged. An octopus merge (3 or more parents) contributes its full first-parent diff instead, a superset that can include foreign content (fail-closed).
  • --diff-merges=remerge needs git 2.36 or later; an older git refuses the window rather than judging less.

References

  • Contract: kitty-specs/consolidation-window-provenance-01M6Y84D/contracts/status-event-wp-window.md.
  • Amends: 2026-10-04-5-approval-stamp-bounds-the-approved-claim, 2026-09-29-1-closed-world-refuse-on-mixed-lanes.
  • Related: 2026-11-07-1-dossier-commit-shas-are-branch-relative-provenance, 2026-10-04-2-started-work-package-lane-membership-is-frozen, 2026-10-14-1-event-native-core-one-canonical-event-writer.
  • Decision Moments: 01M6YAFYHT0RMVZB03THW1WWSE (lane anchor set), 01M6YAFZVZAYR4G20Q2X4PN0FT (resume anchor scope), 01M6YAG16WDVMM37HCJCHAC5YW (window opener), 01M6YAG2HE6Q2XNQMGK6X3MBEK (events issue filing).
  • spec-kitty/spec-kitty-events#229: the Java write service adopts and types policy_metadata.wp_window (context citation, FR-006).
  • Issues: #7403, #7358, #5721, #5048, #7359, #7362, #5703.