empirical-sdd 0.34.0 → 0.36.0

package/CHANGELOG.md

@@ -8,6 +8,271 @@ under the alpha rules in [docs/versioning.md](docs/versioning.md).
 
 ## [Unreleased]
 
+## [0.36.0] - 2026-09-16
+
+### Added
+
+- Added the empirical-init **Track every change** ticket preset. It expands the
+  complete feature/fix/chore by Fast/Quick/Complex matrix to `required`, shows
+  that matrix before setup is saved, and applies the existing strict tracker
+  mutation gate to every kind of work until its ticket is synchronized. Active
+  Empirical tasks now also require a destination action and tracker-gate check
+  before the first write after changing repository root, checkout, worktree, or
+  host environment.
+- Automatic Policy v2 post-commit synchronization, prepared Linear MCP intents,
+  and recovery of this checkout's pending completed tickets.
+- Explicit Init confirmations for all workflow/delivery mappings and the Done
+  milestone, plus receipt-backed release and deployment observations.
+- Action packets, `empirical_status` and `empirical_explain` return a
+  deterministic `roadmap`: `progress` and `phases[]` from the engine's single
+  phase order per profile (Complex 8, Quick 5, Fast 2 non-terminal phases),
+  one `checks[]` entry per verification-matrix check with its state, receipt id
+  and last duration (a `passed` state binds the same proof the completion gate
+  requires, including the current repository tree digest), an `estimateMs` for unrun and failed checks from prior
+  attempt durations, classified `waitingOn[]` items, a concrete `nextAction`
+  and `verificationLeft`. Idle checkouts return `roadmap: null`. Roadmaps and
+  estimates are recomputed on every read and never change a gate or transition.
+- Human CLI output for `status`, `explain`, `next` and `loop` renders the
+  Empirical status card (Done, Not done, Next, Waiting on you, Verification)
+  from that roadmap, and `--json` exposes the same `roadmap` field.
+- Generated agent skills require the status card at start or resume, at every
+  phase change, at every stop, and before any run whose summed estimate is over
+  60 seconds or unknown, where they state the estimate and offer to defer.
+- `empirical_overview` adds a read-only roadmap summary (progress, phase, next
+  action, waiting count, remaining checks) for the first 128 readable spec
+  copies; unreadable, failing and beyond-limit copies keep their bounded
+  diagnostic and report `roadmap: null`.
+- `empirical_qa_execute` and `empirical_integrate` send MCP
+  `notifications/progress` for each existing heartbeat when the request carries
+  a `progressToken`; requests without one are unchanged.
+- Added direct mode: the generated local `empirical` skill and the automatic
+  instruction block now start with a self-contained Direct mode section. A
+  request that says "direct", "without Empirical" or "quick change" is handled
+  as a plain agent turn that makes no Empirical call, reads no specification,
+  decision, capability or context page, runs a test, lint, typecheck or build
+  only when asked, and ends with
+  `Changed <X> in <N> files · not tested (not requested) · say "track this" to formalize`.
+- Added `empirical_direct` (library `direct`, private CLI `direct`) with exactly
+  three actions: `pause` ("go direct") records `pause: { since, baseCommit }` on
+  the selected feature with one `Pause: direct mode` journal event and no spec,
+  delta, decision, receipt or tracker gate; `resume` ("back to Empirical")
+  clears the pause and folds the paths changed since the base commit in as one
+  `iterate` for Fast work in Implement or implemented Done and for iterative
+  Complex work in an iterate-eligible phase, and otherwise as one journal event
+  that also names any iterate guard a paused feature could not have cleared;
+  `track` ("track this") rebuilds direct commits and uncommitted paths from Git
+  and starts a Fast (default) or Complex feature whose request lists them.
+- While a feature is paused, `loop` and `next` return only a paused action naming
+  `resume`, `status` and `overview` report the pause, and `complete`, `iterate`,
+  `consolidate`, `promote`, `retry`, QA execution and recording, evidence
+  execution and collection, `integrate`, `deliver` and `publish` fail with
+  `FEATURE_PAUSED` without state change.
+- Added an optional team `defaultMode` (`empirical` or `direct`) to
+  `.empirical/config.json` and a personal override in the checkout's
+  `<git-dir>/empirical-sdd/preferences.json` through `empirical_configure` with
+  `scope: "personal"`. Absence keeps existing configuration bytes identical, any
+  other value fails `INVALID_CONFIG`, and `status` reports team, personal and
+  effective values with a warning for an unreadable or invalid personal file.
+- Complex Implement actions carry `contractSummary`, a deterministic extract of
+  the feature's goal, acceptance criteria, accepted decisions and open risks
+  bounded to 6,000 characters, with the full spec, design, decisions and plan
+  listed as optional `references`. Their `capabilityContext` lists only the
+  capabilities the feature's own deltas declare. Iteration actions add
+  `adjustmentRequest`, the newest request verbatim, which overrides conflicting
+  earlier criteria and decisions; the superseding decision is recorded after the
+  change and never blocks Implement completion.
+- During an iteration of a Complex feature started with `iterative: true` (recorded
+  durably as `lifecycle.iterative`), contract edits to acceptance criteria, declared
+  requirement contents and decisions are an amendment by default:
+  `empirical_iterate` and the Implement completion accept them and re-approve the
+  amended specification and delta digests in one journal event, without returning
+  to Specify and without a human confirmation gate. `amendContract: true`
+  (`--amend-contract`) is the explicit equivalent, cannot be combined with
+  `reviseContract` (`INVALID_ARGUMENT`), and Fast rejects it with
+  `PROFILE_CONFLICT`. The approved contract is retained in
+  `contract-revisions/<revision>.baseline.json` and each change in
+  `<revision>.amendment.json` with previous and current criterion text and
+  superseded decision ids. Consolidation and Review actions, the Review packet and
+  `empirical_explain` list every amendment since the last full approval. Raising
+  the risk floor, adding or removing a delta capability, adding, removing or
+  renaming a requirement block, changing its operation, or changing `impact.json`
+  fails with `CONTRACT_REVISION_REQUIRED` and re-approves nothing, while a
+  `failed`, `blocked` or `awaiting_human` outcome can still be recorded. The risk
+  limit compares the resulting risk level over criteria and declared requirement
+  text, so rewording, reordering or lowering the floor is not an escalation.
+  Outside the iteration stage, and for Complex features without the iterative
+  opt-in, contract edits keep failing with `SPEC_CHANGED`, `DELTA_CHANGED` or
+  `IMPACT_CHANGED`, and `reviseContract` is unchanged. Retained history is
+  authenticated: a baseline is trusted only while it reproduces the approved
+  specification and delta digests, and a missing or malformed amendment record
+  fails with `CONTRACT_HISTORY_MISSING` or `CONTRACT_HISTORY_INVALID`.
+
+### Fixed
+
+- Any verification command can declare `full-ci`, not only `bun run ci`, so
+  repositories built with pnpm, npm, Make, Python or other tools can satisfy the
+  promotion gate, use integration replay coverage and opt into `remote-checks`
+  (SDD-72). Changed-file commands still cannot declare it. For a non-`bun run ci`
+  full-CI command, changes to task-runner manifests in its `cwd` or to files named
+  in its argv replay every command during integration and require local proof
+  under `remote-checks`. Bun-only policies keep their configuration digest.
+- `rationale.missingContext` now lists only unmet requirements: existing
+  artifacts, evidence kinds proven by accepted receipts at the current revision
+  and QA checks with passing current receipts are excluded, while
+  `requiredContext` is unchanged.
+- CLI step counts came from a hardcoded 10-phase Complex list that included
+  Deliver and Publish; they now equal the engine's `roadmap.progress`.
+
+### Migration
+
+- Schema 5 is unchanged. Update the installed package, refresh the managed
+  Empirical skills and repository instructions, and restart connected agent/MCP
+  sessions to load the new direct-mode and status-card guidance.
+- Existing configurations retain their defaults. To adopt direct mode, request
+  it explicitly or configure the optional team/personal `defaultMode`. To adopt
+  automatic ticket completion on release or deployment, configure and confirm
+  the tracker lifecycle status mappings and production environment in Init.
+- Complex iterative features created before 0.36.0 do not have the durable
+  `lifecycle.iterative` opt-in and continue using strict contract revision.
+  Finish them with the existing revision path, or start new iterative work
+  through the normal workflow to use in-place amendments. Do not edit journal
+  state or baseline files to add the marker manually.
+- Non-Bun repositories may explicitly mark their full-CI command with `full-ci`;
+  changed-file commands remain ineligible. Existing Bun-only policies need no
+  change.
+
+## [0.35.0] - 2026-09-15
+
+### Added
+
+- Approved mockup files and the chosen direction now accompany Implement, with
+  instructions to preserve the approved layout and styles. Missing or unreadable
+  mockup files do not introduce a new implementation gate.
+
+- Added default discovery of ignored, untracked local environment files for
+  worktrees through `isolation.localFiles` (`discover`, `include`, `exclude`;
+  defaults `**/.env` and `**/.env.*` excluding `.env.example`, `.env.sample` and
+  `.env.template`, never under `node_modules`, `.git` or `.empirical`). Proposals
+  list every explicit and discovered path and every refusal; approving the
+  proposal approves exactly those copies. Discovery is bounded to 200 candidates
+  and 1 MiB per file, with refusals reported by path and reason.
+- Added `empirical_worktree_prepare` (library `prepareWorktree`, internal CLI
+  `worktree-prepare`) to preview and apply local file copies for worktrees
+  created by host tools, `git worktree add`, delegation or transfer.
+- Added `localFiles: { copied, skippedExisting, missingOptional, unapproved, refused }`
+  to worktree handoffs and prepare results, plus local file lines in proposal,
+  handoff, configuration and Init text.
+
+- Fast features iterate through `empirical_iterate` from Implement or
+  implemented Done without promotion or test runs: the lifecycle iteration
+  counter increments, the journal keeps every `Iterate:` event, and `id`
+  addresses a Done feature. Fast consolidate requires explicit promotion.
+- Fast starts create `decisions.md`; status and explain list Accepted Fast
+  decisions and report format issues as non-blocking `decisionWarnings`.
+- QA planning, QA execution and evidence execution accept an explicit
+  `verificationProfile`: `iterate` runs only `testFiles: "changed"` commands and
+  `final` runs the configured final scope (Fast `final` excludes full CI and stays
+  unverified). Action packets report `verificationProfiles`.
+- `empirical_yolo` accepts `profile`; explicit Fast defaults to and is limited to
+  the `implemented` ceiling.
+- Routes report `matchedFloors`.
+- Policy v2 accepts optional `promotion.fullCi` (`local` or `remote-checks`);
+  policy and configure results report a read-only `effective` value. Empirical
+  versions before this release reject a policy that sets `promotion`.
+- Opt-in `remote-checks` promotion proof: passing, app-pinned GitHub required
+  check runs for the exact pushed commit create an immutable `remote-checks`
+  receipt through an injectable checks reader. Integrate accepts it only for an
+  already pushed commit; Deliver may push and open the source pull request and
+  returns `promotion-proof-required` until it passes, binding proof per head
+  before any merge; Publish rejects it. Remote proof is refused when the branch
+  changes policy, package scripts, workflows, composite actions, `scripts/**`,
+  lockfiles, `.gitmodules`, symlinks or gitlinks, or when target workflows use
+  unpinned `uses:` references. Repositories whose protection uses legacy
+  unpinned status contexts or ruleset entries without an app pin must pin the app,
+  and must SHA-pin workflow and action references, before `remote-checks` can pass.
+
+### Changed
+
+- Init now declares `.empirical/** -text` in `.gitattributes` to preserve
+  digest-bound journal bytes across Git checkouts. Existing project-specific
+  Empirical attribute rules are preserved.
+- Lock waiters renew their wait budget as ownership changes, while retaining a
+  bounded overall wait, so healthy contention does not report a stuck repository.
+
+- Existing configurations now discover local environment files by default
+  without being rewritten, so worktree proposals and their approval tokens change
+  when ignored environment files exist; pass the proposal's `localFiles`
+  unchanged to `empirical_worktree_create`. Set `discover: false` to opt out.
+- Worktrees created outside Empirical can now receive local files through
+  prepare, and generated agent guidance routes local file provisioning through
+  the Empirical proposal and prepare operation.
+
+- Deliver accepts the full-CI receipt Integrate recorded for an identical
+  candidate instead of requiring a second local full-CI run; `reuseReceiptId` and
+  Publish keep exact revision matching. The delivered source pull request head is
+  bound to the proven commit before review, ready or merge.
+- A failed Fast completion now blocks the same Fast feature with `retry` and
+  explicit `promote` as recovery paths instead of promoting it to Complex, and
+  `promote` accepts that block.
+- An explicit Fast request is no longer promoted by integration or delivery
+  wording; sensitive, migration and publication signals still promote it.
+- Integrate, Deliver and Publish refuse Fast features with `PROMOTION_REQUIRED`
+  guidance; only explicit `empirical_promote` changes a Fast feature to Complex.
+- `receiptIds` is optional on `empirical_integrate` and `empirical_deliver`.
+- Generated skills and phase instructions explain lane choice, Fast iteration,
+  explicit promotion, the phrase-to-profile mapping, one-request test
+  authorization, carry-over and remote-checks, and no longer state that
+  consolidation authorizes tests.
+
+- Fast action packets no longer list every living capability specification;
+  agents open a capability only when the change touches it. Complex and
+  promoted features keep the full list.
+- Verification commands can opt into `testFiles: "changed"` to run only the
+  test files matching changed files, failing with `NO_CHANGED_TESTS` rather than
+  falling back to the whole suite.
+- Independent integration validation no longer re-runs verification commands
+  whose declared checks a full-CI command in the same directory already covers,
+  unless the feature changes the policy or package scripts, and reports which
+  commands executed or were covered.
+
+### Fixed
+
+- Windows worktree creation and recovery recognize canonical directory identity
+  across separator, case and short-path spellings. Recovery errors identify the
+  mismatched check and explain when a newer runtime is needed to load the base.
+- Invalid mockup approval feedback now shows the approval document shape, even
+  during Verify, instead of the fidelity-report shape.
+
+- `empirical update` and `empirical uninstall` work on Windows again. Node refuses
+  to spawn `.cmd` wrappers without a shell (CVE-2024-27980), so npm and the
+  PATH-visible CLI now run through `cmd.exe` by quoted absolute path and the
+  npm-installed CLI runs through Node, including prefixes containing spaces (SDD-66).
+
+### Migration
+
+- Update the package and installed global skills with `empirical update`, restart
+  the coding agent/MCP host, invoke `empirical-init` in each existing repository
+  to refresh managed instructions and local skills, then reload affected sessions.
+- Existing configurations discover ignored, untracked `.env` and `.env.*` files
+  by default. Review the paths in worktree proposals; set
+  `isolation.localFiles.discover` to `false` to retain explicit-only copying.
+  Existing `isolation.copyFiles` entries remain required. Use worktree prepare
+  to provision worktrees created by another tool without overwriting files.
+- Fast failures now stay Fast. Retry or explicitly promote the same feature
+  when stronger verification or integration is needed. To iterate on an existing
+  Complex implementation, request iterative development and explicitly request
+  final verification when ready; iteration alone does not authorize tests.
+- `promotion.fullCi` remains `local` by default. Opt into `remote-checks` only
+  after configuring app-pinned required checks and SHA-pinned workflow/action
+  references. Upgrade every participating agent before adding this policy field;
+  older versions reject it. Publication still requires local proof.
+- When refreshing an existing repository, review and commit the `.gitattributes`
+  journal rule added by Init. An existing rule for `.empirical` is left untouched;
+  ensure it preserves journal bytes across worktrees. Keep existing journal and
+  receipt files intact.
+- Schema 5 and existing specifications, journals, tracker bindings and receipts
+  are retained. Do not delete workflow state to upgrade.
+
 ## [0.34.0] - 2026-09-14
 
 ### Added
