@taskset/cli 4.0.0 → 6.0.0

package/docs/getting-started.md

@@ -0,0 +1,106 @@
+---
+title: Start a Taskset repository
+description: Install the CLI, initialize `.taskset/`, and capture your first plan, decision, and task in any language repository.
+contentType: Tutorial
+navLabel: Getting Started
+---
+
+# Start a Taskset repository
+
+This guide initializes Taskset in a repository and walks one delivery loop: capture intent, record research or a decision, then track the work. You do not need a JavaScript app, and you do not need `taskset.config.ts`.
+
+## Requirements
+
+- Node.js 24 or newer to run the published CLI
+- Any Git repository or project root you can write to
+
+## Install the CLI
+
+Pick one install style:
+
+```bash
+npx @taskset/cli@latest --help
+```
+
+```bash
+pnpm add --save-dev @taskset/cli
+```
+
+```bash
+npm install --global @taskset/cli
+```
+
+The package exposes the `taskset` executable. Package runners work in repositories that never declare a Node dependency.
+
+## Initialize the repository
+
+Run init from the repository root, or from a nested directory when Git or workspace markers identify the root:
+
+```bash
+taskset init
+```
+
+This creates:
+
+```text
+.taskset/
+├── .gitignore
+├── tasks/
+├── stories/
+├── flows/
+├── decisions/
+├── research/
+└── runbooks/
+```
+
+Add an optional config file only when you need custom task defaults:
+
+```bash
+taskset init --config
+```
+
+The nested ignore file excludes `.taskset/cache/`, per-entity `.generated/` directories, and `.taskset/snapshots/`. Snapshots are non-authoritative safety checkpoints. Markdown under `.taskset/` remains canonical.
+
+## Capture intent, then track delivery
+
+Start with the durable context, then create the task that implements it:
+
+```bash
+taskset document create story --title "Member signs in via SSO"
+taskset document create research --title "Compare SSO providers" --related your_story_id_here
+taskset document create adr --title "Use OIDC for member SSO" --related your_research_id_here
+taskset task create --title "Add SSO callback handler" --related your_decision_id_here --file packages/api/src/auth.ts
+taskset task list
+taskset document list --json
+```
+
+You can read every file directly in the editor without the CLI. Cite entities by short hex `id`, never by filename sequence prefixes.
+
+## Query and validate the graph
+
+```bash
+taskset task list --status doing --label core --json
+taskset document list research --search "SSO" --json
+taskset task list --file packages/api --impact --json
+taskset doctor
+```
+
+File and directory filters use repository-relative containment. With `--impact`, list output groups direct matches and work that transitively depends on them. `doctor` reports readable format and graph failures in one non-mutating pass.
+
+## Finish or remove work
+
+```bash
+taskset task status your_task_id_here done
+taskset document status your_research_id_here accepted --type research
+taskset task delete your_task_id_here
+```
+
+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
+
+- [Choose a document type](document-types.md)
+- [Understand task files](task-files.md)
+- [Configure defaults](configuration.md)
+- [Use the complete CLI reference](cli-reference.md)
+- [Follow the agent guide](agents/index.md)

package/docs/index.md

