empirical-sdd 0.28.0 → 0.29.0

package/CHANGELOG.md

@@ -8,6 +8,83 @@ under the alpha rules in [docs/versioning.md](docs/versioning.md).
 
 ## [Unreleased]
 
+## [0.29.0] - 2026-08-28
+
+### Added
+
+- Added a disabled-by-default, protected-environment emergency release path with
+  exact administrator, incident, PR, merge, version, integrity, check, expiry,
+  and audit receipts while preserving ordinary exact protected-merge gates.
+- Added public CLI help and README guidance explaining how Empirical routes and
+  advances work, where durable evidence lives, and how to use one consolidated
+  development setup command block.
+- Added configurable pull-request review with a recommended independently
+  authenticated GitHub bot and an explicit fresh-context fallback, one
+  canonical criterion-complete review body, exact base/head diff binding, and
+  guided name-only credential setup.
+- Added a guarded, idempotent `develop` to `main` release pipeline that binds
+  exact protected PR merge provenance and clean release checks to one
+  changelog-backed Git tag, non-draft GitHub Release, and npm trusted
+  publication with provenance.
+- Added deterministic patch, minor, migration, conflict, partial-effect,
+  lost-response, duplicate, and retry fixtures plus an offline release dry run.
+- Added a checked repository release-request shorthand and canonical playbook so
+  `make a new release` prepares every current `develop` change, verifies the
+  candidate, and creates or resumes the two guarded PR stages without granting
+  merge or direct publication authority.
+- Added opt-in Tracker Policy v2 `strict` enforcement so deterministically
+  required work hard-stops before further source or workflow mutation until its
+  exact current revision is bound and synchronized.
+- Added structured tracker mutation gates, exact feature-addressed terminal
+  synchronization, and crash recovery that refuses new work while strict final
+  tracking remains unresolved.
+- Added criterion-complete risk-based QA matrices, anomaly-visible immutable
+  receipts, fresh-context and clean packaged-consumer acceptance, deterministic
+  failure-path coverage, and exact full-CI promotion gates.
+
+### Changed
+
+- Ordinary release publication now supports solo-owned repositories without a
+  mandatory positive review while retaining `CHANGES_REQUESTED` blocking,
+  protected two-parent merge proof, complete CI and Release Gate, immutable
+  conflict refusal, protected npm environment, and trusted OIDC provenance.
+- Made `develop` the ordinary feature/fix and source-evidence integration base;
+  protected `main` now accepts only the validated release PR from `develop`.
+- Superseded the human-created GitHub Release boundary with exact merged-PR
+  authorization while preserving branch protection, immutable conflicts,
+  least-privilege GitHub/OIDC jobs, and token-free npm publication.
+- Generated agent guidance now treats a blocked strict tracker gate as a hard
+  stop with OAuth/host-file, binding, reconciliation, or sync recovery, while
+  best-effort, optional, off, and Tracker Policy v1 behavior remain compatible.
+- Approved worktree creation now resumes its returned action immediately,
+  including across a required host restart, without requesting a second
+  confirmation.
+
+### Fixed
+
+- Normalized GitHub's null and empty post-merge `reviewDecision` forms before
+  complete review-history reduction so later reconciliation matches the earlier
+  solo-owner authorization while effective change requests still block.
+- Made mutually exclusive ordinary/emergency authorizers use explicit
+  predecessor-success conditions so an intentionally skipped sibling cannot
+  transitively skip GitHub, npm, provenance, or verification jobs.
+- Made immutable tag reconciliation create an annotated tag object and exact
+  tag ref through authenticated GitHub APIs instead of Git transport, while
+  retaining observation-led lost-response recovery and conflict refusal.
+- Made Release Gate authentication available only to its exact read-only
+  candidate preflight while preserving `contents: read` and rejecting GitHub,
+  npm, tag, release, push, publish, and dist-tag mutation authority.
+- Made protected delivery keep request-changes PRs draft, refuse draft or stale
+  merges, stop after two automatic repair rounds, and accept a valid non-author
+  latest approval when GitHub leaves aggregate `reviewDecision` empty.
+- Made guarded tracker host files decode supported single- and double-quoted
+  dotenv values across LF and CRLF while rejecting malformed or control-bearing
+  assignments before provider access.
+
+### Migration
+
+No migration required.
+
 ## [0.28.0] - 2026-08-24
 
 ### Added
@@ -236,7 +313,8 @@ Published through GitHub Actions trusted publishing with npm provenance.
 
 - Prepared and released package version `0.20.2`.
 
-[Unreleased]: https://github.com/goempirical/empirical-sdd/compare/v0.28.0...HEAD
+[Unreleased]: https://github.com/goempirical/empirical-sdd/compare/v0.29.0...HEAD
+[0.29.0]: https://github.com/goempirical/empirical-sdd/compare/v0.28.0...v0.29.0
 [0.28.0]: https://github.com/goempirical/empirical-sdd/compare/v0.27.0...v0.28.0
 [0.27.0]: https://github.com/goempirical/empirical-sdd/compare/v0.26.1...v0.27.0
 [0.26.1]: https://github.com/goempirical/empirical-sdd/compare/v0.26.0...v0.26.1

