empirical-sdd 0.33.0 → 0.35.0

package/CHANGELOG.md

@@ -8,6 +8,207 @@ 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
+
+- Added opt-in iterative Complex development, same-feature adjustments and
+  explicit contract revisions, followed by user-requested consolidation and QA.
+- Added approved `isolation.copyFiles` preparation for ignored local environment
+  files in new worktrees, with independent copies and interrupted-copy recovery.
+- Added Plane Cloud and self-hosted Plane as first-class external tracker
+  providers, including project/state discovery, host-only Personal Access Token
+  authentication, work-item binding and reconciliation, state synchronization,
+  and idempotent milestone comments through current `work-items` endpoints.
+- Added explicit repository activation as the default. Init offers individual
+  invocation or team-approved automatic routing, with safe opt-out that
+  preserves other instructions and workflow history.
+- Added a read-only overview of preserved specs, worktree ownership and progress,
+  with individual diagnostics for malformed records.
+- Added exact-revision Fast-to-Complex promotion and explicit transfer of an
+  unfinished spec between registered worktrees with matching history.
+- Added a host-native sub-agent bridge for bounded consult, specification and
+  implementation assignments, with shared reservations, launch reconciliation
+  and confirmed cancellation. Writable workers use separate worktrees and specs.
+
+### Fixed
+
+- Doctor accepts direct instruction aliases such as `AGENTS.md -> CLAUDE.md`
+  when the canonical target is a regular sibling file. Repair preserves the
+  symlink, validates the target content, and keeps it from becoming dangling
+  when automatic routing is disabled. Unsafe links remain rejected.
+
+### Changed
+
+- Assisted Fast and Complex iteration runs tests on demand, scoped to the active
+  feature. Unrun verification stays pending, full CI is excluded from ordinary
+  feature-check candidates, and final promotion/release gates remain enforced.
+- Treat absent legacy activation choices as explicit; refresh project skills
+  with `empirical-init` and restart the agent session after upgrading.
+- Explicit Fast supports scoped ordinary behavioral and UI features without
+  mandatory tests, formal review or Context and reports implemented with
+  verification skipped. Explicit Complex and sensitive safety floors retain
+  their full workflow; historical completion records remain readable unchanged.
+- Independent specs use narrower operation locks and addressed capability-claim
+  validation so unrelated delayed work or malformed claims do not block progress.
+- Approved worktree creation starts from its committed base while preserving
+  uncommitted source edits, and remains retryable after interruption.
+- Generated agent guidance explains native delegation, preserved specs,
+  ownership transfer and the distinct Fast and Complex completion guarantees.
+
+### Migration
+
+- Update the package and installed global skills with `empirical update`, then
+  restart the coding agent/MCP host so the new Init skill and tools are loaded.
+- Invoke `empirical-init` explicitly in each existing repository to refresh
+  managed instructions and local skills. A missing `activationMode` now means
+  explicit invocation. Choose **Automatically for this team** during repair only
+  when the affected team agrees; an existing saved choice is preserved.
+- Reload or start a fresh affected agent session after repository repair to
+  discard cached routing instructions. In explicit mode invoke the local
+  `empirical` skill for chosen tasks; ordinary requests remain outside it.
+- New Fast work finishes at implemented with verification skipped. Choose
+  Complex or explicitly promote the same feature when stronger assurance is
+  needed. Previously verified Fast history retains its recorded evidence.
+- Existing tracker configurations remain unchanged. Choose Plane explicitly
+  during setup to adopt it; self-hosted Plane needs the exact API origin in the
+  host-controlled `EMPIRICAL_PLANE_ALLOWED_ORIGINS` allowlist before authentication.
+- Schema 5, specifications, tracker bindings and evidence are retained. Do not
+  delete inactive specs or replace instruction symlinks to upgrade. Safe direct
+  aliases such as `AGENTS.md -> CLAUDE.md` are preserved during repair.
+
 ## [0.33.0] - 2026-09-09
 
 ### Added
@@ -474,7 +675,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.33.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
 [0.31.0]: https://github.com/goempirical/empirical-sdd/compare/v0.30.0...v0.31.0

package/README.md

@@ -6,7 +6,7 @@ Empirical is a repository-native harness for coding agents. The model writes;
 Empirical keeps the contract, progress, proof, and exact next action in Git so
 work can resume across sessions, agents, and machines.
 
