empirical-sdd 0.28.0 → 0.30.0

package/CHANGELOG.md

@@ -8,6 +8,121 @@ under the alpha rules in [docs/versioning.md](docs/versioning.md).
 
 ## [Unreleased]
 
+## [0.30.0] - 2026-09-01
+
+### Added
+
+- Added a zero-build, responsive project wiki with practical onboarding,
+  architecture and workflow guidance, searchable task-oriented navigation,
+  accessible Agentum motion, strict content security, reduced-motion support,
+  and meaningful no-JavaScript fallbacks.
+- Added exact GitHub Copilot MCP configuration management that preserves
+  unrelated servers and user-owned collisions while installing and removing
+  only Empirical's managed stdio bridge.
+- Added in-memory OAuth for Linear's official remote MCP endpoint through the
+  standalone `empirical mcp` bridge, using dynamic client registration, PKCE,
+  a state-bound ephemeral loopback callback, URL-mode elicitation, bounded
+  remote operations, sanitized failures, and complete session cleanup.
+
+### Changed
+
+- Replaced the long-form README with a concise project introduction derived
+  from the wiki while retaining strict tracker recovery guidance and keeping
+  obsolete public integration examples out of generated onboarding.
+- Generated initialization guidance now recommends an OAuth-capable Empirical
+  host when the current skill-only host cannot perform the browser handoff,
+  while retaining the secure host-only secret-file fallback.
+
+### Fixed
+
+- Linear discovery, lifecycle suggestion, and preview now accept any finite
+  workflow-state position, including the negative floating-point ordering
+  values Linear legitimately assigns to backlog states.
+- Fixed standalone Linear OAuth lifecycle behavior so cancellation, timeout,
+  callback races, invalid responses, and transport shutdown remain bounded and
+  cannot leak credentials or leave callback listeners running.
+
+### Migration
+
+No migration required.
+
+## [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 +351,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.28.0...HEAD
+[Unreleased]: https://github.com/goempirical/empirical-sdd/compare/v0.30.0...HEAD
+[0.30.0]: https://github.com/goempirical/empirical-sdd/compare/v0.29.0...v0.30.0
+[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,135 @@
 # 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.
+**Agent work that survives the chat.**
 
-> Empirical 0.28 is alpha software. It requires Node.js 22 or newer.
+Empirical is a repository-native harness for coding agents. The model writes;
+Empirical keeps the contract, progress, proof, and exact next action in Git so
+work can resume across sessions, agents, and machines.
 
-## Install
+> Empirical 0.29 is alpha software and requires Node.js 22 or newer.
 
-```sh
-npm install -g empirical-sdd
-empirical install
-```
+**[Open the practical harness guide](https://goempirical.github.io/empirical-sdd/)**
+for the visual walkthrough, diagrams, generated-file explorer, and complete
+workflow. Its zero-build source is [docs/index.html](docs/index.html).
+
+## Start in three steps
+
+1. Install the package and the agent integrations you use.
+
+   ```sh
+   npm install -g empirical-sdd
+   empirical install
+   ```
+
+2. Initialize each repository once from your coding agent.
+
+   - Codex: `$empirical-init`
+   - Claude Code: `/empirical-init`
+
+3. Ask for the change normally.
+
+   ```text
+   Add rate limiting to the public API and prove the failure path.
+   ```
+
+Repository mutations route automatically. Read-only questions remain
+read-only. If work stops, reopen the same checkout and ask the agent to
+continue—the committed journal provides the resume point.
 
-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
-
-| Command | Purpose |
+## Why use it?
+
+| Without a harness | With Empirical |
 | --- | --- |
-| `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. |
+| Lost chat | **Continuity** — resume from repository state. |
+| Ambiguous request | **Shared contract** — agree on observable outcomes first. |
+| Confidence without proof | **Honest evidence** — bind claims to exact source, commands, attempts, and results. |
+| Scope drift | **Reviewable scope** — keep decisions, diffs, failures, and gaps visible. |
+| Unsafe convergence | **Safer integration** — isolate parallel work and validate against an independent target. |
+| Accidental publication | **Bounded authority** — keep implementation, delivery, and publication separate. |
+
+## How it works
 
-`empirical uninstall` preserves project `.empirical` history, evidence, and
-repository configuration. Automation must confirm removal with `--yes`.
+Empirical routes by risk, not prompt length:
 
-## Safety
+- **Fast** handles explicit, tiny, localized, reversible, contract-neutral work
+  with focused proof.
+- **Complex** carries material work through a durable contract, decisions,
+  verification, exact-diff review, and independent integration.
 
-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.
+```text
+Specify → Design → Plan → Implement → Context? → Verify → Review → Integrate
+```
+
+Context runs when repository knowledge needs refinement. Failed verification or
+requested review changes return to implementation. Evidence, review, and
+integration are different claims, and Empirical reports only the highest level
+actually proven: `implemented`, `verified`, `integrated`, `delivered`, or
+`published`.
+
+Delivery is never implied. Empirical does not infer permission to merge a pull
+request, bypass protection, create a release, or publish a package.
+
+## What it creates
+
+Init installs the harness; selected work fills in the record:
+
+```text
+repository/
+├── AGENTS.md / CLAUDE.md / GEMINI.md    bounded activation markers
+├── agent skill + MCP entries            selected integrations
+└── .empirical/
+    ├── config.json                      project setup
+    ├── policy.json                      verification and delivery policy
+    ├── tracker.json                     secret-free tracker choice
+    ├── context/                         repository knowledge
+    ├── specs/<feature>/
+    │   ├── spec.md + decisions.md       contract and decisions
+    │   ├── design.md + plan.md          Complex approach and plan
+    │   ├── impact.json                  affected behavior and surfaces
+    │   ├── state.json + events/         phase and resumable journal
+    │   ├── evidence/receipts/           immutable attempts and artifacts
+    │   ├── reviews/                     exact-diff review, when reached
+    │   └── integration-receipt.json     convergence proof, when reached
+    └── capabilities/<capability>/       living behavior after integration
+```
+
+Exact host files depend on the integrations selected during install. Init
+creates durable setup and empty work containers; a real mutation creates a
+feature record, and conditional artifacts appear only when their phases run.
+
+Optional tracking mirrors approved milestones to Linear, GitHub, or Jira; the
+repository remains authoritative. Policy supports
+`enforcement: "best-effort" | "strict"`; strict recovery retries the exact
+feature. Credentials never belong in chat, prompts, repository files, tool
+arguments, or evidence.
+
+When GitHub Copilot is selected, installation also reconciles the exact
+Empirical stdio bridge in `~/.copilot/mcp-config.json`; start a new session after
+install or update. Linear setup then uses an in-memory OAuth client for Linear's
+official remote MCP endpoint, with browser authorization through negotiated URL
+elicitation. Empirical never reads Copilot's token store or persists the OAuth
+token. The guarded `LINEAR_SECRET_KEY` host file remains a fallback, not the
+default requirement for an OAuth-capable session.
 
 ## 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)
+- [Practical guide](https://goempirical.github.io/empirical-sdd/) — visual onboarding and diagrams
+- [Demo](docs/demo.md) — installation and representative scenarios
+- [Protocol](docs/protocol.md) — state machine, artifacts, and completion rules
+- [Architecture](docs/architecture.md) — persistence and trust boundaries
+- [MCP and tracking](docs/mcp.md) — agent operations and tracker configuration
+- [Security](docs/security.md) — credentials, execution, review, and authority
+- [Releasing](docs/releasing.md) — guarded maintainer playbook
 
 ## Development
 
-Development requires Node.js 22+ and Bun. CI covers Node 22, 24, and 26.
-
 ```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 pull requests.
 
 ## License
 

package/dist/agent-catalog.d.ts

@@ -189,6 +189,8 @@ export declare const AGENT_SKILL_TARGETS: readonly [{
     readonly label: "GitHub Copilot";
     readonly globalSkillPath: ".copilot/skills";
     readonly detectPaths: readonly [".copilot"];
+    readonly reload: "Start a new Copilot CLI or Agent Host session so it reloads the global Empirical MCP bridge.";
+    readonly projectMcp: true;
 }, {
     readonly id: "goose";
     readonly label: "Goose";