empirical-sdd 0.20.0 → 0.20.2

package/README.md

@@ -1,315 +1,261 @@
 # Empirical SDD
 
-Empirical is a small, agent-neutral spec-driven development engine for Codex,
-Claude Code, Cursor, Gemini CLI, Windsurf, and any MCP client. It turns a coding
-request into an exact, resumable workflow with committed contracts, evidence,
-review, living capability specs, and safe Git worktree isolation.
+Empirical is an agent-neutral, spec-driven development engine for Codex, Claude
+Code, Cursor, Gemini CLI, Windsurf, and MCP clients. It turns a coding request
+into a durable contract, exact workflow revisions, verification evidence,
+review, and living capability specifications.
 
-Empirical `0.20.0` is an alpha release. It deliberately uses one active feature
-per checkout and real Git worktrees for parallel work.
+Empirical `0.20.2` is an alpha release. It supports one active feature per
+checkout and uses real Git worktrees for isolated parallel work.
 
 ## Install
 
 ```bash
 npm install -g empirical-sdd
-cd your-repository
-empirical init
+empirical install
 ```
 
-The first interactive init asks once for:
+`empirical install` opens a multi-select list of supported coding agents.
+Detected agents and existing managed installations are selected by default.
+Use Up/Down, Space, `a`, and Enter to submit the exact selection.
 
-- whether Empirical should offer isolation when another feature is active;
-- the detected or edited default Git base;
-- the sibling path template, defaulting to `../{repo}-{feature}`;
-- the branch pattern, defaulting to `{type}/{feature}`;
-- whether Complex features require evidence-backed decision records.
+Every selected agent receives five global skills:
 
-Press Enter to accept each safe default. Edit the answers later with:
+| Intent | Skill |
+| --- | --- |
+| Automatic setup, routing, and execution | `empirical` |
+| Initialize or repair this repository only | `empirical-init` |
+| Draft a concrete specification and stop | `empirical-spec` |
+| Run the five-pass interview, draft, and stop | `empirical-socratic` |
+| Resume the approved specification to completion | `empirical-loop` |
 
-```bash
-empirical config
-```
+The installer removes only marker-owned Empirical skills from agents you
+deselect. It preserves unmanaged files, directories, symbolic links, and
+unrelated settings. It works from any directory and does not create repository
+state or launch an agent.
 
-Automation never waits for terminal input:
+For unattended installation:
 
 ```bash
-empirical init --defaults
-empirical init --isolation ask --base main \
-  --worktree-path '../{repo}-{feature}' \
-  --branch-pattern '{type}/{feature}' \
-  --decisions required
-```
+# Exact selection; repeat -a/--agent
+empirical install --agent codex --agent cursor
 
-## The normal UX
+# Every supported agent
+empirical install --all
 
-You can use Empirical directly in your agent after project or global skills are
-installed. The agent chooses the lane, executes the returned action, completes
-the exact revision, and consumes the next action until Done.
-
-```text
-vague idea ──> five Socratic passes ──> approved refined contract
-                                             │
-concrete request ─────────────────────────────┤
-                                             ▼
-                           Fast or Complex exact workflow
-                                             │
-                           another feature already active?
-                              │ no                  │ yes
-                              ▼                     ▼
-                         work here         preview Git worktree
-                                                    │
-                                           explicit approval
-                                                    │
-                                                    ▼
-                                       create, start, show resume
+# Detected agents plus existing managed installations
+empirical install --yes
 ```
 
-Fast is only for explicit, tiny, localized, reversible, low-risk non-UI work.
-Everything else—including UI, architecture, public APIs, security, migrations,
-and cross-cutting changes—uses Complex.
+Restart or reload the selected agent after installation. Native invocations are:
 
-## Socratic discovery is back
+| Agent | Automatic | Init | Spec | Socratic | Loop |
+| --- | --- | --- | --- | --- | --- |
+| Codex | `$empirical` | `$empirical-init` | `$empirical-spec` | `$empirical-socratic` | `$empirical-loop` |
+| Claude Code | `/empirical` | `/empirical-init` | `/empirical-spec` | `/empirical-socratic` | `/empirical-loop` |
+| Cursor Agent | `empirical` | `empirical-init` | `empirical-spec` | `empirical-socratic` | `empirical-loop` |
+| Gemini CLI | `empirical` | `empirical-init` | `empirical-spec` | `empirical-socratic` | `empirical-loop` |
+| Windsurf Cascade | `@empirical` | `@empirical-init` | `@empirical-spec` | `@empirical-socratic` | `@empirical-loop` |
 