@@ -0,0 +1,43 @@
+---
+title: Keep the whole delivery story beside the code
+description: Taskset stores plans, research, decisions, runbooks, and tasks as Markdown in your repository for agents and humans.
+contentType: Landing
+navLabel: Overview
+---
+
+# Keep the whole delivery story beside the code
+
+Taskset is a local-first delivery workspace. You keep stories, research, decisions, flows, runbooks, and executable tasks as Markdown under `.taskset/`, so agents and humans share one reviewable source of truth.
+
+Install the CLI as `@taskset/cli` from npm. Run it with `npx`, `pnpm dlx`, `yarn dlx`, `bunx`, a project dependency, or a global install.
+
+## What belongs in Taskset
+
+- **Plan**: stories and flows that define outcomes and journeys
+- **Learn**: research that captures evidence and recommendations
+- **Decide**: decisions and ADRs that lock lasting choices
+- **Operate**: runbooks that make recovery safe to repeat
+- **Deliver**: tasks that carry ownership, status, dependencies, and code impact
+
+Documents preserve memory. Tasks move work. Relationships keep the graph honest.
+
+## What you get
+
+- Project knowledge stays in the repository it describes
+- Markdown remains readable without Taskset installed
+- Agents and humans inspect the same plans, decisions, and work
+- CLI, skills, and future interfaces share one domain model
+- Monorepo paths and code relationships are first-class
+
+## What the CLI covers
+
+The CLI initializes repositories, manages optional configuration, creates and queries tasks and documents, runs diagnostics, builds generated views, snapshots state, and syncs the tree after upgrades or repairs.
+
+## Choose your path
+
+- [Start a Taskset repository](getting-started.md)
+- [Choose a document type](document-types.md)
+- [Understand task files](task-files.md)
+- [Configure defaults when you need them](configuration.md)
+- [Look up every CLI command](cli-reference.md)
+- [Read agent workflows and contracts](agents/index.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,44 @@
+---
+title: "ADR 0001: Documentation Platform"
+description: Render canonical documentation through the Taskset website for humans, agents, and maintainers.
+---
+
+# ADR 0001: Documentation Platform
+
+- Status: Accepted
+- Date: 2026-06-12
+- Updated: 2026-10-03
+
+## Context
+
+Taskset needs one documentation source that is readable on Git hosts and can also power a documentation website. Human usage guidance, agent operating contracts, and repository maintenance material have different audiences and should remain visibly separated.
+
+## Decision
+
+- Keep canonical documentation in the root `docs/` directory
+- Keep human usage pages at the top level of `docs/`
+- Keep agent operating guidance under `docs/agents/`, with root `AGENTS.md` and packaged `skills/` as offline entrypoints
+- Keep contributor, product, architecture, ADR, testing, and technology material under `docs/maintainers/`
+- Publish an agent discovery index at `apps/www/public/llms.txt` (served as `/llms.txt`); copy it into the packaged CLI docs for offline use
+- 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 (including `docs/agents/`) and `docs/maintainers/` through separate route layouts and page maps
+- Keep chronological release and project posts under `apps/www/posts/`
+- Follow the [Vercel writing guidelines](https://github.com/vercel-labs/writing-guidelines) for public prose voice and structure
+
+## Why
+
+This keeps one Markdown source of truth while matching how agent-first tools expose denser contracts beside human onboarding. Maintainer material stays out of the primary product navigation. Agent pages and `llms.txt` give coding agents a short index without inventing a second product truth.
+
+## Implementation Contract
+
+`apps/www/content` points to `../../docs`. The usage docs catch-all route loads top-level content, including `docs/agents/`, and excludes `docs/maintainers/` from its page map. The `/maintainers` route loads the same content directory with a maintainer-rooted page map. Root `AGENTS.md` is repository-local agent guidance and may be linked from docs, but docs remain canonical for published pages. Do not place non-Markdown discovery files such as `llms.txt` under `docs/`; Nextra imports the content tree as modules and only Markdown/MDX pages belong there.
+
+## Consequences
+
+- Documentation changes are reviewable without building the site
+- Blog posts are reviewable as app-local Markdown without a CMS
+- New agent pages belong under `docs/agents/` and appear in usage navigation
+- Maintainer documentation 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,58 @@
+---
+title: Contributing
+description: Repository setup, Taskset dogfooding, pull requests, and completion rules.
+---
+
+# Contributing
+
+Keep the core file format and workflow coherent when you change interfaces, packages, or docs.
+
+## 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/` data, optional `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,52 @@
+---
+title: Documentation
+description: How Markdown becomes the Taskset documentation website for humans, agents, and maintainers.
+---
+
+# Documentation
+
+The root `docs/` directory is canonical. Split audiences deliberately:
+
+- Humans: top-level usage pages
+- Agents: `docs/agents/`, root `AGENTS.md`, and packaged `skills/`
+- Maintainers: `docs/maintainers/`
+
+Follow the [Vercel writing guidelines](https://github.com/vercel-labs/writing-guidelines) for public prose.
+
+## 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`, `description`, and `contentType` frontmatter for usage and agent pages
+- 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/`
+- Keep agent operating contracts under `docs/agents/`
+- Keep `/llms.txt` in `apps/www/public/llms.txt`, not under `docs/`, so Nextra does not import it as a page module
+- 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. The top-level usage docs route filters `docs/maintainers/` out of its primary navigation, and the dedicated `/maintainers` route renders 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`.
+
+Run the Next.js development and production builds in webpack mode. Turbopack does not reliably discover newly added Markdown through the external content symlink.
+
+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.