@taskset/cli 4.0.0 → 5.1.0

package/docs/getting-started.md

@@ -0,0 +1,99 @@
+---
+title: Getting Started
+description: Initialize Taskset in a project and create the first repository task.
+---
+
+# Getting Started
+
+Taskset keeps project work in human-readable Markdown beside the code. The
+current pre-alpha release is intended for local repository use.
+
+## Requirements
+
+- Node.js 24 or newer
+- pnpm 11 or newer
+
+## Install
+
+Install the published package as a development dependency in the project that
+will own the tasks:
+
+```bash
+pnpm add --save-dev @taskset/cli
+```
+
+The package exposes the `taskset` executable.
+
+## Initialize
+
+Run Taskset from the repository root:
+
+```bash
+pnpm taskset init
+```
+
+This creates:
+
+```text
+taskset.config.ts
+.taskset/
+├── .gitignore
+└── tasks/
+```
+
+The config controls validated defaults. Task Markdown under `.taskset/tasks/`
+remains the canonical project state. The nested ignore file excludes
+`.taskset/cache/`, per-entity `.generated/` directories, and `.taskset/snapshots/`.
+Snapshots are non-authoritative safety checkpoints; tasks remain canonical.
+
+## Create And Inspect Work
+
+```bash
+pnpm taskset task create --title "Add repository validation"
+pnpm taskset task list
+pnpm taskset task show <task-id>
+pnpm taskset task update <task-id> --status doing
+```
+
+Task files can also be read and reviewed directly without Taskset installed.
+
+## Query And Validate Work
+
+```bash
+pnpm taskset task list --status doing --label core --json
+pnpm taskset task list --file packages/core --impact --json
+pnpm taskset doctor
+```
+
+File and directory filters use normalized repository-relative containment
+matching. With `--impact`, list output groups direct matches and tasks that
+transitively depend on them. Other filters select the direct set before graph
+expansion. `doctor` reports all readable format and graph failures in one
+non-mutating pass.
+
+## Generated Views And Migration
+
+```bash
+pnpm taskset generate
+pnpm taskset snapshot create
+pnpm taskset snapshot list
+```
+
+Snapshot restore previews by default unless `--apply` is present.
+
+## Complete Or Remove Work
+
+```bash
+pnpm taskset task status <task-id> done
+pnpm taskset task delete <task-id>
+```
+
+Completed and canceled tasks are terminal. Deletion fails while another task
+depends on the target. Use `--remove-dependencies` only when Taskset should
+remove those inbound references and the task together.
+
+## Next
+
+- [Configure task defaults](configuration.md)
+- [Use the complete CLI reference](cli-reference.md)
+- [Understand task files](task-files.md)

package/docs/index.md

@@ -0,0 +1,37 @@
+---
+title: Taskset
+description: Offline, inline, AI-friendly project awareness stored beside the code.
+---
+
+# Taskset
+
+Taskset is an offline, inline, AI-friendly, human-readable task manager designed
+to accelerate software delivery and give development teams immediate awareness
+of the work surrounding their code.
+
+Tasks and project knowledge live inside the repository as Markdown. Git supplies
+history, branches, review, and collaboration. Taskset supplies a consistent
+domain model and interfaces over those files.
+
+Install the command-line package from npm as `@taskset/cli`.
+
+## Core Promise
+
+- Work remains readable without Taskset installed.
+- Developers can operate locally without a mandatory service.
+- Humans and AI agents inspect the same project context.
+- CLI, TUI, MCP, editor, Kanban, and reporting views share one source of truth.
+- Monorepo projects and code relationships are first-class.
+
+## Current Status
+
+Taskset is pre-alpha. The CLI supports repository initialization, configuration
+inspection, validated task CRUD and lifecycle changes, repository diagnostics,
+generated views, snapshots, metadata queries, and file-impact analysis.
+
+## Read Next
+
+- [Getting started](getting-started.md)
+- [Configuration](configuration.md)
+- [CLI reference](cli-reference.md)
+- [Task files](task-files.md)

