empirical-sdd 0.33.0 → 0.34.0

package/CHANGELOG.md

@@ -8,6 +8,75 @@ under the alpha rules in [docs/versioning.md](docs/versioning.md).
 
 ## [Unreleased]
 
+## [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 +543,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.33.0...HEAD
+[Unreleased]: https://github.com/goempirical/empirical-sdd/compare/v0.34.0...HEAD
+[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,69 @@ 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`.
 
+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.
+
 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 tests for this feature” selects the smallest relevant configured checks.
+- “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.
+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 +166,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 +220,30 @@ 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.
+
+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/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;