empirical-sdd 0.24.1 → 0.26.0

package/CHANGELOG.md

@@ -8,6 +8,68 @@ under the alpha rules in [docs/versioning.md](docs/versioning.md).
 
 ## [Unreleased]
 
+## [0.26.0] - 2026-08-20
+
+### Added
+
+- Added selectable `concise` or `detailed` interaction questions across project
+  configuration, CLI, MCP, action packets, status rendering, and generated
+  agent guidance. New recommended setup is concise; existing missing fields
+  remain detailed.
+- Added strict optional Tracker Policy v2 ticket-rule matrices, including the
+  `features+large-fixes` preset and resolved change-type/requirement status.
+- Added a packaged provider-independent no-ticket feature demo that proves one
+  guarded create, one durable binding, and zero live-network calls.
+
+### Changed
+
+- Optional ticket work with no explicit reference now remains local before
+  authentication or provider access and no longer causes a redundant ticket
+  question; required work retains attach, marker reconciliation, and
+  exactly-once guarded creation.
+
+### Migration
+
+- Existing Schema 5 and Tracker Policy v1/v2 repositories require no state
+  migration. Repositories without an explicit question mode retain detailed
+  questions until configured otherwise; new setup recommends concise mode.
+
+## [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 +183,9 @@ 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.26.0...HEAD
+[0.26.0]: https://github.com/goempirical/empirical-sdd/compare/v0.25.0...v0.26.0
+[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.26 is alpha software. It requires Node.js 22 or newer.
 
 ## Install
 
@@ -35,6 +35,7 @@ artifacts; unmanaged or unsafe conflicts are preserved and remain visible.
 - 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,
@@ -42,17 +43,45 @@ verified, integrated, delivered, or published.
 
 ## Tracker setup
 
-`empirical-init` always shows a Tracker section. When no prior choice exists,
-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.
+`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`
@@ -64,6 +93,21 @@ 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
 
 | Command | Purpose |