feat: OpenSpecUI 14 — adapt to OpenSpec CLI 1.14.x (target-openspec-cli-114-line)

.changeset/openspec-114-line-adaptation.md

@@ -0,0 +1,8 @@
+---
+'@openspecui/core': major
+'@openspecui/server': major
+'@openspecui/web': major
+'openspecui': major
+---
+
+OpenSpecUI 14: adapt to OpenSpec CLI 1.14.x as a new single-series line (`>=1.14.0 <1.15.0`); the previous 1.13 v13 window, prereleases, `>=1.15.0`, and unparseable versions are blocked by default. Six 1.14 JSON surfaces are typed end-to-end: the `version` command envelope (no network probing), Apply task `sourcePath`/`line` source locations, per-entry `archived` from `list --archived`/`--all`, `status` advisory warnings (single and batch shapes) preserved verbatim through the kernel projection and rendered on the Change Detail direct plane as a collapsed summary row that never gates actions, `show --type spec --json` requirement/scenario names, and store-backed `allowedEditRoots` two-branch action context. The Agent delivery registry rotates to the 1.14 series with ten new tools — amp and gsd join the shared `.agents` skills root (five-writer arbitration; antigravity stays commands-only) alongside atomcode, codestudio, dsh, easycode, gigacode, grok, veai, warp, and IBM Bob — the pinned generator baseline moves to 1.14.0 with series-aware staleness, and the pinned executable fixture matrix rotates to `@fission-ai/openspec@1.14.0` with the retained 1.13.2 executable proving below-admitted boundary rejections and the 1.14-only members absent.

CLAUDE.md