-> Empirical 0.31 is alpha software and requires Node.js 22 or newer.
+> Empirical is alpha software and requires Node.js 22 or newer.
 
 **[Open the practical harness guide](https://goempirical.github.io/empirical-sdd/)**
 for the visual walkthrough, diagrams, generated-file explorer, and complete
@@ -37,15 +37,28 @@ workflow. Its zero-build source is [docs/index.html](docs/index.html).
    Fresh-context review still uses an isolated reviewer, but does not count as
    an independent GitHub approval.
 
-3. Ask for the change normally.
+3. Choose when to use Empirical.
+
+   Init recommends **Only when explicitly requested**. Use the local skill for
+   work you want to run through Empirical: `$empirical` in Codex or `/empirical`
+   in Claude Code. Ordinary coding requests stay outside the workflow.
+
+   Choose **Automatically for this team** only when the team agrees to shared
+   routing instructions. You can then ask for a change normally:
 
    ```text
    Add rate limiting to the public API and prove the failure path.
    ```
 
-Repository mutations route automatically. Read-only questions remain
-read-only. If work stops, reopen the same checkout and ask the agent to
-continue—the committed journal provides the resume point.
+Empirical is optional. You can ask to work without it in either mode. Read-only
+questions remain read-only. If Empirical work stops, invoke it again in the same
+checkout to resume from the committed journal.
+
+To change the choice later, ask your agent to configure Empirical activation.
+Switching to explicit removes only Empirical's shared routing blocks and keeps
+workflow history. Repair preserves saved choices. Older repositories without a
+recorded choice become explicit on repair; start a fresh agent session afterward.
+See [optional adoption](docs/optional-adoption.md) for mixed teams and migration.
 
 ## Why use it?
 
@@ -60,32 +73,83 @@ continue—the committed journal provides the resume point.
 
 ## How it works
 
-Empirical routes by risk, not prompt length:
+Choose the amount of process for the work; Empirical retains the safety floor:
 
-- **Fast** handles explicit, tiny, localized, reversible, contract-neutral work
-  with focused proof.
-- **Complex** carries material work through a durable contract, decisions,
-  verification, exact-diff review, and independent integration.
+- **Fast** handles explicitly requested small, scoped, reversible features and
+  fixes, including ordinary behavior and UI changes. It requires no tests,
+  formal review, or Context phase and finishes **implemented; verification
+  skipped**. Its spec and journal remain available.
+- **Complex** carries work through a durable contract, decisions, verification,
+  exact-diff review, and independent integration. Explicit Complex is honored;
+  sensitive and higher-risk work always requires it.
+
+Fast:
+
+```text
+Implement → Done (implemented; verification skipped)
+```
+
+Complex:
 
 ```text
 Specify → Design → Plan → Implement → Context? → Verify → Review → Integrate
 ```
 
-A feature that shows an interface gets its mockup at Specify, while the
-contract is still open, because seeing a screen reveals states and flows that
-prose misses and those belong in the criteria. `empirical mockups` serves the
+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.
+`empirical mockups` serves the
 directions on a local address so a person can click through and choose one;
 Verify then checks what was built against what was approved.
 
-Context runs when repository knowledge needs refinement. Failed verification or
-requested review changes return to implementation. Evidence, review, and
+Complex runs Context when repository knowledge needs refinement. Failed
+verification or requested review changes return to implementation. Evidence, review, and
 integration are different claims, and Empirical reports only the highest level
 actually proven: `implemented`, `verified`, `integrated`, `delivered`, or
 `published`.
 
+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.
 
+## 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.
+- “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.
+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.
+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.
+
+Existing repositories need their managed skills refreshed with `empirical-init`
+and a restarted agent session after upgrading to receive this guidance.
+
 ## What it creates
 
 Init installs the harness; selected work fills in the record:
@@ -116,7 +180,7 @@ Exact host files depend on the integrations selected during install. Init
 creates durable setup and empty work containers; a real mutation creates a
 feature record, and conditional artifacts appear only when their phases run.
 
-Optional tracking mirrors approved milestones to Linear, GitHub, or Jira; the
+Optional tracking mirrors approved milestones to Linear, GitHub, Jira, or Plane; the
 repository remains authoritative. Policy supports
 `enforcement: "best-effort" | "strict"`; strict recovery retries the exact
 feature. Credentials never belong in chat, prompts, repository files, tool
@@ -170,4 +234,39 @@ feature. Explicit new feature starts and repository setup/context repair are not
 blocked by unrelated unclaimed specs. If a feature-required operation needs a
 choice, it lists candidates rather than choosing or moving a spec. An approved
 worktree handoff can be retried with its original input after interruption.
+Creating it from an approved committed base leaves uncommitted source edits in
+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
+work uses separate locks; overlapping feature writers and integration targets
+still serialize safely. Multiple worktrees cost disk space and setup, and
+changes to shared capabilities can still conflict when they integrate.
 See [selection and recovery semantics](docs/protocol.md#shared-specs-and-checkout-selection).
+
+### Sub-agents for specs and implementation
+
+Ask your agent to delegate bounded specification or implementation work. Empirical
+discovers the host's actual native agent capabilities, reserves each assignment
+before spawning, and tracks its identity through interruption or cancellation.
+Writable children use separate registered worktrees and selected specs. Read-only
+consults require a host that enforces read-only access.
+
+Delegation can progress independent specs concurrently, at the cost of additional
+agent usage, worktrees and integration work. Host support varies: installation
+alone does not prove that spawning, lookup, observation and cancellation are
+available. Worker completion never substitutes for workflow evidence. Fast workers
+remain unverified; Complex workers still pass the full applicable gates.
+See the [native delegation bridge](docs/mcp.md#native-sub-agent-delegation).

package/dist/activation.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+export declare const activationModeSchema: z.ZodEnum<{
+    automatic: "automatic";
+    explicit: "explicit";
+}>;
+export type ActivationMode = z.infer<typeof activationModeSchema>;
+/** Absence is not consent to automatically route a team's work. */
+export declare function resolveActivationMode(value: unknown): ActivationMode;

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

package/dist/checkouts.d.ts

@@ -1,5 +1,9 @@
-/** Serialize checkout ownership across every worktree sharing Git metadata. */
+/** Long operations serialize only their own checkout. */
 export declare function withCheckoutLock<T>(root: string, operation: () => Promise<T>): Promise<T>;
+/** 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;
+}): Promise<T>;
 export interface CheckoutSelection {
     feature: string | null;
     linked: boolean;
@@ -8,6 +12,8 @@ export interface CheckoutSelection {
 }
 export declare function readCheckoutSelection(rootInput: string): Promise<CheckoutSelection>;
 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>;
 /** Read only this checkout's recovery anchor, never sibling selections. */
 export declare function readCheckoutLastFeature(rootInput: string): Promise<{
     git: boolean;