@taskset/cli 4.0.0 → 6.0.0

package/docs/maintainers/development/testing.md

@@ -0,0 +1,89 @@
+---
+title: Testing
+description: Maintainer test strategy, Vitest usage, and pragmatic TDD guidance.
+---
+
+# Testing
+
+Taskset uses Vitest for TypeScript unit and integration tests. The root
+configuration is shared by package-local suites. Turbo runs each owning
+package's Vitest task and the root workspace architecture suite.
+Vitest already provides the Vite-powered test pipeline; the Node library and
+CLI packages use TypeScript directly for builds, so they do not need a separate
+Vite build configuration.
+
+```bash
+pnpm test
+pnpm test:architecture
+pnpm test:watch
+pnpm check
+```
+
+Use filtered package tests for focused work:
+
+```bash
+pnpm --filter @taskset/core test
+pnpm --filter @taskset/cli test
+```
+
+Package-local test scripts are intentional. Turbo and filtered pnpm commands
+execute scripts owned by each workspace; the root script cannot replace those
+entrypoints. `test:architecture` names the separate root-only package-boundary
+suite. There is no `transit` command in the repository.
+
+## TDD Policy
+
+Prefer a red-green-refactor loop for:
+
+- domain invariants
+- parser and serializer behavior
+- lifecycle transitions
+- graph rules
+- migrations
+- bug fixes
+
+Do not force test-first ceremony for documentation, formatting, generated
+configuration, or exploratory spikes. Convert a successful spike into tested
+production behavior before merging it.
+
+## Test Layers
+
+### Unit
+
+Test pure schemas, value objects, state transitions, graph algorithms, filters,
+and serialization rules.
+
+### Integration
+
+Use temporary fixture repositories to test filesystem behavior, Git discovery,
+atomic writes, path safety, monorepo discovery, and package impact.
+
+### Contract
+
+Verify CLI exit codes and output, MCP schemas, package exports, and persisted
+Markdown compatibility.
+
+### UI
+
+Test feature behavior and accessibility in the owning interface. Add browser
+projects only when UI packages exist.
+
+### End to end
+
+Keep a small number of workflows that create a fixture repository and exercise
+the public CLI or hosted interface. Do not duplicate every unit case at this
+level.
+
+## Important Cases
+
+- malformed YAML and unknown fields
+- CRLF, Unicode, and empty Markdown bodies
+- parse and serialize round trips
+- duplicate IDs and branch-safe identity
+- path traversal and symlink boundaries
+- broken graph references and cycles
+- interrupted writes and stale updates
+- old-format fixtures and compatibility rollback behavior
+
+Vitest code snapshots are acceptable for small stable serialized output or
+diagnostics. They are unrelated to Taskset safety snapshots.

package/docs/maintainers/index.md

@@ -0,0 +1,20 @@
+---
+title: Maintainers
+description: Repository maintenance documentation for Taskset contributors.
+---
+
+# Taskset Maintainer Documentation
+
+This section contains repository maintenance material for the Taskset delivery workspace. It stays separate from the primary human and agent guides while remaining available in the same Nextra documentation site.
+
+## Contents
+
+- `product/`: product direction and scope
+- `architecture/`: system boundaries and accepted decisions
+- `development/`: contribution, engineering, testing, and documentation
+  workflows
+- `technology.md`: preferred frontend, backend, language, and database choices
+
+Contributors should start with the root `CONTRIBUTING.md`, then read the
+relevant maintainer document before changing architecture, tooling, or
+repository workflows.

package/docs/maintainers/product/_meta.ts

@@ -0,0 +1,3 @@
+export default {
+	vision: 'Vision',
+}

package/docs/maintainers/product/vision.md

