@taskset/cli 4.0.0 → 5.1.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,22 @@
+---
+title: Maintainers
+description: Repository maintenance documentation for Taskset contributors.
+---
+
+# Taskset Maintainer Documentation
+
+This section contains repository maintenance material. It is intentionally
+separate from the primary user 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,76 @@
+---
+title: Product Vision
+description: Maintainer-facing product direction for Taskset.
+---
+
+# Product Vision
+
+## Origin
+
+Taskset began from a simple need: keep task context offline and inline with the
+code so developers and AI assistants can understand work immediately without
+switching to a disconnected project-management database.
+
+## Vision
+
+Taskset aims to become the Git-native operating system for software delivery.
+
+## Mission
+
+Store planning, execution, and project knowledge as human-readable repository
+files, then provide focused interfaces over that shared task 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.
+- 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.
+
+### Developer first
+
+Taskset proves developer workflows before broad enterprise planning features.
+
+## Near-Term Scope
+
+The MVP should implement:
+
+- repository initialization
+- task creation, listing, display, editing, and removal
+- lifecycle transitions
+- deterministic Markdown parsing and serialization
+- validation and repository diagnostics
+- basic search and filtering
+- dependency integrity
+
+TUI, MCP, extension, Kanban, Office, and integrations follow after the file and
+core contracts are reliable.

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,174 @@
+---
+title: Task Files
+description: The canonical Markdown representation for Taskset work items.
+---
+
+# Task Files
+
+Task files live under `.taskset/tasks/`. YAML frontmatter owns structured
+metadata and the Markdown body owns durable human context.
+
+```markdown
+---
+id: 0000001-add-task-validation
+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 seven-digit sequences plus a lowercase title slug, such
+as `0000001-add-task-validation`. The sequence prevents title collisions while
+the slug keeps filenames recognizable.
+
+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 remain readable so a repository can migrate safely. Run
+`taskset task migrate-ids` once to atomically rename task files and rewrite all
+`dependsOn`, `related`, `duplicates`, and `parent` references. The command
+prints the old-to-new mapping for updating references outside `.taskset/`.
+
+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 0000001-add-task-validation
+```
+
+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,7 +2,7 @@
   "name": "@taskset/cli",
   "type": "module",
   "private": false,
-  "version": "4.0.0",
+  "version": "5.1.0",
   "description": "The scriptable command-line interface for Taskset.",
   "license": "MIT",
   "author": {
@@ -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": "5.0.0",
+    "@taskset/core": "5.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"
   }