empirical-sdd 0.35.0 → 0.37.0

package/CHANGELOG.md

@@ -8,6 +8,453 @@ under the alpha rules in [docs/versioning.md](docs/versioning.md).
 
 ## [Unreleased]
 
+## [0.37.0] - 2026-09-18
+
+### Added
+
+- Repository identity now follows the root of HEAD's first-parent history,
+  so full clones can recognize the same durable artifacts. The original
+  checkout still accepts its old path-derived id; a reviewed
+  `.empirical/identity.json` can declare verified earlier ids for other clones.
+  Shallow clones retain a path identity until their full history is available.
+- A clone with an absent local capability claim can select and verify its
+  feature. Integrate refuses with `CAPABILITY_CLAIM_UNREACHABLE` when the
+  comparison base is unavailable; locks, delegation and ownership transfers
+  remain restricted to linked worktrees of one checkout. Legacy authorization
+  and delivery/publication markers retain their original identity bindings.
+
+- A timed-out verification command now shows its way out. The status card marks the check with `timedOutAfterMs` and adds a decision naming the exits: run it in the background, use a smaller command, hand it to PR CI, raise `timeoutMs` up to the maximum, or stop. The agent is told to offer them instead of rerunning the same command in the foreground, and to suggest the background run before long runs.
+
+- Verification progress now reports where the feature stands and whether each
+  command passed. QA execution and independent integration replay carry the
+  phase and its 1-based position in the feature's phase order
+  (`phase 6/8 verify`), derived from the same order the roadmap reports —
+  including the review-first Complex order — and their closing heartbeat marks
+  `finished: passed` or `finished: failed` alongside the existing exit code,
+  timeout and signal detail. Hosts holding a `progressToken` receive the same
+  facts in the progress message text, with only the standard notification
+  fields. The receipt still decides what a run proves, a timeout or signal is
+  never marked passed, and no argv, environment value or child output enters the
+  progress channel.
+
+- Verify proof no longer goes stale for line-ending-only changes, and human QA
+  records can bind the paths they assessed. (SDD-84)
+  - **Line endings:** QA receipts record `textTreeDigest` (CRLF normalized to
+    LF in text files). At the Verify gate and on the status card, a receipt
+    below full CI survives a CRLF-only change. Scoped digests normalize too.
+    Promotion and full-CI proof stay byte-exact.
+  - **Human records:** `qa-record` accepts `assessedPaths`, so a human record
+    survives changes outside what it assessed.
+  - **Recorded scope:** an executed receipt's recorded scope must still match
+    the current policy command's scope and kind.
+  - **Scope matching:** entries are NFC-normalized, repeated `**` collapses,
+    and `workspace:../path` resolves by directory first.
+
+- After a recorded review, the next local review is a delta re-review. (SDD-85)
+  - **What the reviewer sees:** the packet carries `reReview`: the diff since
+    the previous reviewed head, the previous canonical review, the findings still
+    open, and the non-blocking findings already deferred.
+  - **Finding ids:** the reviewer repeats ids that are still open and omits fixed
+    ones. Triage reports `findingHistory` with each id as open, fixed, deferred
+    or new.
+  - **Full review instead:** used when the base moved, the previous head is not
+    a merge-free ancestor of HEAD, or the criteria, decisions or amendments
+    changed.
+  - **Gate check:** the gate rebuilds the same packet from the recorded context
+    and refuses a context that no longer matches its stored result.
+  - **Pull request body:** deferred findings carried from earlier rounds still
+    appear there.
+
+- New Complex and promoted Fast features run Review before Verify. Saved
+  features retain their original order; Verify preserves and revalidates the
+  independent review before advancing to Integrate.
+- Review results may carry structured findings with a severity and a category.
+  - Critical, high, security and acceptance findings block, and an approval
+    can't carry one.
+  - The recorded review returns `triage` with the round and the exits:
+    fix (with the Verify checks it re-runs and their estimates), defer
+    non-blocking findings to a ticket, open a draft pull request for CI, or
+    stop.
+  - After the review round limit, the exits must be offered instead of
+    another automatic lap.
+  - `empirical_review_defer` (`__internal review-defer`) records deferrals.
+  - Deliver lists every non-blocking finding and its deferral in the pull
+    request body. (SDD-86)
+
+- Verification commands may declare `scope: "workspace"` to derive their
+  Verify-gate QA receipt scope from the pnpm, npm, yarn, bun or Turbo workspace
+  package graph: the target package plus its transitive workspace
+  dependencies. The scope is derived again at validation and a changed graph
+  makes the receipt stale; ambiguous targets bind the whole tree and record a
+  `SCOPE_WORKSPACE_UNRESOLVED` reason.
+- Background verification jobs: `empirical_qa_start`, `empirical_qa_status` and
+  `empirical_qa_cancel` (with `__internal qa-start`, `qa-status` and
+  `qa-cancel`) run a matrix-authorized command in a detached snapshot worktree
+  of the committed `HEAD`, so agents keep working. Jobs are durable records
+  under the Git common directory, run one at a time per repository, record a
+  normal QA receipt bound to the job commit, report `stale` when the feature
+  revision or source tree moves, and always remove their snapshot.
+- Background jobs stream a bounded, redacted live log, record the failing test
+  files named by bun, node `--test` and vitest/jest output, and accept
+  `testFiles` to rerun only tracked test files through a `testFiles: "changed"`
+  command. Roadmaps list recent jobs with stable fields, the CLI status card
+  adds a `Regression:` line, and managed skills ask for approval before a
+  full regression without CI, run it in the background and keep working.
+
+- `empirical_sync_target` (`__internal sync-target [--fetch] [--target <ref>]`)
+  keeps a feature branch current with its target: it predicts conflicts with
+  `git merge-tree`, merges only when the worktree is clean and conflict-free,
+  never rebases, forces or pushes, and otherwise changes nothing and reports the
+  conflicting files.
+- The roadmap adds a `decision` waiting item and a sync `nextAction` when the
+  branch is behind its target with predicted conflicts or by more than
+  `staleness.maxBehind` commits (default 10), read from local refs only. The
+  optional `staleness` configuration never blocks a gate.
+- Managed skills sync with the target at every checkpoint and before opening or
+  updating a pull request, and re-run only the tests for conflicted files.
+- Size guardrail: Complex features over 6 acceptance criteria or 2
+  capabilities in Specify through Implement carry `featureSize`, a non-blocking
+  roadmap decision and a `nextAction` proposing slices. `empirical_split_decision`
+  records keep (reason required) or split at the exact revision, limits are
+  configurable with `sizeGuardrail`, and the skill presents the split option
+  before implementing.
+- Time budget and checkpoints: roadmaps carry `time` (`elapsedMs`,
+  `phaseElapsedMs`, `budgetMs`, `over`) derived from journal timestamps, and
+  the status card shows a `Time:` line. An optional per-lane `budget` in
+  `.empirical/config.json` defaults to Fast 30, Quick 60 and Complex 120
+  minutes; invalid values fail with `INVALID_CONFIG`. An exceeded budget, or
+  Review sending work back to Implement, adds a decision checkpoint with
+  explicit exits, and `empirical_checkpoint` records the choice to continue
+  with more minutes. The generated skill never continues past an exceeded
+  budget without the user's choice.
+- `empirical_qa_plan` returns a Verify `selection` beside the unchanged matrix:
+  one command per automated Verify check, chosen as a deterministic
+  minimum-cost cover (fewest unknown estimates, lowest summed median duration,
+  fewest commands, earliest policy order) with per-entry `estimateMs`,
+  `sharedWith` and `reason`. Full-CI commands are never candidates, and
+  changed-file commands only when a changed test file matches. Profile plans mark
+  `selected` entries, roadmap Verify checks name `selectedCommandId`, and
+  `nextAction` runs the selected command once for every check it covers.
+- Local full-suite runs need an explicit, immutable approval bound to the
+  feature, revision, commit, tree, policy, command, argv and shown estimate.
+  `empirical_qa_approve` (private `qa-approve --revision --command --estimate-ms
+  [--yes]`) records it, asking through MCP form elicitation when the host
+  advertises elicitation and otherwise marking it `agent-relayed`; the CLI marks
+  `cli` or `cli-unattended`. Each approval authorizes one run. Publish's explicit
+  publication authorization, passed to `empirical_qa_execute` as
+  `publicationAuthorization`, approves Publish's own full-CI run.
+- A deterministic `promotionRoute` (`ci` or `local` with every reason) on the
+  roadmap's full-CI check; route `local` shows one authorization item with the
+  command, estimate, revision and first reason.
+
+### Changed
+
+- Raised the verification command timeout ceiling from 15 to 45 minutes, in the
+  runtime bound, both Policy v2 command schemas and the benchmark harness, so a
+  long complete suite is no longer killed mid-run. Projects opt in by raising a
+  command's `timeoutMs`; this repository's own policy moves after the release,
+  because published 0.36.0 and earlier versions, and early 0.37.0 preview
+  builds, reject timeouts above 15 minutes.
+
+- Generated agent guidance now ships early: open a draft pull request at the
+  first coherent commit of feature work, push every commit, and never let test
+  runs block commits or pushes. Tests for the change run in the background and
+  heavy runs belong to pull-request CI. Push authority covers only the agent's
+  own feature branch and draft pull requests, never merges, protected or target
+  branches, or force pushes. Implement instructions carry the same rule.
+- An omitted `promotion.fullCi` now means `auto`: pull-request CI with pinned
+  required checks proves full CI at Deliver unless an SDD-67 local-forcing reason
+  applies, and otherwise the full suite runs locally after approval. The digest
+  of an unchanged policy is kept; an explicit `local` is now kept in the parsed
+  policy (one digest change) and always runs locally. `remote-checks` is unchanged.
+- A fresh `empirical_qa_execute` or `empirical_evidence_execute` full-CI run
+  refuses with `FULL_SUITE_APPROVAL_REQUIRED` before starting without a matching
+  approval; receipt reuse needs none.
+- Integrate on `auto`'s route `ci` needs no full-CI receipt and records the
+  route in its integration receipt. Independent replay never executes full CI
+  and runs only the Verify selection (every bare non-full-CI command when the
+  feature changed verification configuration); `integrationReplayCommands`
+  plans replay (`integrationReplayPlan` stays as a deprecated export), and a
+  policy with only full-CI commands replays nothing with a plan note.
+- Route `ci` also needs delivery authority (`DELIVERY_NOT_AUTHORIZED` otherwise),
+  lifecycle observation refuses full-CI commands, and per-command estimates match
+  a bare command's exact argv only.
+- Under `auto`, Deliver may push and open the source pull request before proof,
+  returns `promotion-proof-required` with `route: "ci"` until the exact head is
+  green, and switches to `route: "local"` with the pending approval when remote
+  proof is ineligible; it merges nothing before proof.
+- Skill guidance, Verify, consolidation, Integrate, Deliver and Publish
+  instructions state that iterating runs nothing, "run the changed tests" runs
+  `iterate` once, Verify runs the selection, the full suite runs only as PR CI or
+  an approved local run, and agents never approve on the user's behalf.
+
+### Fixed
+
+- A source change after an approved review returns `REVIEW_STALE` before
+  validating Verify receipts, including when the collected review's tree is stale.
+- Workspace scope inference refuses every spelling of npm's
+  `--include-workspace-root` flag, including `=true`, so root tests and source
+  remain bound by whole-tree evidence.
+
+- Scoped QA receipts recorded by a passing Verify gate remain valid Verify
+  evidence through later phases. Review artifacts and promotion proof retain
+  exact tree binding; an unrelated edit no longer forces another repair lap.
+- Background log callback declarations use portable byte arrays so packed
+  consumers do not require ambient Node `Buffer` types.
+- Split guidance now provides an executable early exit: explicit contract
+  revision returns Design or Plan to Specify while retaining the approved
+  contract; unapproved Specify work can be narrowed directly. No migration
+  required; existing state and receipts retain their schema.
+- Verify command selection respects each command's criterion allowlist; a
+  cheaper partial command never displaces a command that can satisfy the check.
+- Background jobs retain their originating checkout, feature, command arguments
+  and policy/matrix bindings. A changed policy cannot certify an older command;
+  cancellation terminates the detached test process before snapshot cleanup.
+  Older queued jobs without execution bindings fail `JOB_STALE` and must be
+  restarted; no durable feature-state migration is required.
+- Canonical review failure transitions use triage's recorded-review count and
+  round-limit boundary; earlier Verify failures no longer exhaust the first
+  review repair. Existing review history is honored without a state migration.
+- Command timeouts now terminate POSIX process groups, attempt Windows process
+  tree termination, and bound output cleanup so inherited pipes cannot leave QA
+  waiting indefinitely. Timeout receipts remain non-passing even when a wrapper
+  exits successfully during termination.
+- Bounded command logs now retain the final output after noisy setup, and
+  verification progress reports timeout, signal and exit status on completion.
+- QA reports preparation, command execution, finalization and receipt-reuse
+  timings separately. MCP clients requesting progress receive phase updates,
+  and the final diagnostic timing summary lives in result metadata, outside the
+  immutable receipt.
+- QA skips a second dependency fingerprint when the initial fingerprint is
+  unavailable or the command failed, timed out or was cancelled. Such receipts
+  remain ineligible for reuse. Invalid retry history is rejected before running
+  another command and checked again after execution.
+- Ready-to-close guidance no longer runs full CI during consolidation. Final
+  verification profile plans omit commands covering promotion checks such as
+  `qa-full-ci`. Full CI follows the approved local or eligible remote promotion
+  route instead of being repeated during Verify and integration replay.
+- Verification profile plans list each executable command once with the
+  `coveredCheckIds` a single run covers, so a command declared for two checks
+  is no longer run twice.
+- A Done Fast feature that is implemented and not integrated accepts on-demand
+  optional checks again: `qa-plan`, `qa-execute`, `evidence-execute` and
+  `evidence-collect` take its explicit `id`, refused before migration for any
+  other feature. Evidence execution for it needs an explicit profile. Receipts
+  stay optional and the completion level does not change.
+- Stale evidence receipts refused by `complete` or `reuseReceiptId`, including
+  future revisions, another GitHub repository, unknown matrix checks and
+  modified artifacts, return `RECEIPT_STALE` with the receipt id and the changed
+  binding instead of `UNEXPECTED`.
+- Empty or whitespace-only Context pages are refinement-required, so the
+  Context gate no longer passes them.
+- At Verify, `verify` evaluates the active feature's valid on-disk receipts the
+  way the completion gate would, so it no longer lists them as missing before
+  `complete`. Full-CI, remote-checks and review receipts, and every later gate,
+  stay recorded-only.
+- Review refuses an empty committed diff with `REVIEW_DIFF_EMPTY` and keeps
+  committed evidence receipts and journal events out of the reviewed diff. The
+  diff spans the whole Git worktree when the project is nested in it. Reviews
+  recorded under the previous diff must be requested again.
+- A malformed review submission, including one wrapped in a `submission`
+  property, returns `INVALID_ARGUMENT` instead of crashing.
+- Doctor recommends `core.longpaths=true` for a Git repository on Windows
+  (`GIT_LONGPATHS_DISABLED`), because generated evidence receipt paths can
+  exceed Git's Windows path limit.
+
+### Migration
+
+- Upgrade to `empirical-sdd@0.37.0`, refresh managed repository/global agent
+  skills through Empirical integrations, and restart or reconnect MCP clients
+  so they discover the new tools and guidance. Upgrading the package alone does
+  not rewrite installed skills or refresh a running server.
+- For delta re-review, pass the returned `reReview` context to the isolated
+  reviewer, including the previous verdict and open/deferred findings. Keep the
+  ids of still-open findings. Prepare a new packet if deferrals change while a
+  review is pending; changed bases, merge history or contracts need a full review.
+- New Verify QA receipts normalize CRLF in ordinary text. Older scoped receipts
+  made on a CRLF checkout may become stale and must be rerun. Human records can
+  opt into `assessedPaths`; that scope exception applies during Verify only.
+  Review and full-CI/promotion proof retain exact binding. See the documented
+  line-ending limitations in `docs/protocol.md` when tests depend on text bytes.
+- Keep existing Schema 5 state and receipts; do not reinitialize projects or
+  edit evidence to migrate them. New Complex and promoted Fast features record
+  `reviewFirst: true`; existing features without that field keep Verify before
+  Review. Clients must follow the returned phase and roadmap instead of assuming
+  one global order.
+- If every full-suite run must remain local, explicitly configure
+  `promotion.fullCi: "local"` in the project policy. An omitted setting now uses
+  `auto`, which accepts CI only with eligible pinned required checks and delivery
+  authority, otherwise requiring a local run. Each fresh local full-suite run
+  needs a separate explicit approval bound to the displayed candidate and
+  command; delivery authority alone does not approve it.
+- Re-run checks or obtain a fresh review when Empirical reports stale proof.
+  Explicit `local` normalization can change the policy digest once, and the
+  review diff now excludes receipts and journal events. Do not rewrite receipt
+  bindings to preserve old approvals.
+- To use workspace-derived Verify reuse, opt in with `scope: "workspace"` only
+  for commands whose target/dependency graph is resolvable. Commands without a
+  scope still bind the whole tree; global inputs always bind, and independent
+  review and full-CI promotion proof remain exact.
+- Restart any preview-era background jobs that report `JOB_STALE` because they
+  lack the new execution bindings. Existing feature state needs no rewrite.
+- Treat `roadmap.time` as a live clock when comparing status responses; compare
+  durable action fields separately. Respect the budget checkpoint and explicit
+  continue/split/defer/stop choices returned by the updated guidance.
+- Upgrade every CLI/MCP host before setting command `timeoutMs` above 900000.
+  The new ceiling is 2700000 (45 minutes); existing configured limits stay as
+  configured. A policy change invalidates its old proof and needs a new approved
+  run. Progress consumers should use the returned phase and outcome; MCP keeps
+  standard notification fields and carries the extra facts in message text.
+- Before moving legacy evidence to another clone, use a full-history checkout
+  (unshallow it first when needed). Use the lineage id from post-upgrade receipt
+  provenance and only verified prior ids from that repository's older receipts
+  to prepare and review `.empirical/identity.json`, following the format in
+  `docs/protocol.md`. Commit the record before relying on it in another clone;
+  never admit an unknown id just to make validation pass. Existing local path
+  identities remain recognized in their original checkout.
+- A missing capability claim does not contain a recoverable comparison base.
+  Perform integration from the owning checkout or explicitly transfer to one of
+  its linked worktrees; do not invent a base or copy Git-private claim state to
+  simulate cross-machine ownership.
+
+## [0.36.0] - 2026-09-16
+
+### Added
+
+- Verification commands may declare an optional `scope` of repository-relative
+  path prefixes or simple globs. Their Complex Verify-gate QA receipts record a
+  scoped content digest and stay valid when only files outside the scope and
+  global configuration change. Full-CI commands refuse `scope`, and promotion,
+  remote-checks, review, human and collected evidence keep whole-tree binding.
+- 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 +1122,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.35.0...HEAD
+[Unreleased]: https://github.com/goempirical/empirical-sdd/compare/v0.37.0...HEAD
+[0.37.0]: https://github.com/goempirical/empirical-sdd/compare/v0.36.0...v0.37.0
+[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

@@ -92,9 +92,13 @@ Implement → Done (implemented; verification skipped)
 Complex:
 
 ```text
-Specify → Design → Plan → Implement → Context? → Verify → Review → Integrate
+Specify → Design → Plan → Implement → Context? → Review → Verify → Integrate
 ```
 
+Existing features retain their saved Verify-before-Review order. New Complex
+features and promoted Fast features review first; changing reviewed code requires
+another review before Verify can finish.
+
 A Complex feature that shows an interface gets its mockup at Specify when the
 saved mockup preference is enabled. The contract is still open: seeing a screen
 reveals states and flows that prose misses and those belong in the criteria.
@@ -112,6 +116,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,21 +134,87 @@ 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)
+Time:           1h 12m of 2h budget
+```
+
+Work does not run silently for hours. Elapsed time comes from the feature's
+journal and is measured against a per-lane budget (defaults: Fast 30, Quick 60,
+Complex 120 minutes; override with `"budget": { "fast": 45 }` in
+`.empirical/config.json`). Past the budget, or when Review sends work back to
+Implement, the card stops at a checkpoint and offers explicit exits: ship as
+is with a draft PR, split, defer non-blocking findings, continue with a new
+budget (`empirical_checkpoint`), or stop.
+
+`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.
+
+## Keep features small
+
+When a Complex feature grows past 6 acceptance criteria or 2 capabilities, the
+status card asks whether to split it into independently shippable slices, each
+with its own draft PR, or keep it as one with a recorded reason. The question
+never blocks a gate; tune or disable it with `sizeGuardrail` in
+`.empirical/config.json`.
+
 ## Run tests when you need them
 
 Fast and Complex iteration do not automatically run tests after edits. Ask for a
 run when ready:
 
