@taskset/cli 6.0.0 → 6.1.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @taskset/cli
 
+## 6.1.0
+
+### Minor Changes
+
+- Add operational memory document kinds (`lesson`, `concern`, `audit`), program rollup, optional closeout gates, and taxonomy allowlists.
+  
+  Agents can create and query lessons, concerns, and audits under `.taskset/` with the same document command surface as existing kinds. `taskset task program` summarizes parent-task programs. Optional `closeout`, `taxonomy`, and `doctor` config keep defaults compatible with existing repositories. `taskset sync` creates the new directories.
+
+### Patch Changes
+
+- Updated dependencies
+  - @taskset/contracts@6.1.0
+  - @taskset/core@6.1.0
+
 ## 6.0.0
 
 ### Major Changes

package/README.md

@@ -1,6 +1,6 @@
 # @taskset/cli
 
-The public command-line adapter for Taskset, the Git-native workspace for plans, research, decisions, runbooks, and executable tasks. Full documentation is on [taskset.false.foundation](https://taskset.false.foundation/), including the [CLI reference](./docs/cli-reference.md), [document types](./docs/document-types.md), and [agent guide](./docs/agents/index.md).
+The public command-line adapter for Taskset, the Git-native workspace for plans, research, decisions, runbooks, lessons, concerns, audits, and executable tasks. Full documentation is on [taskset.false.foundation](https://taskset.false.foundation/), including the [CLI reference](./docs/cli-reference.md), [document types](./docs/document-types.md), [memory model](./docs/memory-model.md), and [agent guide](./docs/agents/index.md).
 
 The published package ships the repository `docs/` and `skills/` trees beside the CLI so agents can load offline references from `node_modules/@taskset/cli/docs` and `node_modules/@taskset/cli/skills`.
 
@@ -29,7 +29,7 @@ The package owns argument tokenization, Zod-backed command validation, output, a
 - `taskset document create|import|batch|list|show|update|status|delete` (`doc` is an alias)
 - `taskset snapshot create|list|restore`
 
-`init` creates `.taskset/` for tasks, stories, flows, decisions, research, and runbooks without requiring a config file. Pass `--config` for optional `taskset.config.ts`.
+`init` creates `.taskset/` for tasks, stories, flows, decisions, research, runbooks, lessons, concerns, and audits without requiring a config file. Pass `--config` for optional `taskset.config.ts`.
 
 Exit code `0` means success, `1` means a repository or domain failure, and `2` means invalid CLI usage. Commands reserve stdout for requested output and send diagnostics to stderr.
 

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAuGA,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CACzC;AA6uBD,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAu5B/F"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AA6GA,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CACzC;AAgvBD,wBAAsB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAy7B/F"}

package/dist/cli.js

@@ -1,8 +1,8 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
-import { DocumentIdSchema, DocumentStatusSchema, DocumentTimestampSchema, TaskIdSchema, TaskPrioritySchema, TaskRiskSchema, TaskStatusSchema, TaskTimestampSchema, } from '@taskset/contracts';
-import { buildDocumentGraph, buildTaskIndex, createDocument, createSnapshot, createTask, DOCUMENT_SORT_DIRECTIONS, DOCUMENT_SORT_KEYS, DocumentQuerySchema, deleteDocument, deleteTask, diagnoseRepository, discoverRepository, executeDocumentBatch, generateViews, importDocument, initializeRepository, listDocuments, listSnapshots, migrateTaskIds, normalizeDocumentKind, normalizeRepositoryPath, queryDocuments, queryTasks, RepositoryPathError, readDocument, readTask, restoreSnapshot, serializeDocumentFile, serializeTaskFile, syncRepository, TASK_SORT_DIRECTIONS, TASK_SORT_KEYS, TaskQuerySchema, updateDocument, updateTask, } from '@taskset/core';
+import { ConcernClassSchema, DocumentIdSchema, DocumentStatusSchema, DocumentTimestampSchema, LessonSeveritySchema, TaskIdSchema, TaskPrioritySchema, TaskRiskSchema, TaskStatusSchema, TaskTimestampSchema, } from '@taskset/contracts';
+import { buildDocumentGraph, buildTaskIndex, createDocument, createSnapshot, createTask, DOCUMENT_SORT_DIRECTIONS, DOCUMENT_SORT_KEYS, DocumentQuerySchema, deleteDocument, deleteTask, diagnoseRepository, discoverRepository, executeDocumentBatch, generateViews, getProgramRollup, importDocument, initializeRepository, listDocuments, listSnapshots, migrateTaskIds, normalizeDocumentKind, normalizeRepositoryPath, queryDocuments, queryTasks, RepositoryPathError, readDocument, readTask, restoreSnapshot, serializeDocumentFile, serializeTaskFile, syncRepository, TASK_SORT_DIRECTIONS, TASK_SORT_KEYS, TaskQuerySchema, updateDocument, updateTask, } from '@taskset/core';
 import * as z from 'zod';
 const USAGE = `Usage:
   taskset init [--config] [--cwd <path>]
@@ -18,8 +18,9 @@ const USAGE = `Usage:
   taskset task status <task-id> <status> [--json] [--cwd <path>]
   taskset task delete <task-id> [--remove-dependencies] [--json] [--cwd <path>]
   taskset task migrate-ids [--json] [--cwd <path>]
+  taskset task program <parent-id> [--json] [--cwd <path>]
   taskset sync [--concurrency <count>] [--json] [--cwd <path>]
-  taskset document create <story|flow|decision|adr|dr|research|runbook> --title <title> [metadata options]
+  taskset document create <story|flow|decision|adr|dr|research|runbook|lesson|antipattern|concern|audit> --title <title> [metadata options]
   taskset document import <markdown-path> [--type <type>] [--move]
   taskset document batch <manifest.json> [--concurrency <count>] [--json]
   taskset document list [type] [query options]
@@ -32,10 +33,12 @@ Metadata options:
   --status --priority --order --owner --team --estimate --effort --risk --due-date
   --label --assignee --reviewer --depends-on --related --duplicate
   --parent --file --directory --project --body
+  Lesson/concern options: --severity --related-skill --pack --class --cadence
   Repeat array options. Task and document updates clear arrays with --clear-dependencies,
   --clear-labels, --clear-assignees, --clear-reviewers, --clear-related,
-  --clear-files, --clear-directories, or --clear-projects. Clear scalar
-  relationships with --clear-parent or --clear-owner.
+  --clear-files, --clear-directories, --clear-projects, --clear-related-skills,
+  or --clear-packs. Clear scalar relationships with --clear-parent, --clear-owner,
+  --clear-severity, --clear-class, or --clear-cadence.
 
 List query options:
   --status --priority --label --owner --assignee --reviewer --team --risk
@@ -106,6 +109,11 @@ const DocumentInputSchema = z.strictObject({
     parent: TaskIdSchema.optional(),
     directories: StringListSchema.optional(),
     projects: StringListSchema.optional(),
+    severity: LessonSeveritySchema.optional(),
+    relatedSkills: StringListSchema.optional(),
+    packs: StringListSchema.optional(),
+    class: ConcernClassSchema.optional(),
+    cadence: TrimmedStringSchema.optional(),
     body: z.string().optional(),
 });
 const DocumentUpdateSchema = z
@@ -130,6 +138,11 @@ const DocumentUpdateSchema = z
     parent: TaskIdSchema.nullable().optional(),
     directories: StringListSchema.optional(),
     projects: StringListSchema.optional(),
+    severity: LessonSeveritySchema.nullable().optional(),
+    relatedSkills: StringListSchema.optional(),
+    packs: StringListSchema.optional(),
+    class: ConcernClassSchema.nullable().optional(),
+    cadence: TrimmedStringSchema.nullable().optional(),
     body: z.string().optional(),
 })
     .refine((input) => Object.keys(input).length > 0, 'Document update requires at least one field');
