empirical-sdd 0.22.0 → 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,20 +1,20 @@
 # Empirical SDD
 
 Agent-neutral, resumable spec-driven development with deterministic routing,
-immutable evidence, safe cross-worktree integration, and six agent-native
-skills. Empirical installs across 73 global agent targets and provides verified
-guidance for Codex, Claude Code, Cursor, Gemini CLI, Windsurf, and MCP clients.
+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 0.22 is alpha software and intentionally introduces the breaking
-> Schema 5 protocol. One checkout selects at most one active feature; linked Git
-> worktrees isolate 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 CLI. Node.js 22 or newer is required. |
-| `empirical install` | Choose coding agents and install all six skills. |
+| `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. |
 
@@ -29,31 +29,29 @@ cancel, while automation must use `empirical uninstall --yes` (optionally with
 history, evidence, and repository MCP/agent configuration are always preserved;
 unmanaged or unsafe global paths are also preserved and reported.
 
-### Difference from the previous command surface
+### Upgrade from 0.22
 
-| Previous 0.21 behavior | Updated behavior |
+| Previous 0.22 behavior | Updated 0.23 behavior |
 | --- | --- |
-| Public lifecycle exposed Install and Update only. | Public lifecycle also exposes `empirical uninstall`. |
-| Removing six agent skills required manual per-agent cleanup. | One command scans every unique catalog root and removes only marker-owned skills. |
-| Selection metadata had to be found manually. | Valid Empirical-owned metadata is removed; invalid or user-owned metadata is preserved. |
-| Package removal was a separate manual npm command. | Confirmed uninstall runs exact `npm uninstall -g empirical-sdd` last. |
-| Project preservation was implicit. | Help, confirmation, human output, and JSON explicitly report preserved project state. |
+| 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
 
 These are coding-agent skills, not public shell workflow commands.
 
-| Skill | Purpose |
+| Entry | Purpose |
 | --- | --- |
-| `empirical <request>` | Initialize, resume, route, and run in normal mode. |
-| `empirical-init` | Initialize or repair repository context without starting work. |
-| `empirical-spec <request>` | Draft a concrete Complex contract and stop for approval. |
-| `empirical-socratic <idea>` | Run the durable five-pass interview, then draft the contract. |
-| `empirical-loop` | Resume the selected feature from its exact current revision. |
-| `empirical-yolo <request>` | Run autonomously to an explicit safe completion ceiling. |
+| `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 invocation examples include `$empirical` in Codex, `/empirical` in
-Claude Code, and `@empirical` in Windsurf. Reload an agent after installation.
+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
 
@@ -69,8 +67,8 @@ 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, Verify, Review,
-and independent Integrate. An authorized delivery may continue through two
+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.
 
@@ -80,16 +78,48 @@ 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, knowledge, evidence, worktree, and delivery
-state without mutating the repository.
+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 0.22 operation.
+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.
@@ -114,7 +144,8 @@ The package exposes only `.`, `./protocol`, `./mcp`, and `./integrations`.
 
 [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)
+[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;
 }, {