empirical-sdd 0.35.0 → 0.36.0

package/CHANGELOG.md

@@ -8,6 +8,139 @@ 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
@@ -675,7 +808,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.35.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

package/README.md

@@ -112,6 +112,11 @@ 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
@@ -125,6 +130,42 @@ 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
@@ -198,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

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>;