@taskset/cli 5.1.0 → 6.1.0

package/docs/maintainers/development/documentation.md

@@ -1,69 +1,52 @@
 ---
 title: Documentation
-description: How user Markdown becomes the Taskset documentation website.
+description: How Markdown becomes the Taskset documentation website for humans, agents, and maintainers.
 ---
 
 # 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/`.
+The root `docs/` directory is canonical. Split audiences deliberately:
 
-## Recommended Website Stack
+- Humans: top-level usage pages
+- Agents: `docs/agents/`, root `AGENTS.md`, and packaged `skills/`
+- Maintainers: `docs/maintainers/`
 
-Use Next.js App Router, Nextra, `nextra-theme-docs`, and
-`nextra-theme-blog` in `apps/www`.
+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
+- 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]`.
+## 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 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.
+`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/index.md

@@ -5,9 +5,7 @@ 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.
+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
 

package/docs/maintainers/product/vision.md

@@ -7,9 +7,7 @@ description: Maintainer-facing product direction for Taskset.
 
 ## 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.
+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
 
@@ -17,18 +15,15 @@ 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.
+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.
-- Make monorepos, packages, applications, and code paths first-class.
-- Let managers and stakeholders view repository-backed information without
-  creating another source of truth.
+- 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
 
@@ -38,39 +33,38 @@ 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.
+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.
+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.
+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.
+Every interface reads and changes the same canonical `.taskset/` files through the same domain rules.
 
-### Developer first
+### Agent first, human readable
 
-Taskset proves developer workflows before broad enterprise planning features.
+Taskset optimizes distribution, discovery, and docs for agent operators while keeping Markdown reviewable by humans.
 
-## Near-Term Scope
+### Memory and execution together
 
-The MVP should implement:
+Documents preserve product and engineering memory. Tasks carry ownership, status, and delivery. Relationships bind them into one graph.
 
-- 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
+## Current product surface
 
-TUI, MCP, extension, Kanban, Office, and integrations follow after the file and
-core contracts are reliable.
+The current surface includes:
+
+- repository initialization and optional configuration
+- tasks with lifecycle, dependencies, search, and impact queries
+- stories, flows, decisions, research, runbooks, lessons, concerns, and audits
+  with the same query and mutation family, plus program rollups and optional
+  closeout gates
+- 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/memory-model.md

@@ -0,0 +1,58 @@
+---
+title: Choose Taskset memory layers
+description: When to use task bodies versus research, decisions, runbooks, lessons, and concerns.
+contentType: Conceptual
+navLabel: Memory Model
+---
+
+# Choose Taskset memory layers
+
+Taskset keeps three memory layers in one `.taskset/` store:
+
+| Layer | Kinds | Question it answers |
+| --- | --- | --- |
+| Delivery | tasks (+ checklist subtasks) | What work is open, blocked, or done? |
+| Decision | research, decision/adr, runbook, story, flow | What did we learn, choose, or need to operate? |
+| Operational | lesson, concern, audit | What recurring mistakes, open risks, and spot-checks must future agents respect? |
+
+Do not invent freeform kinds such as `note`, `rfc`, `epic`, or `spec`. Map those intents onto the kinds above.
+
+## Quick chooser
+
+| Situation | Put it here |
+| --- | --- |
+| One-off execution steps for the current outcome | Task body checklist |
+| Independently owned or sequenced deliverable | Child task (`--parent`) |
+| Options, evidence, recommendation still forming | `research` |
+| Lasting architectural or product choice | `decision` / `adr` |
+| Repeatable recovery or ops procedure | `runbook` |
+| User outcome / journey context | `story` / `flow` |
+| Recurring mistake or correct pattern future agents must not rediscover | `lesson` (`antipattern` alias) |
+| Open residual risk (security, authz, money, ops, …) | `concern` |
+| Structured inventory or spot-check pass/fail evidence | `audit` |
+
+## Anti-examples
+
+Bad: close a security task with the lesson only in chat or the finished task body.
+
+Good: create a `lesson`, `--related` the task (and concern if any), and if `--related-skill` is set, update that skill in the same change.
+
+Bad: track “remaining authz risk” as an unfinished checklist item forever.
+
+Good: create a `concern` with class, trust boundary, residual risk, and review cadence; keep it `active` until mitigated or formally `accepted`.
+
+Bad: dump an ADR program into one epic-shaped Markdown note.
+
+Good: use a parent task as the program root, child tasks for workstreams, related `concern` / `research` / `audit` documents for residual risk and evidence, and `taskset task program <parent-id> --json` for rollup.
+
+Bad: edit a consumer primary skill automatically from Taskset.
+
+Good: store the lesson in Taskset; update the skill only when the consumer opts in via `--related-skill` (or an explicit later promote helper). Taskset never auto-edits skills by default.
+
+## Related docs
+
+- [Document types](document-types.md)
+- [Security and compliance tracking](security-compliance-tracking.md)
+- [Agent closeout contract](agent-closeout.md)
+- [Taxonomy cookbook](taxonomy-cookbook.md)
+- [Query recipes for agents](agents/query-recipes.md)

