@taskset/cli 4.0.0 → 5.1.0

package/skills/taskset-implement/references/conventions.md

@@ -0,0 +1,40 @@
+# Conventions
+
+Use this file as the routing map for implementation conventions. Load only the
+topic file needed for the change, then load additional files when the work
+crosses that boundary.
+
+## Routing
+
+- [design.md](conventions/design.md): general design heuristics, SOLID,
+  clean architecture, DDD, feature-based architecture, comments, and diff scope
+- [naming-and-packages.md](conventions/naming-and-packages.md): file, symbol,
+  command, package, and configuration naming
+- [typescript-and-exports.md](conventions/typescript-and-exports.md):
+  TypeScript style, package exports, import boundaries, dependency declarations,
+  and shared configuration
+- [task-files.md](conventions/task-files.md): canonical Taskset entity
+  frontmatter, Markdown body, validation, relationship, timestamp, and
+  serialization rules
+- [interfaces-and-ui.md](conventions/interfaces-and-ui.md): CLI behavior,
+  client ownership, React/TanStack preferences, Kanban, and Office UI rules
+- [backend-and-tooling.md](conventions/backend-and-tooling.md): backend
+  technology choices, database policy, shell scripts, and automation ownership
+- [tests-and-docs.md](conventions/tests-and-docs.md): testing conventions,
+  documentation ownership, docs site content rules, README rules, and completion
+  documentation expectations
+
+## Loading Guidance
+
+- For new or renamed files, packages, exports, commands, or public types, load
+  `naming-and-packages.md` and `typescript-and-exports.md`.
+- For task metadata, canonical Markdown entity files, parsers, serialization,
+  or validation, load `task-files.md`.
+- For CLI, UI, website client, Kanban, Office, extension, TUI, or MCP behavior,
+  load `interfaces-and-ui.md`.
+- For scripts, backend/server technology, or dependency/tooling decisions, load
+  `backend-and-tooling.md`.
+- For tests, READMEs, docs, posts, or completion documentation updates, load
+  `tests-and-docs.md`.
+- For broad design or architecture-sensitive implementation, load `design.md`
+  first, then the specific owner file.

package/skills/taskset-implement/references/release.md