@@ -182,6 +195,14 @@ const UPDATE_CLEAR_PAIRS = [
     ['directory', 'clear-directories'],
     ['project', 'clear-projects'],
 ];
+const DOCUMENT_UPDATE_CLEAR_PAIRS = [
+    ...UPDATE_CLEAR_PAIRS,
+    ['severity', 'clear-severity'],
+    ['related-skill', 'clear-related-skills'],
+    ['pack', 'clear-packs'],
+    ['class', 'clear-class'],
+    ['cadence', 'clear-cadence'],
+];
 const DocumentCreateValuesSchema = z.strictObject({
     title: TrimmedStringSchema,
     status: DocumentStatusSchema.optional(),
@@ -203,6 +224,11 @@ const DocumentCreateValuesSchema = z.strictObject({
     parent: TaskIdSchema.optional(),
     directory: StringListSchema.optional(),
     project: StringListSchema.optional(),
+    severity: LessonSeveritySchema.optional(),
+    'related-skill': StringListSchema.optional(),
+    pack: StringListSchema.optional(),
+    class: ConcernClassSchema.optional(),
+    cadence: TrimmedStringSchema.optional(),
     body: z.string().optional(),
     cwd: CwdSchema,
     json: JsonSchema,
@@ -229,6 +255,11 @@ const DocumentUpdateValuesSchema = z
     parent: TaskIdSchema.optional(),
     directory: StringListSchema.optional(),
     project: StringListSchema.optional(),
+    severity: LessonSeveritySchema.optional(),
+    'related-skill': StringListSchema.optional(),
+    pack: StringListSchema.optional(),
+    class: ConcernClassSchema.optional(),
+    cadence: TrimmedStringSchema.optional(),
     body: z.string().optional(),
     type: TrimmedStringSchema.optional(),
     'clear-priority': z.boolean().optional(),
@@ -249,11 +280,16 @@ const DocumentUpdateValuesSchema = z
     'clear-parent': z.boolean().optional(),
     'clear-directories': z.boolean().optional(),
     'clear-projects': z.boolean().optional(),
+    'clear-severity': z.boolean().optional(),
+    'clear-related-skills': z.boolean().optional(),
+    'clear-packs': z.boolean().optional(),
+    'clear-class': z.boolean().optional(),
+    'clear-cadence': z.boolean().optional(),
     cwd: CwdSchema,
     json: JsonSchema,
 })
     .superRefine((values, context) => {
-    for (const [valueKey, clearKey] of UPDATE_CLEAR_PAIRS) {
+    for (const [valueKey, clearKey] of DOCUMENT_UPDATE_CLEAR_PAIRS) {
         if (values[valueKey] !== undefined && values[clearKey]) {
             context.addIssue({
                 code: 'custom',
@@ -280,6 +316,8 @@ const DocumentListValuesSchema = z.strictObject({
     team: StringListSchema.optional(),
     risk: z.array(TaskRiskSchema).optional(),
     project: StringListSchema.optional(),
+    class: z.array(ConcernClassSchema).optional(),
+    severity: z.array(LessonSeveritySchema).optional(),
     'depends-on': TaskIdSchema.optional(),
     related: TaskIdSchema.optional(),
     duplicate: TaskIdSchema.optional(),
@@ -448,6 +486,14 @@ const metadataOptionDefinitions = {
     directory: { type: 'string', multiple: true },
     project: { type: 'string', multiple: true },
 };
+const documentMetadataOptionDefinitions = {
+    ...metadataOptionDefinitions,
+    severity: { type: 'string' },
+    'related-skill': { type: 'string', multiple: true },
+    pack: { type: 'string', multiple: true },
+    class: { type: 'string' },
+    cadence: { type: 'string' },
+};
 const commonOptionDefinitions = {
     cwd: { type: 'string' },
     json: { type: 'boolean' },
@@ -618,101 +664,107 @@ function updateInputFromValues(repository, values) {
     };
 }
 function documentUpdateInputFromValues(repository, values) {
-    return {
-        ...(values.title !== undefined ? { title: values.title } : {}),
-        ...(values.status !== undefined ? { status: values.status } : {}),
-        ...(values['clear-priority']
-            ? { priority: null }
-            : values.priority !== undefined
-                ? { priority: values.priority }
-                : {}),
-        ...(values['clear-order']
-            ? { order: null }
-            : values.order !== undefined
-                ? { order: values.order }
-                : {}),
-        ...(values['clear-labels']
-            ? { labels: [] }
-            : values.label !== undefined
-                ? { labels: values.label }
-                : {}),
-        ...(values['clear-dependencies']
-            ? { dependsOn: [] }
-            : values['depends-on'] !== undefined
-                ? { dependsOn: values['depends-on'] }
-                : {}),
-        ...(values['clear-files']
-            ? { files: [] }
-            : values.file !== undefined
-                ? { files: normalizeMutationPaths(repository, values.file) }
-                : {}),
-        ...(values['clear-owner']
-            ? { owner: null }
-            : values.owner !== undefined
-                ? { owner: values.owner }
-                : {}),
-        ...(values['clear-assignees']
-            ? { assignees: [] }
-            : values.assignee !== undefined
-                ? { assignees: values.assignee }
-                : {}),
-        ...(values['clear-reviewers']
-            ? { reviewers: [] }
-            : values.reviewer !== undefined
-                ? { reviewers: values.reviewer }
-                : {}),
-        ...(values['clear-team']
-            ? { team: null }
-            : values.team !== undefined
-                ? { team: values.team }
-                : {}),
-        ...(values['clear-estimate']
-            ? { estimate: null }
-            : values.estimate !== undefined
-                ? { estimate: values.estimate }
-                : {}),
-        ...(values['clear-effort']
-            ? { effort: null }
-            : values.effort !== undefined
-                ? { effort: values.effort }
-                : {}),
-        ...(values['clear-risk']
-            ? { risk: null }
-            : values.risk !== undefined
-                ? { risk: values.risk }
-                : {}),
-        ...(values['clear-due-date']
-            ? { dueDate: null }
-            : values['due-date'] !== undefined
-                ? { dueDate: values['due-date'] }
-                : {}),
-        ...(values['clear-related']
-            ? { related: [] }
-            : values.related !== undefined
-                ? { related: values.related }
-                : {}),
-        ...(values['clear-duplicates']
-            ? { duplicates: [] }
-            : values.duplicate !== undefined
-                ? { duplicates: values.duplicate }
-                : {}),
-        ...(values['clear-parent']
-            ? { parent: null }
-            : values.parent !== undefined
-                ? { parent: values.parent }
-                : {}),
-        ...(values['clear-directories']
-            ? { directories: [] }
-            : values.directory !== undefined
-                ? { directories: normalizeMutationPaths(repository, values.directory) }
-                : {}),
-        ...(values['clear-projects']
-            ? { projects: [] }
-            : values.project !== undefined
-                ? { projects: values.project }
-                : {}),
-        ...(values.body !== undefined ? { body: values.body } : {}),
-    };
+    const input = {};
+    if (values.title !== undefined)
+        input.title = values.title;
+    if (values.status !== undefined)
+        input.status = values.status;
+    if (values['clear-priority'])
+        input.priority = null;
+    else if (values.priority !== undefined)
+        input.priority = values.priority;
+    if (values['clear-order'])
+        input.order = null;
+    else if (values.order !== undefined)
+        input.order = values.order;
+    if (values['clear-labels'])
+        input.labels = [];
+    else if (values.label !== undefined)
+        input.labels = values.label;
+    if (values['clear-dependencies'])
+        input.dependsOn = [];
+    else if (values['depends-on'] !== undefined)
+        input.dependsOn = values['depends-on'];
+    if (values['clear-files'])
+        input.files = [];
+    else if (values.file !== undefined)
+        input.files = normalizeMutationPaths(repository, values.file);
+    if (values['clear-owner'])
+        input.owner = null;
+    else if (values.owner !== undefined)
+        input.owner = values.owner;
+    if (values['clear-assignees'])
+        input.assignees = [];
+    else if (values.assignee !== undefined)
+        input.assignees = values.assignee;
+    if (values['clear-reviewers'])
+        input.reviewers = [];
+    else if (values.reviewer !== undefined)
+        input.reviewers = values.reviewer;
+    if (values['clear-team'])
+        input.team = null;
+    else if (values.team !== undefined)
+        input.team = values.team;
+    if (values['clear-estimate'])
+        input.estimate = null;
+    else if (values.estimate !== undefined)
+        input.estimate = values.estimate;
+    if (values['clear-effort'])
+        input.effort = null;
+    else if (values.effort !== undefined)
+        input.effort = values.effort;
+    if (values['clear-risk'])
+        input.risk = null;
+    else if (values.risk !== undefined)
+        input.risk = values.risk;
+    if (values['clear-due-date'])
+        input.dueDate = null;
+    else if (values['due-date'] !== undefined)
+        input.dueDate = values['due-date'];
+    if (values['clear-related'])
+        input.related = [];
+    else if (values.related !== undefined)
+        input.related = values.related;
+    if (values['clear-duplicates'])
+        input.duplicates = [];
+    else if (values.duplicate !== undefined)
+        input.duplicates = values.duplicate;
+    if (values['clear-parent'])
+        input.parent = null;
+    else if (values.parent !== undefined)
+        input.parent = values.parent;
+    if (values['clear-directories'])
+        input.directories = [];
+    else if (values.directory !== undefined) {
+        input.directories = normalizeMutationPaths(repository, values.directory);
+    }
+    if (values['clear-projects'])
+        input.projects = [];
+    else if (values.project !== undefined)
+        input.projects = values.project;
+    if (values['clear-severity'])
+        input.severity = null;
+    else if (values.severity !== undefined)
+        input.severity = values.severity;
+    if (values['clear-related-skills'])
+        input.relatedSkills = [];
+    else if (values['related-skill'] !== undefined)
+        input.relatedSkills = values['related-skill'];
+    if (values['clear-packs'])
+        input.packs = [];
+    else if (values.pack !== undefined)
+        input.packs = values.pack;
+    if (values['clear-class'])
+        input.class = null;
+    else if (values.class !== undefined)
+        input.class = values.class;
+    if (values['clear-cadence'])
+        input.cadence = null;
+    else if (values.cadence !== undefined)
+        input.cadence = values.cadence;
+    if (values.body !== undefined)
+        input.body = values.body;
+    return input;
 }
 export async function runCli(args, context = {}) {
     const cwd = path.resolve(context.cwd ?? process.cwd());
@@ -776,7 +828,7 @@ export async function runCli(args, context = {}) {
                 stdout(`${JSON.stringify(result, null, 2)}\n`);
             }
             else if (result.valid) {
-                stdout(`Taskset repository is valid (${result.taskCount} tasks)\n`);
+                stdout(`Taskset repository is valid (${result.taskCount} tasks, ${result.documentCount} documents)\n`);
             }
             else {
                 for (const diagnostic of result.diagnostics) {
@@ -896,7 +948,7 @@ export async function runCli(args, context = {}) {
                 const parsed = parseArgs({
                     args: subcommandArgs,
                     allowPositionals: true,
-                    options: { ...metadataOptionDefinitions, ...commonOptionDefinitions },
+                    options: { ...documentMetadataOptionDefinitions, ...commonOptionDefinitions },
                 });
                 const [rawType] = requirePositionals(parsed.positionals, 1, 'exactly one document type');
                 const values = parseSchema(DocumentCreateValuesSchema, parsed.values, 'document create options');
@@ -925,6 +977,11 @@ export async function runCli(args, context = {}) {
                         ? { directories: normalizeMutationPaths(repository, values.directory) }
                         : {}),
                     ...(values.project ? { projects: values.project } : {}),
+                    ...(values.severity ? { severity: values.severity } : {}),
+                    ...(values['related-skill'] ? { relatedSkills: values['related-skill'] } : {}),
+                    ...(values.pack ? { packs: values.pack } : {}),
+                    ...(values.class ? { class: values.class } : {}),
+                    ...(values.cadence ? { cadence: values.cadence } : {}),
                     ...(values.body !== undefined ? { body: values.body } : {}),
                 }, { onWarning });
                 writeDocumentRecord(record, values.json, stdout);
@@ -974,6 +1031,8 @@ export async function runCli(args, context = {}) {
                         team: { type: 'string', multiple: true },
                         risk: { type: 'string', multiple: true },
                         project: { type: 'string', multiple: true },
+                        class: { type: 'string', multiple: true },
+                        severity: { type: 'string', multiple: true },
                         'depends-on': { type: 'string' },
                         related: { type: 'string' },
                         duplicate: { type: 'string' },
@@ -1014,6 +1073,8 @@ export async function runCli(args, context = {}) {
                     ...(values.team ? { teams: values.team } : {}),
                     ...(values.risk ? { risks: values.risk } : {}),
                     ...(values.project ? { projects: values.project } : {}),
+                    ...(values.class ? { classes: values.class } : {}),
+                    ...(values.severity ? { severities: values.severity } : {}),
                     ...(values['depends-on'] ? { dependsOn: values['depends-on'] } : {}),
                     ...(values.related ? { related: values.related } : {}),
                     ...(values.duplicate ? { duplicate: values.duplicate } : {}),
@@ -1099,12 +1160,12 @@ export async function runCli(args, context = {}) {
                 return 0;
             }
             if (subcommand === 'update') {
-                const clearDefinitions = Object.fromEntries(UPDATE_CLEAR_PAIRS.map(([, clear]) => [clear, { type: 'boolean' }]));
+                const clearDefinitions = Object.fromEntries(DOCUMENT_UPDATE_CLEAR_PAIRS.map(([, clear]) => [clear, { type: 'boolean' }]));
                 const parsed = parseArgs({
                     args: subcommandArgs,
                     allowPositionals: true,
                     options: {
-                        ...metadataOptionDefinitions,
+                        ...documentMetadataOptionDefinitions,
                         ...clearDefinitions,
                         ...commonOptionDefinitions,
                         type: { type: 'string' },
@@ -1187,6 +1248,24 @@ export async function runCli(args, context = {}) {
                     stdout(`${migration.from}\t${migration.to}\n`);
             return 0;
         }
+        if (subcommand === 'program') {
+            const parsed = parseArgs({
+                args: subcommandArgs,
+                allowPositionals: true,
+                options: commonOptionDefinitions,
+            });
+            const [parentId] = requirePositionals(parsed.positionals, 1, 'exactly one parent task ID');
+            const values = parseSchema(CommonValuesSchema, parsed.values, 'task program options');
+            const repository = await discoverRepository(resolveCommandCwd(cwd, values.cwd));
+            const rollup = await getProgramRollup(repository, parseSchema(TaskIdSchema, parentId, 'parent task ID'));
+            if (values.json) {
+                stdout(`${JSON.stringify(rollup, null, 2)}\n`);
+            }
+            else {
+                stdout(`${rollup.parentId}\t${rollup.status}\tchildren=${rollup.children.total}\topen=${rollup.children.openIds.length}\tconcerns=${rollup.relatedOpenConcerns.length}\tcloseoutReady=${rollup.closeoutReady}\t${rollup.title}\n`);
+            }
+            return 0;
+        }
         if (subcommand === 'create') {
             const parsed = parseArgs({
                 args: subcommandArgs,

package/docs/_meta.ts

@@ -5,5 +5,9 @@ export default {
 	'cli-reference': 'CLI Reference',
 	'task-files': 'Task Files',
 	'document-types': 'Document Types',
+	'memory-model': 'Memory Model',
+	'security-compliance-tracking': 'Security Tracking',
+	'agent-closeout': 'Agent Closeout',
+	'taxonomy-cookbook': 'Taxonomy Cookbook',
 	agents: 'For Agents',
 }

package/docs/agent-closeout.md

@@ -0,0 +1,69 @@
+---
+title: Follow the agent closeout contract
+description: Subtasks done, related docs created, taxonomy valid, optional lesson and skill promotion.
+contentType: How-to
+navLabel: Agent Closeout
+---
+
+# Follow the agent closeout contract
+
+Before marking a Taskset task `done`, agents must leave the repository in a state another agent can trust.
+
+## Required
+
+1. Every checklist item for the outcome is checked (`- [x]`), or intentionally removed with rationale.
+2. Every child task is `done` or `canceled` (not left `todo` / `doing` / `blocked`).
+3. Durable outputs exist as documents when the work produced them:
+   - evidence → `research`
+   - lasting choice → `decision` / `adr`
+   - procedure → `runbook`
+   - product context → `story` / `flow`
+   - recurring mistake → `lesson`
+   - residual risk → `concern`
+   - inventory / spot-check → `audit`
+4. Documents and tasks are linked with `--related` (short hex IDs in CLI flags).
+5. Markdown prose that points at those files uses repository-relative filepaths, not bare hex ids.
+6. Labels and projects reuse repository taxonomy; do not invent one-off tags when an allowlist exists.
+7. `taskset doctor --json` reports no errors for the paths you touched.
+
+## Optional config gates
+
+When enabled in `taskset.config.ts`, core blocks `done` transitions that violate:
+
+```typescript
+closeout: {
+  enforceChildCompletion: true,
+  blockDoneWithOpenConcerns: true,
+  requireLessonWhenLabeled: ['requires-lesson'],
+}
+```
+
+Defaults are off so existing repositories keep current behavior.
+
+## Skill promotion bridge
+
+Lessons may declare skill targets:
+
+```bash
+taskset document create lesson \
+  --title "…" \
+  --related-skill .agents/skills/foo/SKILL.md \
+  --related <task-id>
+```
+
+Contract:
+
+- Taskset stores the lesson evidence and correct pattern.
+- The consumer primary skill stores lasting how-to.
+- Agents update the skill in the same change when `--related-skill` is present.
+- Taskset does not auto-edit skills unless a future promote helper is explicitly applied with config opt-in.
+
+## Program closeout
+
+For multi-task programs:
+
+```bash
+taskset task program <parent-id> --json
+```
+
+Treat `closeoutReady: false` as a signal to finish children, accept or archive open concerns, accept research, and complete checklist items before marking the parent done.

package/docs/agents/_meta.ts

@@ -2,4 +2,5 @@ export default {
 	index: 'For Agents',
 	workflows: 'Agent Workflows',
 	commands: 'Agent Commands',
+	'query-recipes': 'Query Recipes',
 }

package/docs/agents/commands.md

@@ -27,12 +27,15 @@ This page quotes the contracts agents should rely on. For the full human referen
 - Exit `1` means repository or domain failure
 - Exit `2` means usage or validation failure
 
-## Identifiers
+## Identifiers and file links
 
 - Entity `id` values are immutable 5–6 character lowercase hex strings
 - Filenames are `{sequence}-{slug}-{id}.md`
-- Commands and relationships must use the short `id`
-- Never cite the mutable sequence prefix as identity
+- Commands, frontmatter relationships, and JSON handoffs use the short `id`
+- Filename sequence prefixes are display metadata only—never identity
+- Markdown hyperlinks to docs, skills, or `.taskset/` entities must use the
+  repository-relative filepath (include the `.md` file). Do not use a bare hex
+  id as a link target.
 
 ## Array updates and clear flags
 
@@ -48,6 +51,11 @@ Array options replace the whole stored array. Repeat the singular option once pe
 - `--clear-projects`
 - `--clear-parent`
 - `--clear-owner`
+- `--clear-severity`
+- `--clear-related-skills`
+- `--clear-packs`
+- `--clear-class`
+- `--clear-cadence`
 
 Do not guess a clear flag from the singular setter name.
 
@@ -66,5 +74,21 @@ Use only these kinds:
 - `decision` (`adr`, `dr` aliases)
 - `research`
 - `runbook`
+- `lesson` (`antipattern` alias)
+- `concern`
+- `audit`
 
 Document statuses are `draft`, `ready`, `active`, `accepted`, `superseded`, and `archived`.
+
+Lesson options: `--severity`, repeatable `--related-skill`, repeatable `--pack`.
+Concern options: `--class`, `--cadence`. List filters include `--class` and `--severity`.
+
+## Program rollup
+
+```bash
+taskset task program <parent-id> --json
+```
+
+Returns child status counts, blocked deps, related open concerns, research not yet accepted, checklist completion, and `closeoutReady`.
+
+Copy-paste recipes: [Query recipes](query-recipes.md).