package/README.md

@@ -1,153 +1,162 @@
 # Empirical SDD
 
-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.
+Reliable, resumable spec-driven development for coding agents.
 
-> Empirical 0.28 is alpha software. It requires Node.js 22 or newer.
+Empirical turns a normal request such as “fix the pagination bug” into a
+reviewable workflow: define the outcome, implement it, run risk-appropriate
+checks, record exact evidence, review the committed diff, and safely integrate
+the result. State lives in the repository, so work can resume across sessions,
+agents, and machines without relying on chat history.
 
-## Install
+> Empirical 0.29 is alpha software and requires Node.js 22 or newer.
+
+## Quick start
+
+Install Empirical globally, then install its integrations for the coding agents
+you use:
 
 ```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, native skill, and MCP bridge, including nested-directory and
-linked-worktree discovery. It distinguishes missing, stale, malformed, unsafe,
-non-canonical, shadowing, and global-collision states. Invoke `empirical-init`
-explicitly to reconcile Empirical-owned artifacts; unmanaged or unsafe
-conflicts are preserved. Correct files do not prove that an existing host
-session loaded them, so Doctor reports runtime loading as unverified and gives
-the applicable reload or fresh-session step.
-
-## 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.
-- Selectable concise or detailed agent questions and runtime summaries.
-- 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 Interaction and Tracker sections. New recommended
-setup selects **concise** questions: agents ask only when an answer changes
-scope, architecture, authorization, or a safety gate. **Detailed** preserves
-the expanded guidance used by existing Schema-5 repositories. Automation can
-set the same value with `--questions concise|detailed` or the MCP `questions`
-field.
-
-When no tracker choice exists, Init recommends **Track work by type** and
-requires choosing that or **No tracking** before setup can be saved. Track work
-selects Linear, GitHub Projects, or Jira; No tracking persists a provider-free
-choice and makes no provider requests.
-
-Authentication starts with OAuth when a trusted host supplies a connection.
-MCP clients may open that connection only through explicitly negotiated
-URL-mode elicitation; Empirical never requests a credential through a form,
-tool argument, tool result, assistant message, or repository file. The default
-standalone CLI has no hosted OAuth broker and truthfully proceeds to the
-host-only fallback.
-
-> **Never paste credentials into chat.** If OAuth is unavailable, edit the
-> secrets file directly on the host: `${XDG_CONFIG_HOME:-$HOME/.config}/empirical/secrets.env`
-> on POSIX or `%APPDATA%\Empirical\secrets.env` on Windows. Do not put a
-> credential value in a shell command, process argument, tool call, or
-> repository `.env` file.
-
-New setup uses `LINEAR_SECRET_KEY` for Linear, `GITHUB_TOKEN` for GitHub, and
-both `JIRA_EMAIL` and `JIRA_API_TOKEN` for Jira. The file must be a regular,
-non-symbolic-link file outside the repository and, on POSIX, owner-only (for
-example mode `0600`). Runtime precedence is connected host OAuth, then a
-complete injected environment set, then the checked host file. Existing
-Tracker Policy v1/v2 names—including `LINEAR_API_KEY` and custom names—remain
-valid and are never rewritten automatically.
-
-After authentication, Empirical 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 or explicit No
-tracking choice unless you change 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.
-
-An optional strict `ticketRules` matrix refines `ensure` by change type and
-workflow size. The recommended `features+large-fixes` preset is:
-
-| Work | Fast | Quick | Complex |
-| --- | --- | --- | --- |
-| Feature | required | required | required |
-| Fix | optional | required | required |
-| Chore | optional | optional | optional |
-
-Optional work with no referenced ticket stays local without OAuth, provider
-access, ticket creation, or a redundant question. One explicit reference is
-attached; multiple references fail closed. See the [demo](docs/demo.md) for a
-provider-independent new-feature run and [MCP documentation](docs/mcp.md) for
-the complete custom JSON form.
-
-## CLI
+In each repository, initialize Empirical once from your agent:
+
+- Codex: `$empirical-init`
+- Claude Code: `/empirical-init`
+- Windsurf: `@empirical-init`
+
+Reload the agent if prompted. Then ask for work normally:
+
+```text
+Add rate limiting to the public API and prove the failure path.
+```
+
+Empirical activates automatically for repository changes. Read-only questions
+stay read-only and do not start a workflow.
+
+## What Empirical does
+
+- Routes tiny, contract-neutral edits through a fast path and material changes
+  through a complete specification and review path.
+- Persists specifications, decisions, journal events, capability contracts, and
+  evidence under `.empirical/`.
+- Links every acceptance criterion to executable evidence or an explicit human
+  QA step.
+- Selects focused, integration, fault-injection, cross-platform, clean-consumer,
+  and full-CI checks according to risk.
+- Requires fresh-context review of the exact committed diff.
+- Keeps concurrent work isolated with Git worktrees and detects overlapping
+  capability changes before they collide.
+- Optionally mirrors progress to Linear, GitHub Issues + Projects, or Jira.
+- Reports only the highest level actually proven: implemented, verified,
+  integrated, delivered, or published.
+
+## Workflow at a glance
+
+Material work follows a deterministic state machine:
+
+```text
+Specify → Design → Plan → Implement → Context → Verify → Review → Integrate
+```
+
+Each transition has concrete requirements. A test receipt is bound to the
+command, platform, source tree, duration, attempts, and output digests; changing
+the code makes stale evidence unusable. Failed retries, skipped checks, missing
+environments, and unsupported platforms remain visible.
+
+Behavioral changes also update living capability specifications during
+integration. This keeps “what the system does now” derived from reviewed change
+history instead of a separate document that quietly drifts.
+
+Delivery and publication are separate explicit boundaries. Empirical does not
+infer permission to merge pull requests, bypass protection, create releases, or
+publish packages from ordinary implementation work.
+
+## Everyday use
+
+You communicate with your coding agent, not a workflow CLI.
+
+```text
+Where does the current Empirical feature stand?
+Continue the active feature.
+Show me which acceptance criteria still lack evidence.
+Why did this change require the clean package-consumer check?
+```
+
+If a session stops, open the repository in a supported agent and ask it to
+continue. The committed journal and receipts provide the resume point.
+
+Useful lifecycle commands remain intentionally small:
 
 | Command | Purpose |
 | --- | --- |
-| `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. |
+| `empirical install` | Select agents and install or repair integrations. |
+| `empirical update` | Upgrade Empirical and refresh integrations. |
+| `empirical uninstall` | Remove managed global integrations and the package. |
+| `empirical help` | Explain commands, routing, phases, and documentation. |
+
+`empirical uninstall` preserves repository `.empirical` history and
+configuration. Workflow operations are machine-facing and reached by agents
+over MCP; there is no human CLI command for manually advancing a phase.
+
+## Review and tracking
+
+Recommended review uses a separately authenticated GitHub bot so PR approval is
+genuinely non-author. Teams that do not use a second identity can explicitly
+choose fresh-context review; Empirical records that distinction rather than
+mislabeling it as independent forge approval.
+
+Tracking is optional. Setup can select Linear, GitHub Projects, Jira, or no
+tracking. Best-effort tracking never rewinds local work when a provider is
+unavailable. Strict tracking is opt-in and blocks only work whose configured
+ticket rule is required. Policy exposes `enforcement: "best-effort" | "strict"`;
+strict recovery retries the exact feature after credentials or provider state
+recover, without accepting a token through chat.
+
+Credentials never belong in chat, repository files, prompts, tool arguments,
+or evidence. Use connected host OAuth where available. For the guarded host-file
+fallback and complete policy options, see [MCP and tracking](docs/mcp.md) and
+[Security](docs/security.md).
+
+## Safety model
 