@@ -0,0 +1,68 @@
+---
+title: Product Vision
+description: Maintainer-facing product direction for Taskset.
+---
+
+# Product Vision
+
+## Origin
+
+Taskset began from a need to keep delivery context offline and inline with the code. Tasks alone were not enough. Teams and agents also needed stories, research, decisions, flows, and runbooks that travel with the repository instead of living in a disconnected project-management database.
+
+## Vision
+
+Taskset aims to become the Git-native operating system for software delivery.
+
+## Mission
+
+Store planning, learning, decisions, operations, and execution as human-readable repository files, then provide focused interfaces over that shared work graph.
+
+## Product Goals
+
+- Accelerate delivery by reducing context switching
+- Give developers immediate awareness of related tasks, dependencies, specs, decisions, and releases
+- Give AI systems direct, structured, reviewable project context across plans and execution
+- Make monorepos, packages, applications, and code paths first-class
+- Let managers and stakeholders view repository-backed information without creating another source of truth
+
+## Principles
+
+### Offline first
+
+Core workflows must work from a local repository without a network service.
+
+### Inline with code
+
+Project context belongs beside the code it affects and travels with the repository.
+
+### Human and AI readable
+
+Markdown carries durable prose. Structured frontmatter carries data that tools can validate and query.
+
+### Git native
+
+Commits, branches, pull requests, diffs, and reviews are normal collaboration mechanisms.
+
+### One source of truth
+
+Every interface reads and changes the same canonical `.taskset/` files through the same domain rules.
+
+### Agent first, human readable
+
+Taskset optimizes distribution, discovery, and docs for agent operators while keeping Markdown reviewable by humans.
+
+### Memory and execution together
+
+Documents preserve product and engineering memory. Tasks carry ownership, status, and delivery. Relationships bind them into one graph.
+
+## Current product surface
+
+The current surface includes:
+
+- repository initialization and optional configuration
+- tasks with lifecycle, dependencies, search, and impact queries
+- stories, flows, decisions, research, and runbooks with the same query and mutation family
+- validation, diagnostics, generated views, snapshots, and sync
+- packaged agent skills and dual-audience documentation
+
+TUI, MCP, extension, Kanban, Office, and integrations build on the same file and core contracts.

package/docs/maintainers/technology.md

@@ -0,0 +1,55 @@
+---
+title: Technology Preferences
+description: Preferred frontend, backend, language, and database choices for Taskset.
+---
+
+# Technology Preferences
+
+These are defaults for new Taskset implementation work. They guide choices
+when requirements do not demand a different tool; they are not a requirement
+to install every library in every package.
+
+## Frontend
+
+Use TypeScript and React for web interfaces. Prefer the TanStack ecosystem for
+headless application behavior:
+
+- TanStack Query for server-state fetching, caching, and mutations
+- TanStack Form for complex validated forms
+- TanStack Table for data grids and tabular state
+- TanStack Hotkeys for keyboard command handling
+- TanStack Pacer for debouncing, throttling, queuing, and rate control
+- TanStack Virtual for large virtualized lists and grids
+- TanStack DB when a client-side reactive data layer is justified
+- TanStack Devtools and library-specific devtools during development
+
+Adopt these tools by demonstrated feature need. Do not add speculative
+dependencies to scaffolds or force TanStack abstractions around simple local
+state.
+
+## Backend
+
+Prefer TypeScript for services and hosted adapters.
+
+- Start with a small framework-independent composition root where practical.
+- Use NestJS when dependency injection, modules, guards, transport adapters, or
+  a larger service boundary justify the framework.
+- In NestJS applications, prefer `class-transformer` and `class-validator` for
+  transport DTO transformation and validation.
+- Prefer TypeORM when a relational object mapper is appropriate.
+- Keep Taskset domain rules in `@taskset/core`; server frameworks own transport,
+  authentication, persistence adapters, and process lifecycle.
+
+Use Rust for components where systems-level performance, memory control,
+portability, concurrency, or a standalone native executable provides a clear
+advantage. Keep language boundaries explicit and narrow.
+
+## Databases
+
+- Prefer MariaDB for smaller conventional hosted applications.
+- Prefer PostgreSQL for larger systems, advanced relational workloads, and
+  features that benefit from its ecosystem.
+- Do not introduce a database as an authority for canonical Taskset entities;
+  `.taskset/` Markdown remains the product source of truth.
+- Document schema ownership, migrations, backup, and consistency behavior
+  before adding a database-backed adapter.

package/docs/task-files.md

