empirical-sdd 0.36.0 → 0.37.0

package/CHANGELOG.md

@@ -8,10 +8,324 @@ 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
@@ -808,7 +1122,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.36.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

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.
@@ -142,8 +146,17 @@ 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
@@ -166,21 +179,42 @@ 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.
@@ -188,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.
 
@@ -297,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

package/dist/changed-tests.d.ts

@@ -1,3 +1,4 @@
+export declare const TEST_FILE: RegExp;
 /** Paths changed on this branch since `base`, plus uncommitted and untracked work. */
 export declare function changedPaths(root: string, base: string | null): string[];
 /**
@@ -16,3 +17,17 @@ export declare function resolveCommandArgv(root: string, command: {
     cwd: string;
     testFiles?: "changed" | undefined;
 }, base: string | null): string[];
+/**
+ * The argv for an explicit rerun of named test files, such as a failed job's
+ * failing files. Only `testFiles: "changed"` commands accept file arguments,
+ * and every file must be a tracked, existing test file of this repository.
+ */
+export declare function resolveExplicitTestArgv(root: string, command: {
+    id: string;
+    argv: readonly string[];
+    cwd: string;
+    testFiles?: "changed" | undefined;
+}, files: readonly unknown[]): {
+    argv: string[];
+    files: string[];
+};