empirical-sdd 0.20.1 → 0.20.2

package/README.md

@@ -1,12 +1,12 @@
 # Empirical SDD
 
-Empirical is an agent-neutral spec-driven development engine for Codex, Claude
+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 an exact, resumable workflow with observable contracts, evidence, review,
-living capability specifications, and safe Git worktree isolation.
+into a durable contract, exact workflow revisions, verification evidence,
+review, and living capability specifications.
 
-Empirical `0.20.1` is an alpha release. It 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
 
@@ -15,17 +15,26 @@ npm install -g empirical-sdd
 empirical install
 ```
 
-`empirical install` opens a multi-select list of every supported coding agent.
-Detected agents and existing Empirical installations are labeled and selected
-by default. Use the arrow keys to move, Space to select, `a` to toggle all, and
-Enter to install.
+`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.
 
-The selection is exact: Empirical installs one global entrypoint in every
-selected agent and removes only Empirical-managed entrypoints from agents you
-deselect. Unmanaged files are never overwritten or deleted. The installer works
-from any directory and neither creates repository state nor launches an agent.
+Every selected agent receives five global skills:
 
-For scripts and unattended setup, choose agents explicitly:
+| 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` |
+
+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.
+
+For unattended installation:
 
 ```bash
 # Exact selection; repeat -a/--agent
@@ -38,66 +47,75 @@ empirical install --all
 empirical install --yes
 ```
 
-Then open your repository in a coding agent and use its one Empirical entrypoint:
+Restart or reload the selected agent after installation. Native invocations are:
 
-| Agent | Invocation |
-| --- | --- |
-| Codex | `$empirical` |
-| Claude Code | `/empirical` |
-| Cursor Agent chat | `empirical` |
-| Gemini CLI | `empirical` |
-| Windsurf Cascade | `@empirical` |
+| 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` |
 
-To upgrade both the package and installed entrypoints:
+To upgrade the package and refresh every selected skill:
 
 ```bash
 empirical update
 ```
 
 `empirical install` and `empirical update` are the entire public terminal CLI.
-Repository setup and feature work happen inside the current coding agent; old
-terminal verbs such as `init`, `config`, `explore`, `fast`, `complex`, and
-`loop` are rejected.
-
-## One entrypoint owns the workflow
+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.
 
-Ask the installed Empirical entrypoint for repository work in ordinary language.
-It deterministically:
+## Choose automatic or deliberate mode
 
-1. initializes an uninitialized repository in the current runtime;
-2. builds or refreshes compact repository knowledge;
-3. resumes non-terminal work already owned by this checkout;
-4. uses the original five-pass Socratic interview only when the request is
-   genuinely vague;
-5. routes an approved, concrete request internally to Fast or Complex;
-6. executes exact revisions through evidence, review, and living-spec archive;
-7. offers an explicit agent handoff only after a Complex specification exists.
+Both modes use the same state machine, artifacts, evidence gates, and safety
+rules.
 
 ```text
-one Empirical invocation
-          │
-          ├─ repository uninitialized ──> first-run setup + compact context
-          ├─ active feature found ──────> resume exact revision
-          └─ new request
-                ├─ genuinely vague ────> five Socratic passes ──> approval
-                └─ concrete ───────────> internal Fast / Complex routing
-                                                         │
-                                      approved Complex spec exists?
-                                                         │
-                                  Continue here | Save | Continue in agent
+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
+                                             ┘
 ```
 
-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.
+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.
+
+## Initialize a repository
+
+Inside the repository, invoke the Init skill in your coding agent. For Codex:
+
+> `$empirical-init`
+
+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:
 
-## First use and repository knowledge
+- 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.
 
-On first use, the agent initializes `.empirical/`. It applies safe defaults or
-asks only questions that materially change Git isolation or Complex decision
-policy. It does not install project-local workflow skills.
+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.
 
-Initialization also creates a compact, committed context set:
+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.
+
+Initialization creates:
 
 ```text
 .empirical/context/
@@ -109,119 +127,135 @@ Initialization also creates a compact, committed context set:
 └── conventions.md
 ```
 
-The deterministic manifest contains bounded path, size, and content-digest
-metadata—not source contents. Dependency trees, build output, ignored files,
-secret-like paths, credentials, binary files, and large files are excluded.
-Topic pages are maintained from repository evidence and are not overwritten by
-a routine refresh. There are no embeddings, hosted services, or vector database.
+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.
+
+## Explicit Spec: a small concrete feature
+
+In Codex:
+
+> `$empirical-spec` Add a keyboard shortcut that opens the existing command
+> palette with Cmd/Ctrl+K. Do not change the palette design.
+
+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.
+
+Review the files under `.empirical/specs/<feature>/`. When the contract is right:
+
+> `$empirical-loop`
+
+That invocation is explicit approval to complete Specify and continue through
+Design, Plan, Implement, Verify, Review, and Archive.
 
-## Socratic discovery
+## Explicit Socratic: a complex or vague feature
 
-For a vague idea such as “make onboarding better,” Empirical asks one question
-at a time across five passes:
+In Codex:
+
+> `$empirical-socratic` Build a team notification center that works well across
+> desktop and mobile.
+
+Socratic asks one question at a time across the original five passes:
 
 1. primary user and observed problem;
 2. smallest observable outcome;
 3. boundaries, constraints, and explicit non-goals;