@@ -0,0 +1,180 @@
+---
+title: Understand Taskset task files
+description: The canonical Markdown representation for Taskset work items.
+contentType: Conceptual
+navLabel: Task Files
+---
+
+# Understand Taskset task files
+
+Tasks are the executable layer of Taskset. Use them to carry ownership, status, dependencies, and code impact for delivery work. Pair them with [stories, research, decisions, flows, and runbooks](document-types.md) when the surrounding memory should stay durable.
+
+Task files live under `.taskset/tasks/`. YAML frontmatter owns structured metadata. The Markdown body owns durable human context for that piece of execution.
+
+```markdown
+---
+id: a1b2c3
+title: Add task validation
+status: doing
+priority: high
+order: 10
+owner: platform
+assignees:
+  - maintainer
+reviewers:
+  - reviewer
+team: core
+estimate: 90
+effort: 3
+risk: high
+dueDate: 2026-06-30
+createdAt: 2026-06-12
+updatedAt: 2026-06-12 09:30 UTC
+labels:
+  - core
+dependsOn: []
+related: []
+duplicates: []
+files:
+  - packages/core/src/tasks/taskFile.ts
+directories:
+  - packages/core
+projects:
+  - taskset
+---
+
+# Context
+
+Explain why the task exists.
+```
+
+## Canonical Data
+
+Required fields are `id`, `title`, `status`, `createdAt`, and `updatedAt`.
+Task IDs are immutable 5-6 character lowercase hex values, such as `a1b2c3`.
+Filenames keep a separate display sequence and title slug:
+`0000001-add-task-validation-a1b2c3.md`. Agents and commands reference the short
+`id`, never the mutable sequence prefix.
+
+Task files use one strict versionless metadata shape. Optional fields:
+
+- Planning: `priority`, `order`, `estimate` in integer minutes, `effort` as a
+  finite nonnegative number, `risk`, and `dueDate`
+- People: `owner`, `assignees`, `reviewers`, and `team`
+- Relationships: `dependsOn`, `related`, `duplicates`, and `parent`
+- Scope: `labels`, `files`, `directories`, and `projects`
+
+People and project values are trimmed free-form strings. Arrays must not
+contain duplicates. Paths are normalized repository-relative POSIX paths.
+Dates use `YYYY-MM-DD` or `YYYY-MM-DD HH:mm UTC`; documented legacy
+millisecond ISO UTC timestamps remain readable.
+
+Unknown fields, invalid enum values, self-links, duplicate list values, path
+traversal, and an `updatedAt` earlier than `createdAt` are rejected.
+
+`order` is the optional user-controlled sequence. Lower order values sort
+first. Missing values sort after ordered tasks, and duplicate order values fall
+back to deterministic task ID ordering.
+
+## Compatibility Cutover
+
+Legacy `TS-` ULIDs and sequential `0000001-title` IDs remain readable so a
+repository can migrate safely. Run `taskset sync` or `taskset task migrate-ids`
+to atomically assign short hex IDs, normalize filenames to
+`{sequence}-{slug}-{id}.md`, repair duplicate sequence prefixes by `createdAt`,
+and rewrite relationships plus repository text references. The command prints
+the old-to-new mapping for any ID rewrites.
+
+Task metadata is versionless. Versioned task frontmatter is invalid input and
+fails with a schema diagnostic rather than being silently rewritten.
+Repositories created with earlier Taskset releases must convert task files by
+removing only the legacy version field from task frontmatter while preserving
+all other metadata and Markdown body content. Take a Git commit or
+`taskset snapshot create` checkpoint before converting existing repositories.
+
+## Relationships
+
+`dependsOn`, `related`, `duplicates`, and `parent` are canonical. Taskset
+derives:
+
+- `blockedBy`: direct dependencies
+- `blocks`: direct inverse dependencies
+- `children`: direct inverse parents
+- `subtasks`: all transitive descendants
+
+Use `--include-derived` with task list or JSON task show output. Derived values
+are never written to canonical Markdown. The graph validates missing targets,
+self-links, dependency cycles, and parent cycles.
+
+## Writes And Lifecycle
+
+Taskset serializes fields deterministically, normalizes line endings to LF,
+preserves the Markdown body, and emits one final newline. Canonical mutations
+use failure-safe file operations.
+
+Allowed lifecycle transitions are:
+
+- `todo` to `doing`, `blocked`, or `canceled`
+- `doing` to `todo`, `blocked`, `done`, or `canceled`
+- `blocked` to `todo`, `doing`, or `canceled`
+- `done` and `canceled` are terminal
+
+Deletion is rejected while another task has an inbound canonical relationship
+to the target. `--remove-dependencies` repairs those references and removes the
+target in one transaction.
+
+## Queries And Derived State
+
+`task list` supports metadata, relationship, planning range, timestamp range,
+text, file, and directory filters. Numeric and timestamp ranges are inclusive:
+
+```bash
+taskset task list --file packages/core --impact --json
+taskset task list --sort order
+taskset task list --estimate-min 30 --estimate-max 120 --risk high
+taskset task list --duplicate a1b2c3
+```
+
+Repeated enum, person, project, file, and directory values use OR within the
+same option. Repeated labels require every requested label. Different filter
+categories compose with AND. For example, two `--file` values match either
+path, while adding `--owner` requires both the path match and owner match.
+`--file` is the unified containment query over task files and task directories;
+`--directory` matches only canonical directory metadata. All path inputs are
+normalized relative to the repository before matching.
+
+Planning filters are `--estimate-min`, `--estimate-max`, `--effort-min`, and
+`--effort-max`. Timestamp filters are `--due-before`, `--due-after`,
+`--created-before`, `--created-after`, `--updated-before`, and
+`--updated-after`. Title and Markdown body use case-insensitive `--search`;
+every whitespace-separated search term must occur somewhere in those fields,
+but terms need not be adjacent or ordered. Exact task IDs use `task show` or
+relationship filters rather than a redundant list ID filter.
+
+With `--impact`, every direct filter is applied first, then the graph adds tasks
+that transitively depend on those direct matches. JSON output uses
+`{ "direct": [...], "impacted": [...] }`; `--include-derived` adds relationship
+projections to records in both groups.
+
+`.taskset/cache/` and each entity folder's `.generated/` directory are disposable.
+Generated metadata
+indexes are deterministic projections for supported non-ID task metadata fields
+and refresh on a best-effort basis after canonical mutations. Date and
+timestamp metadata is grouped by calendar date only. Generated filenames remain
+human-readable: spaces are preserved and path separators are displayed with
+`∕` instead of URL-encoded text. Generated views sort tasks by `order` when
+present and display ordered rows with the order value.
+
+## Snapshots
+
+Git remains the normal history. `.taskset/snapshots/` contains immutable,
+non-authoritative safety checkpoints:
+
+```bash
+taskset snapshot create
+taskset snapshot list
+taskset snapshot restore <snapshot-id>
+taskset snapshot restore <snapshot-id> --apply
+```
+
+Restore previews by default and requires `--apply` to mutate canonical tasks.