@@ -121,7 +121,7 @@ await ctx.cliExecutor.archiveStream(changeId, options, (event) => {
 
 ## Important Reference Files
 
-**At the start of each session, read `references/openspec-1.13.2-report.md` for the current OpenSpec protocol and OpenSpecUI adaptation boundary. Use `references/openspec-1.13.1-report.md`, `references/openspec-1.13.0-report.md`, `references/openspec-1.12.0-report.md`, `references/openspec-1.9.0-report.md`, and `references/openspec-0.16.0-report.md` only as historical domain-model context.**
+**At the start of each session, read `references/openspec-1.14.0-report.md` for the current OpenSpec protocol and OpenSpecUI adaptation boundary. Use `references/openspec-1.13.2-report.md`, `references/openspec-1.13.1-report.md`, `references/openspec-1.13.0-report.md`, `references/openspec-1.12.0-report.md`, `references/openspec-1.9.0-report.md`, and `references/openspec-0.16.0-report.md` only as historical domain-model context.**
 
 This file contains:
 

README-1.13.0.md

@@ -0,0 +1,223 @@
+<!--
+Orthogonal intents (updated 2026-08-28 Asia/Shanghai):
+1. Document the current OpenSpec compatibility and project workflow.
+2. Document serve, App-daemon, Direct Web, and static-export commands.
+3. Document project hooks without hiding OpenSpec CLI authority.
+
+Original request (2026-07-29): "补充 openspecui --web == openspecui serve --web；README 文档需要补充这些命令的介绍。"
+Original request (2026-08-01): "v7不兼容1.6.x，明确要求必须使用 v1.7.x。"
+Original request (2026-08-15): "v9的适配需要同时适配 1.8和1.9。"
+Original request (2026-08-28): "直接将 0.10.0 和 0.11.0 一起适配，然后发布 v11。"
+Original request (2026-09-12): "Openspec 1.13.0 释放了，你更新一下，调查变更内容，然后开始规划适配工作，我们将用标准工作流worktree来推进。让 codex 参与。"
+-->
+
+# OpenSpec UI
+
+[English](./README.md) | [中文](./README-zh.md)
+
+OpenSpecUI is a web interface for OpenSpec workflows (live mode + static export).
+
+## Version Compatibility
+
+| OpenSpecUI         | OpenSpec CLI line                                          |
+| ------------------ | ---------------------------------------------------------- |
+| `@latest` / `@^13` | current + supported: `>=1.13.0 <1.14.0`                    |
+| `@^12` (legacy)    | current + supported: `>=1.12.0 <1.13.0`                    |
+| `@^11` (legacy)    | current: `>=1.11.0 <1.12.0`; supported: `>=1.10.0 <1.12.0` |
+| `@^9`              | current: `>=1.9.0 <1.10.0`; supported: `>=1.8.0 <1.10.0`   |
+| `@^7`              | `>=1.7.0 <1.8.0`                                           |
+| `@^6`              | current: `>=1.6.0 <1.7.0`; compatible: `>=1.7.0 <1.8.0`    |
+| `@^5`              | current: `>=1.5.0 <1.6.0`; accepted: `>=1.4.0 <1.6.0`      |
+| `@^4`              | current: `>=1.4.0 <1.5.0`; accepted: `>=1.3.0 <1.5.0`      |
+| `@^3`              | `>=1.3.0 <1.4.0`                                           |
+| `@^2`              | `>=1.2.0 <1.3.0`                                           |
+| `@^1`              | `>=1.0.0 <1.2.0`                                           |
+
+OpenSpecUI major versions ordinarily track OpenSpec CLI minor lines. OpenSpecUI 13 adapts OpenSpec
+CLI 1.13.x as a single-series line: stable 1.13.x is current and recommended, and `1.14` is not
+pre-claimed — when it ships, admission is a separately verified decision (a 13.x window widening or
+a new major). OpenSpecUI 12 remains the historical 1.12.x product line, OpenSpecUI 11 the historical
+1.10.x/1.11.x line.
+
+Legacy docs:
+
+- 1.12: [`README-1.12.0.md`](./README-1.12.0.md)
+- 1.11: [`README-1.11.0.md`](./README-1.11.0.md)
+- 1.9: [`README-1.9.0.md`](./README-1.9.0.md)
+- 1.7: [`README-1.7.0.md`](./README-1.7.0.md)
+- 1.6: [`README-1.6.0.md`](./README-1.6.0.md)
+- 1.3: [`README-1.3.0.md`](./README-1.3.0.md)
+- 1.2: [`README-1.2.0.md`](./README-1.2.0.md)
+- 1.x UI / pre-1.2 CLI line: [`README-1.x.md`](./README-1.x.md)
+- 0.16: [`README-0.16.0.md`](./README-0.16.0.md)
+
+## Quick Start
+
+```bash
+# Recommended: run without global install
+npx openspecui@latest
+bunx openspecui@latest
+
+# Optional: install globally
+npm install -g openspecui
+openspecui
+```
+
+Direct Project Web defaults to `http://localhost:3100` when that presentation is selected.
+
+## OpenSpec CLI Compatibility
+
+- OpenSpecUI 13 accepts stable OpenSpec CLI `>=1.13.0 <1.14.0` and recommends the 1.13 line.
+- Stable 1.13.x is identified as the current line; this is a single-series window.
+- OpenSpec CLI 1.12.x (the OpenSpecUI 12 window), older lines, CLI `>=1.14.0`, and every
+  prerelease are unsupported by OpenSpecUI 13 and blocked by default.
+- If an incompatible CLI executable is available, the mismatch Dialog offers **Skip version check**.
+  This bypass is held only by the current page runtime, clears on refresh/reopen, and does not
+  create a compatibility promise.
+
+OpenSpecUI 13 adds: CLI-owned Apply readiness guidance — `instructions apply` warnings (the
+no-delta-specs advisory that predicts a `validate` failure) render on the Change Detail direct plane,
+and the `missingPrerequisites` build-order chain renders as readable next-step evidence. The Agent
+delivery registry rotates to the 1.13 series with every 1.12 physical fact carried forward, and the
+pinned generator baseline moves to 1.13.0. Validation findings (`--report findings`), merge-conflict
+informational findings, SourceCraft Code Assistant (`.codeassistant`), batch status (`status --all`),
+requirement diff evidence (`show --diff`), `init --language`, Zed, and the Antigravity `.agent` →
+`.agents` migration continue on the admitted 1.13 line.
+
+Upgrade CLI:
+
+```bash
+npm install -g @fission-ai/openspec@1.13
+```
+
+## Common Flows
+
+### Serve a project
+
+```bash
+openspecui
+openspecui ./my-project
+openspecui serve ./my-project
+openspecui --port 3200
+```
+
+The bare command is an alias for `serve`. Each `serve` process owns its project Server. If an App
+daemon is already running, the project is added to its **Workspaces**. Otherwise an interactive
+terminal asks `Start OpenSpecUI App? [Y/n]`; non-interactive execution opens Direct Project Web.
+
+### App daemon and explicit presentation
+
+```bash
+# Serve this project through the local App daemon (native OpenTray by default)
+openspecui --app
+openspecui serve --app
+
+# Open Direct Project Web; also attach to an already-running daemon
+openspecui --web
+openspecui serve --web
+openspecui serve --no-open
+
+# Manage only the user-level App daemon, never project Servers
+openspecui start
+openspecui start --web
+openspecui stop
+openspecui restart
+openspecui restart --web
+```
+
+Daemon host mode is fixed at startup: native uses a retained OpenTray window; `--web` uses the
+Browser host. If a repeated `start` explicitly requests another mode, use the exact `restart`
+command reported by the CLI. `serve --no-open` performs no prompt, daemon start, Workspace
+registration, or Browser opening. URL-valued App mode and project-level shell-location settings are
+no longer supported; the daemon serves the App shell bundled with the same CLI release. Every
+Workspace tab can ask the daemon to open its current backend in the system browser without exposing
+the backend URL as page-controlled input.
+
+### Static export
+
+```bash
+openspecui export -o ./dist
+openspecui export -o ./dist --base-path /docs --clean
+```
+
+### Nix
+
+```bash
+nix run github:jixoai/openspecui -- --help
+nix develop
+```
+
+## Project Hooks
+
+OpenSpecUI can load project-local hooks from `openspec/openspecui.hooks.ts`.
+Hooks are intentionally kept outside `openspec/.openspecui.json` so executable project behavior
+does not pollute persisted UI configuration.
+
+Install-time types are available from the CLI package:
+
+```ts
+import type { OnReadDocumentHookV1, OnRunWorkflowHookV2 } from 'openspecui/hooks'
+```
+
+### `onReadDocument`
+
+Use `onReadDocument` when a project needs to project OpenSpec markdown differently for UI
+consumers without rewriting source files. Typical use cases include resolving requirement IDs from
+another file, translating markdown for readers, or adding derived context for search/export.
+
+```ts
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { OnReadDocumentHookV1 } from 'openspecui/hooks'
+
+export const onReadDocument: OnReadDocumentHookV1 = async (ctx, read) => {
+  const result = await read()
+  if (ctx.document.kind !== 'spec') return result
+
+  const glossaryPath = join(ctx.projectDir, 'openspec', 'glossary.md')
+  const glossary = await readFile(glossaryPath, 'utf-8')
+
+  return {
+    ...result,
+    markdown: `${result.markdown}\n\n---\n\n${glossary}`,
+    watchFiles: [glossaryPath],
+  }
+}
+```
+
+`onReadDocument` runs server-side in OpenSpecUI V1. It applies to processed document reads for
+live views, search, and static export. Source reads stay raw and audit-safe, so editing,
+validation, and source inspection still use the original OpenSpec files.
+
+### `onRunWorkflow`
+
+Use `onRunWorkflow` to adjust the final OPSX invocation payload before OpenSpecUI hands it to an
+agent or command runner. OpenSpec CLI remains the source of truth for workflow status,
+instructions, schemas, validation, and archive behavior.
+
+```ts
+import type { OnRunWorkflowHookV2 } from 'openspecui/hooks'
+
+export const onRunWorkflow: OnRunWorkflowHookV2 = async (ctx, run) => {
+  const result = await run()
+  if (result.kind !== 'agent-prompt') return result
+
+  return {
+    ...result,
+    text: `${result.text}\n\nPlanning root: ${ctx.target.planningRoot.path}\nProject policy: include security impact in the final summary.`,
+  }
+}
+```
+
+If a hook throws, OpenSpecUI falls back to the default result and attaches diagnostics instead of
+blocking the UI.
+
+## Key Features
+
+- Dashboard for specs/changes/tasks status
+- Config/Schema viewers and editors
+- OPSX compose panel for change actions
+- Multi-tab PTY terminal (xterm + ghostty-web)
+- Search in live mode and static mode
+- Static snapshot export for docs hosting
+- Project-local hooks for document projection and OPSX invocation customization