diff --git a/openspec/changes/align-shared-artifact-inventory-ui/.openspec.yaml b/openspec/changes/align-shared-artifact-inventory-ui/.openspec.yaml new file mode 100644 index 0000000..913564e --- /dev/null +++ b/openspec/changes/align-shared-artifact-inventory-ui/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-08-08 diff --git a/openspec/changes/align-shared-artifact-inventory-ui/design.md b/openspec/changes/align-shared-artifact-inventory-ui/design.md new file mode 100644 index 0000000..d91ef5e --- /dev/null +++ b/openspec/changes/align-shared-artifact-inventory-ui/design.md @@ -0,0 +1,91 @@ +## Context + +See `proposal.md` for motivation. Current baseline after `add-complete-artifact-inventory`: + +- Host can enrich `getChangeDetails` with `artifacts` + `otherArtifacts` and open/reveal works. +- Webview Change Detail still centers a fixed `WorkflowStepIndicator` and a compact Other chip strip. +- Dashboard has no selected-change Complete Artifact Inventory; cards only show coarse badges. + +Design references: `docs/new-design/OpenSpec_UI_ChangeDetail_HighFidelity.png`, `docs/new-design-append-2/OpenSpec_UI_v4_ChangesWorkspace.png`, PRD v4 §9.4 / §10 / §22. + +## Goals / Non-Goals + +**Goals:** + +- One Host-built `ArtifactInventory` (`defined` + `other`) per change+scope, shared by Dashboard selected panel and Change Detail. +- Reusable webview Inventory / Plan Readiness components (same data props; layout variants allowed). +- Change Detail: remove fixed stepper as primary readiness UI; add Plan Readiness cards, shared Inventory Other section, Execution Progress, richer header context. +- Dashboard: selected-change Complete Artifact Inventory with Schema cards + Other section. + +**Non-Goals:** + +- Full Store Add Operation modal / Store Quick View IA (keep existing compact store controls). +- Workset Workspace redesign. +- Full Rendered|Source dual-mode editor chrome for every artifact. +- Treating apply/verify/archive as Schema inventory artifacts (PRD text wins over mock boxes). +- Replacing lifecycle filtering/pagination work (`add-change-lifecycle-filtering-and-pagination`); integrate with existing list, don’t rewrite status model here. + +## Decisions + +### D1: Canonical inventory type lives in shared module + +Introduce `ArtifactInventory` / `ArtifactInventoryItem` in a shared types module (aligned with PRD §22), built once in Extension Host (extend/replace ad-hoc `otherArtifacts` attachment in `getChangeDetails`). + +Dashboard and Detail both receive this structure via messages (`changeDetails` / dashboard selected-change payload). Webview MUST NOT re-diff the filesystem. + +**Alternative considered:** Let each surface call different APIs and “mostly agree” — rejected; user explicitly requires one inventory. + +### D2: Plan Readiness cards are a presentation of `defined` + +Plan Readiness is not a second data source. It is a card layout over `inventory.defined` (status, counts, deps, actions). Content tabs remain for reading markdown/tasks. + +``` +Host: buildArtifactInventory(change, scope) + │ + ├─► Dashboard selected panel ── ArtifactInventoryView(variant=workspace) + └─► Change Detail ──────────── PlanReadiness(defined) + ArtifactInventoryView(variant=detail) + ExecutionProgress(tasks) + Content tabs(defined ids + other entry) +``` + +### D3: Remove fixed stepper from Detail primary chrome + +`WorkflowStepIndicator` with hardcoded Proposal→Archive MUST leave Change Detail primary layout. Keep Apply/Verify/Archive as ActionBar / VerifyArchive panel / workflow launch actions. + +**Alternative:** Restyle stepper to look like cards — rejected; PRD forbids fixed phase UI. + +### D4: Dashboard selected panel placement + +MVP: when a change card is selected (or when Detail isn’t open, on explicit select), show inventory in an expandable section under the changes list / in the dashboard main column without requiring opening the editor Detail panel first. Opening Detail still uses the same inventory fetch/cache key `(scopeId, changeName)`. + +If current Dashboard has no true “selected change” state beyond navigation into Detail, add lightweight selection: click selects + shows inventory; double-click or “Open” opens Detail (preserve existing open behavior with clear affordance). Prefer: single click opens Detail today — add an inventory preview region that loads for the last-focused/opened change from the list (including when Detail is open), keyed by selection state already used by the UI if present. + +**Concrete MVP choice:** Introduce `selectedChangeName` in Dashboard; clicking a card sets selection and requests inventory; a dedicated “Open detail” control / card title action opens Change Detail. If that is too breaking, fall back to: inventory panel shows for the change currently open in Detail (synced), AND for hover/focus preview — but primary acceptance is “Workspace shows inventory without relying on a different Other list.” Prefer selection state. + +### D5: Visual system + +Follow existing Tailwind + VS Code CSS variables (no new design system). Schema cards: compact colored tiles with name + count + status. Other: secondary section title `Other Artifacts · Not defined in schema` / `其他工件 (未定义)` + chips/cards with counts + More (Open / Reveal / Copy path). + +### D6: Compatibility with prior inventory change + +Keep `buildOtherArtifacts` / `openAndRevealPath`; wrap them inside `buildArtifactInventory`. Retain message types where possible; evolve payloads to include `inventory: { defined, other }` and deprecate parallel-only `otherArtifacts` once both surfaces migrate (temporary dual-field ok during migration). + +## Risks / Trade-offs + +- [Dashboard click behavior change] → Mitigate with explicit Open affordance + preserve keyboard/accessibility; document in tasks. +- [Status mapping incomplete when CLI status fails] → Reuse filesystem fallback statuses; show Unknown rather than omit. +- [Visual scope creep into Store Quick View] → Hard Non-Goal; reject in review if PRs expand there. +- [Duplicate fetches] → Cache inventory on Host per `(scopeId, changeName)` short TTL / invalidate with existing file watcher. + +## Migration Plan + +1. Ship shared types + Host builder behind existing `getChangeDetails`. +2. Switch Change Detail to Plan Readiness + shared Other section; remove stepper. +3. Add Dashboard selected inventory panel consuming same message/builder. +4. Remove temporary dual fields after both surfaces read `inventory` only. +5. Rollback: revert webview layout; Host inventory field is additive. + +## Open Questions + +- None that block specs/tasks: Dashboard selection UX default locked in D4 (selectedChangeName + inventory panel; Open detail is explicit). diff --git a/openspec/changes/align-shared-artifact-inventory-ui/proposal.md b/openspec/changes/align-shared-artifact-inventory-ui/proposal.md new file mode 100644 index 0000000..cd82a41 --- /dev/null +++ b/openspec/changes/align-shared-artifact-inventory-ui/proposal.md @@ -0,0 +1,30 @@ +## Why + +`add-complete-artifact-inventory` 已经把 Schema 动态 Tab、Other Artifacts 扫描和 Reveal+Open 接到 Change Detail,但视觉与信息架构仍停留在旧页:固定 `Proposal → … → Archive` 步进条、无 Plan Readiness 卡片、Other Artifacts 只是一条紧凑 chip,且 Dashboard / Changes Workspace 完全看不到同一份 Inventory。对照 v2 Change Detail 高保真与 v4 Changes Workspace,用户感知是「功能有了,设计稿完全对不上」。现在需要把 **Changes Workspace(Dashboard 选中 Change)** 与 **Change Detail** 一起对齐设计,并强制 **共用同一份 Artifact Inventory 数据源**。 + +## What Changes + +- 抽出共享的 `ArtifactInventory` 数据模型与构建入口(`defined` / `other`),供 Changes Workspace 与 Change Detail 共同消费;禁止两套各自拼装的列表。 +- **Changes Workspace(Dashboard 选中 Change 面板)**:按 v4 §9.4 展示 Complete Artifact Inventory——Schema Artifact 卡片行(类型、文件/任务数、状态)+ `Other Artifacts · Not defined in schema` 分区;主点击 Reveal+Open。 +- **Change Detail**:对齐 v2/v4 Detail 设计——移除固定生命周期 Stepper;用 **Plan Readiness** Artifact Cards(Done/Ready/Blocked/Missing/Error、文件数、依赖、Open/Reveal);同一 Inventory 的 Schema + Other 分区;独立 **Execution Progress** 区;Header 补充 Writable Root / Schema / 任务进度等关键上下文。 +- Artifact Content View:保留 Schema 动态 Tab;Other 作为内容分组/入口与 Inventory 联动,不再只是永久贴在 Tab 下的无名 chip 条。 +- 升级 Other Artifacts 文案与布局至设计稿语义(「Not defined in schema / 未定义」);条目支持 Open / Reveal / Copy path(More 或等价入口)。 + +## Capabilities + +### New Capabilities + +- `artifact-inventory`: 定义共享 Artifact Inventory 的数据契约、Schema vs Other 分区规则,以及 Changes Workspace 与 Change Detail 必须共用同一数据源的行为要求。 + +### Modified Capabilities + +- `artifact-viewing`: Change Detail 从「动态 Tab + 紧凑 Other strip」升级为 Plan Readiness 卡片 + 共享 Inventory 分区 + 去掉固定 Stepper;内容区与 Inventory 联动。 +- `dashboard`: Changes Workspace / Dashboard 在选中 Change 时展示与 Detail 同源的 Complete Artifact Inventory(Schema 卡片 + Other 分区),而不只是列表卡片上的简单徽标。 + +## Impact + +- Extension Host:在现有 `buildOtherArtifacts` / `getChangeDetails` 之上收敛为统一的 `ArtifactInventory` 构建与消息载荷;Dashboard 与 Detail 的 webview 消息共用该结构。 +- Webview:新增可复用的 Inventory / Plan Readiness 组件;改造 `ChangeDetail.tsx` 与 Dashboard 选中态面板;移除或降级 `WorkflowStepIndicator` 固定阶段条在 Detail 上的主导地位。 +- Types / i18n:共享 Inventory 类型;中英文「Other Artifacts · Not defined in schema / 其他工件 (未定义)」等文案。 +- 依赖前序 change:`add-complete-artifact-inventory` 的扫描与 open/reveal 能力作为基础,本 change 做 UI 对齐与数据共享。 +- **不在本 change**:Store Add Operation / Store Quick View 完整表单、Workset Workspace、Rendered|Source 全套内容编辑器能力、自定义 Schema 的通用多文件子选择器泛化。 diff --git a/openspec/changes/align-shared-artifact-inventory-ui/specs/artifact-inventory/spec.md b/openspec/changes/align-shared-artifact-inventory-ui/specs/artifact-inventory/spec.md new file mode 100644 index 0000000..932b989 --- /dev/null +++ b/openspec/changes/align-shared-artifact-inventory-ui/specs/artifact-inventory/spec.md @@ -0,0 +1,70 @@ +## Purpose + +Defines the shared Artifact Inventory contract that both Changes Workspace and Change Detail MUST consume so Schema-defined and undeclared (Other) artifacts stay consistent across surfaces. + +## ADDED Requirements + +### Requirement: Shared Artifact Inventory Contract + +The system SHALL expose a single Artifact Inventory per change that contains: + +1. `defined`: Schema-declared artifacts in Schema order +2. `other`: Change-directory entries that exist on disk but are not declared by the current Schema + +Both Changes Workspace and Change Detail MUST render from this same inventory payload for a given change identity (name + scope/root). The system MUST NOT build divergent Schema or Other lists per surface. + +#### Scenario: Same inventory on workspace and detail + +- **WHEN** the user selects a change in Changes Workspace and later opens the same change in Change Detail under the same scope +- **THEN** both surfaces show the same Schema artifact keys/order and the same Other artifact entries (paths and file counts) + +#### Scenario: Schema and Other partitions are distinct + +- **WHEN** an inventory is built for a change that has both Schema artifacts and undeclared files +- **THEN** Schema items appear only under `defined` and undeclared items appear only under `other` (no silent reclassification) + +### Requirement: Schema Inventory Item Fields + +Each Schema inventory item SHALL include enough information for Plan Readiness / inventory cards: + +- stable key / id +- display name +- source marked as schema-defined +- status among Done / Ready / Blocked / Missing / Error (or an equivalent mapped set) +- file count (0 when missing) +- optional dependency ids +- optional updated time when known + +Missing Schema-declared artifacts (declared but file not created) SHALL still appear as inventory items with Missing or Ready status, not be omitted. + +#### Scenario: Missing schema artifact remains visible + +- **WHEN** Schema declares an artifact whose output file does not yet exist +- **THEN** the inventory still includes that artifact marked Missing or Ready (not hidden) + +#### Scenario: Schema order is preserved + +- **WHEN** Schema returns artifacts in a specific order +- **THEN** `defined` preserves that order for consumers + +### Requirement: Other Inventory Item Fields + +Each Other inventory item SHALL include: + +- stable key / id +- relative path +- whether it is a directory +- file count (single-level for directories; 1 for files) +- source marked as filesystem / not schema-defined + +Undeclared entries MUST NOT be hidden, discarded, or auto-merged into a Schema artifact type. + +#### Scenario: Undeclared directory is listed with count + +- **WHEN** the change directory contains `task-details/` with six files and Schema does not declare it +- **THEN** `other` includes that directory with file count 6 + +#### Scenario: Empty other partition + +- **WHEN** every top-level change entry is covered by Schema known paths +- **THEN** `other` is empty and consumers MAY hide the Other section diff --git a/openspec/changes/align-shared-artifact-inventory-ui/specs/artifact-viewing/spec.md b/openspec/changes/align-shared-artifact-inventory-ui/specs/artifact-viewing/spec.md new file mode 100644 index 0000000..35d86e4 --- /dev/null +++ b/openspec/changes/align-shared-artifact-inventory-ui/specs/artifact-viewing/spec.md @@ -0,0 +1,103 @@ +## MODIFIED Requirements + +### Requirement: Artifact List Display + +The Change Detail view SHALL present planning readiness and complete artifact inventory from the shared Artifact Inventory (see `artifact-inventory`), not from a hardcoded four-tab-only model or a permanent fixed lifecycle stepper. + +Change Detail MUST: + +1. Show **Plan Readiness** as Schema artifact cards driven by inventory `defined` (status, file count, optional deps, Open/Reveal) +2. Show **Complete Artifact Inventory** partitions for Schema and Other using the same inventory payload +3. Keep content tabs dynamically generated from Schema artifact ids +4. NOT use an irreversible fixed stepper of `Proposal → Specs → Design → Tasks → Apply → Verify → Archive` as the primary readiness UI + +Apply / Verify / Archive remain actions (or dedicated workflow panels), not Schema artifacts. + +#### Scenario: Show available artifacts + +- **GIVEN** a change with multiple Schema artifacts +- **WHEN** the user opens change details +- **THEN** all Schema artifacts MUST be shown as Plan Readiness cards and/or inventory items and content tabs +- **AND** the set and order of artifacts MUST come from the change's current Schema instead of a hardcoded list +- **AND** Schema-defined artifacts that have not been created yet MUST remain visible as Missing/Not created + +#### Scenario: Show available artifacts as readiness cards + +- **WHEN** a user opens Change Detail for a change with Schema artifacts +- **THEN** Plan Readiness shows one card per Schema artifact with status and Open/Reveal affordance + +#### Scenario: Fixed lifecycle stepper is not primary readiness UI + +- **WHEN** a user opens Change Detail +- **THEN** the primary readiness presentation is Plan Readiness cards / inventory, not a fixed Proposal→…→Archive phase stepper + +#### Scenario: Artifact status indication + +- **WHEN** Schema artifacts have Done / Ready / Blocked / Missing / Error statuses +- **THEN** Plan Readiness cards reflect those statuses visually + +#### Scenario: Other artifacts section on detail + +- **WHEN** inventory `other` is non-empty +- **THEN** Change Detail shows an Other Artifacts section labeled to indicate items are not defined in schema + +#### Scenario: Other artifacts section hidden when empty + +- **WHEN** inventory `other` is empty +- **THEN** Change Detail does not render an empty Other Artifacts section + +### Requirement: Artifact Actions + +The system SHALL provide artifact actions consistent with Reveal-first inventory behavior: + +- Open in editor +- Reveal in Explorer +- Copy path (for existing paths) +- Refresh artifact content + +Primary click on an existing Schema or Other inventory card MUST Reveal + Open (single file) or Reveal directory and focus the most recently updated file (multi-file). Missing Schema artifacts MUST NOT attempt reveal; they offer continue/create planning actions instead. + +#### Scenario: Open in editor + +- **WHEN** user chooses Open on an existing single-file artifact +- **THEN** the file opens in the VS Code editor and is revealed in Explorer + +#### Scenario: Copy file path + +- **WHEN** user chooses Copy path for an existing artifact path +- **THEN** the absolute path is copied to the clipboard + +#### Scenario: Refresh artifact + +- **WHEN** user refreshes while viewing an artifact +- **THEN** content reloads from disk without leaving Change Detail + +#### Scenario: Reveal multi-file artifact + +- **WHEN** user activates a directory artifact (Schema or Other) +- **THEN** Explorer reveals/expands the directory and focuses the most recently updated file when one exists + +#### Scenario: Missing artifact does not attempt reveal + +- **WHEN** user activates a Missing Schema artifact +- **THEN** the system does not call reveal for a non-existent path and instead offers continue/create planning + +## ADDED Requirements + +### Requirement: Change Detail Context Header + +Change Detail Header SHALL surface enough context to answer “where is this change?” including at least: change name, writable root label/path when known, schema id when known, and task progress when tasks exist. Linked store summary MAY appear when a store is in scope. + +#### Scenario: Header shows root and schema + +- **WHEN** a scoped change is opened in Change Detail +- **THEN** the header shows the change name plus writable root and schema information when available + +### Requirement: Execution Progress Panel + +Change Detail SHALL show Execution Progress separately from Plan Readiness, including tasks completed/total when task data exists. Implementation/archive workflow controls MAY live adjacent but MUST NOT replace Plan Readiness cards. + +#### Scenario: Execution progress shows task counts + +- **WHEN** a change has tasks with a known completed/total count +- **THEN** Execution Progress displays that progress separately from Plan Readiness diff --git a/openspec/changes/align-shared-artifact-inventory-ui/specs/dashboard/spec.md b/openspec/changes/align-shared-artifact-inventory-ui/specs/dashboard/spec.md new file mode 100644 index 0000000..52db414 --- /dev/null +++ b/openspec/changes/align-shared-artifact-inventory-ui/specs/dashboard/spec.md @@ -0,0 +1,32 @@ +## ADDED Requirements + +### Requirement: Selected Change Complete Artifact Inventory + +When a change is selected in the Changes Workspace (Dashboard change list / selected-change panel), the system SHALL display Complete Artifact Inventory for that change using the **same shared Artifact Inventory payload** consumed by Change Detail. + +The inventory MUST include: + +1. Schema-defined artifact cards (Schema order; file/task counts and status when available) +2. An Other Artifacts section titled to indicate items are not defined in schema, listing undeclared files/directories with counts + +Primary card click MUST Reveal + Open existing paths; Missing Schema cards MUST NOT reveal. + +#### Scenario: Selected change shows schema inventory cards + +- **WHEN** the user selects a change that has Schema artifacts +- **THEN** the Changes Workspace selected panel shows Schema inventory cards for those artifacts + +#### Scenario: Selected change shows other artifacts + +- **WHEN** the selected change directory contains undeclared entries such as `task-details/` +- **THEN** the selected panel lists them under Other Artifacts with file counts + +#### Scenario: Workspace and detail stay consistent + +- **WHEN** the user opens Change Detail for the currently selected change without changing scope +- **THEN** Detail inventory Schema keys and Other entries match what the Workspace selected panel showed + +#### Scenario: No selection hides inventory panel + +- **WHEN** no change is selected in Changes Workspace +- **THEN** the Complete Artifact Inventory selected panel is not shown as if it belonged to another change diff --git a/openspec/changes/align-shared-artifact-inventory-ui/tasks.md b/openspec/changes/align-shared-artifact-inventory-ui/tasks.md new file mode 100644 index 0000000..199ee3e --- /dev/null +++ b/openspec/changes/align-shared-artifact-inventory-ui/tasks.md @@ -0,0 +1,33 @@ +## 1. Shared Inventory 数据契约与 Host 构建 + +- [ ] 1.1 在 shared 类型中新增 `ArtifactInventory` / `ArtifactInventoryItem`(对齐 design D1 / PRD §22 字段:key、displayName、source、schemaDefined、status、paths、fileCount、dependencies、updatedAt) +- [ ] 1.2 实现 `buildArtifactInventory(changeDir, schemaArtifacts, changeName)`:`defined` 来自 Schema/fallback artifacts,`other` 复用现有 `buildOtherArtifacts` +- [ ] 1.3 在 `DataManager.getChangeDetails`(及必要的 Dashboard 拉取路径)返回统一 `inventory`;迁移期可同时保留 `otherArtifacts` 兼容字段 +- [ ] 1.4 为 `buildArtifactInventory` 与 getChangeDetails enrichment 编写单元测试(Schema+Other、Missing 仍出现、Workspace/Detail 同 payload 形状) + +## 2. 可复用 Webview Inventory / Plan Readiness 组件 + +- [ ] 2.1 新增 `ArtifactInventoryView`:Schema 卡片行 + `Other Artifacts · Not defined in schema` / `其他工件 (未定义)` 分区;空 Other 不渲染 +- [ ] 2.2 新增 `PlanReadinessCards`:基于 `inventory.defined` 展示状态、文件数、依赖摘要、Open/Reveal 入口 +- [ ] 2.3 统一卡片主点击与 More 菜单动作:Open / Reveal / Copy path;Missing 走 continue/create,不 reveal +- [ ] 2.4 为上述组件补充渲染/交互测试(空 Other、目录计数文案、Missing 不发 reveal) + +## 3. Change Detail 对齐设计稿 + +- [ ] 3.1 从 Change Detail 主布局移除固定 `WorkflowStepIndicator`(Proposal→Archive)作为 readiness 主导航;保留 ActionBar / VerifyArchive 等动作入口 +- [ ] 3.2 接入 Plan Readiness + 共享 `ArtifactInventoryView`;内容 Tab 继续由 Schema ids 动态生成,并与 Inventory 选择联动 +- [ ] 3.3 增加 Execution Progress 区(tasks completed/total)与 Header 上下文(writable root、schema、任务进度;有 store 时摘要) +- [ ] 3.4 更新 Change Detail 相关路由/源码断言测试与 i18n 文案 + +## 4. Changes Workspace(Dashboard)共用 Inventory + +- [ ] 4.1 Dashboard 增加 `selectedChangeName`(或等价选中态):选中 change 后请求与 Detail 同源的 inventory +- [ ] 4.2 在选中面板渲染同一套 `ArtifactInventoryView`(workspace variant);提供明确 Open Detail 入口,避免破坏现有打开习惯 +- [ ] 4.3 确保同一 scope 下 Workspace 与 Detail 展示的 Schema keys / Other entries 一致(集成或单测断言同 payload) +- [ ] 4.4 Dashboard 无选中时不展示张冠李戴的 Inventory + +## 5. 收尾验证 + +- [ ] 5.1 运行 `pnpm test` 与 `pnpm run build` +- [ ] 5.2 运行 `openspec validate align-shared-artifact-inventory-ui --strict` +- [ ] 5.3 手工验证:Dashboard 选中 `add-change-lifecycle-filtering-and-pagination` 可见 `task-details · 6 files`;打开 Detail 看到相同 Other,且无固定 Stepper 作为主 readiness UI