pi-ui-extend 1.0.41 → 1.0.45

package/docs/desktop-task-manager.md

@@ -2,123 +2,187 @@
 
 ## Type
 
-Change
+As-is
+
+## Lifecycle
+
+Active current contract.
 
 ## Goal
 
-Add a project-scoped task list to Pix Desktop in a persistent left sidebar and
-allow a saved task to start work immediately in a new session tab.
+Provide a project-scoped task list in Pix Desktop and let a saved task start or
+reopen work in a Desktop session without conflating project tasks with the
+agent's session-local todo list.
 
 ## Scope
 
-- A collapsible, resizable left sidebar with `Tasks` and `Project` tabs.
-- A compact task list with create, edit, delete, filtering, and manual status
-  changes.
-- Task type (`bug`, `feature`, `improvement`), status (`backlog`, `todo`,
-  `in-progress`, `done`), and priority (`low`, `medium`, `high`, `urgent`).
-- Project-local persistence in `.pi/tasks.json` with a versioned schema.
-- Starting a task in a new ACP session, automatically sending a generated
-  prompt, marking the task in progress, and storing the new session id.
-- Opening an already-linked session instead of creating a duplicate.
+- A collapsible, resizable left activity sidebar whose project-scoped views
+  include `Tasks` and `Project` alongside other workspace views.
+- Create, edit, delete, manual status changes, drag reordering, and moving tasks
+  between type groups.
+- Create an untitled task directly from the normal message composer through its
+  overflow menu, carrying the current draft text and attachments without
+  sending a prompt.
+- Task type (`bug`, `feature`, `improvement`) and status (`backlog`, `todo`,
+  `in-progress`, `done`).
+- Persisted priority (`low`, `medium`, `high`, `urgent`). New tasks currently
+  receive `medium`; priority is not exposed by the current task editor or rows.
+- Project-local persistence in `.pi/tasks.jsonc` with a versioned schema.
+- Starting an unlinked task in a new ACP session and reopening an already-linked
+  session instead of creating a duplicate.
+- Task descriptions can contain attachment markers; those attachments are
+  resolved when the task prompt is built.
 
 ## Non-goals
 
-- Kanban, drag and drop, subtasks, dependencies, assignees, due dates,
-  comments, or task history.
+- Kanban columns, subtasks, dependencies, assignees, due dates, comments, or
+  task history.
+- Task filtering controls in the current sidebar UI.
+- Editing or displaying priority in the current sidebar UI.
 - Automatic transition to `done` when an agent turn finishes.
-- Synchronizing the project task file with the agent's session-local todo list.
+- Synchronizing `.pi/tasks.jsonc` with the agent's session-local todo list.
 - Concurrent multi-window file merging.
 
 ## Behavior
 