-4. failures and solution-changing risks;
+4. failure behavior and solution-changing risks;
 5. concrete verification.
 
-It adds only material follow-ups, saves the answers, presents the complete
-refined contract, and waits for explicit approval before creating workflow
-state. A concrete request does not pay this discovery cost.
+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.
 
-## Small feature demo
+After reviewing the draft:
 
-In your coding agent:
-
-> `$empirical` Add a health command that prints `ok`.
+> `$empirical-loop`
 
-Empirical recognizes an explicit, localized, low-risk non-UI change and routes
-it internally to Fast. The agent inspects only relevant files, implements the
-generated observable criterion, runs one focused test, reviews the diff, and
-completes the exact revision. The durable result is:
+## Automatic demos
 
-```text
-.empirical/specs/add-a-health-command-that-prints-ok/
-├── spec.md
-├── state.json
-├── events/
-└── evidence.json
-```
+For a tiny, localized, reversible, low-risk, non-UI change:
 
-You do not choose or invoke a separate Fast command.
+> `$empirical` Add a health command that prints `ok`.
 
-## Complex feature demo
+Empirical routes internally to Fast, implements the criterion, runs focused
+tests, reviews the diff, and completes the exact revision.
 
-In your coding agent:
+For a substantial feature:
 
 > `$empirical` Add team invitations with expiration, revocation, and audit
 > history. Existing members must keep access during rollout.
 
-Empirical routes the request to Complex and drives seven gates:
+Empirical routes to Complex and drives seven gates:
 
-1. Specify observable criteria, scope, risks, verification, and capability
-   deltas.
-2. Design the architecture and record accepted evidence-backed decisions.
+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 evidence.
-6. Review the diff against criteria and accepted decisions.
+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.
 
-After Specify passes, the agent offers:
+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.
 
-- Continue here.
-- Save for later.
-- Continue in a detected agent.
+## Resume safely with Loop
+
+`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.
+
+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.
 
-For an external handoff, Empirical displays the target, whether it accepts a
-prompt or only a workspace, the exact working directory, and exact argument
-array. Detection and Save launch nothing. The command is revalidated and
-authorized only after you explicitly approve that exact option.
+## Worktrees and agent handoff
 
-Decision records store reviewable evidence, options, the selected approach,
-trade-offs, risks, and verification—not private chain-of-thought, prompts,
-scratchpads, tokens, or credentials.
+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.
 
-## Parallel work uses Git worktrees
+After a Complex specification passes, Automatic or Loop offers:
 
-If a different feature is active, the single entrypoint returns a read-only
-worktree proposal instead of overwriting state. It shows the base and immutable
-base commit, branch, sibling path, exact Git argument array, and approval token.
+- Continue here.
+- Save for later.
+- Continue in a detected agent.
 
-After explicit approval Empirical requires a clean source checkout, revalidates
-every field, rejects collisions, creates the linked checkout without force, and
-starts the exact request there. It never stashes, commits, moves local changes,
-deletes worktrees, or deletes branches.
+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.
 
-Active selection lives in checkout-local Git metadata while portable feature
-contracts remain committed under `.empirical/specs/`. A linked checkout therefore
-does not accidentally inherit a blocked feature owned by another checkout.
+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.
 
 ## Internal automation API
 
-The TypeScript API and MCP tools remain available for agent runtimes and
-programmatic integrations. They include setup, context refresh, discovery,
-Fast/Complex routing, resume, exact completion, verification, review, archive,
-status/explain, handoff, capability projection, and worktree proposal/creation.
-They are automation primitives, not additional user-facing terminal commands.
-
-The stdio MCP server exposes these groups:
-
-- setup/context: `empirical_init`, `empirical_adopt`, `empirical_configure`,
-  `empirical_context`;
-- routing/workflow: `empirical_explore`, `empirical_fast`,
-  `empirical_complex`, `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`,
+The TypeScript API and MCP server expose the primitives used by installed
+skills. They are not additional public terminal commands.
+
+- 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 explicitly approved worktree creation mutates Git. Agent handoff returns an
-approval-bound command but never launches it itself.
+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
 
@@ -246,28 +280,26 @@ approval-bound command but never launches it itself.
     └── evidence.json
 ```
 
-Feature contracts, journals, context, capability specs, configuration, and
-policy are committed. The checkout's selected feature is stored in its own Git
-metadata and is not shared across linked worktrees.
+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.
 
-## Migration and the 0.20 alpha
+## Migration and development
 
-Running the installer again is the migration: it removes only marker-owned old
-global and project-local Empirical workflow artifacts, preserves unmanaged
-content and existing runtime configuration, and converges without unnecessary
-second-run changes. Existing schema-4 projects and discovery records remain
-readable.
+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.
 
-Schema-1, schema-2, and schema-3 default root state migrates idempotently into
-the matching feature directory. Historical alternate parallel-state data is
-left untouched and unsupported.
+Schema-1 through schema-3 root state migrates idempotently into feature-local
+state. Empirical v1 `ai/` adoption remains available through agent automation.
 
-See [migration details](docs/migration-v1.md), the [architecture](docs/architecture.md),
-the [MCP guide](docs/mcp.md), the [security model](docs/security.md), and the
+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).
 
-## Development
-
 ```bash
 bun install
 bun run ci