empirical-sdd 0.34.0 → 0.35.0

package/CHANGELOG.md

@@ -8,6 +8,138 @@ under the alpha rules in [docs/versioning.md](docs/versioning.md).
 
 ## [Unreleased]
 
+## [0.35.0] - 2026-09-15
+
+### Added
+
+- Approved mockup files and the chosen direction now accompany Implement, with
+  instructions to preserve the approved layout and styles. Missing or unreadable
+  mockup files do not introduce a new implementation gate.
+
+- Added default discovery of ignored, untracked local environment files for
+  worktrees through `isolation.localFiles` (`discover`, `include`, `exclude`;
+  defaults `**/.env` and `**/.env.*` excluding `.env.example`, `.env.sample` and
+  `.env.template`, never under `node_modules`, `.git` or `.empirical`). Proposals
+  list every explicit and discovered path and every refusal; approving the
+  proposal approves exactly those copies. Discovery is bounded to 200 candidates
+  and 1 MiB per file, with refusals reported by path and reason.
+- Added `empirical_worktree_prepare` (library `prepareWorktree`, internal CLI
+  `worktree-prepare`) to preview and apply local file copies for worktrees
+  created by host tools, `git worktree add`, delegation or transfer.
+- Added `localFiles: { copied, skippedExisting, missingOptional, unapproved, refused }`
+  to worktree handoffs and prepare results, plus local file lines in proposal,
+  handoff, configuration and Init text.
+
+- Fast features iterate through `empirical_iterate` from Implement or
+  implemented Done without promotion or test runs: the lifecycle iteration
+  counter increments, the journal keeps every `Iterate:` event, and `id`
+  addresses a Done feature. Fast consolidate requires explicit promotion.
+- Fast starts create `decisions.md`; status and explain list Accepted Fast
+  decisions and report format issues as non-blocking `decisionWarnings`.
+- QA planning, QA execution and evidence execution accept an explicit
+  `verificationProfile`: `iterate` runs only `testFiles: "changed"` commands and
+  `final` runs the configured final scope (Fast `final` excludes full CI and stays
+  unverified). Action packets report `verificationProfiles`.
+- `empirical_yolo` accepts `profile`; explicit Fast defaults to and is limited to
+  the `implemented` ceiling.
+- Routes report `matchedFloors`.
+- Policy v2 accepts optional `promotion.fullCi` (`local` or `remote-checks`);
+  policy and configure results report a read-only `effective` value. Empirical
+  versions before this release reject a policy that sets `promotion`.
+- Opt-in `remote-checks` promotion proof: passing, app-pinned GitHub required
+  check runs for the exact pushed commit create an immutable `remote-checks`
+  receipt through an injectable checks reader. Integrate accepts it only for an
+  already pushed commit; Deliver may push and open the source pull request and
+  returns `promotion-proof-required` until it passes, binding proof per head
+  before any merge; Publish rejects it. Remote proof is refused when the branch
+  changes policy, package scripts, workflows, composite actions, `scripts/**`,
+  lockfiles, `.gitmodules`, symlinks or gitlinks, or when target workflows use
+  unpinned `uses:` references. Repositories whose protection uses legacy
+  unpinned status contexts or ruleset entries without an app pin must pin the app,
+  and must SHA-pin workflow and action references, before `remote-checks` can pass.
+
+### Changed
+
+- Init now declares `.empirical/** -text` in `.gitattributes` to preserve
+  digest-bound journal bytes across Git checkouts. Existing project-specific
+  Empirical attribute rules are preserved.
+- Lock waiters renew their wait budget as ownership changes, while retaining a
+  bounded overall wait, so healthy contention does not report a stuck repository.
+
+- Existing configurations now discover local environment files by default
+  without being rewritten, so worktree proposals and their approval tokens change
+  when ignored environment files exist; pass the proposal's `localFiles`
+  unchanged to `empirical_worktree_create`. Set `discover: false` to opt out.
+- Worktrees created outside Empirical can now receive local files through
+  prepare, and generated agent guidance routes local file provisioning through
+  the Empirical proposal and prepare operation.
+
+- Deliver accepts the full-CI receipt Integrate recorded for an identical
+  candidate instead of requiring a second local full-CI run; `reuseReceiptId` and
+  Publish keep exact revision matching. The delivered source pull request head is
+  bound to the proven commit before review, ready or merge.
+- A failed Fast completion now blocks the same Fast feature with `retry` and
+  explicit `promote` as recovery paths instead of promoting it to Complex, and
+  `promote` accepts that block.
+- An explicit Fast request is no longer promoted by integration or delivery
+  wording; sensitive, migration and publication signals still promote it.
+- Integrate, Deliver and Publish refuse Fast features with `PROMOTION_REQUIRED`
+  guidance; only explicit `empirical_promote` changes a Fast feature to Complex.
+- `receiptIds` is optional on `empirical_integrate` and `empirical_deliver`.
+- Generated skills and phase instructions explain lane choice, Fast iteration,
+  explicit promotion, the phrase-to-profile mapping, one-request test
+  authorization, carry-over and remote-checks, and no longer state that
+  consolidation authorizes tests.
+
+- Fast action packets no longer list every living capability specification;
+  agents open a capability only when the change touches it. Complex and
+  promoted features keep the full list.
+- Verification commands can opt into `testFiles: "changed"` to run only the
+  test files matching changed files, failing with `NO_CHANGED_TESTS` rather than
+  falling back to the whole suite.
+- Independent integration validation no longer re-runs verification commands
+  whose declared checks a full-CI command in the same directory already covers,
+  unless the feature changes the policy or package scripts, and reports which
+  commands executed or were covered.
+
+### Fixed
+
+- Windows worktree creation and recovery recognize canonical directory identity
+  across separator, case and short-path spellings. Recovery errors identify the
+  mismatched check and explain when a newer runtime is needed to load the base.
+- Invalid mockup approval feedback now shows the approval document shape, even
+  during Verify, instead of the fidelity-report shape.
+
+- `empirical update` and `empirical uninstall` work on Windows again. Node refuses
+  to spawn `.cmd` wrappers without a shell (CVE-2024-27980), so npm and the
+  PATH-visible CLI now run through `cmd.exe` by quoted absolute path and the
+  npm-installed CLI runs through Node, including prefixes containing spaces (SDD-66).
+
+### Migration
+
+- Update the package and installed global skills with `empirical update`, restart
+  the coding agent/MCP host, invoke `empirical-init` in each existing repository
+  to refresh managed instructions and local skills, then reload affected sessions.
+- Existing configurations discover ignored, untracked `.env` and `.env.*` files
+  by default. Review the paths in worktree proposals; set
+  `isolation.localFiles.discover` to `false` to retain explicit-only copying.
+  Existing `isolation.copyFiles` entries remain required. Use worktree prepare
+  to provision worktrees created by another tool without overwriting files.
+- Fast failures now stay Fast. Retry or explicitly promote the same feature
+  when stronger verification or integration is needed. To iterate on an existing
+  Complex implementation, request iterative development and explicitly request
+  final verification when ready; iteration alone does not authorize tests.
+- `promotion.fullCi` remains `local` by default. Opt into `remote-checks` only
+  after configuring app-pinned required checks and SHA-pinned workflow/action
+  references. Upgrade every participating agent before adding this policy field;
+  older versions reject it. Publication still requires local proof.
+- When refreshing an existing repository, review and commit the `.gitattributes`
+  journal rule added by Init. An existing rule for `.empirical` is left untouched;
+  ensure it preserves journal bytes across worktrees. Keep existing journal and
+  receipt files intact.
+- Schema 5 and existing specifications, journals, tracker bindings and receipts
+  are retained. Do not delete workflow state to upgrade.
+
 ## [0.34.0] - 2026-09-14
 
 ### Added