-1. The sidebar is visible below the title/session chrome, starts on `Tasks`,
-   remembers its width and collapsed state locally, and preserves the main
-   session workspace at narrow window sizes.
-2. Task rows show a title, type, status, priority, and actions. Status and
-   priority are communicated by a Lucide icon, text, and color so meaning never
-   depends on color alone. `done` is green, `in-progress` is yellow, and idle
-   states are neutral; all colors support light and dark themes.
-3. Creating or editing validates a non-empty title. A description is optional.
-4. Filters affect only the visible list and do not modify persisted ordering.
-5. A missing `.pi/tasks.json` is treated as an empty version-1 document.
-6. Starting an unlinked task creates and selects a new ACP session, persists
-   its id and `in-progress` status, appends the generated user prompt to the
-   transcript, and sends it immediately.
-7. Starting a linked task loads that session. A missing/stale linked session is
-   reported as a recoverable error and does not silently create another one.
-8. Task completion remains manual.
+1. On first use the sidebar starts on `Tasks`; afterward it restores the last
+   active sidebar view. It remembers its width/collapsed state locally and keeps
+   a compact activity rail available while collapsed.
+2. Tasks are grouped by type. Dragging a task reorders it; dropping it into a
+   different group also changes its type and updates `updatedAt`.
+3. Task rows show the title when present. Untitled tasks use the first line of
+   description as their display label, or `Untitled task` when they contain only
+   attachments. Rows also show status, session/run action, edit, and delete
+   controls. Status uses icon, text, and color rather than color alone.
+4. Manual creation through the task editor still requires a non-empty title.
+   Tasks start with status `todo` and priority `medium`, and may include
+   description text and attachments. Newly selected/pasted task attachments are
+   persisted into `.pi/task-attachments` so the task owns its files. Existing
+   untitled composer-captured tasks may be edited without inventing a title as
+   long as description content or attachments remain.
+5. Editing changes title, description, and type. Status is changed separately.
+   Existing persisted priority is preserved.
+6. `.pi/tasks.jsonc` is authoritative. Missing `.pi`/task storage produces an
+   empty version-1 document. JSONC comments and trailing commas are accepted.
+7. Only `.pi/tasks.jsonc` is recognized as task storage. Other sibling task
+   files are ignored; Pix does not import, migrate, delete, or interpret them.
+8. Starting an unlinked task creates/selects a new ACP session, persists its
+   session id, changes any non-`done` task to `in-progress`, preserves `done`,
+   appends the generated task prompt, and sends it immediately.
+9. Starting a linked task opens that session. A stale/missing linked session is
+   a recoverable error and does not silently create another session.
+10. Task completion remains manual.
+11. The normal message composer's vertical-ellipsis menu exposes `Create task`
+    whenever the current draft has text, attachments, or active voice input.
+    Voice input is finalized first. The resulting task has an empty persisted
+    title, type `feature`, status `todo`, priority `medium`, and stores the
+    composer text plus attachment markers in its description. The prompt is not
+    sent to the agent. Composer attachments are persisted into
+    `.pi/task-attachments` before those markers are written; path-backed files
+    are copied there and pathless images are materialized from their bytes.
+12. After composer task persistence succeeds, Pix expands/selects the Tasks
+    sidebar view, scrolls the newly created task into view, highlights it, and
+    clears the composer only if the draft is still the exact draft that was
+    captured for task creation. A failed save or edits made while the save is in
+    flight preserve the composer.
+13. After a task-document write succeeds, Pix prunes regular files from
+    `.pi/task-attachments` that are no longer referenced by any remaining task.
+    Shared attachments stay on disk until the last task reference is removed.
+14. Every successful task-document write also marks the Registry `tasks` project
+    artifact dirty for background synchronization. Rapid task mutations are
+    debounced/coalesced; a failed local write never enters the remote sync queue.
+    If the Registry session is busy, the dirty task state remains pending until
+    an idle sync window is available.
 
 ## Contracts
 
-- Project file: `.pi/tasks.json` containing `{ version: 1, tasks: [...] }`.
-- Every task has a unique id, title, type, status, priority, `createdAt`, and
-  `updatedAt`; description and `sessionId` may be omitted.
-- Tauri exposes narrow read/write commands for this one file. Workspace paths
-  are validated and `.pi` symlinks may not escape the workspace.
-- The webview sends a complete validated document on each mutation. Writes use
-  a same-directory temporary file and replacement to avoid partial JSON.
+- Project file: `.pi/tasks.jsonc`.
+- Document shape: optional `$schema`, `version: 1`, and `tasks`.
+- Each task has a unique id, string title, type, status, priority, `createdAt`,
+  and `updatedAt`; description and `sessionId` are optional. The title may be an
+  empty string only when description content is present.
+- Unknown fields, duplicate ids, unsupported enum values, completely empty task
+  content, malformed timestamps, unsupported versions, and oversized documents
+  are rejected.
+- The Tauri backend confines task paths to the active workspace, rejects escape
+  through `.pi` symlinks, and caps the document at 1 MB.
+- Writes validate the complete document, write a same-directory temporary file,
+  and replace the target to avoid partial JSONC files.
 
 ## Invariants
 
-- The task document version must be supported before it is displayed or saved.
-- Duplicate ids, unknown enum values, empty titles, and malformed timestamps
-  are rejected.
-- A task is linked to at most one session in this MVP.
-- Starting a task is disabled while another prompt/session operation is active.
-- A failed save does not leave the UI claiming a task state that was not
-  persisted.
+- Failed validation never replaces the task file.
+- Failed persistence restores the previous in-memory task document.
+- Composer task creation never clears a newer draft that changed while task
+  persistence was in flight.
+- Task attachments are persisted through the same task-description marker
+  format used by the task editor, and newly attached files are owned by the
+  project's `.pi/task-attachments` storage so running the task restores them
+  without depending on the expiring chat cache or original source path.
+- Attachment cleanup runs only after the replacement `tasks.jsonc` has been
+  committed successfully. Cleanup is reference-based across the complete task
+  document and never deletes paths outside `.pi/task-attachments`.
+- Create/edit/delete/status/reorder/session-link task mutations all flow through
+  the same save method, so they share the same background Registry scheduling
+  semantics.
+- A task is linked to at most one session.
+- Running/reordering/editing is disabled while conflicting task/session work is
+  active.
+- Dragging between groups changes only ordering/type; other task fields survive.
 
 ## Edge cases
 
