empirical-sdd 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -8,14 +8,53 @@ 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
 
-- Nothing yet.
+- 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
 
-This version is prepared in the repository but is not published by the version
-change alone.
+Published through GitHub Actions trusted publishing with npm provenance.
 
 ### Changed
 
@@ -70,7 +109,8 @@ change alone.
 
 - Prepared and released package version `0.20.2`.
 
-[Unreleased]: https://github.com/goempirical/empirical-sdd/compare/v0.23.0...HEAD
+[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

package/README.md

@@ -1,151 +1,102 @@
 # Empirical SDD
 
-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.
+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.23 is alpha software. Schema 5 remains unchanged. 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 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. |
-
-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`.
 
-### Upgrade from 0.22
-
-| 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. |
+## 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
 
-| Entry | Purpose |
-| --- | --- |
-| `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.
+[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) · [Versioning](docs/versioning.md) ·
-[Changelog](CHANGELOG.md)
+The package exports `.`, `./protocol`, `./mcp`, and `./integrations`.
 
 ## License