@@ -543,7 +675,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.34.0...HEAD
+[Unreleased]: https://github.com/goempirical/empirical-sdd/compare/v0.35.0...HEAD
+[0.35.0]: https://github.com/goempirical/empirical-sdd/compare/v0.34.0...v0.35.0
 [0.34.0]: https://github.com/goempirical/empirical-sdd/compare/v0.33.0...v0.34.0
 [0.33.0]: https://github.com/goempirical/empirical-sdd/compare/v0.32.0...v0.33.0
 [0.32.0]: https://github.com/goempirical/empirical-sdd/compare/v0.31.0...v0.32.0

package/README.md

@@ -108,10 +108,19 @@ integration are different claims, and Empirical reports only the highest level
 actually proven: `implemented`, `verified`, `integrated`, `delivered`, or
 `published`.
 
-Fast trades verification confidence for less waiting and process. If a quick
-feature needs the full workflow, promote that same spec to Complex; its history
-and original identity are preserved. Historical completed Fast records retain
-the evidence and completion level they originally earned.
+Choose Fast for small, self-contained changes. Work that builds on an existing
+foundation and will be integrated belongs in Complex iterative
+(`empirical_complex` with `iterative: true`): adjust with `empirical_iterate`
+without test runs, then say "ready to close" to run final verification once.
+
+Fast trades verification confidence for less waiting and process. A follow-up
+adjustment to the same Fast feature uses `empirical_iterate`, from Implement or
+after Done: no promotion, no test run, and the journal keeps every adjustment.
+A failed Fast completion blocks in place for `retry` or explicit promotion.
+Promotion is always explicit: Fast consolidate, Integrate and Deliver require
+`empirical_promote`, which continues the same spec through Complex Specify and
+preserves its history and identity. Historical completed Fast records retain the
+evidence and completion level they originally earned.
 
 Delivery is never implied. Empirical does not infer permission to merge a pull
 request, bypass protection, create a release, or publish a package.