-For a genuinely vague idea:
+To upgrade the package and refresh every selected skill:
 
 ```bash
-empirical explore "Build a cooperative browser puzzle with time loops"
+empirical update
 ```
 
-Empirical asks one question at a time across five passes:
+`empirical install` and `empirical update` are the entire public terminal CLI.
+Init, Spec, Socratic, and Loop are coding-agent skills, not shell commands.
+Internal workflow operations remain available to installed skills through MCP
+and a private compatibility transport.
 
-1. primary user and observed problem;
-2. smallest observable outcome;
-3. boundaries, constraints, and explicit non-goals;
-4. failures and solution-changing risks;
-5. concrete verification.
+## Choose automatic or deliberate mode
 
-It saves every answer under `.empirical/discoveries/`, shows the full refined
-contract, and waits for explicit approval before starting Fast or Complex.
+Both modes use the same state machine, artifacts, evidence gates, and safety
+rules.
 
-Use packet mode for an already-running agent:
-
-```bash
-empirical explore "<idea>" --no-interview
-empirical explore "<idea>" --json
+```text
+Automatic
+  empirical request
+      └─ setup/repair → resume or discover/route → execute → verify → review → done
+
+Deliberate SDD
+  empirical-init
+      └─ empirical-spec request ──────────────┐
+      └─ empirical-socratic idea → interview ├─ review contract → empirical-loop → done
+                                             ┘
 ```
 
-`--agent codex` is an optional human terminal entrypoint after approval. Agent
-skills continue in their current runtime and never launch another AI.
-
-## Simple feature demo
+Use `empirical` when you want the agent to choose the right path and keep going.
+Use the explicit skills when you want to inspect the specification before any
+implementation begins. Fast and Complex are internal profiles; users do not
+need separate skills for them.
 
-Request:
+## Initialize a repository
 
-```bash
-empirical fast "Add a health command that prints ok"
-```
+Inside the repository, invoke the Init skill in your coding agent. For Codex:
 
-The response is the implementation action and exact completion command:
+> `$empirical-init`
 
-```text
-Empirical · step 1/1
+Init inspects manifests, documentation, source, tests, Git state, existing
+Empirical configuration, and living capabilities. It asks one focused question
+at a time only when the answer changes:
 
-add-a-health-command-that-prints-ok: implement (fast, waiting, revision 1)
+- whether unrelated active work should use a sibling Git worktree;
+- the base branch, worktree path, and branch pattern;
+- whether Complex decisions require reviewable decision records.
 
-Fast lane: implement the generated observable criterion, run one focused test,
-review the diff, and complete revision 1.
+It then creates or repairs `.empirical/`, installs repository MCP bridges,
+refreshes compact context, confirms `setupComplete: true`, and stops. It does not
+create a feature or specification.
 
-Complete with: empirical complete --revision 1 --outcome passed \
-  --summary "Added the health command" \
-  --test "health command test passed" \
-  --review "focused diff reviewed"
-```
+You can skip explicit Init and invoke `$empirical` directly; the automatic skill
+performs the same preflight first. A partial schema-4 repository—such as one with
+`setupComplete: false` or missing `.empirical/context/`—is repaired rather than
+mistaken for a complete setup. Marker-owned old project-local skills are removed
+so they cannot shadow global updates; unmanaged collisions are preserved and
+reported.
 
-Fast writes everything below one feature directory:
+Initialization creates:
 
 ```text
-.empirical/specs/add-a-health-command-that-prints-ok/
-├── spec.md
-├── state.json
-├── events/
-└── evidence.json                  # after evidenced completion
-```
-
-## Complex feature demo
-
-Request:
-
-```bash
-empirical complex "Add team invitations with expiration and revocation"
+.empirical/context/
+├── manifest.json
+├── index.md
+├── overview.md
+├── architecture.md
+├── commands.md
+└── conventions.md
 ```
 
-The seven gates are:
+The deterministic manifest contains bounded path, size, and digest metadata,
+not source contents. Dependencies, build output, ignored files, secret-like
+paths, credentials, binaries, and large files are excluded. There are no
+embeddings, hosted RAG services, or vector databases.
 
-1. Specify: observable criteria, scope, risks, verification, capability deltas.
-2. Design: architecture plus accepted decisions.
-3. Plan: executable implementation sequence.
-4. Implement: code and focused checks.
-5. Verify: criterion-by-criterion evidence; real browser and screenshot for UI.
-6. Review: diff, criteria, and accepted-decision alignment.
-7. Archive: apply reviewed deltas to living capability specifications.
+## Explicit Spec: a small concrete feature
 
-Each completion response is already the next action:
+In Codex:
 
-```bash
-empirical complete --revision 1 --outcome passed --summary "Specified invitations"
-# edit design.md and decisions.md
-empirical complete --revision 2 --outcome passed --summary "Designed invitation ownership"
-# continue with the exact commands returned by Empirical
-```
-
-A material decision is concise and reviewable:
+> `$empirical-spec` Add a keyboard shortcut that opens the existing command
+> palette with Cmd/Ctrl+K. Do not change the palette design.
 
-```markdown
-## D-001: Own invitation expiry in the domain service
+Spec ensures the repository is initialized, starts internal Complex Specify,
+inspects the relevant code and living capabilities, and writes observable
+acceptance criteria, scope, non-goals, risks, verification, and capability
+deltas. It then stops. No implementation code is written and the pending
+Specify revision is not completed.
 