@@ -543,7 +808,9 @@ Published through GitHub Actions trusted publishing with npm provenance.
 
 - Prepared and released package version `0.20.2`.
 
-[Unreleased]: https://github.com/goempirical/empirical-sdd/compare/v0.34.0...HEAD
+[Unreleased]: https://github.com/goempirical/empirical-sdd/compare/v0.36.0...HEAD
+[0.36.0]: https://github.com/goempirical/empirical-sdd/compare/v0.35.0...v0.36.0
+[0.35.0]: https://github.com/goempirical/empirical-sdd/compare/v0.34.0...v0.35.0
 [0.34.0]: https://github.com/goempirical/empirical-sdd/compare/v0.33.0...v0.34.0
 [0.33.0]: https://github.com/goempirical/empirical-sdd/compare/v0.32.0...v0.33.0
 [0.32.0]: https://github.com/goempirical/empirical-sdd/compare/v0.31.0...v0.32.0

package/README.md

@@ -108,24 +108,79 @@ integration are different claims, and Empirical reports only the highest level
 actually proven: `implemented`, `verified`, `integrated`, `delivered`, or
 `published`.
 
-Fast trades verification confidence for less waiting and process. If a quick
-feature needs the full workflow, promote that same spec to Complex; its history
-and original identity are preserved. Historical completed Fast records retain
-the evidence and completion level they originally earned.
+Choose Fast for small, self-contained changes. Work that builds on an existing
+foundation and will be integrated belongs in Complex iterative
+(`empirical_complex` with `iterative: true`): adjust with `empirical_iterate`
+without test runs, then say "ready to close" to run final verification once.
+Each Complex implementation packet carries a bounded contract summary instead of
+the full documents, and the newest adjustment wins: a behavior change at the same
+risk floor amends the criteria and decisions in place, with the approved contract
+snapshotted for review. Raising the risk floor or changing the declared capability
+scope still requires an explicit contract revision through Specify/Design/Plan.
+
+Fast trades verification confidence for less waiting and process. A follow-up
+adjustment to the same Fast feature uses `empirical_iterate`, from Implement or
+after Done: no promotion, no test run, and the journal keeps every adjustment.
+A failed Fast completion blocks in place for `retry` or explicit promotion.
+Promotion is always explicit: Fast consolidate, Integrate and Deliver require
+`empirical_promote`, which continues the same spec through Complex Specify and
+preserves its history and identity. Historical completed Fast records retain the
+evidence and completion level they originally earned.
 
 Delivery is never implied. Empirical does not infer permission to merge a pull
 request, bypass protection, create a release, or publish a package.
 