@@ -121,11 +130,16 @@ request, bypass protection, create a release, or publish a package.
 Fast and Complex iteration do not automatically run tests after edits. Ask for a
 run when ready:
 
-- “Run tests for this feature” selects the smallest relevant configured checks.
+- “Run the changed tests” or “run the affected tests” uses the `iterate`
+  verification profile: only commands configured with `testFiles: "changed"`.
+- “Now run it”, “run everything” or “ready to close” uses the `final` profile.
 - “Keep iterating; skip tests for now” leaves verification pending.
-- “Run the full suite” explicitly requests broader verification.
 
-One test request does not enable automatic reruns after subsequent changes.
+One test request does not enable automatic reruns after subsequent changes, and
+no phase, iteration or consolidation runs tests by itself. One exact full-CI
+receipt recorded at Integrate also serves Deliver when nothing changed, and a
+repository can opt into `promotion.fullCi: "remote-checks"` so passing GitHub
+required checks on the exact pushed commit stand in for local full CI.
 If no focused command is configured, the agent reports the gap instead of
 silently running the entire suite. Complex still requires real evidence before
 claiming verified completion; Fast can finish implemented and unverified.
@@ -225,6 +239,15 @@ their original checkout. Transferring an unfinished spec to another worktree
 requires its exact source revision and matching destination history; it keeps
 the original capability bases and receipts.
 
+Ignored local environment files such as `apps/api/.env` or `apps/web/.env.local`
+are discovered by default, listed by path in each worktree proposal, and copied
+into the new worktree when you approve it. Copies are independent, never
+overwrite existing files and never enter Git. Set `isolation.localFiles.discover`
+to `false` to opt out, or adjust its `include` and `exclude` patterns. For a
+worktree created by another tool or `git worktree add`, your agent previews and
+applies Empirical prepare to fill in the missing files.
+See [local environment files](docs/protocol.md#local-environment-files-in-worktrees).
+
 Ask your agent for the read-only overview to see specs, owners, branches,
 profiles, progress and verification status together. Unrelated malformed records
 appear as local diagnostics without selecting or deleting any spec. Independent

package/dist/changed-tests.d.ts

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