empirical-sdd 0.31.0 → 0.32.0

package/CHANGELOG.md

@@ -8,6 +8,63 @@ under the alpha rules in [docs/versioning.md](docs/versioning.md).
 
 ## [Unreleased]
 
+## [0.32.0] - 2026-09-08
+
+### Added
+
+- Added a six-step initialization wizard covering Setup, Preferences, Review
+  bot, Tracking, Confirm, and Apply, with Back/Edit navigation, retained
+  choices, and explicit Save before setup changes.
+- Added clickable app and feature mockup previews through `empirical mockups`,
+  human approval before UI contracts freeze, and fidelity checks against the
+  approved design during verification.
+- Added explicit reuse of exact-revision QA receipts after validating source,
+  specification, policy, command, runtime, executable, and artifact identities.
+- Added bounded verification progress and a repeatable benchmark for measuring
+  final verification without treating diagnostics as promotion evidence.
+- Added explicit selection of existing specs and recoverable approved worktree
+  handoffs, including retries after interrupted Git creation or feature setup.
+
+### Changed
+
+- Capability claims are now non-exclusive: specs in separate worktrees can
+  progress on the same capability while integration retains semantic conflict
+  detection against each spec's recorded base.
+- Git worktrees now use their own selected feature instead of automatically
+  inheriting unfinished spec histories. Multiple unclaimed specs may remain
+  inactive without blocking unrelated new work.
+- Reviewer-bot setup is optional, includes an explicit disable choice, and
+  preserves saved fresh-context review without repeated credential prompts.
+- Linear tracking prefers authenticated sibling MCP tools, including upgrade
+  recovery from legacy API-key configuration, and derives ticket content from
+  the specification while storing recovery identities in attachment metadata.
+
+### Fixed
+
+- Prevented unrelated malformed or blocked feature histories and sibling
+  checkout metadata from blocking normal work in another Git checkout.
+- Preserved strict tracker recovery obligations and checkout ownership across
+  terminal transitions, interrupted handoffs, and explicit feature selection.
+- Bound reused verification evidence to the selected executable and runtime
+  permission metadata so changed execution conditions cannot reuse stale proof.
+- Rejected blank mockup approvals and ambiguous fidelity fields, and preserved
+  path containment and explicit human design decisions.
+- Preserved user-authored tracker content while validating bounded MCP recovery
+  results and avoiding repeated provider mutations after ambiguous responses.
+
+### Migration
+
+After upgrading, run `empirical update` to refresh installed bootstrap guidance
+and invoke `empirical-init` in existing repositories to refresh managed local
+workflow instructions while retaining saved settings. Schema 5 remains in use;
+no manual data conversion is required.
+
+A Git checkout without a selected feature now remains idle. To resume an existing
+spec, explicitly select its feature through `empirical_select`; unclaimed specs
+are retained. UI changes must record the mockup approval and fidelity artifacts
+requested by the workflow. Verification receipts without matching current runtime
+and executable identities must be rerun rather than reused.
+
 ## [0.31.0] - 2026-09-04
 
 ### Added
@@ -381,7 +438,8 @@ 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.31.0...HEAD
+[Unreleased]: https://github.com/goempirical/empirical-sdd/compare/v0.32.0...HEAD
+[0.32.0]: https://github.com/goempirical/empirical-sdd/compare/v0.31.0...v0.32.0
 [0.31.0]: https://github.com/goempirical/empirical-sdd/compare/v0.30.0...v0.31.0
 [0.30.0]: https://github.com/goempirical/empirical-sdd/compare/v0.29.0...v0.30.0
 [0.29.0]: https://github.com/goempirical/empirical-sdd/compare/v0.28.0...v0.29.0

package/README.md

@@ -26,6 +26,17 @@ workflow. Its zero-build source is [docs/index.html](docs/index.html).
    - Codex: `$empirical-init`
    - Claude Code: `/empirical-init`
 
