From e448effd2f6890692ff6174c61357ca07db041b9 Mon Sep 17 00:00:00 2001 From: typebasedio Date: Thu, 7 May 2026 20:54:29 -0400 Subject: [PATCH] docs(v0.5.2): record v0.5.2 completion in notes.md Add the v0.5.2 round summary (commits a5e508b..3b6be0d + 5910100): restore/notes/path commands, direct-lookup archived-inclusive policy, resume archived hint, list --names, shell completion, cross-workspace context seed section. Windows + WSL validation passed; Linux binary statically linked. Add load-bearing v0.5.2 invariants to the "don't unlearn" section (archived-inclusive lookup policy, list --names emits basenames not slugs, completion calls ListWorkspaces directly, etc.). Replace the "Next: v0.5.2" pointer with a "Next: v0.6 (planning)" stub covering config/agent profile work, resume-error polish, and flag-aware completion for open/delete --all. Drop v0.5.2-spec.md from the untracked-files list (committed in a5e508b). --- notes.md | 67 +++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 54 insertions(+), 13 deletions(-) diff --git a/notes.md b/notes.md index 994dd88..a1ceee0 100644 --- a/notes.md +++ b/notes.md @@ -1,6 +1,6 @@ # ctask — Session Handoff Notes -Last touched: 2026-05-07 (after v0.5.1 Linux baseline merge). Pause before starting v0.5.2. +Last touched: 2026-05-07 (after v0.5.2 ship). Pause before starting v0.6. ## Where we are @@ -81,20 +81,52 @@ Two rounds shipped under the v0.5.1 tag: **wall-clock date for user-facing surfa - **`WorkspacePath` removed from `TaskMeta`.** The audit (`audit-report.md`) confirmed the field was write-only with no production readers — it persisted an absolute Windows path into `task.yaml` that would have been misleading on cross-OS shares. Existing `task.yaml` files with `workspace_path` continue to load (Go's YAML unmarshal silently ignores unknown fields). `TestMetaTypeMissingDefaultsToTask` keeps the legacy YAML literal in its fixture as a backward-compat regression guard. - **Validation:** Windows `go test ./...` green across all 7 packages; cross-compile produces ELF x86-64. **WSL-native validation passed:** `go test ./... -count=1` green; `just build-linux` produces a `statically linked` ELF (`ldd` reports `not a dynamic executable`); `./scripts/install.sh` installs to `~/.local/bin/ctask` and registers the statusline helper; `ctask doctor` recognizes the Linux statusline helper. -### Next: v0.5.2 +### What v0.5.2 delivered -Workspace retrieval and cross-workspace context (spec at `v0.5.2-spec.md`): +Theme: **workspace retrieval and cross-workspace context**. Five feature commits (`a5e508b..3b6be0d`) plus a version bump (`5910100`). -- `ctask restore ` — un-archive (metadata-only) -- `ctask notes ` — print another workspace's `notes.md` to stdout (raw, agent-consumable) -- `ctask path ` — print the absolute filesystem path -- `ctask info ` — archived-inclusive by default; drop the `--all` flag -- `ctask resume ` — fail with a restore hint instead of generic "not found" -- `ctask list --names` — machine-readable enumeration of workspace directory basenames -- `ctask completion {bash,zsh,fish,powershell}` — Cobra-generated, with `ValidArgsFunction` hooks per command -- Seed CLAUDE.md gets a concise cross-workspace context section +- **Three new direct-lookup commands** (`176e788`): + - `ctask restore ` — un-archive (metadata-only flip; mirrors archive's lease guard; refuses already-active workspaces) + - `ctask notes ` — stream `notes.md` to stdout raw, no framing; `[ctask]`-prefixed stderr on missing file (`SilenceErrors: true` so the spec format is the only diagnostic shown) + - `ctask path ` — print absolute filesystem path on one line, OS-native separators +- **Direct-lookup commands are archived-inclusive by default** (`b923ae8`). The `--all/-a` flag was dropped from `info` entirely; the `Status:` line in info output surfaces archived state. `delete` and `open` keep their `--all` flags (they are potentially destructive). `resume` and `archive` resolve archived-inclusive then filter, so they can give actionable error messages. +- **`ctask resume ` prints a restore hint** (`b923ae8`): -Lookup policy: **listing is filtered, direct lookup is comprehensive**. Active-only (`resume`, `archive`); archived-inclusive by default (`info`, `notes`, `path`, `restore`); current `--all/-a` semantics preserved on `delete` and `open`. + ``` + [ctask] error: workspace "X" is archived + + To restore it: + ctask restore X + ``` + + Genuine not-found and ambiguity behavior preserved. +- **`ctask list --names`** (`56d2e07`) — machine-readable enumeration. One workspace directory basename per line, no header. Empty stdout on no match (no "No workspaces found." placeholder). Honors all existing list filters. Spec invariant `TestListNamesCandidatesResolveUniquely` enforces that every emitted line resolves to exactly one workspace. +- **Shell completion via Cobra** (`176e788`, `b923ae8`). `ctask completion {bash,zsh,fish,powershell}` works through Cobra's auto-injected subcommand. `ValidArgsFunction` hooks per spec policy: + - `resume`, `archive` → active only + - `restore` → archived only + - `info`, `notes`, `path` → both + - `delete`, `open` → active only (flag-aware completion deferred) + + Candidates are workspace directory basenames (unique under the resolver's exact-match step), not bare slugs (which can collide across categories or dates). +- **Cross-workspace context section in seed CLAUDE.md** (`3b6be0d`). Both task and project templates teach agents to inspect related workspaces with `list --all` / `info` / `notes` / `path` before starting work, and to treat other workspaces as read-only. Applies to newly-created workspaces only — no retroactive overwrite of existing CLAUDE.md files. +- **Version bump** to `0.5.2` (`5910100`). + +**Validation:** + +- Windows: `go test ./... -count=1` green across all 7 packages; `go vet` clean; `go build` clean. End-to-end smoke against the binary covered the full archive ↔ restore cycle plus completion-script generation. +- WSL/Linux: refreshed validation copy; reinstalled via `install.sh`; full smoke checklist passed (16 behaviors across new + active + archived + restore + completion). Cross-built Linux binary is statically linked (`file` reports `statically linked`; `ldd` reports `not a dynamic executable`). + +### Known limitation (v0.5.2) + +- **`ctask resume ` prints `Error: workspace archived` below the actionable hint.** Cosmetic only — the user-visible hint is shown first and is correct. Suppressing the trailing line would require `SilenceErrors: true` on `resume`, which would also swallow unrelated session-launch errors. Acceptable trade; revisit only if the redundancy actively confuses users. + +### Next: v0.6 (planning) + +Not yet specced. Likely scope: + +- **Config / agent profile work.** The long-flagged direction towards `~/.config/ctask/` configuration; may supersede the env-var resolution dance for `CTASK_ROOT`/`CTASK_PROJECT_ROOT`/`CTASK_SEED_DIR`/`CTASK_AGENT`. +- **Optional polish for resume error output.** Silence the trailing Cobra "Error: workspace archived" line — likely via per-error-path `SilenceErrors` or a sentinel-error wrapper. +- **Flag-aware completion for `open`/`delete --all`.** Cobra supports `RegisterFlagCompletionFunc` per flag; would let completion offer archived candidates only when `--all` is passed. ## Post-v0.4 bugfixes (still live, carried forward) @@ -114,7 +146,6 @@ Covered in v0.4.1 notes. The exit-code gate (`childExitCode != 0 && startManifes - `docs/superpowers/plans/2026-04-22-v0.4.1-patch.md` (v0.4.1 plan — executed) - `docs/superpowers/plans/2026-04-22-v0.5-implementation.md` (v0.5 plan — executed) - `v0.4-spec.md`, `v0.4.1-patch-spec.md`, `v0.5-spec.md` (specs the implementations followed) - - `v0.5.2-spec.md` (next-round spec, in progress) ## How to resume @@ -201,6 +232,16 @@ ctask list --projects - **`WorkspacePath` is gone from `TaskMeta`.** Don't add it back. If a persistent workspace identifier is ever needed, add a properly relative-to-root `workspace_id` (forward-slash normalized). Old `task.yaml` files with `workspace_path` parse silently — the field is ignored on read. - **POSIX install script does not modify shell config.** It warns the user about PATH but never edits `~/.bashrc` / `~/.zshrc`. Don't change this without an explicit user request. +### From v0.5.2 (new — don't unlearn) + +- **`info` no longer has `--all`/`-a`.** Direct lookup is archived-inclusive by default. Don't add the flag back. The `Status:` line in info output makes archived state obvious. `TestInfoFindsArchivedWorkspaceWithoutFlag` enforces this. +- **`resume` / `archive` resolve archived-inclusive then filter.** Don't switch back to `includeArchived=false` at the resolver layer. The two-step pattern (resolve broadly, reject explicitly) is what lets `resume` give the actionable restore hint instead of a generic "not found". +- **Direct-lookup commands (`info`, `notes`, `path`, `restore`) use `includeArchived=true`.** Active-only commands (`resume`, `archive`) reject archived after resolve. Potentially-destructive commands (`delete`, `open`) keep their explicit `--all` opt-in. Don't drift back to a uniform default — the policy is intentional. See `v0.5.2-spec.md` "Workspace Lookup Policy". +- **`list --names` emits directory basenames, not bare slugs.** Bare slugs can collide (e.g., `promptvolley` archived in v1, active in v2). Basenames are unique under the resolver's exact-match step. `TestListNamesCandidatesResolveUniquely` enforces the invariant. +- **`ValidArgsFunction` hooks call `workspace.ListWorkspaces` directly.** No subprocess shell-out to `ctask list --names`. Don't add one — direct calls are faster and don't depend on PATH state. +- **Cobra adds the `completion` subcommand lazily on first `Execute()`.** A test that calls `rootCmd.Find("completion")` before any `Execute()` returns "unknown command". For unit tests, prefer the `rootCmd.GenXxxCompletion(...)` generators directly. For end-to-end, one `SetArgs(...)` + `Execute()` per test — running multiple `Execute()` calls in succession with different shell args has state issues. +- **`notes` uses `SilenceErrors: true`** so the `[ctask] no notes.md found in workspace "X"` stderr line is the only diagnostic the user/agent sees. Don't set `SilenceErrors: false` and add a `[ctask]` prefix to the returned error message — Cobra would then print both, doubling the message. + ## Open follow-ups (NOT in v0.4/v0.4.1/v0.5, deferred) ### Potentially worth doing