empirical-sdd 0.20.4 → 0.23.0

package/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to Empirical SDD are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+under the alpha rules in [docs/versioning.md](docs/versioning.md).
+
+## [Unreleased]
+
+### Changed
+
+- Nothing yet.
+
+## [0.23.0] - 2026-08-11
+
+This version is prepared in the repository but is not published by the version
+change alone.
+
+### Changed
+
+- Replaced the globally automatic `empirical` skill with the explicit,
+  setup-only `empirical-init` bootstrap.
+- Made initialized repositories route ordinary change prompts automatically
+  through marker-owned local instructions and skills; read-only prompts remain
+  outside the workflow.
+- Added explicit-only invocation metadata where supported and retained all
+  existing workflow, evidence, tracker, integration, and publication gates.
+
+### Added
+
+- Added this changelog and a documented alpha Semantic Versioning and release
+  policy.
+
+### Migration
+
+- After upgrading from `0.22.x`, invoke `empirical-init` once in each existing
+  repository to install local automatic activation. Repair preserves Schema 5
+  configuration, context, feature history, and evidence unless setup values are
+  explicitly changed.
+
+## [0.22.0] - 2026-08-03
+
+### Added
+
+- Introduced the Schema 5 protocol, strict Policy v2 evidence, resumable
+  journals, capability claims, independent integration, protected delivery,
+  explicit publication, and a single consolidated global workflow skill.
+
+## [0.20.4] - 2026-07-31
+
+### Fixed
+
+- Completed the `0.20.4` release and its recorded release evidence.
+
+## [0.20.3] - 2026-07-31
+
+### Fixed
+
+- Made CI and release fixtures portable across supported operating systems,
+  including Windows executable-extension casing.
+
+### Changed
+
+- Simplified installation guidance and clarified README commands.
+
+## [0.20.2] - 2026-07-30
+
+### Changed
+
+- Prepared and released package version `0.20.2`.
+
+[Unreleased]: https://github.com/goempirical/empirical-sdd/compare/v0.23.0...HEAD
+[0.23.0]: https://github.com/goempirical/empirical-sdd/compare/v0.22.0...v0.23.0
+[0.22.0]: https://github.com/goempirical/empirical-sdd/compare/v0.20.4...v0.22.0
+[0.20.4]: https://github.com/goempirical/empirical-sdd/compare/v0.20.3...v0.20.4
+[0.20.3]: https://github.com/goempirical/empirical-sdd/compare/v0.20.2...v0.20.3
+[0.20.2]: https://github.com/goempirical/empirical-sdd/releases/tag/v0.20.2

package/README.md

@@ -1,75 +1,151 @@
 # Empirical SDD
 
-Agent-neutral, resumable spec-driven development for 73 global agent-skill
-targets, with verified runtime guidance for Codex, Claude Code, Cursor, Gemini
-CLI, Windsurf, and MCP clients.
+Agent-neutral, resumable spec-driven development with deterministic routing,
+immutable evidence, safe cross-worktree integration, optional external ticket
+mirrors, and an explicit bootstrap that makes normal repository work automatic.
+Empirical installs across 73 global agent targets and provides verified guidance
+for Codex, Claude Code, Cursor, Gemini CLI, Windsurf, and MCP clients.
 
-> Empirical is alpha software. It supports one active feature per checkout and
-> uses Git worktrees for isolated parallel work.
+> Empirical 0.23 is alpha software. Schema 5 remains unchanged. One checkout
+> selects at most one active feature; linked Git worktrees isolate parallel work.
 
 ## Install
 
 | Command | Purpose |
 | --- | --- |
-| `npm install -g empirical-sdd` | Install the Empirical CLI globally. |
-| `empirical install` | Choose coding agents and install their five Empirical skills. |
-| `empirical update` | Upgrade Empirical and refresh the installed skills. |
+| `npm install -g empirical-sdd` | Install the CLI. Node.js 22 or newer is required. |
+| `empirical install` | Choose coding agents and install the single explicit `empirical-init` skill. |
+| `empirical update` | Upgrade Empirical and reconcile installed skills. |
+| `empirical uninstall` | Remove managed global skills, owned selection metadata, then the global package. |
 
-Restart or reload each selected agent after installation.
+The installer uses a pinned local catalog. It remembers exact target IDs,
+deduplicates shared skill roots, and performs no runtime network fetch or `npx`
+execution. Automation can use repeatable `--agent`/`-a`, `--all`, `--yes`, and
+`--json` options.
 
-`empirical install` uses a searchable, scrollable local catalog pinned to a
-reviewed `vercel-labs/skills` release. It remembers the exact selected ids,
-deduplicates shared skill roots, and never runs `npx` or uses the network. Type
-to search by agent name, id, or destination; use arrows, Space, Enter, Escape,
-or Ctrl-C. Automation can use repeatable `--agent`/`-a`, `--all`, `--yes`, and
-`--json`; the legacy ids `claude` and `gemini` remain aliases.
+Uninstall is fail-closed: interactive use shows the exact scope and defaults to
+cancel, while automation must use `empirical uninstall --yes` (optionally with
+`--json`). It removes only marker-owned global artifacts. Project `.empirical`
+history, evidence, and repository MCP/agent configuration are always preserved;
+unmanaged or unsafe global paths are also preserved and reported.
 