-Status: Accepted
+Review the files under `.empirical/specs/<feature>/`. When the contract is right:
 
-### Evidence
-- Existing invitation writes already pass through the domain service.
+> `$empirical-loop`
 
-### Options
-1. Expire in the request handler.
-2. Expire in the domain service.
+That invocation is explicit approval to complete Specify and continue through
+Design, Plan, Implement, Verify, Review, and Archive.
 
-### Chosen approach
-Use the domain service so API and background jobs share one rule.
+## Explicit Socratic: a complex or vague feature
 
-### Trade-offs and risks
-The service gains time semantics; inject a clock for deterministic tests.
+In Codex:
 
-### Verification
-Test API and background expiry against the same injected clock.
-```
-
-This is a visible decision trail, not persisted private chain-of-thought. Raw
-prompts, scratchpads, tokens, credentials, and secrets do not belong there.
+> `$empirical-socratic` Build a team notification center that works well across
+> desktop and mobile.
 
-## Understand the next action
+Socratic asks one question at a time across the original five passes:
 
-```bash
-empirical explain
-empirical explain --json
-```
+1. primary user and observed problem;
+2. smallest observable outcome;
+3. boundaries, constraints, and explicit non-goals;
+4. failure behavior and solution-changing risks;
+5. concrete verification.
 
-Explain is read-only and reports:
+It reflects each answer, asks only a material follow-up, and saves progress after
+every pass. After all five, it displays one exact refined request. Rejecting or
+saving creates no workflow state. Approving binds that exact request to Complex
+Specify, drafts the specification and capability deltas, and stops again for
+contract review.
 
-- current feature, phase, status, and revision;
-- why the state machine selected the next action;
-- required and missing context;
-- whether the gate says proceed or stop;
-- accepted decision summaries.
+After reviewing the draft:
 
-MCP clients use `empirical_explain` and receive the same structured fields.
+> `$empirical-loop`
 
-## Parallel work uses Git worktrees
+## Automatic demos
 
-If a different feature is active, Fast or Complex returns a proposal instead of
-overwriting state:
+For a tiny, localized, reversible, low-risk, non-UI change:
 
-```text
-Empirical needs an isolated Git worktree (approval required)
-Active feature: add-team-invitations
-New request: Fix password reset expiry
-Workflow/type: complex/fix
-Base: main
-Base commit: <approved-base-commit>
-Branch: fix/fix-password-reset-expiry
-Path: /projects/my-app-fix-password-reset-expiry
-Command: git worktree add -b fix/fix-password-reset-expiry ... <approved-base-commit>
-No mutation has occurred.
-```
+> `$empirical` Add a health command that prints `ok`.
 
-After approval Empirical:
+Empirical routes internally to Fast, implements the criterion, runs focused
+tests, reviews the diff, and completes the exact revision.
 
-1. requires the current checkout to be clean, including untracked files;
-2. resolves the selected base;
-3. rejects existing branches, paths, and registered checkout collisions;
-4. runs `git worktree add -b <branch> <path> <approved-base-commit>` without
-   `--force`, so the approved base cannot move before creation;
-5. initializes or migrates the new checkout;
-6. starts the exact request there;
-7. returns path, branch, base, feature, revision, and resume command.
+For a substantial feature:
 
-Human terminal form:
+> `$empirical` Add team invitations with expiration, revocation, and audit
+> history. Existing members must keep access during rollout.
 
-```bash
-empirical worktree create "Fix password reset expiry" \
-  --workflow complex --type fix
-```
+Empirical routes to Complex and drives seven gates:
 
-Use `--yes` only after reviewing the rendered proposal in automation. Empirical
-never stashes, commits, moves local changes, forces Git, deletes worktrees, or
-deletes branches.
+1. Specify observable behavior and capability deltas.
+2. Design the solution and record accepted evidence-backed decisions.
+3. Plan an executable implementation sequence.
+4. Implement the approved contract.
+5. Verify every criterion; UI work requires real-browser and screenshot evidence.
+6. Review the diff against criteria and decisions.
+7. Archive reviewed deltas into living capability specifications.
 
-## Agent skills and commands
+For a genuinely vague automatic request, Empirical uses the same durable
+five-pass Socratic operation before routing. A concrete request does not pay that
+discovery cost.
 
-Project-local integrations are installed by `empirical init` and refreshed by:
+## Resume safely with Loop
 
-```bash
-empirical integrate
-```
+`empirical-loop` takes no new feature request. It asks Empirical for the selected
+action, completes its exact revision with required artifacts and evidence, and
+continues until Done, Blocked, or Awaiting Human.
 
-Install the five Empirical skills globally for every supported agent:
+If no feature is selected, Loop creates nothing and points to Automatic, Spec,
+or Socratic. Attached text never replaces active work. If another feature is
+already active, starting unrelated work returns a read-only worktree proposal
+instead of overwriting state.
 
-```bash
-empirical integrate --global
-```
+## Worktrees and agent handoff
 
-The skills are `empirical`, `empirical-explore`, `empirical-fast`,
-`empirical-complex`, and `empirical-loop`. Native invocation depends on the
-agent: `$empirical` in Codex, `/empirical` in Claude Code, and the corresponding
-skill/command discovery UX in Cursor, Gemini CLI, and Windsurf.
+An isolation proposal shows its base and immutable base commit, branch, sibling
+path, exact Git argument array, and approval token. Empirical waits for explicit
+approval, requires a clean source checkout, revalidates every field, rejects
+collisions, and creates the linked checkout without force. It never stashes,
+commits, moves local changes, deletes worktrees, or deletes branches.
 
-Generated guidance explicitly tells the current agent to conduct the Socratic
-passes, show a worktree proposal, wait for approval, execute creation, maintain
-Complex decisions, and consume exact revisions. It never starts another agent.
+After a Complex specification passes, Automatic or Loop offers:
 
-## CLI reference
+- Continue here.
+- Save for later.
+- Continue in a detected agent.
 
-```text
-empirical init [--defaults|--interactive]
-empirical config [--defaults|--interactive]
-empirical adopt
-empirical explore "<problem>" [--interactive] [--agent codex|none]
-empirical fast "<request>"
-empirical complex "<request>"
-empirical worktree create "<request>" [--workflow fast|complex]
-empirical loop
-empirical explain
-empirical status
-empirical complete --revision N --outcome <outcome> --summary "..."
-empirical verify
-empirical retry --revision N
-empirical archive --revision N
-empirical capabilities [name]
-empirical policy
-empirical integrate [--global]
-empirical doctor
-empirical migrate
-empirical mcp
-empirical update [--check]
-```
+Detection and Save launch nothing. Before external handoff, Empirical displays
+the agent, its prompt/workspace capability, cwd, and exact argv; it authorizes
+only the unchanged option after explicit approval.
 
-Global options are `--root <path>` and `--json`. Legacy Quick can only be
-resumed from migrated state; it is never selected for new work.
+Active selection lives in checkout-local Git metadata. Portable feature
+contracts remain under `.empirical/specs/`, so a linked checkout does not inherit
+a blocked feature owned by another checkout.
 
-## MCP tools
+## Internal automation API
 
-The server runs over stdio with `empirical mcp` and exposes:
+The TypeScript API and MCP server expose the primitives used by installed
+skills. They are not additional public terminal commands.
 
-- discovery/setup: `empirical_explore`, `empirical_init`, `empirical_adopt`,
-  `empirical_configure`;
-- workflow: `empirical_fast`, `empirical_complex`, `empirical_loop`,
-  `empirical_next`, `empirical_complete`, `empirical_retry`,
-  `empirical_verify`, `empirical_archive`;
-- isolation: `empirical_worktree_propose`, `empirical_worktree_create`;
-- understanding: `empirical_explain`, `empirical_status`, `empirical_doctor`;
-- project context: `empirical_capabilities`, `empirical_policy`,
-  `empirical_integrate`, `empirical_migrate`.
+- Setup/context: `empirical_init`, `empirical_adopt`, `empirical_configure`,
+  `empirical_context`.
+- Discovery/routing: `empirical_explore`, `empirical_discovery`,
+  `empirical_fast`, `empirical_complex`.
+- Workflow: `empirical_loop`, `empirical_next`, `empirical_complete`,
+  `empirical_retry`, `empirical_verify`, `empirical_archive`.
+- Handoff/isolation: `empirical_handoff`, `empirical_worktree_propose`,
+  `empirical_worktree_create`.
+- Understanding: `empirical_explain`, `empirical_status`,
+  `empirical_capabilities`, `empirical_policy`, `empirical_doctor`.
 
-Only `empirical_worktree_create` performs the approved Git mutation. Proposal
-and Explain tools are annotated read-only.
+Generated skills use MCP first and `empirical __internal` only as a private
+fallback when MCP is unavailable. Humans should not invoke that namespace.
 
 ## Committed layout
 
@@ -317,6 +263,7 @@ and Explain tools are annotated read-only.
 .empirical/
 ├── config.json
 ├── policy.json
+├── context/
 ├── capabilities/<capability>/spec.md
 ├── discoveries/<discovery>/
 │   ├── interview.json
@@ -333,34 +280,32 @@ and Explain tools are annotated read-only.
     └── evidence.json
 ```
 