-- “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.
+- “Run the changed tests” or “run the affected tests” runs the `iterate`
+  verification profile once: only commands configured with `testFiles: "changed"`.
+- “Now run it”, “run everything” or “ready to close” uses the `final` profile,
+  which runs only the Verify selection: one cheapest configured command per
+  Verify check, never full CI.
 - “Keep iterating; skip tests for now” leaves verification pending.
 
 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.
+no phase, iteration or consolidation runs tests by itself. The full suite runs
+once, at the very end. By default (`promotion.fullCi` omitted, which means
+`auto`) it runs as pull-request CI when the repository's GitHub delivery pins
+required checks and no SDD-67 local-forcing reason applies; Deliver merges
+nothing until those checks pass on the exact head. Otherwise it runs locally,
+only after you approve that exact run (command, revision and estimate), and one
+exact full-CI receipt recorded at Integrate also serves Deliver when nothing
+changed. Agents never approve on your behalf; Publish's explicit publication
+authorization is the approval for its own full-CI run. An explicit
+`promotion.fullCi: "local"` always runs locally, and `"remote-checks"` keeps
+remote proof without a local fallback.
+A focused command can declare a `scope` of paths so an edit elsewhere does not
+invalidate its Verify receipt; global configuration (policy, manifests,
+lockfiles, workflows, argv-named files) always invalidates it, and full CI and
+promotion proof are never scoped. See [docs/mcp.md](docs/mcp.md).
 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.
