empirical-sdd 0.24.1 → 0.25.0

package/CHANGELOG.md

@@ -8,6 +8,42 @@ under the alpha rules in [docs/versioning.md](docs/versioning.md).
 
 ## [Unreleased]
 
+## [0.25.0] - 2026-08-19
+
+### Added
+
+- Added a trusted-host OAuth resolver contract for Linear, GitHub, and Jira,
+  with provider tokens kept ephemeral and outside Tracker Policy, MCP tool
+  input/output, chat, logs, and repository state.
+- Added explicit MCP URL-mode capability negotiation for out-of-band OAuth;
+  form-only, legacy-empty, absent, declined, and cancelled clients fail closed
+  to the host fallback without receiving a credential form.
+- Added a guarded read-only user secrets file fallback at
+  `${XDG_CONFIG_HOME:-$HOME/.config}/empirical/secrets.env` on POSIX or
+  `%APPDATA%\Empirical\secrets.env` on Windows, including containment, link,
+  size, syntax, completeness, and POSIX permission checks.
+
+### Changed
+
+- Made new Linear setup default to `LINEAR_SECRET_KEY`, while preserving every
+  existing Tracker Policy v1/v2 name—including `LINEAR_API_KEY` and custom
+  valid names—without migration or repair rewrites.
+- Made Jira OAuth use Atlassian's Cloud API base with Bearer authorization while
+  retaining tenant-origin Basic authentication for email/API-token fallback.
+- Made Linear OAuth use its required Bearer authorization while preserving the
+  raw `Authorization` value required by existing personal API-key fallbacks.
+- Aligned CLI, MCP, generated `empirical-init` guidance, Doctor, README, and
+  protocol/security documentation around OAuth-first setup, the exact host
+  fallback path, and the rule: `Never paste credentials into chat`.
+
+### Fixed
+
+- Made tracker secret-file path construction honor explicit POSIX and Windows
+  semantics, with platform-correct permission fixtures and recovery-path tests.
+- Serialized the process-heavy release test suite so temporary Git worktree
+  tests cannot exhaust their timeout and race cleanup under parallel load, and
+  removed a redundant non-coverage pass from local CI to match the GitHub gate.
+
 ## [0.24.1] - 2026-08-19
 
 ### Fixed
@@ -121,7 +157,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.24.1...HEAD
+[Unreleased]: https://github.com/goempirical/empirical-sdd/compare/v0.25.0...HEAD
+[0.25.0]: https://github.com/goempirical/empirical-sdd/compare/v0.24.1...v0.25.0
 [0.24.1]: https://github.com/goempirical/empirical-sdd/compare/v0.24.0...v0.24.1
 [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

package/README.md

@@ -4,7 +4,7 @@ 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.24 is alpha software. It requires Node.js 22 or newer.
+> Empirical 0.25 is alpha software. It requires Node.js 22 or newer.
 
 ## Install
 
@@ -46,13 +46,34 @@ verified, integrated, delivered, or published.
 it recommends **Track all work** and requires choosing that or **No tracking**
 before setup can be saved. Track all selects Linear, GitHub Projects, or Jira;
 No tracking persists a provider-free choice and makes no provider requests.
-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 or explicit No tracking choice unless you change it.
+
+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`