@taskset/cli 4.0.0 → 6.0.0

package/docs/cli-reference.md

@@ -0,0 +1,461 @@
+---
+title: Look up Taskset CLI commands
+description: Complete reference for the taskset command-line interface.
+contentType: Reference
+navLabel: CLI Reference
+---
+
+# Look up Taskset CLI commands
+
+The `taskset` command is a thin adapter over `@taskset/core` for the full Taskset surface: stories, flows, research, decisions, runbooks, and tasks. It parses arguments, validates options, calls core operations, and renders human or JSON output.
+
+Invoke it with `npx @taskset/cli`, `pnpm dlx @taskset/cli`, `yarn dlx @taskset/cli`, `bunx @taskset/cli`, a project binary, or a global install. Examples below use `taskset` directly.
+
+## Common Behavior
+
+```bash
+taskset help
+taskset --help
+taskset -h
+```
+
+Running without a command also prints usage. These help paths exit with code
+`0`.
+
+Most repository commands accept:
+
+| Option | Description |
+| --- | --- |
+| `--cwd <path>` | Resolve repository discovery from another working directory. |
+| `--json` | Emit structured JSON instead of human-readable text where supported. |
+
+Stdout is reserved for requested output. Diagnostics, validation failures, and
+best-effort generated-view refresh warnings are written to stderr.
+
+Exit codes:
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Command succeeded. |
+| `1` | Repository or domain operation failed, such as invalid task state or delete blockers. |
+| `2` | CLI usage, argument validation, path normalization, or parse validation failed. |
+
+## Repository Commands
+
+### `init`
+
+```bash
+taskset init [--config] [--cwd <path>]
+```
+
+Initializes a Taskset repository. The command resolves a root from an existing `.taskset/`, Git or workspace markers, or the working directory, then creates `.taskset/` task and document directories plus `.taskset/.gitignore` when they do not already exist. Pass `--config` to also write optional `taskset.config.ts`.
+
+Human output:
+
+```text
+Initialized Taskset in <root-directory>
+```
+
+### `config`
+
+```bash
+taskset config [--json] [--cwd <path>]
+```
+
+Discovers the nearest `.taskset/` directory by walking upward from the working directory. Optional `taskset.config.ts` at that root overlays defaults when present.
+
+Human output is the config file path when a config exists, or `defaults (<root-directory>)` when it does not. JSON output contains:
+
+```json
+{
+  "rootDirectory": "...",
+  "configPath": "...",
+  "hasConfig": false,
+  "dataDirectory": "...",
+  "config": {}
+}
+```
+
+### `doctor`
+
+```bash
+taskset doctor [--json] [--cwd <path>]
+```
+
+Validates the repository without modifying files. It scans canonical task
+metadata, paths, and graph relationships.
+
+Human success output:
+
+```text
+Taskset repository is valid (<count> tasks)
+```
+
+Human failure output is tab-separated:
+
+```text
+<code>	<path-or->	<message>	<remediation>
+```
+
+JSON output is the full doctor result, including `valid`, `taskCount`, and
+diagnostics.
+
+### `generate`
+
+```bash
+taskset generate [--json] [--cwd <path>]
+```
+
+Rebuilds disposable generated views under each entity folder's `.generated/`
+directory (for example `.taskset/tasks/.generated/` and
+`.taskset/stories/.generated/`). Removes any legacy `.taskset/generated/` tree.
+
+Human output:
+
+```text
+Generated <count> views in <directory>
+```
+
+JSON output is the generated-views result with the target directory and written
+files.
+
+## Snapshot Commands
+
+Snapshots are non-authoritative safety checkpoints under `.taskset/snapshots/`.
+Git remains the normal history and collaboration mechanism.
+
+### `snapshot create`
+
+```bash
+taskset snapshot create [--json] [--cwd <path>]
+```
+
+Creates an immutable archive of canonical task files.
+
+Human output is the snapshot ID. JSON output is the snapshot manifest.
+
+### `snapshot list`
+
+```bash
+taskset snapshot list [--json] [--cwd <path>]
+```
+
+Lists available snapshots.
+
+Human output is tab-separated:
+
+```text
+<snapshot-id>	<created-at>	<file-count>
+```
+
+JSON output is an array of snapshot manifests.
+
+### `snapshot restore`
+
+```bash
+taskset snapshot restore <snapshot-id> [--apply] [--json] [--cwd <path>]
+```
+
+Previews or restores canonical task files from a snapshot. The default is a dry
+run. Use `--apply` to mutate task files.
+
+Human output:
+
+```text
+Would restore <count> task files from <snapshot-id>
+Restored <count> task files from <snapshot-id>
+```
+
+JSON output is the restore result, including `applied` and `changes`.
+
+## Task Metadata Options
+
+`task create` and `task update` accept the same metadata options unless noted.
+Array options are repeatable.
+
+| Option | Field | Notes |
+| --- | --- | --- |
+| `--title <title>` | `title` | Required for create, optional for update. |
+| `--status <status>` | `status` | One of `todo`, `doing`, `blocked`, `done`, `canceled`. |
+| `--priority <priority>` | `priority` | One of `low`, `medium`, `high`, `urgent`. |
+| `--order <number>` | `order` | Nonnegative finite number. Lower values sort first. |
+| `--label <label>` | `labels` | Repeatable. |
+| `--depends-on <task-id>` | `dependsOn` | Repeatable. |
+| `--file <path>` | `files` | Repeatable; normalized to a repository-relative POSIX path. |
+| `--owner <owner>` | `owner` | Trimmed string. |
+| `--assignee <assignee>` | `assignees` | Repeatable. |
+| `--reviewer <reviewer>` | `reviewers` | Repeatable. |
+| `--team <team>` | `team` | Trimmed string. |
+| `--estimate <minutes>` | `estimate` | Nonnegative integer. |
+| `--effort <value>` | `effort` | Nonnegative finite number. |
+| `--risk <risk>` | `risk` | One of `low`, `medium`, `high`. |
+| `--due-date <date>` | `dueDate` | `YYYY-MM-DD` or `YYYY-MM-DD HH:mm UTC`. |
+| `--related <task-id>` | `related` | Repeatable. |
+| `--duplicate <task-id>` | `duplicates` | Repeatable. |
+| `--parent <task-id>` | `parent` | Single task ID. |
+| `--directory <path>` | `directories` | Repeatable; normalized to a repository-relative POSIX path. |
+| `--project <project>` | `projects` | Repeatable. |
+| `--body <markdown>` | body | Replaces the Markdown body. |
+| `--json` | output | Emit a task record as JSON. |
+| `--cwd <path>` | discovery | Resolve repository discovery from another directory. |
+
+## Task Commands
+
+### `task create`
+
+```bash
+taskset task create --title <title> [metadata options] [--json] [--cwd <path>]
+```
+
+Creates a versionless task file using repository defaults for omitted
+configured fields.
+
+Human output is the task ID. JSON output is a task record containing
+`relativePath` and metadata fields.
+
+### `task list`
+
+```bash
+taskset task list [query options] [--json] [--cwd <path>]
+```
+
+Lists tasks using metadata, relationship, planning, timestamp, text, path, and
+impact filters.
+
+Filter options:
+
+| Option | Description |
+| --- | --- |
+| `--status <status>` | Repeatable; OR within statuses. |
+| `--priority <priority>` | Repeatable; OR within priorities. |
+| `--label <label>` | Repeatable; every requested label must be present. |
+| `--owner <owner>` | Repeatable; OR within owners. |
+| `--assignee <assignee>` | Repeatable; OR within assignees. |
+| `--reviewer <reviewer>` | Repeatable; OR within reviewers. |
+| `--team <team>` | Repeatable; OR within teams. |
+| `--risk <risk>` | Repeatable; OR within risks. |
+| `--project <project>` | Repeatable; OR within projects. |
+| `--depends-on <task-id>` | Match a direct dependency. |
+| `--related <task-id>` | Match a related task. |
+| `--duplicate <task-id>` | Match a duplicate task relationship. |
+| `--parent <task-id>` | Match a direct parent. |
+| `--file <path>` | Repeatable; unified containment query over `files` and `directories`. |
+| `--directory <path>` | Repeatable; containment query over `directories` only. |
+| `--estimate-min <minutes>` | Inclusive minimum estimate. |
+| `--estimate-max <minutes>` | Inclusive maximum estimate. |
+| `--effort-min <value>` | Inclusive minimum effort. |
+| `--effort-max <value>` | Inclusive maximum effort. |
+| `--due-before <date>` | Inclusive due-date upper bound. |
+| `--due-after <date>` | Inclusive due-date lower bound. |
+| `--created-before <date>` | Inclusive created-at upper bound. |
+| `--created-after <date>` | Inclusive created-at lower bound. |
+| `--updated-before <date>` | Inclusive updated-at upper bound. |
+| `--updated-after <date>` | Inclusive updated-at lower bound. |
+| `--search <text>` | Search task title and Markdown body; every whitespace-separated term must match. |
+| `--sort <key>` | Sort key. |
+| `--direction <asc|desc>` | Sort direction. |
+| `--impact` | Add tasks that transitively depend on direct matches. |
+| `--include-derived` | Include derived relationship projections in JSON output. |
+
+Sort keys are `id`, `title`, `status`, `priority`, `order`, `owner`, `team`,
+`estimate`, `effort`, `risk`, `dueDate`, `createdAt`, and `updatedAt`. With
+`--sort order`, tasks without `order` sort after ordered tasks; duplicate
+values fall back to task ID ordering.
+
+Different filter categories compose with AND. Repeated enum, person, project,
+file, and directory values use OR within their category. Repeated labels are
+stricter and require all requested labels.
+
+Search is Unicode-normalized and case-insensitive. Its terms may occur in any
+order or location across the combined title and Markdown body, so
+`--search "cache invalidation"` does not require that exact phrase.
+
+Without `--impact`, human output is:
+
+```text
+<task-id>	<status>	<title>
+```
+
+With `--impact`, human output prefixes direct and impacted rows:
+
+```text
+direct	<task-id>	<status>	<title>
+impact	<task-id>	<status>	<title>
+```
+
+JSON output without `--impact` is an array of task records. JSON output with
+`--impact` is:
+
+```json
+{
+  "direct": [],
+  "impacted": []
+}
+```
+
+Use `--include-derived` to include `blockedBy`, `blocks`, `children`, and
+`subtasks` projections in each JSON record.
+
+### `task show`
+
+```bash
+taskset task show <task-id> [--include-derived] [--json] [--cwd <path>]
+```
+
+Shows one task by ID.
+
+Human output is the serialized task Markdown. JSON output contains:
+
+```json
+{
+  "relativePath": ".taskset/tasks/0000001-short-title-a1b2c3.md",
+  "metadata": {},
+  "body": "...",
+  "derived": {}
+}
+```
+
+The `derived` property is present only with `--include-derived`.
+
+### `task update`
+
+```bash
+taskset task update <task-id> [metadata options] [clear options] [--json] [--cwd <path>]
+```
+
+Updates one task. At least one non-control option is required. A field cannot
+be set and cleared in the same command.
+
+Clear options:
+
+| Option | Effect |
+| --- | --- |
+| `--clear-priority` | Remove `priority`. |
+| `--clear-order` | Remove `order`. |
+| `--clear-labels` | Replace `labels` with an empty list. |
+| `--clear-dependencies` | Replace `dependsOn` with an empty list. |
+| `--clear-files` | Replace `files` with an empty list. |
+| `--clear-owner` | Remove `owner`. |
+| `--clear-assignees` | Replace `assignees` with an empty list. |
+| `--clear-reviewers` | Replace `reviewers` with an empty list. |
+| `--clear-team` | Remove `team`. |
+| `--clear-estimate` | Remove `estimate`. |
+| `--clear-effort` | Remove `effort`. |
+| `--clear-risk` | Remove `risk`. |
+| `--clear-due-date` | Remove `dueDate`. |
+| `--clear-related` | Replace `related` with an empty list. |
+| `--clear-duplicates` | Replace `duplicates` with an empty list. |
+| `--clear-parent` | Remove `parent`. |
+| `--clear-directories` | Replace `directories` with an empty list. |
+| `--clear-projects` | Replace `projects` with an empty list. |
+
+Human output is the task ID. JSON output is the updated task record.
+
+### `task status`
+
+```bash
+taskset task status <task-id> <status> [--json] [--cwd <path>]
+```
+
+Updates only task status and enforces lifecycle transition rules. `done` and
+`canceled` are terminal states.
+
+Human output is the task ID. JSON output is the updated task record.
+
+### `task delete`
+
+```bash
+taskset task delete <task-id> [--remove-dependencies] [--json] [--cwd <path>]
+```
+
+Deletes one task. By default, deletion is blocked while another task has an
+inbound canonical dependency on the target. Use `--remove-dependencies` to
+remove those inbound references and delete the target in one mutation.
+
+Human output is the deleted task ID. JSON output contains `deleted: true`
+alongside the deleted task record.
+
+### `task migrate-ids`
+
+```bash
+taskset task migrate-ids [--json] [--cwd <path>]
+```
+
+Atomically converts legacy `TS-` and sequential task IDs to immutable short hex
+IDs, normalizes filenames to `{sequence}-{slug}-{id}.md`, repairs duplicate
+sequence prefixes by `createdAt`, and rewrites canonical relationships plus
+references in repository text files. Dependencies, Git internals, build output,
+caches, generated views, indexes, and snapshots are excluded. Human output is a
+tab-separated old-to-new mapping; JSON emits the same mapping as objects.
+
+### `sync`
+
+```bash
+taskset sync [--concurrency <count>] [--json] [--cwd <path>]
+```
+
+Ensures every canonical document directory exists under `.taskset`, migrates
+legacy task and document IDs to short hex IDs, normalizes filenames, repairs
+duplicate sequence prefixes by `createdAt`, rewrites repository text
+references, and rebuilds generated views. Progress counts and percentages are
+sent to stderr.
+
+## Document Commands
+
+`document` may be shortened to `doc`. Supported types are `story`, `flow`,
+`decision`, `research`, and `runbook`; `adr` and `dr` alias `decision`.
+
+```bash
+taskset document create <type> --title <title> [metadata options]
+taskset document import <markdown-path> [--type <type>] [--title <title>] [--move]
+taskset document batch <manifest.json> [--concurrency <count>] [--json]
+taskset document list [type] [query options]
+taskset document show <document-id> [--type <type>] [--include-derived] [--json]
+taskset document update <document-id> [metadata options] [--type <type>]
+taskset document status <document-id> <status> [--type <type>] [--json]
+taskset document delete <document-id> [--type <type>] [--remove-dependencies] [--json]
+```
+
+Create uses the type-specific template unless `--body` is supplied and accepts
+the same metadata options as `task create`. Import preserves the Markdown body
+and infers type from a recognized parent directory when possible. It copies by
+default; `--move` deletes the source only after the canonical document is
+written successfully.
+
+List, show, update, status, and delete mirror the task commands, including
+search, filters, sort, impact, derived relationships, clear flags, and
+guarded deletion. Document statuses are `draft`, `ready`, `active`, `accepted`,
+`superseded`, and `archived`.
+
+Batch manifests contain an array of `create`, `import`, `update`, and `export`
+operations. Work is paced with bounded concurrency, results preserve manifest
+order, progress is sent to stderr, and `--json` reserves stdout for the result
+array. See [Document Types](document-types.md#batch-workflows) for a complete
+manifest example.
+
+## Generated-View Warnings
+
+Task and document creation, update, status changes, deletion, and snapshot
+restore mutate canonical Markdown first and then refresh disposable generated
+views. If that refresh fails after the canonical mutation succeeds, the command
+still succeeds and writes a stderr warning:
+
+```text
+warning: <message>
+```
+
+Run `taskset generate` later to rebuild generated views explicitly.
+
+## Compatibility Notes
+
+`tasks-for-file` was removed. Use:
+
+```bash
+taskset task list --file <path> --impact
+```
+
+Task files are versionless. Frontmatter that still contains a legacy version
+field is invalid and must be converted by removing that field while preserving
+the rest of the task metadata and Markdown body. Snapshot restore previews by
+default; pass `--apply` only when the displayed plan is the mutation you intend
+to commit.

package/docs/configuration.md

@@ -0,0 +1,63 @@
+---
+title: Configure Taskset defaults
+description: Optionally add taskset.config.ts to overlay defaults and vocabulary on a `.taskset/` repository.
+contentType: How-to
+navLabel: Configuration
+---
+
+# Configure Taskset defaults
+
+Taskset repositories are identified by a `.taskset/` directory. `taskset.config.ts` is optional. When the file is absent, built-in statuses, priorities, and creation defaults apply.
+
+## When to add a config file
+
+Add `taskset.config.ts` when you need at least one of these:
+
+- A repository `project.name`
+- Different task creation defaults
+- A reduced or reordered status or priority vocabulary
+
+Create one during init:
+
+```bash
+taskset init --config
+```
+
+Or author the file beside `.taskset/`:
+
+```typescript
+import { defineConfig } from '@taskset/cli'
+
+export default defineConfig({
+	project: {
+		name: 'taskset',
+	},
+	tasks: {
+		defaults: {
+			status: 'todo',
+			priority: 'medium',
+			labels: ['taskset'],
+		},
+		statuses: ['todo', 'doing', 'blocked', 'done', 'canceled'],
+		priorities: ['low', 'medium', 'high', 'urgent'],
+	},
+})
+```
+
+## Contract
+
+- `project.name` is optional repository metadata
+- `tasks.defaults.status`, `priority`, and `labels` are optional creation defaults
+- `tasks.statuses` selects and orders the active status vocabulary from Taskset’s canonical values
+- `tasks.priorities` selects and orders the active priority vocabulary from Taskset’s canonical values
+- `urgent` is the highest supported priority
+- Unknown fields, invalid enum values, empty names, and duplicate default labels or vocabulary values are rejected
+- The config file is trusted project TypeScript and may use erasable syntax supported by your Node version
+
+The config identifies behavior. It is not task storage. Canonical task state remains under `.taskset/tasks/`.
+
+## Discovery
+
+Commands started in nested directories walk upward until they find `.taskset/`. If `taskset.config.ts` exists at that root, Taskset loads and validates it. Otherwise it uses built-in defaults.
+
+Use `taskset config --json` to inspect the discovered root, whether a config file is present, and the resolved defaults.

package/docs/document-types.md

@@ -0,0 +1,103 @@
+---
+title: Choose a Taskset document type
+description: Canonical stories, flows, decisions, research, and runbooks.
+contentType: Conceptual
+navLabel: Document Types
+---
+
+# Choose a Taskset document type
+
+Documents are how Taskset keeps product and engineering memory: what to build, what you learned, what you decided, and how to recover. Use them when the material should outlive a single task. Each type has strict common frontmatter and a body template suited to its purpose. Documents share planning, people, path, and relationship fields with tasks, and use document-specific statuses.
+
+| Type | Directory | Template focus |
+| --- | --- | --- |
+| `story` | `.taskset/stories/` | user outcome and acceptance criteria |
+| `flow` | `.taskset/flows/` | preconditions, journey, variants, checks |
+| `decision` (`adr`, `dr`) | `.taskset/decisions/` | context, decision, alternatives, consequences |
+| `research` | `.taskset/research/` | question, sources, findings, recommendation |
+| `runbook` | `.taskset/runbooks/` | symptoms, checks, actions, rollback, escalation |
+
+Create a document from its template:
+
+```bash
+taskset document create story --title "Member signs in via SSO"
+taskset document create flow --title "Recover a delayed deposit"
+taskset document create adr --title "Use transactional outbox"
+taskset document create research --title "Evaluate queue providers" --related your_task_id_here
+taskset document create runbook --title "Recover consumer lag"
+```
+
+Document IDs are immutable 5-6 character lowercase hex values. Filenames keep a
+per-type display sequence and title slug, for example
+`.taskset/flows/0000001-member-signs-in-via-sso-a1b2c3.md`. Agents and commands
+reference the short `id`. Disposable metadata indexes for that kind live beside
+the files in `.taskset/flows/.generated/`.
+
+## Query And Mutation
+
+Documents support the same command surface as tasks:
+
+```bash
+taskset document list research --search "queue" --owner platform --impact
+taskset document show <document-id> --type research --include-derived --json
+taskset document update <document-id> --status ready --label infra --file packages/core
+taskset document status <document-id> accepted --type decision
+taskset document delete <document-id> --remove-dependencies
+```
+
+Statuses are `draft`, `ready`, `active`, `accepted`, `superseded`, and
+`archived`. `--related` may point at tasks or documents. `--depends-on` and
+`--parent` must resolve to other Taskset documents.
+
+## Import Existing Markdown
+
+Use `document import` when a repository already has material under paths such
+as `docs/stories`, `docs/flows`, `docs/adr`, `docs/research`, or
+`docs/runbooks`:
+
+```bash
+taskset document import docs/flows/0001-sign-in.md
+taskset document import docs/architecture/use-postgres.md --type decision
+taskset document import docs/runbooks/consumer-lag.md --move
+```
+
+The type is inferred from recognized parent directory names when `--type` is
+omitted. `adr`, `dr`, `decision`, and `decisions` all normalize to `decision`.
+The first H1 supplies the title unless `--title` is passed. Existing
+frontmatter is replaced with Taskset's canonical metadata while the Markdown
+body is preserved. Import copies by default; `--move` removes the source only
+after the canonical file has been written successfully.
+
+Use `document list [type]`, `document show <id>`, and `--json` for inspection
+and automation. Sequences are per type, so pass `--type` to `document show`
+when the same ID exists in more than one kind.
+
+## Batch Workflows
+
+Use a JSON manifest when an agent or migration needs to create, import, update,
+or export many documents. Operations run through a bounded TanStack Pacer queue;
+progress such as `3/8 (38%)` is written to stderr, while `--json` keeps stdout
+safe for automation.
+
+```json
+[
+  { "action": "create", "input": { "type": "story", "title": "Member upgrades" } },
+  { "action": "import", "sourcePath": "docs/flows/checkout.md", "options": { "type": "flow" } },
+  { "action": "update", "id": "a1b2c3", "type": "story", "input": { "status": "ready" } },
+  { "action": "export", "id": "a1b2c3", "type": "story", "targetPath": "exports/member-upgrades.md" }
+]
+```
+
+```bash
+taskset document batch taskset-documents.json --concurrency 4 --json
+taskset sync --concurrency 8
+```
+
+`taskset sync` creates missing document-kind directories inside `.taskset`,
+migrates legacy task and document IDs to short hex IDs, normalizes
+`{sequence}-{slug}-{id}.md` filenames, repairs duplicate sequence prefixes by
+`createdAt`, rewrites repository text references, refreshes data `.gitignore`
+rules for scoped `.generated/` directories, removes legacy global
+`.taskset/generated/`, and rebuilds generated views. Build outputs,
+dependencies, caches, snapshots, and Git internals are excluded from reference
+rewriting.