-Feature state and journals are branch-local. Capability specs, configuration,
-and policy are project-wide committed contracts.
-
-## Migration and the 0.20 reset
+Specifications, decisions, journals, context, capabilities, configuration, and
+policy are durable, reviewable state. Decision records contain evidence,
+options, the chosen approach, trade-offs, risks, and verification—not private
+chain-of-thought, prompts, tokens, credentials, or scratchpads.
 
-Schema-1, schema-2, and schema-3 default root state migrates idempotently into
-the matching feature directory. Terminal root state does not reserve the
-checkout. Historical named parallel-state data is deliberately unsupported and
-is not merged; inspect it with the older package before upgrading if needed.
+## Migration and development
 
-The public alpha version is reset to `0.20.0`. The old `2.0.0`, `2.2.0`,
-`2.3.0`, and `2.3.1` package versions are intentionally removed after 0.20.0 is
-published and verified. Removed npm version numbers cannot be reused.
+Running `empirical install` again migrates global integrations. Repository Init
+removes only marker-owned old local skills and repairs partial setup. Both
+operations converge, preserve unmanaged content, and keep schema-4 projects and
+discovery records readable.
 
-See [migration details](docs/migration-v1.md), the [protocol](docs/protocol.md),
-the [MCP guide](docs/mcp.md), and the [OpenSpec comparison](docs/openspec-comparison.md).
+Schema-1 through schema-3 root state migrates idempotently into feature-local
+state. Empirical v1 `ai/` adoption remains available through agent automation.
 