@@ -0,0 +1,135 @@
+# Release and Completion
+
+## Changesets
+
+The consumer-facing npm package is `@taskset/cli`. It exposes the `taskset`
+executable, re-exports `defineConfig` for `taskset.config.ts`, and ships the
+repository `docs/` and `skills/` trees in the published tarball (copied beside
+the package during `pnpm --filter @taskset/cli build`).
+
+The public runtime package set is:
+
+```text
+@taskset/cli
+@taskset/core
+@taskset/contracts
+@taskset/utils
+```
+
+The CLI depends on the other public packages, so they must remain publishable
+unless the CLI is deliberately changed to bundle them. Configs, unfinished
+interfaces, and apps remain private.
+
+`.github/workflows/publish-npm.yml` runs repository validation and then uses
+`pnpm --recursive publish --access public --no-git-checks` when a GitHub Release
+is published. pnpm skips private workspaces and publishes the public dependency
+chain. The workflow requires the `NPM_TOKEN` repository secret and enables npm
+provenance through GitHub's OIDC permission.
+
+The npm account used by CI must control the `@taskset` scope.
+
+Once configured, create a Changeset when a versioned package's behavior,
+contract, build, persisted format, or user-visible tooling changes:
+
+```bash
+pnpm changeset
+```
+
+Select the exact current manifest names for changed public packages:
+
+```text
+@taskset/contracts
+@taskset/utils
+@taskset/core
+@taskset/cli
+```
+
+Do not add Changesets for private packages or select a duplicate or misplaced
+scaffold name. Correct package identity first.
+
+Choose the bump by impact:
+
+- `patch`: compatible fix or internal correction
+- `minor`: compatible feature, command, field, tool, or public behavior
+- `major`: breaking API, package identity, command contract, persisted schema,
+  migration requirement, or workflow change
+
+Persisted Markdown compatibility is a public contract. A parser change that
+makes existing repositories unreadable is breaking.
+
+Write summaries for users:
+
+- lead with behavior
+- state compatibility and migration consequences
+- avoid raw file lists and implementation diaries
+
+Do not create a Changeset for:
+
+- `skills/` instructions
+- tests-only changes
+- internal documentation corrections
+- formatting-only changes
+- repository notes that do not alter supported behavior
+
+Use these only during explicit release work:
+
+```bash
+pnpm changeset status
+pnpm changeset version
+```
+
+Do not manually edit package versions or generated changelogs during ordinary
+feature work.
+
+## Commit Language
+
+Prefer concise conventional subjects:
+
+```text
+feat(core): add deterministic task parsing
+fix(cli): report malformed frontmatter
+refactor(types): unify relationship contracts
+chore(tooling): align workspace package names
+docs(standards): migrate repository guidance to Taskset
+```
+
+Use an imperative, behavior-focused subject. Add a body when architecture,
+compatibility, migration, or verification needs explanation.
+
+## Compatibility Review
+
+Review these surfaces before release:
+
+- Markdown and frontmatter read compatibility
+- defaults, enums, and validation strictness
+- generated filenames and entity IDs
+- CLI command names, flags, output, and exit codes
+- MCP tool names, input schemas, and result shapes
+- package exports and runtime requirements
+- configuration file names and defaults
+- relationship and graph semantics
+- snapshot creation and restore semantics
+- documentation routes and public examples
+
+Do not call a change internal merely because only one current interface uses it.
+If it affects canonical repository data, it affects every future interface.
+
+## Definition of Done
+
+A change is complete when:
+
+- the requested outcome is correct, not merely implemented literally
+- canonical `.taskset/` data remains the persistent authority
+- all affected schemas, core operations, clients, tests, and docs agree
+- no interface-specific duplicate of domain behavior was introduced
+- package names, exports, and dependencies match ownership
+- user-owned worktree changes remain intact
+- focused tests cover new or corrected behavior
+- broader checks match the blast radius
+- persisted format changes include compatibility and migration handling
+- generated outputs were regenerated rather than hand-edited
+- a Changeset exists when release policy requires one
+- documentation uses current paths, commands, and package names
+- `skills/taskset-implement/` was updated when repository rules or workflows changed
+- the final report distinguishes passed checks, skipped checks, prerequisites,
+  and pre-existing failures

package/skills/taskset-implement/references/workflows/dependencies-and-docs-site.md

@@ -0,0 +1,54 @@
+# Dependencies And Docs Site
+
+Dependency management, website workflow, publishing pages, and backend dependency choices.
+
+## Dependency Management
+
+Add dependencies to the package that imports them:
+
+```bash
+pnpm --filter <package-name> add <runtime-package>
+pnpm --filter <package-name> add --save-dev <tooling-package>
+pnpm --filter <package-name> add @taskset/core@workspace:*
+```
+
+Rules:
+
+- Do not add a root dependency to make a child package compile.
+- Do not rely on root hoisting, transitive dependencies, or another package's
+  `node_modules`.
+- Keep browser and React dependencies out of core, types, and domain-light
+  utilities.
+- Prefer one parser, validator, and serialization stack for the canonical file
+  format.
+- Review license, runtime support, ESM compatibility, maintenance, and bundle
+  impact before adding foundational dependencies.
+- Keep lockfile changes scoped to the dependency operation.
+
+Frontend packages should follow the TanStack preference in
+`docs/maintainers/technology.md`, but only install Query, Form, Table, Hotkeys,
+Pacer, Virtual, DB, or their devtools when the owning feature uses them.
+
+`@taskset/www` uses Next.js webpack mode for development and production because
+Turbopack does not reliably discover new files through the external `docs/`
+content symlink.
+
+The website renders canonical documentation from the `apps/www/content`
+symlink and canonical blog posts from `apps/www/posts/`. Top-level usage docs
+and `docs/maintainers/` use separate route layouts and page maps; keep
+maintainer material out of the primary usage-docs navigation. Add each post to
+`apps/www/src/blog/posts.ts` so `/posts/[slug]` remains statically enumerable.
+Docs and blog routes use separate Nextra theme wrappers.
+
+`.github/workflows/publish-pages.yml` builds `@taskset/www` as a static export
+and deploys `apps/www/out` to GitHub Pages on pushes to `main` or manual
+dispatch. The workflow supplies the Pages base path through `STATIC_EXPORT` so
+project sites work below the repository subpath; `/` represents a root site.
+Local development and server builds keep their normal Next.js configuration.
+
+For backend work, prefer TypeScript first. Add NestJS,
+`class-transformer`, `class-validator`, and TypeORM only in the owning server
+application when its architecture needs them. Use Rust for a clearly bounded
+systems-level component, not as an incidental second implementation of core
+domain behavior. Choose MariaDB for smaller hosted applications and PostgreSQL
+for larger or more advanced relational workloads.