package/docs/security-compliance-tracking.md

@@ -0,0 +1,107 @@
+---
+title: Track security and compliance in Taskset
+description: Model ADR programs, audits, residual risk, and continuous inventories with concerns, lessons, and program rollups.
+contentType: How-to
+navLabel: Security Tracking
+---
+
+# Track security and compliance in Taskset
+
+Use Taskset’s operational memory kinds for security programs without a second tracker.
+
+## Model
+
+| Artifact | Kind | Role |
+| --- | --- | --- |
+| Program root | Parent task (optional `program` label/project) | Rollup + closeout owner |
+| Workstreams | Child tasks | Independently trackable delivery |
+| Design choices | `decision` / `adr` | Lasting accepted choices |
+| Spot checks | `audit` | Inventory / matrix pass-fail evidence |
+| Residual risk | `concern` | Living open-risk register |
+| Recurring failure modes | `lesson` | Prevent rediscovery |
+
+## Create a concern
+
+```bash
+taskset document create concern \
+  --title "Telegram capability must not grant CASL" \
+  --class authz \
+  --cadence on-release \
+  --label security \
+  --directory apps/bot \
+  --related <task-id> \
+  --json
+```
+
+Concern statuses:
+
+- open work → `draft` / `ready` / `active`
+- mitigated or formally accepted → `accepted`
+- replaced → `superseded`
+- retired → `archived`
+
+## Create a lesson
+
+```bash
+taskset document create lesson \
+  --title "Capability flags are enablement only" \
+  --severity high \
+  --related-skill .agents/skills/security/SKILL.md \
+  --pack security \
+  --related <concern-or-task-id> \
+  --json
+```
+
+When `--related-skill` is present, agents should update that skill in the same change. Taskset stores the evidence and pattern; it does not auto-edit the skill.
+
+## Audits
+
+Prefer the `audit` kind for structured inventories:
+
+```bash
+taskset document create audit --title "Public route inventory" --related <program-task-id> --json
+```
+
+Template covers scope, method, findings (`pass` | `fail` | `residual`), residual items, required follow-ups, and next due date.
+
+## Program health and closeout
+
+```bash
+taskset task program <parent-id> --json
+taskset doctor --json
+```
+
+Optional closeout gates in `taskset.config.ts` (default off):
+
+```typescript
+import { defineConfig } from '@taskset/cli'
+
+export default defineConfig({
+	closeout: {
+		enforceChildCompletion: true,
+		blockDoneWithOpenConcerns: true,
+		requireLessonWhenLabeled: ['requires-lesson'],
+	},
+	taxonomy: {
+		labels: ['security', 'trust-boundary', 'public-ingress', 'authz', 'concurrency'],
+		projects: ['platform', 'bot'],
+		concernClasses: ['security', 'privacy', 'authz', 'concurrency', 'ops', 'compliance'],
+		mode: 'error',
+	},
+	doctor: {
+		activeConcernRequiresOwner: true,
+		staleResearchDays: 14,
+	},
+})
+```
+
+## Example label set
+
+Reuse stable taxonomy instead of inventing labels each task:
+
+- `trust-boundary`
+- `public-ingress`
+- `authz`
+- `concurrency`
+- `adr-NNNN` (link-style labels for named ADRs)
+- `requires-lesson` (closeout gate trigger when configured)

