empirical-sdd 0.22.0 → 0.24.0

package/CHANGELOG.md

@@ -0,0 +1,118 @@
+# 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]
+
+## [0.24.0] - 2026-08-18
+
+### Added
+
+- Added guided Linear, GitHub Projects, and Jira discovery/preview during Init,
+  provider-neutral semantic state suggestions, and strict equivalent MCP and
+  non-interactive setup surfaces.
+- Added Tracker Policy v2 ticket behavior (`off`, `manual`, `ensure`), progress
+  visibility, automatic one-ticket reconciliation, idempotent milestone
+  comments, and receipt-approved evidence uploads or commit-pinned links.
+- Added a packaged, runnable integration-repair demo that reproduces a
+  completed repository with missing activation artifacts and proves the
+  before, repair, and verified-after states without touching user data.
+
+### Changed
+
+- Tracker synchronization now commits local state first, preserves user-authored
+  Linear descriptions, and resumes transition/comment/artifact effects from a
+  durable acknowledgement ledger.
+- Existing Tracker Policy v1 repositories remain manual/legacy compatible and
+  repair preserves tracker bytes unless explicitly changed or disabled.
+- Simplified the README around installation, everyday use, safety, and links to
+  the detailed project documentation.
+
+### Fixed
+
+- Made Doctor validate both behavioral and non-behavioral integration receipts
+  without falsely treating a valid null capability claim as corruption.
+- Made the shell-free GitHub delivery and publication runner reuse the host's
+  existing `gh` configuration locator without persisting credentials or secret
+  values in policy or runtime receipts.
+- Made sanitized HTTPS pushes use the host's authenticated `gh` store through
+  an ephemeral, push-only Git helper configuration without inheriting `HOME`,
+  exporting tokens, or changing persistent Git configuration.
+- Made Doctor report missing, drifted, or unsafe required project integrations
+  whenever Schema 5 setup is complete, instead of incorrectly reporting the
+  repository as activation-ready.
+- Kept Doctor read-only and made its remediation point to explicit
+  `empirical-init`; repair recreates missing artifacts and updates
+  Empirical-owned content while preserving unmanaged conflicts for manual
+  resolution.
+- Completed the lower stem of the terminal brand mark so its outline renders as
+  a closed cross.
+
+## [0.23.0] - 2026-08-11
+
+Published through GitHub Actions trusted publishing with npm provenance.
+
+### 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.24.0...HEAD
+[0.24.0]: https://github.com/goempirical/empirical-sdd/compare/v0.23.0...v0.24.0
+[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,120 +1,102 @@
 # 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.
+Agent-neutral, resumable spec-driven development for coding agents. Empirical
+turns an ordinary change request into a deterministic workflow with durable
+state, reviewable evidence, and safe Git integration.
 
-> 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.24 is alpha software. It requires Node.js 22 or newer.
 
 ## Install
 
+```sh
+npm install -g empirical-sdd
+empirical install
+```
+
+Choose the agents you use, reload them, then run `empirical-init` once in each
+repository. After initialization, ask for work normally—for example, “fix the
+pagination bug.” Empirical activates automatically for change requests while
+read-only questions stay outside the workflow.
+
+Codex uses `$empirical-init`, Claude Code uses `/empirical-init`, and Windsurf
+uses `@empirical-init`. Existing 0.22 repositories should invoke it once after
+upgrading; configuration, history, and evidence are preserved.
+
+Doctor verifies that completed repositories still have every required local
+instruction, skill, and MCP bridge. If it reports missing or drifted project
+integrations, invoke `empirical-init` explicitly to reconcile Empirical-owned
+artifacts; unmanaged or unsafe conflicts are preserved and remain visible.
+
+## What it provides
+
+- Deterministic Fast or Complex routing based on the request's risk.
+- Resumable Specify, Design, Plan, Implement, Verify, Review, and Integrate phases.
+- Immutable evidence tied to criteria, source state, and provenance.
+- Isolated parallel work through linked Git worktrees.
+- Guided Linear, GitHub Issues + Projects, or Jira ticket mirrors with automatic
+  binding, milestone comments, and safe evidence projection.
+- Explicit, guarded delivery and npm publication boundaries.
+
+Completion is reported only at the highest proven level: implemented,
+verified, integrated, delivered, or published.
+
+## Tracker setup
+
+`empirical-init` always shows a Tracker section. Keep Local-only to make no
+provider requests, or select Linear, GitHub Projects, or Jira. Empirical reads
+credential values only from the environment-variable names you provide,
+discovers accessible targets and workflow states, proposes all seven semantic
+mappings, and shows the complete secret-free policy before saving. Ambiguous
+state suggestions require an explicit choice; simple boards may intentionally
+reuse one provider state for several phases. Repair preserves an existing
+tracker policy unless you explicitly change or disable it.
+
+Tracker Policy v2 supports `off`, `manual`, and `ensure` ticket behavior plus
+blockers/final, phase-milestone, or every-revision progress comments. `ensure`
+validates a referenced ticket, reconciles the feature marker, and creates only
+when neither identifies one unique ticket. Local workflow state commits first;
+provider outages leave exact retry state and never rewind local work. Comments
+preserve user-authored descriptions, and receipt-approved evidence is uploaded
+or linked only after repository containment, media, size, and digest checks.
+Existing Tracker Policy v1 files remain valid with manual binding and legacy
+projection until deliberately upgraded.
+
+## CLI
+
 | 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 update` | Upgrade Empirical and reconcile installed skills. |
-| `empirical uninstall` | Remove managed global skills, owned selection metadata, then the global package. |
-
-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` | Select agents and install or repair Empirical integrations. |
+| `empirical update` | Upgrade the package and refresh installed integrations. |
+| `empirical uninstall` | Remove Empirical-managed global files and the package. |
+| `empirical --help` | Show commands and automation options. |
 
-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.
+`empirical uninstall` preserves project `.empirical` history, evidence, and
+repository configuration. Automation must confirm removal with `--yes`.
 
-### Difference from the previous command surface
-
-| Previous 0.21 behavior | Updated 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. |
+## Safety
 
-## Skills
+Empirical asks when a material product choice or permission is missing. It does
+not bypass host permissions or branch protection, extract credentials,
+force-write Git history, delete real worktrees, or infer publication. Releases
+remain bound to an exact version, commit, tag, and npm dist-tag.
 
-These are coding-agent skills, not public shell workflow commands.
+## Documentation
 
-| Skill | 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. |
-
-Native invocation examples include `$empirical` in Codex, `/empirical` in
-Claude Code, and `@empirical` in Windsurf. Reload an agent after installation.
-
-## 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, 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.
-
-## 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.
-
-Schema 4 repositories migrate atomically on the first mutating 0.22 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.
+[Protocol](docs/protocol.md) · [Architecture](docs/architecture.md) ·
+[MCP and tracking](docs/mcp.md) · [Demo](docs/demo.md) ·
+[Security](docs/security.md) · [Migration](docs/migration-v1.md) ·
+[Versioning](docs/versioning.md) · [Changelog](CHANGELOG.md)
 
 ## Development
 
 Development requires Node.js 22+ and Bun. CI covers Node 22, 24, and 26.
 
-| Command | Purpose |
-| --- | --- |
-| `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`.
+```sh
+bun install
+bun run ci
+```
 
-## Documentation
-
-[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)
+The package exports `.`, `./protocol`, `./mcp`, and `./integrations`.
 
 ## 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;
 }, {