package/skills/taskset-implement/references/workflows/environment-and-pnpm.md

@@ -0,0 +1,108 @@
+# Environment And Pnpm
+
+Pinned environment, pnpm, Turbo, Taskset dogfooding, and package scripts.
+
+## Environment and Setup
+
+Use the versions pinned by the repository:
+
+- Node `24.16.0` from `.nvmrc`
+- pnpm `11.5.2` from `packageManager`
+- TypeScript and other tools from the lockfile
+
+Initial setup:
+
+```bash
+pnpm install --frozen-lockfile
+```
+
+Do not replace pnpm with npm, Yarn, or Bun for workspace operations. Update
+`.nvmrc`, `engines`, `packageManager`, and the lockfile together when changing
+the supported toolchain.
+
+## pnpm and Turbo
+
+`pnpm-workspace.yaml` recursively includes `apps/**` and `packages/**`.
+
+Current root commands:
+
+```bash
+pnpm dev
+pnpm build
+pnpm test
+pnpm test:watch
+pnpm lint
+pnpm format
+pnpm check
+pnpm clean
+pnpm taskset
+```
+
+Current behavior:
+
+- `dev` runs `turbo dev`.
+- `build` runs dependency builds first through Turbo.
+- `test` uses Turbo to run package-local Vitest suites plus the root workspace
+  architecture suite exposed as `test:architecture`.
+- `test:watch` uses Turbo to start package-local Vitest watch tasks.
+- `check` runs lint, tests, and the build in sequence.
+- `lint` runs `biome check .` without writing fixes.
+- `format` runs `biome format --write .`.
+- `clean` runs the Turbo clean task.
+- `taskset` runs the built entrypoint from the root workspace-installed
+  `@taskset/cli` package. Build first when generated `dist/` output is absent.
+
+`@taskset/contracts`, `@taskset/utils`, `@taskset/core`, and `@taskset/cli`
+currently define `build` and `test`. Their builds run strict TypeScript
+compilation into disposable `dist/` output, and their tests run the owning
+source tests through the root Vitest config. Other packages remain scaffolds,
+so inspect each affected manifest before assuming it defines `build`, `test`,
+`typecheck`, or `dev`.
+
+Those four packages form the public npm runtime and are published recursively.
+Keep their runtime dependency chain public and keep package tarballs restricted
+to built output, runtime source used by workspace development conditions,
+package documentation, and—for `@taskset/cli`—the copied repository `docs/` and
+`skills/` trees. Exclude tests, local build caches, and tool configs.
+Their builds clean `dist/` before TypeScript emits so renamed files cannot leak
+into published tarballs. The CLI build also refreshes `packages/cli/docs` and
+`packages/cli/skills` from the repository root; those copies are gitignored and
+must be present in the tarball listed by the CLI `files` field.
+
+Use exact package names:
+
+```bash
+pnpm --filter @taskset/core test
+pnpm --filter @taskset/cli build
+pnpm --filter @taskset/mcp dev
+```
+
+The repository dogfoods Taskset through:
+
+```bash
+pnpm build
+pnpm taskset config --json
+pnpm taskset task list
+pnpm taskset task create --title "Describe the work"
+pnpm taskset task list --file packages/core --impact
+pnpm taskset task status <task-id> doing
+pnpm taskset snapshot create
+pnpm taskset doctor
+```
+
+Package-local `test` and `test:watch` scripts are required because Turbo
+orchestrates scripts declared by each workspace and filtered package commands
+must remain available. Root-only architecture tests run once after Turbo rather
+than being duplicated inside every package. There is no `transit` script;
+Turbo's dependency traversal is orchestration, not another test suite.
+
+`taskset.config.ts` is loaded as trusted project code using Node's native
+erasable TypeScript support. Keep it free of syntax that requires TypeScript
+code generation.
+
+If Turbo reports duplicate workspace names, fix the incorrect package manifest.
+Do not work around the graph with directory filters or aliases.
+
+`pnpm update-deps` performs broad recursive upgrades, deduplication, and audit
+mutation. Run it only for an explicit dependency-update task and review the
+lockfile and compatibility impact.