package/package.json

@@ -2,8 +2,8 @@
   "name": "@taskset/cli",
   "type": "module",
   "private": false,
-  "version": "4.0.0",
-  "description": "The scriptable command-line interface for Taskset.",
+  "version": "6.0.0",
+  "description": "CLI for Taskset: plan, research, decide, operate, and track repository work as Markdown.",
   "license": "MIT",
   "author": {
     "name": "junkieshuffle",
@@ -23,6 +23,8 @@
     "dist",
     "src",
     "!src/**/*.test.ts",
+    "docs",
+    "skills",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -44,8 +46,8 @@
   },
   "dependencies": {
     "zod": "4.6.5",
-    "@taskset/contracts": "4.0.0",
-    "@taskset/core": "4.0.0"
+    "@taskset/contracts": "6.0.0",
+    "@taskset/core": "6.0.0"
   },
   "devDependencies": {
     "@types/node": "^26.6.3",
@@ -54,8 +56,8 @@
     "@taskset/configs": "0.1.1"
   },
   "scripts": {
-    "build": "pnpm clean && tsc",
-    "clean": "node --eval \"import { rmSync } from 'node:fs'; rmSync('dist', { recursive: true, force: true })\"",
+    "build": "pnpm clean && tsc && node ./scripts/copy-package-assets.mjs",
+    "clean": "node --eval \"import { rmSync } from 'node:fs'; for (const name of ['dist', 'docs', 'skills']) rmSync(name, { recursive: true, force: true })\"",
     "test": "vitest run --root ../.. packages/cli/src",
     "test:watch": "vitest --root ../.. packages/cli/src"
   }