@@ -147,6 +222,24 @@ Explicit final verification or promotion requests include their required checks,
 and CI/release gates remain enforced. An explicit no-tests request takes
 precedence over execution and leaves any conflicting gate pending.
 
+Long local runs can go to the background: `empirical_qa_start` runs the command
+in a snapshot worktree of the committed `HEAD` and returns a job id immediately,
+`empirical_qa_status` reports progress and the receipt, and `empirical_qa_cancel`
+stops it. See [MCP usage](docs/mcp.md#background-verification-jobs).
+When CI is not available, agents ask before a full regression at the end, run
+it in the background with your approval, keep working, and rerun only the
+failing test files if it fails.
+
+### Ship early
+
+Agents open a draft pull request at the first coherent commit of feature work
+and push every commit. Commits and pushes never wait on tests: the change's
+tests run in the background while work continues, and heavy or full-suite runs
+belong to pull-request CI unless you approve a local run. This authority covers
+only the agent's own feature branch and draft pull requests; agents never merge,
+never push to protected or target branches, and never force push. Without a
+remote or `gh`, the agent says so and continues locally.
+
 Existing repositories need their managed skills refreshed with `empirical-init`
 and a restarted agent session after upgrading to receive this guidance.
 
@@ -198,6 +291,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
@@ -248,6 +349,12 @@ 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).
 
+Long-lived branches drift. The status card flags a branch that is behind its
+target with predicted conflicts or by more than 10 commits, and your agent syncs
+at each checkpoint: Empirical merges the target only when it is clean and
+conflict-free, never rebases or force-pushes, and names conflicting files right
+away. See [staying current](docs/mcp.md#stay-current-with-the-target-branch).
+
 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