package/skills/taskset-implement/references/workflows/persisted-data-and-git.md

@@ -0,0 +1,30 @@
+# Persisted Data And Git Workflows
+
+Persisted format, generated view, Git, and concurrency-sensitive workflow rules.
+
+## Persisted Data and Git Workflows
+
+Use temporary fixture repositories for tests that invoke Git. Configure test
+identity locally inside the fixture; never depend on the developer's global Git
+configuration.
+
+For persisted format changes:
+
+1. Add old-format fixtures.
+2. Define read compatibility and write behavior.
+3. Implement an explicit compatibility path when rewriting is required.
+4. Verify compatibility behavior and rollback safety.
+5. Preserve a recoverable backup or fail before mutation.
+6. Document user-visible consequences.
+
+For generated indexes and views:
+
+1. Delete the derived state under each entity folder's `.generated/` directory.
+2. Rebuild it from canonical entities in that folder's scope.
+3. Verify equivalent observable output and stale-file removal.
+4. Confirm `.taskset/.gitignore` ignores `**/.generated/` and staging
+   `**/.generated.*/` paths; do not revive a global `.taskset/generated/`.
+
+For concurrency-sensitive writes, test stale reads, competing updates, and
+partial failures. Do not imply database-style transaction guarantees that the
+filesystem and Git do not provide.

package/skills/taskset-implement/references/workflows/validation.md

@@ -0,0 +1,34 @@
+# Validation Workflow
+
+Validation command order, root checks, and handling unrelated failures.
+
+## Validation
+
+Start narrow:
+
+```bash
+pnpm --filter <package-name> test
+pnpm --filter <package-name> build
+```
+
+Then run relevant root checks:
+
+```bash
+pnpm lint
+pnpm test
+pnpm build
+git diff --check
+```
+
+Use `pnpm format` only when formatting changes are intended, then inspect the
+diff. Biome is authoritative; do not introduce ESLint or Prettier to solve a
+local issue.
+
+When a root check fails because of pre-existing scaffold state:
+
+1. Confirm the failure is unrelated to the current change.
+2. Run the narrowest check that validates the changed owner.
+3. Report the exact blocker.
+4. Fix it only when it belongs to the request or prevents reliable validation.
+
+Never claim an unrun or failed check passed.

package/skills/taskset-implement/references/workflows/vitest-and-test-strategy.md

