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 ina5e508b).
This commit is contained in:
@@ -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 <workspace>` — un-archive (metadata-only)
|
||||
- `ctask notes <workspace>` — print another workspace's `notes.md` to stdout (raw, agent-consumable)
|
||||
- `ctask path <workspace>` — print the absolute filesystem path
|
||||
- `ctask info <workspace>` — archived-inclusive by default; drop the `--all` flag
|
||||
- `ctask resume <archived-workspace>` — 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 <ws>` — un-archive (metadata-only flip; mirrors archive's lease guard; refuses already-active workspaces)
|
||||
- `ctask notes <ws>` — 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 <ws>` — 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 <archived-ws>` 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 <archived-ws>` 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
|
||||
|
||||
Reference in New Issue
Block a user