+Every read returns one deterministic roadmap, and every stop shows the same
+status card built from it, so you always see where the work is and what it
+needs from you:
+
+```text
+Empirical · add-team-invitations · Complex · verify (6/8) · rev 5
+Done:           specify, design, plan, implement, context
+Not done:       verify: qa-unit unrun, qa-browser missing-environment
+Next:           Run qa-unit at revision 5 (~2m 10s) when you request tests
+Waiting on you: [test-request] Ask to run 1 check (~2m 10s), or keep iterating
+                [environment] qa-browser needs isolated-consumer
+Verification:   2 of 4 checks left (~2m 10s known; 1 unknown)
+```
+
+`empirical status`, `explain`, `next` and `loop` print it, `--json` carries the
+same `roadmap`, and the agent skill shows it at every start, phase change and
+stop, and before a long run it estimates and offers to defer. The card reports
+facts; it authorizes nothing.
+## Work directly when you want to
+
+Say "direct", "without Empirical" or "quick change" and the agent just edits:
+no specification, state, phase, receipt, gate, tracker update or worktree
+proposal, and no reading of specs, decisions or context pages. Nothing runs
+unless you ask for it, and the turn ends with one line such as
+`Changed the button label in 1 files · not tested (not requested) · say "track this" to formalize`.
+
+Inside a repository or feature that uses Empirical, "go direct" pauses the
+selected feature, "back to Empirical" folds the direct diff back in as one
+iteration, and "track this" rebuilds recent direct commits and uncommitted files
+from Git into a Fast (or Complex) feature. Push, merge, pull request, tag,
+publish, credential use and destructive Git still need an explicit request.
+
+A team can set `defaultMode` to `direct` in `.empirical/config.json`, and each
+developer can override it for their own checkout; explicit Fast, Complex or
+"use Empirical" requests always start those lanes.
+
 ## Run tests when you need them
 
 Fast and Complex iteration do not automatically run tests after edits. Ask for a
 run when ready:
 