package/docs/task-files.md

@@ -1,16 +1,19 @@
 ---
-title: Task Files
+title: Understand Taskset task files
 description: The canonical Markdown representation for Taskset work items.
+contentType: Conceptual
+navLabel: Task Files
 ---
 
-# Task Files
+# Understand Taskset task files
 
-Task files live under `.taskset/tasks/`. YAML frontmatter owns structured
-metadata and the Markdown body owns durable human context.
+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, runbooks, lessons, concerns, and audits](document-types.md) when the surrounding memory should stay durable. For multi-task programs, use `taskset task program <parent-id> --json`.
+
+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: 0000001-add-task-validation
+id: a1b2c3
 title: Add task validation
 status: doing
 priority: high
@@ -48,9 +51,10 @@ 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 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:
 
@@ -74,10 +78,12 @@ 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/`.
+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.
@@ -126,7 +132,7 @@ text, file, and directory filters. Numeric and timestamp ranges are inclusive:
 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
+taskset task list --duplicate a1b2c3
 ```
 
 Repeated enum, person, project, file, and directory values use OR within the

package/docs/taxonomy-cookbook.md

@@ -0,0 +1,59 @@
+---
+title: Control Taskset taxonomy
+description: Allowlists for labels, projects, and concern classes with doctor enforcement.
+contentType: How-to
+navLabel: Taxonomy Cookbook
+---
+
+# Control Taskset taxonomy
+
+Without allowlists, Taskset accepts any trimmed label, project, or concern class from the built-in concern vocabulary. Configure allowlists when discovery drift becomes expensive.
+
+## Config
+
+```typescript
+import { defineConfig } from '@taskset/cli'
+
+export default defineConfig({
+	taxonomy: {
+		labels: [
+			'security',
+			'trust-boundary',
+			'public-ingress',
+			'authz',
+			'concurrency',
+			'requires-lesson',
+			'program',
+		],
+		projects: ['platform', 'bot', 'wallet'],
+		concernClasses: ['security', 'privacy', 'authz', 'concurrency', 'ops', 'compliance', 'money'],
+		mode: 'error', // or 'warn'
+	},
+})
+```
+
+Rules:
+
+- Empty / omitted allowlists keep permissive behavior.
+- `concernClasses` values must be from the canonical set: `security`, `privacy`, `money`, `authz`, `concurrency`, `ops`, `compliance`, `other`.
+- `mode: 'error'` rejects create/update mutations with unknown values and fails doctor.
+- `mode: 'warn'` allows mutations; doctor reports `unknown-taxonomy` warnings and still exits `0` when no errors exist.
+
+## Example security taxonomy
+
+| Label / class | Use for |
+| --- | --- |
+| `trust-boundary` | Cross-plane trust assumptions |
+| `public-ingress` | Unauthenticated or internet-facing entry |
+| `authz` | Authorization grants and checks |
+| `concurrency` | Race / idempotency hazards |
+| `adr-NNNN` | Work tied to a named ADR |
+| `requires-lesson` | Closeout must produce a related `lesson` when closeout config enables it |
+
+## Doctor
+
+```bash
+taskset doctor --json
+```
+
+Look for `unknown-taxonomy`, `missing-template-heading`, `missing-reference`, `closeout-gap`, `missing-owner`, and `stale-research` diagnostics.

package/package.json

@@ -2,8 +2,8 @@
   "name": "@taskset/cli",
   "type": "module",
   "private": false,
-  "version": "5.1.0",
-  "description": "The scriptable command-line interface for Taskset.",
+  "version": "6.1.0",
+  "description": "CLI for Taskset: plan, research, decide, operate, and track repository work as Markdown.",
   "license": "MIT",
   "author": {
     "name": "junkieshuffle",
@@ -46,8 +46,8 @@
   },
   "dependencies": {
     "zod": "4.6.5",
-    "@taskset/contracts": "5.0.0",
-    "@taskset/core": "5.0.0"
+    "@taskset/core": "6.1.0",
+    "@taskset/contracts": "6.1.0"
   },
   "devDependencies": {
     "@types/node": "^26.6.3",