package/docs/maintainers/_meta.ts

@@ -0,0 +1,7 @@
+export default {
+	index: 'Overview',
+	technology: 'Technology',
+	product: 'Product',
+	architecture: 'Architecture',
+	development: 'Development',
+}

package/docs/maintainers/architecture/_meta.ts

@@ -0,0 +1,5 @@
+export default {
+	overview: 'Overview',
+	synchronization: 'Synchronization',
+	decisions: 'Decisions',
+}

package/docs/maintainers/architecture/decisions/0001-documentation-platform.md

@@ -0,0 +1,70 @@
+---
+title: "ADR 0001: Documentation Platform"
+description: Render canonical user documentation through the Taskset website.
+---
+
+# ADR 0001: Documentation Platform
+
+- Status: Accepted
+- Date: 2026-06-12
+
+## Context
+
+Taskset needs one documentation source that is readable on Git hosts and can
+also power a documentation website. User guidance and repository maintenance
+material have different audiences and should remain visibly separated.
+
+## Decision
+
+- Keep canonical user documentation in the root `docs/` directory.
+- Keep contributor, product, architecture, ADR, testing, and technology
+  material under `docs/maintainers/`.
+- Use plain Markdown by default and MDX only for interactive pages.
+- Build `apps/www` with Next.js App Router, Nextra, and the stock Nextra docs
+  and blog themes.
+- Expose root `docs/` as the app's Nextra `content` directory through a
+  repository-relative symlink.
+- Render top-level usage docs and `docs/maintainers/` through separate route
+  layouts and page maps so their navigation stays audience-specific.
+- Keep chronological release and project posts under `apps/www/posts/`.
+- Isolate usage docs, maintainer docs, and blog layouts and MDX component sets
+  by route.
+- Keep the Nextra configuration and layout close to the upstream defaults.
+
+Nextra supports App Router content-directory routing and typed `_meta.ts`
+navigation:
+
+- <https://nextra.site/docs/file-conventions/content-directory>
+- <https://nextra.site/docs/docs-theme/start>
+
+## Why
+
+This matches the existing Next.js direction, provides navigation and search
+without a custom content loader, and keeps user documentation readable in its
+canonical location. Moving maintainer material into a dedicated
+`docs/maintainers/` section prevents the root README and user pages from
+becoming contributor handbooks.
+
+## Implementation Contract
+
+`apps/www/content` points to `../../docs`. The usage docs catch-all route loads
+top-level content and excludes `docs/maintainers/` from its page map. The
+`/maintainers` route loads the same content directory with a maintainer-rooted
+page map. The app may generate `.next/`, search data, and static output, but
+none of those become documentation source.
+
+`apps/www/posts/` is the source for blog Markdown. An app-local registry maps
+each post to `/posts/[slug]` so static export can enumerate routes without
+copying posts into `docs/`. The global MDX component file contains only base
+Nextra components; docs and blog routes apply their own theme components.
+
+## Consequences
+
+- Documentation changes are reviewable without building the site.
+- Blog posts are reviewable as app-local Markdown without a CMS.
+- The site build must include root `docs/` files in its input.
+- New posts must be added to the app-local static post registry.
+- MDX components remain owned by `apps/www`.
+- Maintainer documentation is reviewed from `docs/maintainers/` and remains in
+  its own `/maintainers` navigation section.
+- Broken links and invalid frontmatter should fail CI.

package/docs/maintainers/architecture/decisions/0002-code-architecture.md