@@ -0,0 +1,82 @@
+# Vitest And Test Strategy
+
+Vitest workflow and Taskset-specific test coverage strategy.
+
+## Vitest and Test-Driven Development
+
+Vitest is the default runner for TypeScript domain, filesystem, CLI adapter, and
+integration tests. Use the root `vitest.config.ts` until a package needs a
+distinct runtime such as browser mode. Add Vitest `projects` only when separate
+Node, browser, or extension environments provide real value.
+Vitest already uses Vite internally. Do not add a standalone Vite build to
+Node-focused libraries or the CLI unless a concrete bundling requirement
+appears; use the owning UI application's build tool for browser products.
+
+Compile Node libraries and the CLI to `dist/` and keep the runtime `import`
+export pointed at emitted JavaScript. Source exports may serve types and
+development tooling, but source-only runtime exports are not a substitute for
+verifying executable build artifacts.
+
+Use this loop for domain behavior and bug fixes:
+
+1. Write or update the smallest failing test that describes observable
+   behavior.
+2. Implement the minimum coherent behavior.
+3. Refactor with tests green.
+4. Add boundary and failure cases proportional to risk.
+5. Run the owning suite, then broader repository checks.
+
+TDD is a feedback technique, not a coverage quota. Avoid testing private helper
+shape, reproducing the implementation in mocks, or creating snapshots that
+hide meaningful behavioral assertions.
+
+Vitest snapshots are acceptable for stable serialized output, diagnostics, and
+small renderer fragments when review remains readable. They are unrelated to
+Taskset repository safety snapshots.
+
+## Taskset Test Strategy
+
+### Types and schema
+
+- valid and invalid enum values
+- required and optional fields
+- defaults and versionless task reads/writes
+- forward and backward compatibility fixtures
+
+### Parsing and serialization
+
+- YAML frontmatter and Markdown body separation
+- deterministic key ordering and final newlines
+- parse/serialize round-trip stability
+- Unicode and CRLF input
+- unknown, malformed, and duplicate fields
+- preservation of human-authored Markdown
+
+### Storage and CRUD
+
+- repository discovery
+- create, read, update, move, and delete
+- atomic replacement and cleanup after failure
+- duplicate IDs and filename collisions
+- path traversal and symlink boundaries
+- explicit timestamps through a test clock
+- restore previews and atomic apply
+
+### Graph and search
+
+- missing references and cycles
+- canonical versus derived relationships
+- stable traversal and query ordering
+- project, package, file, and directory matching
+- monorepo impact analysis fixtures
+
+### Interfaces
+
+- CLI exit codes, stdout, stderr, and structured output
+- MCP tool schemas and error mapping
+- TUI keyboard behavior
+- extension lifecycle and repository switching
+- Kanban and Office loading, stale, conflict, and failure states
+
+Prefer realistic fixture repositories over mocks for filesystem and Git
+behavior. Keep unit-level domain logic pure where possible.

package/skills/taskset-implement/references/workflows.md

@@ -0,0 +1,33 @@
+# Workflows
+
+Use this file as the routing map for repository workflows. Load only the topic
+file needed for the change, then load additional files when the work crosses
+that boundary.
+
+## Routing
+
+- [environment-and-pnpm.md](workflows/environment-and-pnpm.md): pinned Node and
+  pnpm versions, root commands, Turbo behavior, package scripts, Taskset
+  dogfooding, and dependency update caveats
+- [dependencies-and-docs-site.md](workflows/dependencies-and-docs-site.md):
+  dependency installation rules, docs website workflow, GitHub Pages static
+  export, and backend dependency preferences
+- [validation.md](workflows/validation.md): validation command order, root
+  checks, formatting, and handling unrelated scaffold failures
+- [vitest-and-test-strategy.md](workflows/vitest-and-test-strategy.md): Vitest
+  workflow, TDD guidance, and Taskset test coverage strategy
+- [persisted-data-and-git.md](workflows/persisted-data-and-git.md): persisted
+  data, generated view, Git fixture, compatibility, and concurrency workflows
+
+## Loading Guidance
+
+- For setup, root commands, package scripts, Turbo behavior, or Taskset
+  dogfooding, load `environment-and-pnpm.md`.
+- For adding dependencies, website/docs builds, static export, or backend
+  dependency choices, load `dependencies-and-docs-site.md`.
+- For any implementation or documentation change that needs verification, load
+  `validation.md`.
+- For tests, bug fixes, parser behavior, CLI behavior, or domain changes, load
+  `vitest-and-test-strategy.md`.
+- For persisted format changes, generated views, snapshots, Git fixture tests,
+  or concurrency-sensitive writes, load `persisted-data-and-git.md`.