-- “Run tests for this feature” selects the smallest relevant configured checks.
+- “Run the changed tests” or “run the affected tests” uses the `iterate`
+  verification profile: only commands configured with `testFiles: "changed"`.
+- “Now run it”, “run everything” or “ready to close” uses the `final` profile.
 - “Keep iterating; skip tests for now” leaves verification pending.
-- “Run the full suite” explicitly requests broader verification.
 
-One test request does not enable automatic reruns after subsequent changes.
+One test request does not enable automatic reruns after subsequent changes, and
+no phase, iteration or consolidation runs tests by itself. One exact full-CI
+receipt recorded at Integrate also serves Deliver when nothing changed, and a
+repository can opt into `promotion.fullCi: "remote-checks"` so passing GitHub
+required checks on the exact pushed commit stand in for local full CI.
 If no focused command is configured, the agent reports the gap instead of
 silently running the entire suite. Complex still requires real evidence before
 claiming verified completion; Fast can finish implemented and unverified.
@@ -184,6 +239,14 @@ executes them through the authenticated Linear MCP tools, and validated results
 converge the same binding, milestone, and strict-gate records without sharing
 the OAuth token.
 
+### Automatic lifecycle tracking
+
+Policy v2 workflow actions now synchronize automatically. Linear MCP hosts
+receive a prepared tracker intent, and trusted host dispatchers can execute it
+automatically. Init confirms every discovered mapping and whether Done means
+local completion, a confirmed release, or production deployment. See
+[Lifecycle tracking](docs/tracking.md) for setup, recovery, and the observation hook.
+
 ## Documentation
 
 - [Practical guide](https://goempirical.github.io/empirical-sdd/) — visual onboarding and diagrams
@@ -225,6 +288,15 @@ their original checkout. Transferring an unfinished spec to another worktree
 requires its exact source revision and matching destination history; it keeps
 the original capability bases and receipts.
 
+Ignored local environment files such as `apps/api/.env` or `apps/web/.env.local`
+are discovered by default, listed by path in each worktree proposal, and copied
+into the new worktree when you approve it. Copies are independent, never
+overwrite existing files and never enter Git. Set `isolation.localFiles.discover`
+to `false` to opt out, or adjust its `include` and `exclude` patterns. For a
+worktree created by another tool or `git worktree add`, your agent previews and
+applies Empirical prepare to fill in the missing files.
+See [local environment files](docs/protocol.md#local-environment-files-in-worktrees).
+
 Ask your agent for the read-only overview to see specs, owners, branches,
 profiles, progress and verification status together. Unrelated malformed records
 appear as local diagnostics without selecting or deleting any spec. Independent

package/dist/changed-tests.d.ts

@@ -0,0 +1,18 @@
+/** Paths changed on this branch since `base`, plus uncommitted and untracked work. */
+export declare function changedPaths(root: string, base: string | null): string[];
+/**
+ * Existing test files that correspond to the changed paths: changed test files
+ * themselves, and tests whose name stem matches a changed source file.
+ */
+export declare function selectChangedTests(root: string, changed: readonly string[]): string[];
+/**
+ * The argv to execute for a configured command. Commands that opt into
+ * `testFiles: "changed"` receive only matching test paths and never fall back
+ * to their bare argv, which would usually run the whole suite.
+ */
+export declare function resolveCommandArgv(root: string, command: {
+    id: string;
+    argv: readonly string[];
+    cwd: string;
+    testFiles?: "changed" | undefined;
+}, base: string | null): string[];

package/dist/checkouts.d.ts

@@ -3,6 +3,8 @@ export declare function withCheckoutLock<T>(root: string, operation: () => Promi
 /** A shared feature lock prevents a writer from racing ownership transfer. */
 export declare function withFeatureLock<T>(root: string, feature: string, operation: () => Promise<T>, options?: {
     allowPendingTransfer?: boolean;
+    /** Completed tracking may use its recorded owner or a validated delivery event. */
+    completedTransfer?: "tracker-owner" | "lifecycle-record";
 }): Promise<T>;
 export interface CheckoutSelection {
     feature: string | null;
@@ -14,6 +16,11 @@ export declare function readCheckoutSelection(rootInput: string): Promise<Checko
 export declare function writeCheckoutSelection(rootInput: string, feature: string | null, expectedFeature?: string): Promise<void>;
 /** Transfer releases an unfinished owner without creating terminal obligations. */
 export declare function moveCheckoutSelection(sourceRoot: string, targetRoot: string, feature: string): Promise<void>;
+/** Call under the shared feature lock before automatic external side effects. */
+export declare function assertCheckoutFeatureOwner(root: string, feature: string): Promise<void>;
+/** A receipt-backed delivery event may adopt completed work in another checkout.
+ * Call as the guarded journal effect, and roll back if that commit fails. */
+export declare function adoptCompletedTrackerFeature(root: string, feature: string): Promise<() => Promise<void>>;
 /** Read only this checkout's recovery anchor, never sibling selections. */
 export declare function readCheckoutLastFeature(rootInput: string): Promise<{
     git: boolean;
@@ -27,3 +34,5 @@ export declare function readCheckoutRecoveryFeatures(rootInput: string): Promise
  * commit, so a process exit before selector cleanup cannot orphan the effect. */
 export declare function recordCheckoutRecoveryFeature(rootInput: string, feature: string): Promise<void>;
 export declare function forgetCheckoutRecoveryFeatures(rootInput: string, resolvedFeatures: string[]): Promise<void>;
+/** A checkout-local runtime file under `<git-dir>/empirical-sdd/`, guarded like the selector; null outside Git. */
+export declare function checkoutRuntimePath(rootInput: string, name: string): Promise<string | null>;