@@ -0,0 +1,31 @@
+---
+title: "ADR 0002: Client and Server Code Architecture"
+description: Use FBA for interfaces and a DDD-lite modular monolith for core and server code.
+---
+
+# ADR 0002: Client and Server Code Architecture
+
+- Status: Accepted
+- Date: 2026-06-12
+
+## Context
+
+Feature-based architecture fits user-facing surfaces, but applying it alone to
+domain-heavy storage and workflow code can mix business rules with adapters.
+Full enterprise DDD would add unnecessary ceremony to an early product.
+
+## Decision
+
+- Use FBA for CLI, TUI, MCP, extension, Kanban, Office, and website surfaces.
+- Use a DDD-lite modular monolith for `@taskset/core` and any future server.
+- Organize core by domain module first.
+- Within a module, use `domain`, `application`, and `infrastructure` only when
+  those boundaries contain meaningful code.
+- Keep one deployable unit and direct in-process module calls.
+
+## Consequences
+
+- Domain rules remain reusable across every interface.
+- Filesystem and Git details stay replaceable and testable.
+- Teams avoid premature services, queues, and distributed state.
+- Small modules are allowed to stay flat until complexity justifies layers.

package/docs/maintainers/architecture/decisions/0003-snapshot-policy.md

@@ -0,0 +1,31 @@
+---
+title: "ADR 0003: Snapshot Policy"
+description: Use Git for history and reserve Taskset snapshots for explicit safety checkpoints.
+---
+
+# ADR 0003: Snapshot Policy
+
+- Status: Accepted
+- Date: 2026-06-12
+
+## Context
+
+Taskset needs safe mutation and recovery, but Git already records durable
+project history. A second automatic history system would duplicate state and
+confuse authority.
+
+## Decision
+
+- Git remains the normal task history and rollback system.
+- Prefer dry runs, atomic writes, validation, diffs, and Git-aware warnings.
+- The explicit snapshot subsystem protects uncommitted state before schema
+  migrations and supports user-invoked safety checkpoints.
+- Snapshots are immutable, non-authoritative, conflict-aware on restore, and
+  removable without changing current project state.
+- Migration and restore preview by default. Migration snapshots before apply;
+  restore requires an explicit `--apply`.
+
+## Consequences
+
+Snapshots add a bounded recovery mechanism without becoming hidden history.
+They live under `.taskset/snapshots/`, remain disposable, and never replace Git.

package/docs/maintainers/architecture/decisions/_meta.ts

@@ -0,0 +1,5 @@
+export default {
+	'0001-documentation-platform': 'ADR 0001: Documentation Platform',
+	'0002-code-architecture': 'ADR 0002: Code Architecture',
+	'0003-snapshot-policy': 'ADR 0003: Snapshot Policy',
+}

package/docs/maintainers/architecture/overview.md