-- Switching workspaces discards the previous workspace's in-memory task view
-  and loads the new project file.
-- Empty and missing files have distinct behavior: missing means no tasks;
-  malformed or empty JSON is an error.
-- Save, session creation, and prompt failures remain visible and retryable.
-- Collapsing the sidebar keeps its tab rail available; choosing a tab expands
-  it.
+- Switching workspaces discards the previous in-memory task view and loads the
+  new project's task document.
+- Missing storage means no tasks; malformed or empty `.pi/tasks.jsonc` is an error.
+- Unsupported sibling task files do not participate in task loading.
+- Save, session creation, attachment preparation, and prompt failures remain
+  visible and retryable.
 
 ## Related files
 
-- `desktop/src/App.svelte`
-- `desktop/src/components/`
-- `desktop/src/lib/`
-- `desktop/src/styles.css`
+- `desktop/src/app/project-actions.svelte.ts`
+- `desktop/src/app/desktop-project-action-services.ts`
+- `desktop/src/components/PromptComposerActionsMenu.svelte`
+- `desktop/src/components/WorkspaceSidebar.svelte`
+- `desktop/src/components/workspace-sidebar-layout-controller.svelte.ts`
+- `desktop/src/components/workspace-sidebar-task-drag-controller.svelte.ts`
+- `desktop/src/components/WorkspaceSidebarTasksPanel.svelte`
+- `desktop/src/components/WorkspaceSidebarTaskEditor.svelte`
+- `desktop/src/lib/attachments.ts`
+- `desktop/src/lib/attachments.test.ts`
+- `desktop/src/lib/project-tasks.ts`
+- `desktop/src/lib/project-tasks.test.ts`
 - `desktop/src-tauri/src/lib.rs`
+- `src/schemas/tasks-schema.ts`
 
 ## Verification
 
-- Unit tests for task parsing, validation, filtering, prompt generation, and
-  sidebar preference parsing.
-- Rust tests for missing/read/write/malformed files and workspace escape.
-- `npm --prefix desktop test`
-- `npm --prefix desktop run check`
-- `npm --prefix desktop run build:web`
-- `cargo test --manifest-path desktop/src-tauri/Cargo.toml`
+- `desktop/src/lib/project-tasks.test.ts` covers untitled composer task creation,
+  parsing, prompt generation, and drag/reorder semantics.
+- `desktop/src/lib/attachments.test.ts` covers data-URL decoding used when a
+  pathless composer image is persisted into project task storage.
+- Rust tests in `desktop/src-tauri/src/lib.rs` cover missing/read/write/malformed
+  JSONC, validation, workspace confinement, and ignoring unsupported task files.
+- Run `npm --prefix desktop test`, `npm --prefix desktop run check`, and
+  `cargo test --manifest-path desktop/src-tauri/Cargo.toml`.
 
 ## Risks / unknowns
 
-- Whole-document writes assume one active desktop writer per project.
-- A linked session may later be removed outside Pix Desktop; the first version
-  reports this rather than automatically unlinking it.
-- Windows replacement semantics may require a fallback around replacing an
-  existing task file while retaining best-effort crash safety.
+- Whole-document writes assume one active writer per project; multi-window merge
+  semantics remain out of scope.
+- A linked session can be removed outside Pix Desktop and remains linked until
+  the user repairs or edits the task.
+- Priority remains part of the persisted schema although the current UI does not
+  expose priority editing.
 
 ## Evidence
 