+   Init guides you through six steps in your agent chat: **Setup → Preferences →
+   Review bot → Tracking → Confirm → Apply**. It shows your current step and asks
+   one question at a time. Use **Back** or **Edit** to revisit a section while
+   keeping your other answers. Nothing is applied until you confirm **Save**.
+
+   Bot review is optional. Init offers it once; say “no,” “skip,” or “ignore”
+   to save fresh-context review without a bot token. Future init runs preserve
+   that choice. To enable it later, tell your agent “enable bot review.”
+   Fresh-context review still uses an isolated reviewer, but does not count as
+   an independent GitHub approval.
+
 3. Ask for the change normally.
 
    ```text
@@ -60,6 +71,12 @@ Empirical routes by risk, not prompt length:
 Specify → Design → Plan → Implement → Context? → Verify → Review → Integrate
 ```
 
+A feature that shows an interface gets its mockup at Specify, while the
+contract is still open, because seeing a screen reveals states and flows that
+prose misses and those belong in the criteria. `empirical mockups` serves the
+directions on a local address so a person can click through and choose one;
+Verify then checks what was built against what was approved.
+
 Context runs when repository knowledge needs refinement. Failed verification or
 requested review changes return to implementation. Evidence, review, and
 integration are different claims, and Empirical reports only the highest level
@@ -82,8 +99,10 @@ repository/
     ├── policy.json                      verification and delivery policy
     ├── tracker.json                     secret-free tracker choice
     ├── context/                         repository knowledge
+    ├── mockups/decision.md              app mockups adopted or declined
     ├── specs/<feature>/
     │   ├── spec.md + decisions.md       contract and decisions
+    │   ├── mockups/                     approved directions and fidelity
     │   ├── design.md + plan.md          Complex approach and plan
     │   ├── impact.json                  affected behavior and surfaces
     │   ├── state.json + events/         phase and resumable journal
@@ -138,3 +157,17 @@ reserved for validated release pull requests.
 ## License
 
 [MIT](LICENSE)
+
+### Shared specs across worktrees
+
+Specs and capability contracts are repository artifacts. Each Git worktree
+selects and claims its own active feature in local Git metadata; different
+worktrees can execute different features concurrently. Unclaimed or temporarily
+inactive specs stay in `.empirical/specs/`. They are not abandoned work.
+
+Use the agent's `empirical_select` operation to resume an existing unclaimed
+feature. Explicit new feature starts and repository setup/context repair are not
+blocked by unrelated unclaimed specs. If a feature-required operation needs a
+choice, it lists candidates rather than choosing or moving a spec. An approved
+worktree handoff can be retried with its original input after interruption.
+See [selection and recovery semantics](docs/protocol.md#shared-specs-and-checkout-selection).

package/dist/checkouts.d.ts

@@ -1,3 +1,5 @@
+/** Serialize checkout ownership across every worktree sharing Git metadata. */
+export declare function withCheckoutLock<T>(root: string, operation: () => Promise<T>): Promise<T>;
 export interface CheckoutSelection {
     feature: string | null;
     linked: boolean;
@@ -5,4 +7,17 @@ export interface CheckoutSelection {
     claimedElsewhere: Set<string>;
 }
 export declare function readCheckoutSelection(rootInput: string): Promise<CheckoutSelection>;
-export declare function writeCheckoutSelection(rootInput: string, feature: string | null): Promise<void>;
+export declare function writeCheckoutSelection(rootInput: string, feature: string | null, expectedFeature?: string): Promise<void>;
+/** Read only this checkout's recovery anchor, never sibling selections. */
+export declare function readCheckoutLastFeature(rootInput: string): Promise<{
+    git: boolean;
+    feature: string | null;
+}>;
+export declare function readCheckoutRecoveryFeatures(rootInput: string): Promise<{
+    git: boolean;
+    features: string[];
+}>;
+/** Write-ahead ownership: call after validation but before a terminal journal
+ * 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>;