@@ -0,0 +1,111 @@
+---
+title: Architecture Overview
+description: Maintainer-facing package boundaries, runtime flow, and code organization.
+---
+
+# Architecture Overview
+
+Taskset is a local-first modular system built around canonical Markdown files.
+
+```text
+CLI / TUI / MCP / Extension / Kanban / Office
+                    |
+             @taskset/core
+                    |
+       parse -> validate -> operate -> serialize
+                    |
+          .taskset/ Markdown files
+                    |
+         disposable indexes and views
+```
+
+## Package Direction
+
+```text
+contracts    utils
+    \         /
+       core
+        |
+cli  tui  mcp  extension  kanban  office
+```
+
+- `@taskset/contracts` owns shared runtime schemas and TypeScript contracts.
+- `@taskset/utils` owns domain-light reusable primitives.
+- `@taskset/core` owns domain behavior and persistence orchestration.
+- Interface packages own input, rendering, transport, and interaction.
+- Client packages do not become domain APIs for each other.
+
+## Client Organization
+
+UI and interaction surfaces use feature-based architecture. Each feature
+colocates its components, state, adapters, fixtures, and tests. Shared code is
+promoted only when several features genuinely depend on it.
+
+## Core and Server Organization
+
+Core uses a DDD-lite modular monolith:
+
+```text
+src/
+├── tasks/
+│   ├── domain/
+│   ├── application/
+│   └── infrastructure/
+├── diagnostics/
+├── graph/
+├── generated/
+├── indexing/
+├── projects/
+├── search/
+├── snapshots/
+├── sync/
+└── repository/
+```
+
+This is not ceremonial DDD:
+
+- organize by domain module first
+- keep pure invariants in `domain`
+- coordinate use cases in `application`
+- isolate filesystem, Git, and framework code in `infrastructure`
+- omit layers that have no meaningful behavior
+- keep one process and deployable unit
+
+If hosted collaboration requires a server, `apps/server` becomes a thin
+composition root over core. It owns transport, authentication, authorization,
+repository checkout, concurrency, and process lifecycle, not duplicate domain
+rules. Prefer TypeScript and add NestJS only when the service boundary benefits
+from its module and transport model. Use Rust for clearly bounded native or
+systems-level components.
+
+Relational adapters prefer MariaDB for smaller applications and PostgreSQL for
+larger or more advanced workloads. No database becomes canonical Taskset state.
+
+## Persistence Projections
+
+Canonical tasks live in `.taskset/tasks/` as strict versionless Markdown
+entities. Versioned task frontmatter is rejected instead of being silently
+rewritten.
+
+Each entity folder owns disposable `.generated/` metadata indexes with
+date-only grouping and readable filenames (for example
+`.taskset/tasks/.generated/`). `.taskset/cache/` and generated views are
+disposable. Legacy `.taskset/generated/` is removed by `generate` / `sync`.
+`.taskset/snapshots/` contains immutable safety checkpoints and is not normal
+history or a second source of truth.
+
+## Documentation
+
+The root `docs/` tree contains canonical user guidance and maintainer guidance.
+User pages stay at the top level. Maintainer material lives under
+`docs/maintainers/`. `apps/www` renders usage docs and maintainer docs from the
+same content symlink but exposes them through separate route layouts and
+navigation. See the
+[documentation platform decision](decisions/0001-documentation-platform.md).
+
+## Decisions
+
+- [Documentation platform](decisions/0001-documentation-platform.md)
+- [Client FBA and modular core/server](decisions/0002-code-architecture.md)
+- [Snapshot policy](decisions/0003-snapshot-policy.md)
+- [Synchronization](synchronization.md)

package/docs/maintainers/architecture/synchronization.md

@@ -0,0 +1,56 @@
+---
+title: Synchronization
+description: Provider-neutral ownership, conflict, deletion, and apply rules for Taskset adapters.
+---
+
+# Synchronization
+
+Synchronization is an explicit adapter workflow around canonical `.taskset/`
+files. A provider record, identity mapping, baseline, revision, or cache never
+becomes an alternate Taskset task store.
+
+## Core Policy
+
+`@taskset/contracts` defines pull, push, and bidirectional data, plan, conflict,
+checkpoint, and result types. `@taskset/core` owns:
+
+- deterministic plan ordering and dry runs
+- local and external stale-read fingerprints
+- field-level three-way comparison against the last synchronized baseline
+- deletion policy and conflict detection
+- canonical task validation and relationship integrity
+- failure-safe local apply through the shared filesystem transaction boundary
+
+Plans report creates, updates, deletions, unchanged records, and unresolved
+conflicts before mutation. Apply rejects any plan with conflicts and re-reads
+both sides to reject stale input.
+
+## Adapter Ownership
+
+Provider adapters own authentication, pagination, rate limits, provider field
+mapping, remote revisions, and atomic application of external changes and
+checkpoints. They return explicit external identities and optional canonical
+task IDs. They must not write `.taskset/` files directly.
+
+Adapters apply their changes before core mutates canonical files. An adapter
+failure therefore leaves canonical Taskset state unchanged. Adapters should
+make their own batch operation atomic or expose the provider's partial-failure
+details; core cannot claim to roll back a remote service.
+
+## Identity And Baselines
+
+Identity mappings are adapter records, not canonical task metadata. A
+remote-only record receives a deterministic Taskset ID in its synchronization
+plan, and the adapter checkpoint records that mapping after apply.
+
+Each synchronized record may carry a baseline containing the prior shared task
+data and stale-read revisions. Bidirectional synchronization merges
+non-overlapping field changes. Different edits to the same field, or deletion
+combined with an unsynchronized edit, produce conflicts.
+
+## Deletion
+
+The default deletion behavior is `preserve`. With `delete`, deletion propagates
+only when the surviving side has not changed from the baseline. Otherwise the
+plan reports a record-level conflict. Local deletion also remains subject to
+the task graph's inbound-dependency policy.