-`empirical uninstall` preserves project `.empirical` history, evidence, and
-repository configuration. Automation must confirm removal with `--yes`.
+Empirical fails closed at the boundaries that matter:
 
-## Safety
+- no silent acceptance of stale evidence or changed review heads;
+- no force-writing Git history or deleting real worktrees;
+- no implicit credential discovery from repository files;
+- no claim that mocked tests replace required live acceptance;
+- no automatic merge, branch-protection bypass, or inferred publication;
+- no hiding a failed attempt by reporting a later retry as first-pass green.
 
-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.
+Run `empirical-init` again to repair Empirical-owned repository integrations.
+Doctor-style diagnostics preserve unmanaged conflicts and explain when a reload
+or fresh agent session is still required.
 
 ## Documentation
 
-[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)
+- [Protocol](docs/protocol.md) — state machine, artifacts, and completion rules
+- [Architecture](docs/architecture.md) — trust boundaries and system design
+- [MCP and tracking](docs/mcp.md) — agent operations and tracker configuration
+- [Demo](docs/demo.md) — provider-independent feature walkthrough
+- [Security](docs/security.md) — credentials, isolation, and threat model
+- [Versioning](docs/versioning.md) — alpha compatibility policy
+- [Releasing](docs/releasing.md) — guarded repository release procedure
+- [Changelog](CHANGELOG.md) — shipped behavior and migrations
 
 ## Development
 
-Development requires Node.js 22+ and Bun. CI covers Node 22, 24, and 26.
+Development requires Node.js 22+ and the Bun version pinned by CI.
 
 ```sh
-bun install
+bun install --frozen-lockfile
 bun run ci
 ```
 
-The package exports `.`, `./protocol`, `./mcp`, and `./integrations`.
+CI covers Node.js 22, 24, and 26. Ordinary changes target `develop`; `main` is
+reserved for validated release PRs. The package exports `.`, `./protocol`,
+`./mcp`, and `./integrations`.
 
 ## License