empirical-sdd 0.29.0 → 0.30.0

package/CHANGELOG.md

@@ -8,6 +8,44 @@ 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
@@ -313,7 +351,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.29.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

package/README.md

@@ -1,162 +1,135 @@
 # Empirical SDD
 
-Reliable, resumable spec-driven development for coding agents.
+**Agent work that survives the chat.**
 
-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.
+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.
 
 > Empirical 0.29 is alpha software and requires Node.js 22 or newer.
 
-## Quick start
+**[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).
 
-Install Empirical globally, then install its integrations for the coding agents
-you use:
+## Start in three steps
 
-```sh
-npm install -g empirical-sdd
-empirical install
-```
-
-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:
+1. Install the package and the agent integrations you use.
 
-```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.
+   ```sh
+   npm install -g empirical-sdd
+   empirical install
+   ```
 
-## What Empirical does
+2. Initialize each repository once from your coding agent.
 
-- 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.
+   - Codex: `$empirical-init`
+   - Claude Code: `/empirical-init`
 
-## Workflow at a glance
+3. Ask for the change normally.
 
-Material work follows a deterministic state machine:
+   ```text
+   Add rate limiting to the public API and prove the failure path.
+   ```
 
-```text
-Specify → Design → Plan → Implement → Context → Verify → Review → Integrate
-```
+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.
 
-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.
+## Why use it?
 
-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.
+| Without a harness | With Empirical |
+| --- | --- |
+| 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. |
 
-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.
+## How it works
 
-## Everyday use
+Empirical routes by risk, not prompt length:
 
-You communicate with your coding agent, not a workflow CLI.
+- **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.
 
 ```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?
+Specify → Design → Plan → Implement → Context? → Verify → Review → Integrate
 ```
 
-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 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.
+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`.
 
-## Review and tracking
+Delivery is never implied. Empirical does not infer permission to merge a pull
+request, bypass protection, create a release, or publish a package.
 
-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.
+## What it creates
 
-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.
+Init installs the harness; selected work fills in the record:
 
-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
+```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
+```
 
-Empirical fails closed at the boundaries that matter:
+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.
 
-- 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.
+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.
 
-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.
+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
 
+- [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) — trust boundaries and system design
+- [Architecture](docs/architecture.md) — persistence and trust boundaries
 - [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
+- [Security](docs/security.md) — credentials, execution, review, and authority
+- [Releasing](docs/releasing.md) — guarded maintainer playbook
 
 ## Development
 
-Development requires Node.js 22+ and the Bun version pinned by CI.
-
 ```sh
 bun install --frozen-lockfile
 bun run ci
 ```
 
 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`.
+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";