package/docs/maintainers/development/_meta.ts

@@ -0,0 +1,6 @@
+export default {
+	contributing: 'Contributing',
+	engineering: 'Engineering',
+	testing: 'Testing',
+	documentation: 'Documentation',
+}

package/docs/maintainers/development/contributing.md

@@ -0,0 +1,59 @@
+---
+title: Contributing
+description: Repository setup, Taskset dogfooding, pull requests, and completion rules.
+---
+
+# Contributing
+
+Taskset is pre-alpha. Strengthen the core file format and workflow before
+expanding the number of interfaces.
+
+## Start Here
+
+Read `AGENTS.md`, `skills/taskset-implement/SKILL.md`, the product vision, the
+architecture overview, and the technology preferences before changing the
+repository. Discuss persisted formats, package boundaries, public commands,
+synchronization, or snapshots before implementation.
+
+## Setup
+
+```bash
+pnpm install --frozen-lockfile
+pnpm check
+pnpm taskset task list
+```
+
+Use the Node and pnpm versions declared by `.nvmrc` and `packageManager`.
+
+## Develop Taskset With Taskset
+
+The repository dogfoods Taskset. Use the root `taskset.config.ts`, the CLI, and
+canonical `.taskset/tasks/` files to plan and inspect work. When the CLI
+supports the required operation, update the task through the CLI instead of
+editing generated or derived state.
+
+## Engineering Rules
+
+- Keep `.taskset/` Markdown as the persistent source of truth.
+- Put shared domain behavior in `@taskset/core`.
+- Keep runtime schemas and shared data contracts in `@taskset/contracts`.
+- Keep core and future server code as a pragmatic modular monolith.
+- Use feature-based architecture in UI and interaction surfaces.
+- Add dependencies to the package that imports them.
+- Preserve deterministic serialization and human-authored Markdown.
+- Prefer test-first work for domain rules, parsers, compatibility changes, transitions,
+  and bug fixes.
+
+## Finish The Work
+
+Before declaring a workspace task complete:
+
+1. Run the narrowest relevant test, then the broader checks required by risk.
+2. Update the canonical Taskset task through the CLI when supported.
+3. Update affected user docs, maintainer docs, tests, and
+   `skills/taskset-implement/`.
+4. Run `pnpm check` and `git diff --check`.
+5. Report compatibility consequences, checks, and remaining limitations.
+
+Add a Changeset only when release configuration is active and a versioned
+contract changes.

package/docs/maintainers/development/documentation.md