-## Development
+See [migration details](docs/migration-v1.md), the
+[architecture](docs/architecture.md), [MCP guide](docs/mcp.md),
+[security model](docs/security.md), [demos](docs/demo.md), and
+[OpenSpec comparison](docs/openspec-comparison.md).
 
 ```bash
 bun install
-bun run check
-bun test
-bun run test:dist
-npm pack --dry-run
+bun run ci
 ```
 
-Empirical targets Node.js 20+ at runtime. Bun is used only for development,
-tests, and building the published JavaScript package.
+Empirical targets Node.js 20+ at runtime. Bun is used for development, tests,
+and building the published JavaScript package.
 
 License: MIT.

package/dist/agents.d.ts

@@ -0,0 +1,27 @@
+import type { AgentHandoffOption, AgentIntegrationId, AgentLaunchCapability, DetectedAgent } from "./types.js";
+export interface SupportedAgentDefinition {
+    id: AgentIntegrationId;
+    agent: string;
+    executables: string[];
+    skillSegments: string[];
+    invocation: string;
+    reload: string;
+    capability: AgentLaunchCapability;
+}
+export declare const SUPPORTED_AGENTS: SupportedAgentDefinition[];
+export interface AgentDetectionOptions {
+    homeRoot?: string;
+    pathValue?: string;
+    includeAll?: boolean;
+    includeConfigured?: boolean;
+}
+export declare function detectSupportedAgents(options?: AgentDetectionOptions): Promise<DetectedAgent[]>;
+export declare function agentDefinition(id: AgentIntegrationId): SupportedAgentDefinition;
+export declare function buildHandoffOption(input: {
+    root: string;
+    feature: string;
+    specification: string;
+    specDigest: string;
+    agent: DetectedAgent;
+}): AgentHandoffOption;
+export declare function handoffToken(value: unknown): string;

package/dist/checkouts.d.ts

@@ -0,0 +1,8 @@
+export interface CheckoutSelection {
+    feature: string | null;
+    linked: boolean;
+    selectionPath: string | null;
+    claimedElsewhere: Set<string>;
+}
+export declare function readCheckoutSelection(rootInput: string): Promise<CheckoutSelection>;
+export declare function writeCheckoutSelection(rootInput: string, feature: string | null): Promise<void>;