-## Use
+### Upgrade from 0.22
 
-These are coding-agent skills, not shell commands:
+| Previous 0.22 behavior | Updated 0.23 behavior |
+| --- | --- |
+| A global `empirical` skill watched every prompt. | The global skill is explicit `empirical-init` and is limited to setup or repair. |
+| Normal work required naming `empirical`. | Initialized repositories route ordinary change prompts automatically. |
+| Project workflow guidance was removed. | Short marker-owned project dispatchers and detailed local skills are restored. |
+| Existing repositories needed no integration repair. | Invoke `empirical-init` once per existing checkout; configuration and history are preserved. |
+
+## Skills
 
-| 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 | `empirical` | `empirical-init` | `empirical-spec` | `empirical-socratic` | `empirical-loop` |
-| Gemini CLI | `empirical` | `empirical-init` | `empirical-spec` | `empirical-socratic` | `empirical-loop` |
-| Windsurf | `@empirical` | `@empirical-init` | `@empirical-spec` | `@empirical-socratic` | `@empirical-loop` |
+These are coding-agent skills, not public shell workflow commands.
 
-| Skill | Purpose |
+| Entry | Purpose |
 | --- | --- |
-| `empirical <request>` | Initialize if needed, select the workflow, and run the request through review. |
-| `empirical-init` | Initialize or repair repository setup without starting work. |
-| `empirical-spec <request>` | Draft a concrete specification and stop for approval. |
-| `empirical-socratic <idea>` | Refine an idea through a five-pass interview, then draft a specification. |
-| `empirical-loop` | Resume the active approved specification and drive it to completion. |
-
-On first `empirical-init`, the agent shows the complete recommended setup before
-writing anything. Apply the defaults, customize Verification, Parallel work,
-and Decisions one section at a time, or cancel. Repair shows current values and
-keeps them unless edited. Verification independently stores acceptance-test,
-UI-browser, UI-screenshot, and code-review gates; all default on. Turning off
-criterion evidence makes its UI sub-policies inactive without erasing them, and
-does not turn off code review.
-
-Broad catalog membership means an agent can read global `SKILL.md` files. MCP
-bridging and executable handoff remain separately verified capabilities; the
-installer does not infer either one.
+| `empirical-init` | Explicitly initialize a new repository or repair an existing repository's context and integrations. |
+| Ordinary change prompt | Automatically route, optionally interview or mirror, resume, and complete work in a valid initialized repository. |
+
+Native bootstrap examples include `$empirical-init` in Codex,
+`/empirical-init` in Claude Code, and `@empirical-init` in Windsurf. Reload an
+agent after installation. Once initialized, ask normally—for example, “fix the
+pagination bug.” Read-only questions remain outside Empirical, and a repository
+without valid completed `.empirical/config.json` is never enrolled implicitly.
+
+## Trust model
+
+Requests are classified into deterministic risk floors: contract-neutral,
+behavioral, sensitive, migration, integration, delivery, or publication. Fast
+is available only to contract-neutral work. Every higher floor uses Complex;
+wording a risky request as “quick” cannot demote it.
+
+Normal mode asks only when a material product choice or permission is missing.
+YOLO persists bounded standing authorization and asks only for genuine blockers
+before its authorized ceiling. It never bypasses host permissions or branch
+protection, force-writes Git, extracts credentials, deletes real worktrees or
+branches, replaces immutable releases, or infers publication.
+
+Fast is contract-neutral and ends at verified. Complex records an impact
+manifest and proceeds through Specify, Design, Plan, Implement, conditional
+Context refinement, Verify, Review, and independent Integrate. An authorized delivery may continue through two
+protected GitHub PRs. Publication is always a separate explicit operation bound
+to an exact version, commit, tag, and dist-tag.
+
+Evidence is not a caller-supplied boolean. Empirical either executes a Policy v2
+command or collects a content-addressed artifact, then writes an immutable
+receipt tied to criteria, source state, and provenance. Completion reports only
+the highest proven level: implemented, verified, integrated, delivered, or
+published.
+
+## External ticket tracking
+
+External tracking is optional and local-only by default. When enabled through
+the repository-local workflow, one selected feature can create or attach one ticket in
+Linear, GitHub Issues + Projects v2, or Jira Cloud. Empirical's hash-chained
+local journal remains authoritative; the ticket is a one-way projection of the
+committed phase, normalized status, revision, completion level, and blocker
+summary.
+
+The provider-neutral Tracker Policy v1 lives at `.empirical/tracker.json`.
+It selects exactly one provider, names its board/project and normalized status
+IDs, and stores only credential environment-variable names. Credential values
+are injected into the Empirical runtime by the host, must carry access to the
+configured provider target, and are never written to `.empirical/`. Bindings
+pin the exact provider target; changing that target fails closed until explicit
+replacement, while a same-target status-map change forces the committed
+revision to be projected again. Bindings and durable retry operations live
+under each feature's `tracker/` directory.
+
+After every local journal commit, the skill asks the granular MCP tracker layer
+to converge the remote ticket. A provider outage never rolls back or blocks
+local SDD progress. Status and action packets expose `local-only`, `synced`,
+`pending`, or `failed` tracker health. Ordinary retries resume the exact durable
+pending operation. If ticket creation has an ambiguous outcome, Empirical does
+not issue another create automatically: it first performs bounded reconciliation
+using the persisted marker. If no unique match is found, attachment is required
+unless the caller explicitly confirms a new attempt that may create a duplicate.
+See [MCP usage](docs/mcp.md#external-ticket-mirror) for the strict provider
+schemas, runtime permissions, state mapping, and recovery details.
+
+## Repository model
+
+Schema 5 stores strict Policy v2 configuration, Manifest v2 knowledge
+fingerprints, impact manifests, receipts, Git-common-dir capability claims, and
+hash-chained per-feature journals. Terminal journals compact transactionally to
+a verified snapshot boundary. `empirical_doctor` diagnoses schema, journal,
+lock, claim, toolchain, policy, tracker configuration, credential presence,
+knowledge, evidence, worktree, and delivery state without mutating the
+repository. It still validates dormant feature binding and pending files when
+tracking is local-only or disabled.
+
+Schema 4 repositories migrate atomically on the first mutating Schema-5 operation.
+The migration validates a complete candidate tree before promotion and retains
+a recovery receipt. Earlier schemas must first be upgraded to Schema 4 with the
+version that created them.
 
 ## Development
 
-Requires Node.js 20+ and Bun.
+Development requires Node.js 22+ and Bun. CI covers Node 22, 24, and 26.
 
 | Command | Purpose |
 | --- | --- |
-| `bun install` | Install development dependencies. |
-| `bun run ci` | Run type checking, tests, build smoke tests, and package tests. |
+| `bun install` | Install dependencies. |
+| `bun run check` | Type-check the source. |
+| `bun run test` | Run the test suite. |
+| `bun run test:coverage` | Enforce aggregate and per-module coverage gates. |
+| `bun run test:dist` | Build and smoke-test the packaged CLI and MCP server. |
+| `bun run test:package` | Install and import the generated npm package. |
+| `bun run ci` | Run every required gate. |
+
+The package exposes only `.`, `./protocol`, `./mcp`, and `./integrations`.
 
 ## Documentation
 
-[Architecture](docs/architecture.md) · [Demos](docs/demo.md) ·
-[MCP](docs/mcp.md) · [Security](docs/security.md) ·
-[Migration](docs/migration-v1.md)
+[Protocol](docs/protocol.md) · [Architecture](docs/architecture.md) ·
+[MCP](docs/mcp.md) · [Demo](docs/demo.md) · [Security](docs/security.md) ·
+[Migration](docs/migration-v1.md) · [Versioning](docs/versioning.md) ·
+[Changelog](CHANGELOG.md)
 
 ## License
 

package/dist/agent-catalog.d.ts

@@ -64,7 +64,7 @@ export declare const AGENT_SKILL_TARGETS: readonly [{
     readonly aliases: readonly ["claude"];
     readonly executables: readonly ["claude"];
     readonly invocation: "/empirical";
-    readonly reload: "Restart Claude Code so it reloads the global Empirical skills, then invoke the desired /empirical skill.";
+    readonly reload: "Restart Claude Code so it reloads the global Empirical Init skill, then invoke /empirical-init for repository setup or repair.";
     readonly projectMcp: true;
     readonly handoff: true;
 }, {
@@ -104,7 +104,7 @@ export declare const AGENT_SKILL_TARGETS: readonly [{
     readonly detectPaths: readonly [".codex"];
     readonly executables: readonly ["codex"];
     readonly invocation: "$empirical";
-    readonly reload: "Restart or reopen Codex so it rescans user skills, then invoke any installed $empirical skill.";
+    readonly reload: "Restart or reopen Codex so it rescans user skills, then invoke $empirical-init for repository setup or repair.";
     readonly projectMcp: true;
     readonly handoff: true;
 }, {
@@ -371,7 +371,7 @@ export declare const AGENT_SKILL_TARGETS: readonly [{
     readonly detectPaths: readonly [".codeium/windsurf"];
     readonly executables: readonly ["windsurf"];
     readonly invocation: "@empirical";
-    readonly reload: "Reload Windsurf or start a new Cascade session, then invoke the desired @empirical skill.";
+    readonly reload: "Reload Windsurf or start a new Cascade session, then invoke @empirical-init for repository setup or repair.";
     readonly projectMcp: true;
     readonly handoff: true;
 }, {