@taskset/cli 6.0.0 → 6.1.0

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

@@ -7,7 +7,7 @@ navLabel: Task Files
 
 # Understand Taskset task files
 
-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, and runbooks](document-types.md) when the surrounding memory should stay durable.
+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.
 

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,7 +2,7 @@
   "name": "@taskset/cli",
   "type": "module",
   "private": false,
-  "version": "6.0.0",
+  "version": "6.1.0",
   "description": "CLI for Taskset: plan, research, decide, operate, and track repository work as Markdown.",
   "license": "MIT",
   "author": {
@@ -46,8 +46,8 @@
   },
   "dependencies": {
     "zod": "4.6.5",
-    "@taskset/contracts": "6.0.0",
-    "@taskset/core": "6.0.0"
+    "@taskset/core": "6.1.0",
+    "@taskset/contracts": "6.1.0"
   },
   "devDependencies": {
     "@types/node": "^26.6.3",

package/skills/taskset/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: taskset
-description: Taskset workflow guidance for agents that plan, research, decide, operate, and track delivery with stories, flows, research, decisions, runbooks, and tasks stored in .taskset/, including batch imports and cross-package monorepo work. While executing work, agents must create follow-up tasks or subtasks (Taskset child tasks or body checklist items) for newly discovered work, keep parent and subtask progress current mid-work, mark every finished subtask done or checked, create Taskset documents (research, decision, runbook, story, or flow) when work produces reusable evidence, lasting choices, or procedures, link them with --related, and update the session or repository primary skill when lasting lessons should prevent future failures.
+description: Taskset workflow guidance for agents that plan, research, decide, operate, and track delivery with stories, flows, research, decisions, runbooks, lessons, concerns, audits, and tasks stored in .taskset/, including batch imports and cross-package monorepo work. While executing work, agents must create follow-up tasks or subtasks (Taskset child tasks or body checklist items) for newly discovered work, keep parent and subtask progress current mid-work, mark every finished subtask done or checked, create Taskset documents (research, decision, runbook, story, flow, lesson, concern, or audit) when work produces reusable evidence, lasting choices, procedures, recurring patterns, or residual risks, link them with --related, and update the session or repository primary skill when lasting lessons should prevent future failures (especially when a lesson declares --related-skill).
 ---
 
 # Taskset
@@ -18,8 +18,8 @@ treat those paths as the detailed offline reference set:
 | `node_modules/@taskset/cli/skills/taskset/SKILL.md` | This skill (agent workflow for tasks and documents) |
 | `node_modules/@taskset/cli/skills/taskset/references/` | Task modeling, document modeling, monorepo, and Changesets examples |
 | `node_modules/@taskset/cli/skills/taskset-implement/` | Engineering standards used while developing Taskset itself |
-| `node_modules/@taskset/cli/docs/` | Human docs: getting started, configuration, CLI reference, task files, document types |
-| `node_modules/@taskset/cli/docs/agents/` | Agent docs: workflows, command contracts, discovery index |
+| `node_modules/@taskset/cli/docs/` | Human docs: getting started, configuration, CLI reference, task files, document types, memory model, closeout, taxonomy |
+| `node_modules/@taskset/cli/docs/agents/` | Agent docs: workflows, command contracts, query recipes, discovery index |
 | `node_modules/@taskset/cli/docs/maintainers/` | Architecture, ADRs, testing, and maintainer workflows |
 
 In the Taskset repository itself, prefer the workspace copies at `skills/` and
@@ -28,13 +28,16 @@ In the Taskset repository itself, prefer the workspace copies at `skills/` and
 under `node_modules/@taskset/cli/` before inventing workflow or command
 behavior. Useful deep links from an installed package:
 
-- CLI contracts: `node_modules/@taskset/cli/docs/cli-reference.md`
-- Document kinds and commands: `node_modules/@taskset/cli/docs/document-types.md`
-- Task file shape: `node_modules/@taskset/cli/docs/task-files.md`
-- Task modeling examples: `node_modules/@taskset/cli/skills/taskset/references/task-modeling-examples.md`
-- Document modeling examples: `node_modules/@taskset/cli/skills/taskset/references/document-modeling-examples.md`
-- Monorepo modeling: `node_modules/@taskset/cli/skills/taskset/references/monorepo-task-modeling.md`
-- Changesets examples: `node_modules/@taskset/cli/skills/taskset/references/changesets-examples.md`
+- CLI contracts: [`docs/cli-reference.md`](../../docs/cli-reference.md) (installed: `node_modules/@taskset/cli/docs/cli-reference.md`)
+- Document kinds: [`docs/document-types.md`](../../docs/document-types.md)
+- Memory model: [`docs/memory-model.md`](../../docs/memory-model.md)
+- Query recipes: [`docs/agents/query-recipes.md`](../../docs/agents/query-recipes.md)
+- Agent closeout: [`docs/agent-closeout.md`](../../docs/agent-closeout.md)
+- Task file shape: [`docs/task-files.md`](../../docs/task-files.md)
+- Task modeling examples: [references/task-modeling-examples.md](references/task-modeling-examples.md)
+- Document modeling examples: [references/document-modeling-examples.md](references/document-modeling-examples.md)
+- Monorepo modeling: [references/monorepo-task-modeling.md](references/monorepo-task-modeling.md)
+- Changesets examples: [references/changesets-examples.md](references/changesets-examples.md)
 
 Relative links inside the packaged skill still resolve against the packaged
 `docs/` and `skills/` trees because both directories sit at the `@taskset/cli`
@@ -55,8 +58,8 @@ package root.
   require `pnpm taskset`.
 - While executing or working a task, agents MUST create follow-up Taskset tasks or subtasks for newly discovered work. In this skill, "subtask" means either a Taskset child task (`--parent`) or a Markdown checklist item (`- [ ]`) in the parent task body—choose child tasks when independent status, ownership, dependencies, or history are needed; otherwise prefer checklist items. Do not leave that work only in chat, memory, or an informal note.
 - Agents MUST keep the parent task status and every subtask current mid-work: set Taskset tasks and child tasks to `doing` when work starts, check off completed checklist items as `- [x]`, update statuses when progress or blockers change, and mark each finished child task `done` when its acceptance criteria are met. Do not leave finished checklist items unchecked or finished child tasks open, and do not mark a parent task `done` while any tracked subtask (child task or checklist item) remains unfinished.
-- While executing a task, agents MUST create a Taskset document in the same change when work produces reusable evidence (`research`), a lasting choice (`decision` / `adr`), an operational procedure (`runbook`), or durable product context (`story` / `flow`). Link the document and originating task with `--related`. Do not leave that material only in chat, memory, or a closed task body. Short scratch notes and one-off checklist steps stay in the task body.
-- When the repository or current session designates one or more skills as primary, and task work surfaces a lesson that future agents should reuse—tool or command selection, a bug fix pattern, a repeated failure mode, or an architecture decision—update that primary skill (and its relevant references) in the same change so the failure is not rediscovered later. Prefer skills for lasting how-to; prefer research/decision documents for what was learned or chosen. Do not leave durable guidance only in a closed task body or chat transcript.
+- While executing a task, agents MUST create a Taskset document in the same change when work produces reusable evidence (`research`), a lasting choice (`decision` / `adr`), an operational procedure (`runbook`), durable product context (`story` / `flow`), a recurring mistake or correct pattern (`lesson`), an open residual risk (`concern`), or structured spot-check evidence (`audit`). Link the document and originating task with `--related`. Do not leave that material only in chat, memory, or a closed task body. Short scratch notes and one-off checklist steps stay in the task body.
+- When the repository or current session designates one or more skills as primary, and task work surfaces a lesson that future agents should reuse—tool or command selection, a bug fix pattern, a repeated failure mode, or an architecture decision—create a `lesson` document and update that primary skill (and its relevant references) in the same change so the failure is not rediscovered later. If the lesson uses `--related-skill`, update those skill paths in the same change. Prefer skills for lasting how-to; prefer research/decision documents for what was learned or chosen; prefer `lesson` for recurring incorrect/correct patterns. Taskset never auto-edits skills. Do not leave durable guidance only in a closed task body or chat transcript.
 
 ## Recommended Workflow
 
@@ -93,11 +96,15 @@ taskset task list --search "multiple terms" --json
 taskset task list --file packages/core --impact --json
 taskset document create story --title "Describe the user outcome"
 taskset document create research --title "Evaluate options" --related your_task_id_here
+taskset document create lesson --title "Capability flags are enablement only" --severity high --related your_task_id_here
+taskset document create concern --title "Open authz residual risk" --class authz --related your_task_id_here
 taskset document update your_document_id_here --status ready --type research
 taskset document list research --search "queue" --impact --json
+taskset document list concern --directory apps/foo --status active --json
 taskset document show your_document_id_here --type research --include-derived --json
 taskset document import docs/adr/0001-example.md --type adr --move
 taskset document batch taskset-documents.json --concurrency 4 --json
+taskset task program your_parent_task_id_here --json
 taskset sync --json
 ```
 
@@ -119,13 +126,16 @@ taskset sync --json
   status, update, and delete commands as tasks. Document statuses remain
   `draft`, `ready`, `active`, `accepted`, `superseded`, and `archived`.
 - Use `document create` for stories, flows, decisions (`decision`, `adr`, and
-  `dr` are aliases), research, and runbooks. Use `document import` to preserve
-  an existing Markdown body in canonical frontmatter; add `--move` only when
-  the source should be removed after a successful canonical write.
+  `dr` are aliases), research, runbooks, lessons (`antipattern` alias),
+  concerns, and audits. Use `document import` to preserve an existing Markdown
+  body in canonical frontmatter; add `--move` only when the source should be
+  removed after a successful canonical write.
 - Pick the kind by purpose: stories capture user value and acceptance criteria;
   flows describe journeys and failure variants; decisions preserve rationale
   and consequences; research records evidence and recommendations; runbooks
-  make repeatable operations and recovery safe.
+  make repeatable operations and recovery safe; lessons capture recurring
+  incorrect/correct patterns; concerns track open residual risk; audits store
+  structured inventory or spot-check evidence.
 - Use `document batch <manifest.json>` for repeatable multi-document create,
   import, update, and export jobs. Progress belongs on stderr and `--json`
   output on stdout. Use `sync` after upgrades to ensure canonical directories,
@@ -135,12 +145,14 @@ taskset sync --json
 - Disposable metadata indexes live beside each entity folder
   (`.taskset/tasks/.generated/`, `.taskset/stories/.generated/`, and the other
   document-kind folders), not under a global `.taskset/generated/`.
-- New task and document IDs are immutable 5-6 character lowercase hex values
-  such as `a1b2c3`. Filenames use `{sequence}-{slug}-{id}.md`. Agents MUST
-  reference the short `id` in commands, relationships, and handoffs—never the
-  mutable filename sequence prefix. Use `sync` or `task migrate-ids` for legacy
-  repositories; do not rename entity files by hand because canonical
-  relationships must be rewritten together.
+-   New task and document IDs are immutable 5-6 character lowercase hex values
+  such as `a1b2c3`. Filenames use `{sequence}-{slug}-{id}.md`. Agents MUST use
+  the short `id` in commands, frontmatter relationships, and JSON
+  handoffs—never the mutable filename sequence prefix alone. When linking to
+  the file in Markdown prose, use the full repository-relative filepath so the
+  link is clickable. Use `sync` or `task migrate-ids` for legacy repositories;
+  do not rename entity files by hand because canonical relationships must be
+  rewritten together.
 - When a task change affects repository behavior, follow up with the relevant tests, docs, and `git diff --check`.
 
 ## Task Modeling
@@ -171,24 +183,27 @@ For multi-task prompts or uncertainty about task granularity and relationships,
 
 ## Document Modeling
 
-- Prefer the five document kinds that already exist. Do not invent notes, specs,
+- Prefer the document kinds that already exist. Do not invent notes, specs,
   epics, or RFCs as new kinds: investigation is `research`, lasting choices are
-  `decision`, product context is `story` or `flow`, and recovery procedures are
-  `runbook`. Keep short scratch in the task body.
+  `decision`, product context is `story` or `flow`, recovery procedures are
+  `runbook`, recurring mistakes are `lesson`, residual risks are `concern`, and
+  spot-check inventories are `audit`. Keep short scratch in the task body.
 - Search existing documents before creating new ones. Update or `--related` a
   matching document instead of duplicating it.
-- Create documents mid-work as soon as the evidence, decision, or procedure is
-  clear enough to reuse. Link both sides with `--related` to the originating
-  task when practical.
-- Status habits: start research and stories as `draft`; move them to `ready` or
-  `accepted` when the recommendation or criteria stabilize; record decided ADRs
-  as `accepted` (the create default); keep usable runbooks `active`.
+- Create documents mid-work as soon as the evidence, decision, procedure,
+  lesson, or risk is clear enough to reuse. Link both sides with `--related` to
+  the originating task when practical.
+- Status habits: start research, stories, and audits as `draft`; move them to
+  `ready` or `accepted` when they stabilize; record decided ADRs as `accepted`
+  (the create default); keep usable runbooks, lessons, and open concerns
+  `active`; move mitigated concerns to `accepted` and obsolete lessons to
+  `superseded` or `archived`.
 - Attach owner, assignees, labels, projects, files, and directories when they help
   discovery the same way they do on tasks. Use `--depends-on` and `--parent`
   only for real document-to-document prerequisites within Taskset documents.
 - Do not dump raw research into a primary skill. Capture the evidence in a
-  research document, the choice in a decision document, and only the lasting
-  how-to in the skill.
+  research document, the choice in a decision document, the recurring pattern in
+  a lesson, and only the lasting how-to in the skill.
 
 For paired good and bad examples, read [document-modeling examples](references/document-modeling-examples.md).
 
@@ -227,14 +242,18 @@ For paired examples of required, multi-package, and unnecessary changesets, read
 - Read the task and the surrounding repository context first.
 - Before mutating or executing a task, compare its owner and assignees with the current Git user and obtain confirmation when another person is responsible.
 - While executing, create follow-up tasks, child tasks, or checklist subtasks for every distinct piece of newly discovered work before moving on or closing the current task.
-- While executing, create research, decision, runbook, story, or flow documents for reusable evidence, lasting choices, procedures, or product context; link them with `--related`.
-- Keep parent status and every subtask current mid-work: check off finished checklist items, mark finished child tasks `done`, and only then close the parent.
-- When lasting lessons emerge and a primary skill is in play, update that skill so future sessions avoid the same tool-choice, bug-fix, repeated-failure, or architecture mistake.
+- While executing, create research, decision, runbook, story, flow, lesson, concern, or audit documents for reusable evidence, lasting choices, procedures, product context, recurring patterns, or residual risks; link them with `--related`.
+- Keep parent status and every subtask current mid-work: check off finished checklist items, mark finished child tasks `done`, and only then close the parent. Use `taskset task program <parent-id> --json` for multi-task program health.
+- When lasting lessons emerge, create a `lesson` and update any primary or `--related-skill` skill so future sessions avoid the same tool-choice, bug-fix, repeated-failure, or architecture mistake.
 - In monorepos, verify affected packages and consumers against the workspace and task-runner graphs rather than relying only on the initially named directory.
 - In repositories using Changesets, reconcile the task's declared Changeset requirement with the actual affected packages before completion.
 - Prefer the smallest Taskset command that proves the intended state.
-- Cite tasks and documents by their short hex `id` (`a1b2c3`), not by filename
-  sequence numbers. Use that `id` with `task show`, `task update`, `--related`,
-  `--depends-on`, and `--parent`.
+- Use short hex `id` values (`a1b2c3`) with `task show`, `task update`,
+  `--related`, `--depends-on`, and `--parent`. Filename sequence prefixes are
+  display metadata only—never identity and never Markdown link targets.
+- When writing a Markdown hyperlink to a Taskset entity, doc, or skill file,
+  use the repository-relative filepath (for example
+  `.taskset/lessons/0000001-…-a1b2c3.md` or `docs/memory-model.md`). Inline
+  mentions may still show the short `id` for humans and CLI copy-paste.
 - Avoid editing generated output, caches, or any non-canonical `.taskset/` artifacts.
 - Report validation failures plainly and only claim success after the command has run.

package/skills/taskset/references/document-modeling-examples.md

@@ -12,10 +12,14 @@ Good: create a research document, keep the task focused on the delivery outcome,
 and link both.
 
 ```bash
-pnpm taskset document create research --title "Evaluate queue providers" --related <task-id>
-pnpm taskset task update <task-id> --related <research-id>
+taskset document create research --title "Evaluate queue providers" --related <task-id>
+taskset task update <task-id> --related <research-id>
 ```
 
+In Markdown prose, link the created file by filepath (for example
+`.taskset/research/0000001-evaluate-queue-providers-<research-id>.md`), not by
+a bare hex id as the link target.
+
 ## Decision Versus Research
 
 Bad: write an ADR before evidence exists, or leave a chosen architecture only as
@@ -61,3 +65,50 @@ implementation tasks that `--related` that document and carry the code work.
 pnpm taskset document create story --title "Member signs in via SSO"
 pnpm taskset task create --title "Add SSO callback handler" --related <story-id> --file packages/api/src/auth.ts
 ```
+
+## Lesson Versus Closed Task Note
+
+Bad: rediscover “channel capability ≠ authz grant” in chat after the fixing task
+is already `done`, or paste the pattern only into a skill with no Taskset trail.
+
+Good: create a `lesson` with trigger, incorrect pattern, correct pattern,
+severity, prevention, and evidence; relate the originating task/concern; and if
+`--related-skill` is set, update that skill in the same change.
+
+```bash
+pnpm taskset document create lesson \
+  --title "Capability flags are enablement only" \
+  --severity high \
+  --related-skill .agents/skills/security/SKILL.md \
+  --related <task-id>
+```
+
+## Concern Versus ADR Or Runbook
+
+Bad: leave residual authz risk as an unfinished checklist forever, or write an
+ADR that only says “still risky” with no review cadence.
+
+Good: create a `concern` for living open/residual risk (class, trust boundary,
+evidence, residual risk, mitigation/acceptance, cadence). Use `decision` for the
+chosen design and `runbook` for recovery steps.
+
+```bash
+pnpm taskset document create concern \
+  --title "Telegram capability must not grant CASL" \
+  --class authz \
+  --cadence on-release \
+  --related <task-id>
+```
+
+## Audit Versus Informal Research Dump
+
+Bad: paste a route inventory into a research body with no findings status or
+follow-ups.
+
+Good: use `audit` for structured spot-checks with scope, method, findings
+(`pass` | `fail` | `residual`), residual items, required follow-ups, and next
+due date.
+
+```bash
+pnpm taskset document create audit --title "Public route inventory" --related <program-task-id>
+```

package/skills/taskset-implement/SKILL.md

@@ -117,12 +117,15 @@ Non-negotiable rules:
 - Canonical task files use one strict versionless metadata shape. Versioned
   task frontmatter and unknown fields are rejected.
 - Canonical supporting documents live in kind-specific `.taskset/` directories:
-  stories, flows, decisions, research, and runbooks. Use their shared strict
-  metadata (aligned with task planning, people, path, and relationship fields)
-  and kind-specific body templates instead of modeling every durable document
-  as a task. Documents expose the same create, update, status, delete, list
-  query, search, impact, and derived-relationship operations as tasks, with
-  document-specific statuses.
+  stories, flows, decisions, research, runbooks, lessons, concerns, and audits.
+  Use their shared strict metadata (aligned with task planning, people, path,
+  and relationship fields), kind-specific optional fields (`severity` /
+  `relatedSkills` / `packs` for lessons; `class` / `cadence` for concerns), and
+  kind-specific body templates instead of modeling every durable document as a
+  task. Documents expose the same create, update, status, delete, list query,
+  search, impact, and derived-relationship operations as tasks, with
+  document-specific statuses. Optional closeout gates, taxonomy allowlists, and
+  `taskset task program` rollups extend delivery without a second tracker.
 - Document mutations, imports, exports, and batches belong to core. The CLI
   validates manifests and renders output only. Use TanStack Pacer for bounded
   heavy batches and migrations, emit count and percentage progress, preserve

package/skills/taskset-implement/references/architecture/product-and-source.md

@@ -9,7 +9,8 @@ workspace: not only tasks, but the plans, research, decisions, flows, and
 runbooks that make delivery coherent.
 
 It is a Git-native software delivery platform. Stories, flows, decisions,
-research, runbooks, and tasks live beside the code as human-readable Markdown.
+research, runbooks, lessons, concerns, audits, and tasks live beside the code as
+human-readable Markdown.
 
 Vision: become the Git-native operating system for software delivery.
 
@@ -30,7 +31,10 @@ Design for:
   repositories
 
 Near-term work should keep the task and supporting-document workflows coherent
-before inventing additional entity kinds or investing heavily in new interfaces.
+before inventing freeform kinds (`note`, `rfc`, `epic`, `spec`) or investing
+heavily in new interfaces. Operational memory kinds (`lesson`, `concern`,
+`audit`) are first-class document kinds under the existing document command
+surface.
 
 ## Source-of-Truth Model
 
@@ -50,6 +54,12 @@ Canonical project state lives under `.taskset/`.
 │   └── .generated/
 ├── runbooks/
 │   └── .generated/
+├── lessons/
+│   └── .generated/
+├── concerns/
+│   └── .generated/
+├── audits/
+│   └── .generated/
 ├── snapshots/
 └── cache/
 ```

package/skills/taskset-implement/references/architecture/storage-and-snapshots.md

@@ -9,8 +9,11 @@ Storage, graph, and snapshot rules for canonical repository data.
   expressions.
 - Normalize stored code references to repository-relative POSIX paths.
 - Reject paths that escape the repository or `.taskset/` ownership boundary.
-- Keep entity IDs immutable short hex values. Filename display sequences are
-  mutable maintenance metadata repaired by `sync`; they are not identity.
+- Keep entity IDs immutable short hex values for commands and canonical
+  relationships. Filename display sequences are mutable maintenance metadata
+  repaired by `sync`; they are not identity. Markdown hyperlinks to entity or
+  documentation files must use repository-relative filepaths, not bare hex ids
+  or sequence prefixes.
 - Store one canonical direction for inverse relationships unless the schema
   explicitly defines otherwise. Derive `blocks` from `dependsOn`, for example,
   rather than allowing silent divergence.