@@ -0,0 +1,69 @@
+---
+title: Documentation
+description: How user Markdown becomes the Taskset documentation website.
+---
+
+# Documentation
+
+The root `docs/` directory is canonical for user-facing guidance and maintainer
+guidance. Top-level pages are for users. Repository maintenance material belongs
+under `docs/maintainers/`.
+
+## Recommended Website Stack
+
+Use Next.js App Router, Nextra, `nextra-theme-docs`, and
+`nextra-theme-blog` in `apps/www`.
+
+Why:
+
+- `apps/www` owns the public documentation renderer
+- the repository already has a Next.js TypeScript preset
+- Nextra supplies Markdown routing, documentation navigation, blog layout, and
+  search
+- Markdown remains the source rather than a CMS database
+
+## Content Rules
+
+- Use `.md` unless the page needs an interactive component.
+- Add `title` and `description` frontmatter.
+- Keep conceptual pages separate from current command reference.
+- Mark future behavior as planned.
+- Link to source files with repository-relative paths.
+- Keep generated API reference separate from hand-authored concepts.
+- Keep architecture, ADRs, development workflows, and technology preferences
+  under `docs/maintainers/`, not in top-level usage navigation.
+- Keep chronological release and project posts under `apps/www/posts/`.
+- Require `title`, `description`, and `date` frontmatter for blog posts.
+- Register each post in `apps/www/src/blog/posts.ts` so the static build can
+  enumerate `/posts/[slug]`.
+
+## Integration
+
+`apps/www/content` is a repository-relative symlink to `../../docs`. Nextra's
+standard content-directory loader renders that source without copying it or
+maintaining a second source tree. The top-level usage docs route filters
+`docs/maintainers/` out of its primary navigation, and the dedicated
+`/maintainers` route renders the same canonical maintainer Markdown with its own
+page map.
+
+Usage docs, maintainer docs, and blog pages use separate route layouts and
+receive their own MDX component sets. Do not merge docs and blog themes in the
+global `mdx-components.tsx`; their wrapper components own different page
+contracts. Blog Markdown is loaded from `apps/www/posts/` through the app-local
+post registry.
+
+Run the Next.js development and production builds in webpack mode. Turbopack
+does not reliably discover newly added Markdown through the external content
+symlink.
+
+Keep stable public site metadata such as `docsRepositoryBase` in the owning app
+configuration. Do not add a root `.env` for a non-secret constant. Use an
+app-local environment variable and checked-in `.env.example` only when a value
+genuinely differs by deployment.
+
+The website may generate `.next/`, search data, and build output. These are
+derived and ignored. Root `docs/` Markdown remains authoritative for
+documentation, and `apps/www/posts/` Markdown remains authoritative for blog
+posts.
+
+See [ADR 0001](../architecture/decisions/0001-documentation-platform.md).

package/docs/maintainers/development/engineering.md

@@ -0,0 +1,59 @@
+---
+title: Engineering
+description: Design principles and pragmatic package and tooling decisions for Taskset.
+---
+
+# Engineering
+
+Taskset favors minimal designs with explicit ownership and testable boundaries.
+Apply SOLID, separation of concerns, encapsulation, high cohesion, low coupling,
+clean architecture, pragmatic DDD, and feature-based architecture as decision
+tools rather than reasons to add layers.
+
+## Objects And Functions
+
+Use classes when they improve a stateful domain model, lifecycle, polymorphic
+adapter, or dependency-injected boundary. Keep stateless parsers, serializers,
+validators, and transformations as focused functions. Converting
+`frontmatter`, repository operations, or the current CLI to classes without a
+state or substitution need would add ceremony rather than clarity.
+
+Use in-process domain events when several independent reactions need
+decoupling. Do not introduce brokers or distributed event infrastructure
+without a concrete product requirement.
+
+## Package Boundaries
+
+`@taskset/contracts` is a useful boundary because clients and core share runtime
+schemas and TypeScript contracts without depending on filesystem behavior. The
+name is more accurate than `@taskset/types` because the package emits runtime
+Zod schemas.
+
+Do not add `@taskset/validations`. Static schemas belong in contracts; domain
+validation policy and migrations belong in core. A second package would split
+one responsibility and make imports harder to understand.
+
+Node libraries and the CLI build to `dist/`. Their runtime `import` exports
+point to JavaScript artifacts so builds and future packaging are actually
+verified. Source exports remain available for types and development tooling.
+
+## Tool Ownership
+
+- Keep Next.js and React compiler dependencies in `apps/www`, the only current
+  Next.js owner.
+- Keep reusable TypeScript presets in `@taskset/configs`; move framework runtime
+  configuration there only after multiple consumers need it.
+- Use TypeScript directly for Node packages and the CLI. Vitest already uses
+  Vite; add a Vite build only for a browser package or a demonstrated bundling
+  requirement.
+- Keep one repository standards skill while usage and maintenance rules share
+  product contracts. Keep its references split by topic so agents can load only
+  the relevant guidance. Split a separate user skill only when it has a distinct
+  audience, installation path, and lifecycle.
+
+## Task Semantics
+
+Priority is Taskset's importance signal, and `urgent` is its highest value.
+`order` is the optional user-controlled sequence signal. A separate urgency
+scale is intentionally omitted because overlapping importance scales increase
+ambiguity and synchronization work.