-- Confirmed by code: desktop session creation/loading and prompt submission are
-  orchestrated in `desktop/src/App.svelte` through `AcpClient`.
-- Confirmed by code: Tauri already validates workspace-contained project file
-  reads in `desktop/src-tauri/src/lib.rs`.
-- Confirmed by tests: session tab ordering and ACP request behavior have focused
-  Vitest coverage under `desktop/src/lib/`.
-- Confirmed by docs: `DESIGN.md` specifies a compact persistent sidebar,
-  semantic theme roles, Lucide icons, and non-color status cues.
-- Implemented: `.pi/tasks.json` now has an explicit version-1 contract and
-  rejects unsupported versions rather than guessing a migration.
-- Verified by tests: all 82 desktop Vitest tests and all 8 Rust tests pass;
-  Svelte/TypeScript checks report no errors or warnings.
-- Verified visually: browser QA covered clean preference state, resize/collapse,
-  tabs, filters, and semantic colors in light/dark themes.
-- Verified natively: actual Tauri UI/backend CRUD, Run, persisted linkage,
-  Open session without duplication, and delete cleanup all passed.
+- Confirmed by code: `desktop/src/app/project-actions.svelte.ts`,
+  `desktop/src/app/desktop-project-action-services.ts`, the extracted composer/
+  sidebar task surfaces, and `desktop/src/lib/project-tasks.ts` implement the
+  current task lifecycle and composer capture action.
+- Confirmed by code: `desktop/src-tauri/src/lib.rs` owns JSONC persistence,
+  validation, confinement, atomic replacement, and ignores unsupported sibling
+  task-storage formats.
+- Confirmed by tests: project-task unit tests and Tauri task persistence tests.

package/docs/release.md

@@ -13,15 +13,39 @@ npm run smoke-test
 `release:check` runs type checking, the test suite, a production build, and `npm pack --dry-run`.
 `smoke-test` packs the real tarball, installs it into an isolated temp directory, checks the bundled files, and runs non-interactive `pix` commands from the installed package.
 
-## Publish a new npm version
+## CI regression guardrails
 
-Pix uses the same release style as `indexer-cli`: a local command bumps the version, smoke-tests the tarball, then pushes the release commit and tag. GitHub Actions publishes the tag to npm using the `NPM_TOKEN` repository secret.
+The normative CI invariants are recorded in [`specs/ci-release.md`](../specs/ci-release.md). This section is the operational checklist for release work.
 
-One-time setup:
+The GitHub Actions release workflow has two different responsibilities and they should stay separate:
 
-```bash
-gh secret set NPM_TOKEN
-```
+- `build-and-test` runs on Ubuntu, macOS, and Windows. This is the cross-platform correctness gate: type checks, unit/integration tests, platform-specific host checks, and the Pix build belong here.
+- Package smoke tests validate the artifact a user actually installs. Run the full payload/tarball smoke test on Ubuntu, and a smaller pack/install/CLI sanity check on Windows. A separate macOS package smoke job is unnecessary unless packaging gains macOS-specific behavior.
+
+Keep CI tests deterministic across runner speed and operating systems:
+
+- Assert explicit byte/count/state thresholds instead of assuming a background producer will do enough work within a short wall-clock interval. For example, a truncation test should write a fixed amount greater than the limit rather than write repeatedly for 300 ms and assume the runner will exceed the limit.
+- Use timers only when timeout behavior itself is the contract. Do not use elapsed time as a proxy for produced output, process progress, or cleanup completion.
+- When a test needs asynchronous process teardown, wait for an observable owned-process condition rather than relying on a short sleep.
+- Run configuration-sensitive suite checks with an isolated `HOME` when reproducing CI locally. User-level Pix/pi-tools-suite config can intentionally change DCP and other opt-in behavior and must not be mistaken for a CI regression.
+
+Windows process tests have additional invariants:
+
+- `@lydell/node-pty` on Windows does not support POSIX signal arguments to `kill`; terminate an owned Windows PTY with signal-less `kill()` and release its ConPTY resources.
+- Browser/process cleanup must stay ownership-scoped. When a PowerShell helper discovers descendants, it must not select or terminate itself; kill owned child roots recursively and verify cleanup before returning.
+- Treat CRLF/LF differences as presentation differences unless line endings are the behavior under test.
+
+Package smoke assertions should check stable package contracts. If a bundled guide title, required payload path, CLI entry point, or other intentionally asserted artifact changes, update the corresponding smoke assertion in the same change. Do not remove the smoke test merely because ordinary source tests are green: source tests do not prove that `npm pack` contains an installable, runnable artifact.
+
+Current implementation:
+
+- `.github/workflows/publish.yml` owns the CI matrix and release gates.
+- `scripts/smoke-test-package.sh` is the full packed-artifact/payload smoke test.
+- `scripts/smoke-test-package-cli.mjs` is the cross-platform pack/install/CLI sanity check used on Windows.
+
+## Publish a new npm version
+
+Pix uses the same release style as `indexer-cli`: a local command bumps the version, smoke-tests the tarball, then pushes the release commit and tag. GitHub Actions publishes the tag to npm using npm trusted publishing (GitHub OIDC), so the publish job does not require a long-lived `NPM_TOKEN` secret.
 
 Release commands: