@taskset/cli 6.0.0 → 6.1.0

package/docs/agents/index.md

@@ -1,6 +1,6 @@
 ---
 title: Operate Taskset as an agent
-description: Plan, research, decide, and track repository work with the Taskset CLI, skill, and JSON contracts.
+description: Plan, research, decide, operate, and track repository work with the Taskset CLI, skill, and JSON contracts.
 contentType: How-to
 navLabel: For Agents
 ---
@@ -9,7 +9,7 @@ navLabel: For Agents
 
 Use this page when you are an agent operating Taskset in a repository. Humans should start with [Getting started](../getting-started.md). Maintainer architecture lives under [Maintainer docs](../maintainers/index.md).
 
-Taskset is not only a task tracker. You use it to capture plans, research, decisions, flows, runbooks, and the tasks that execute them in one Git-native graph.
+Taskset is not only a task tracker. You use it to capture plans, research, decisions, flows, runbooks, lessons, concerns, audits, and the tasks that execute them in one Git-native graph.
 
 ## Load the skill first
 
@@ -51,18 +51,23 @@ No config file is required. `taskset init` creates `.taskset/` only. Pass `--con
 | Evidence, options, or a recommendation | `research` |
 | A lasting architectural or product choice | `decision` / `adr` |
 | A repeatable recovery or ops procedure | `runbook` |
+| A recurring mistake or correct pattern | `lesson` |
+| An open residual risk | `concern` |
+| A structured inventory or spot-check | `audit` |
 | Scoped execution with status and owners | `task` |
+| Multi-task program health | parent task + `taskset task program` |
 
-Link documents and tasks with `--related`. Keep one-off scratch in the task body.
+Link documents and tasks with `--related`. Keep one-off scratch in the task body. See [Memory model](../memory-model.md) for anti-examples.
 
 ## Core operating rules
 
 - Treat `.taskset/tasks/` and kind-specific document directories as the source of truth
 - Mutate through CLI commands when a command exists
-- Cite short hex ids such as `a1b2c3`, never filename sequence prefixes
+- Use short hex ids such as `a1b2c3` in commands and `--related`. Filename sequence prefixes are display-only.
+- Markdown hyperlinks to files must use repository-relative paths (for example [document types](../document-types.md)), not bare hex ids
 - Prefer `--json` for handoffs
 - Create follow-up tasks or checklist subtasks for newly discovered work
-- Create research, decision, runbook, story, or flow documents when work produces reusable evidence or lasting choices
+- Create research, decision, runbook, story, flow, lesson, concern, or audit documents when work produces reusable evidence, lasting choices, recurring patterns, or residual risks
 - Keep statuses current mid-work
 
 ## Command map
@@ -73,27 +78,36 @@ Link documents and tasks with `--related`. Keep one-off scratch in the task body
 | Validate repository | `taskset doctor --json` |
 | List or search tasks | `taskset task list --search "terms" --json` |
 | List or search documents | `taskset document list research --search "terms" --json` |
+| Open concerns on a path | `taskset document list concern --directory apps/foo --status active --json` |
+| Lessons by search | `taskset document list lesson --search "casl" --json` |
 | Show one entity | `taskset task show your_task_id_here --json` |
 | Create executable work | `taskset task create --title "Describe the work"` |
 | Create durable memory | `taskset document create research --title "Evaluate options" --related your_task_id_here` |
+| Create a lesson | `taskset document create lesson --title "…" --severity high --related your_task_id_here` |
+| Create a concern | `taskset document create concern --title "…" --class authz --related your_task_id_here` |
+| Program health | `taskset task program your_parent_task_id_here --json` |
 | Change status | `taskset task status your_task_id_here doing` |
 | Impact query | `taskset task list --file path/or/dir --impact --json` |
 | Repair and rebuild | `taskset sync --json` |
 
-Full contracts: [CLI reference](../cli-reference.md) and [Agent command contracts](commands.md).
+Full contracts: [CLI reference](../cli-reference.md), [Agent command contracts](commands.md), and [Query recipes](query-recipes.md).
 
 ## Workflow checklist
 
 1. Confirm the repository root with `taskset config --json`
 2. Search existing tasks and documents before creating duplicates
-3. Capture durable evidence or decisions as documents mid-work
+3. Capture durable evidence, decisions, lessons, or concerns as documents mid-work
 4. Create or update tasks for executable delivery
 5. Resolve ownership before mutating assigned work
-6. Keep statuses current, then re-validate after edits
+6. Keep statuses current, then re-validate with `taskset doctor --json`
 
 ## Related pages
 
 - [Agent workflows](workflows.md)
 - [Agent command contracts](commands.md)
+- [Query recipes](query-recipes.md)
+- [Memory model](../memory-model.md)
+- [Agent closeout](../agent-closeout.md)
+- [Security tracking](../security-compliance-tracking.md)
 - [Document types](../document-types.md)
 - [Task files](../task-files.md)

package/docs/agents/llms.txt

@@ -1,15 +1,19 @@
 # Taskset
 
-> Git-native Markdown workspace for planning, research, decisions, operations, and delivery.
+> Git-native Markdown workspace for planning, research, decisions, operations, residual risk, and delivery.
 
-Taskset stores stories, flows, research, decisions, runbooks, and tasks under `.taskset/`. The CLI is published as `@taskset/cli` and runs through package runners or a global install. Config files are optional.
+Taskset stores stories, flows, research, decisions, runbooks, lessons, concerns, audits, and tasks under `.taskset/`. The CLI is published as `@taskset/cli` and runs through package runners or a global install. Config files are optional.
 
 ## For agents
 
 - [Operate Taskset as an agent](https://taskset.false.foundation/docs/agents)
 - [Follow agent workflows](https://taskset.false.foundation/docs/agents/workflows)
 - [Use Taskset command contracts](https://taskset.false.foundation/docs/agents/commands)
+- [Query operational memory](https://taskset.false.foundation/docs/agents/query-recipes)
 - [Choose a document type](https://taskset.false.foundation/docs/document-types)
+- [Choose memory layers](https://taskset.false.foundation/docs/memory-model)
+- [Agent closeout contract](https://taskset.false.foundation/docs/agent-closeout)
+- [Security and compliance tracking](https://taskset.false.foundation/docs/security-compliance-tracking)
 - [Understand task files](https://taskset.false.foundation/docs/task-files)
 - [CLI reference](https://taskset.false.foundation/docs/cli-reference)
 
@@ -18,6 +22,7 @@ Taskset stores stories, flows, research, decisions, runbooks, and tasks under `.
 - [Keep the whole delivery story beside the code](https://taskset.false.foundation/docs)
 - [Start a Taskset repository](https://taskset.false.foundation/docs/getting-started)
 - [Configure Taskset defaults](https://taskset.false.foundation/docs/configuration)
+- [Taxonomy cookbook](https://taskset.false.foundation/docs/taxonomy-cookbook)
 
 ## Optional offline skill
 
@@ -26,3 +31,5 @@ After install, load `node_modules/@taskset/cli/skills/taskset/SKILL.md`, or inst
 ```text
 npx skills add FalseFoundation/taskset --skill taskset
 ```
+
+Offline docs also ship at `node_modules/@taskset/cli/docs/`. Prefer repository-relative `.md` filepaths for Markdown hyperlinks; use short hex entity ids only in CLI commands and `--related`.

package/docs/agents/query-recipes.md

@@ -0,0 +1,76 @@
+---
+title: Query operational memory
+description: Copy-paste --json recipes for program blockers and open security concerns.
+contentType: Reference
+navLabel: Query Recipes
+---
+
+# Query operational memory
+
+Prefer `--json` for agent handoffs. Use short hex IDs in commands and
+`--related`. Filename sequence prefixes are display-only. Markdown hyperlinks
+to files must use repository-relative paths (see [commands](commands.md)).
+
+## Open concerns on a path
+
+```bash
+taskset document list concern --directory apps/foo --status active --json
+taskset document list concern --label security --status active --json
+taskset document list concern --class authz --status active --json
+```
+
+## Lessons by search or severity
+
+```bash
+taskset document list lesson --search "casl capability" --json
+taskset document list lesson --severity high --json
+taskset document show <lesson-id> --type lesson --json
+```
+
+## Audits and research
+
+```bash
+taskset document list audit --status ready --json
+taskset document list research --status ready --json
+```
+
+## Program health
+
+```bash
+taskset task program <parent-id> --json
+```
+
+Useful fields:
+
+- `children.byStatus` / `children.openIds`
+- `blockedDependencies`
+- `relatedOpenConcerns`
+- `relatedResearchNotAccepted`
+- `checklist`
+- `closeoutReady`
+
+## Closeout gaps
+
+```bash
+taskset doctor --json
+```
+
+Interpret:
+
+| Code | Meaning |
+| --- | --- |
+| `missing-template-heading` | lesson/concern/audit body missing required `##` section |
+| `missing-reference` | related/dependsOn target ID does not exist |
+| `unknown-taxonomy` | label/project/class outside allowlist |
+| `closeout-gap` | done task labeled for lesson without a related lesson |
+| `missing-owner` | active concern without owner (when configured) |
+| `stale-research` | ready research older than N days without follow-up task |
+
+## Create trail in one change
+
+```bash
+taskset document create concern --title "Telegram capability must not grant CASL" --class authz --related <task-id> --json
+taskset document create lesson --title "Capability flags are enablement only" --severity high --related <concern-or-task-id> --json
+taskset task program <parent-id> --json
+taskset doctor --json
+```

package/docs/agents/workflows.md

@@ -1,6 +1,6 @@
 ---
 title: Follow agent workflows in Taskset
-description: Ownership checks, mid-work updates, documents, and monorepo habits for agent operators.
+description: Ownership checks, mid-work updates, operational memory, and monorepo habits for agent operators.
 contentType: How-to
 navLabel: Agent Workflows
 ---
@@ -25,9 +25,11 @@ Matching ownership does not override blockers. A generic instruction such as “
 - Create child tasks (`--parent`) or checklist items (`- [ ]`) for newly discovered work
 - Check off finished checklist items as `- [x]`
 - Mark finished child tasks `done`
-- Create research, decision, runbook, story, or flow documents when evidence or lasting choices appear
-- Link documents and tasks with `--related`
-- Update a primary skill when the session designates one and a lasting lesson emerges
+- Create research, decision, runbook, story, flow, lesson, concern, or audit documents when evidence, lasting choices, recurring patterns, or residual risks appear
+- Link documents and tasks with `--related` (short hex ids in CLI flags)
+- When linking to those files in Markdown prose, use the repository-relative filepath
+- Update a primary skill when the session designates one and a lasting lesson emerges; if a lesson uses `--related-skill`, update those skill paths in the same change
+- For multi-task programs, inspect health with `taskset task program <parent-id> --json`
 
 Do not leave discovered work only in chat.
 
@@ -35,8 +37,11 @@ Do not leave discovered work only in chat.
 
 1. Confirm acceptance criteria are met
 2. Confirm every tracked subtask is finished or intentionally resolved
-3. Set the parent task to `done`
-4. Run the repository’s relevant tests or `taskset doctor --json` when the change touched contracts or many files
+3. Confirm related lessons/concerns/audits exist when the work produced them
+4. Set the parent task to `done` only after children and checklists are complete
+5. Run `taskset doctor --json` when the change touched contracts, taxonomy, or many files
+
+See [Agent closeout](../agent-closeout.md) for the full contract and optional config gates.
 
 ## Monorepo habits
 
@@ -44,7 +49,12 @@ Do not leave discovered work only in chat.
 - Record `--depends-on` only for real execution prerequisites
 - Attach the narrowest accurate `--file` or `--directory` scopes
 - Validate the changed package and affected dependents
+- Reuse taxonomy labels and projects; do not invent one-off tags when allowlists exist
 
 ## Batch and sync
 
 Use `taskset document batch manifest.json --json` for multi-document jobs. Use `taskset sync --json` after upgrades or when filenames, ids, or generated views need repair.
+
+## Discovery recipes
+
+Copy-paste JSON recipes for open concerns, lessons, and program blockers live in [Query recipes](query-recipes.md).

package/docs/cli-reference.md

@@ -7,7 +7,7 @@ navLabel: CLI Reference
 
 # Look up Taskset CLI commands
 
-The `taskset` command is a thin adapter over `@taskset/core` for the full Taskset surface: stories, flows, research, decisions, runbooks, and tasks. It parses arguments, validates options, calls core operations, and renders human or JSON output.
+The `taskset` command is a thin adapter over `@taskset/core` for the full Taskset surface: stories, flows, research, decisions, runbooks, lessons, concerns, audits, and tasks. It parses arguments, validates options, calls core operations, and renders human or JSON output.
 
 Invoke it with `npx @taskset/cli`, `pnpm dlx @taskset/cli`, `yarn dlx @taskset/cli`, `bunx @taskset/cli`, a project binary, or a global install. Examples below use `taskset` directly.
 
@@ -82,13 +82,14 @@ Human output is the config file path when a config exists, or `defaults (<root-d
 taskset doctor [--json] [--cwd <path>]
 ```
 
-Validates the repository without modifying files. It scans canonical task
-metadata, paths, and graph relationships.
+Validates the repository without modifying files. It scans canonical task and
+document metadata, paths, graph relationships, required template headings for
+operational kinds, taxonomy allowlists, and optional closeout gaps.
 
 Human success output:
 
 ```text
-Taskset repository is valid (<count> tasks)
+Taskset repository is valid (<count> tasks, <count> documents)
 ```
 
 Human failure output is tab-separated:
@@ -97,8 +98,8 @@ Human failure output is tab-separated:
 <code>	<path-or->	<message>	<remediation>
 ```
 
-JSON output is the full doctor result, including `valid`, `taskCount`, and
-diagnostics.
+JSON output is the full doctor result, including `valid`, `taskCount`,
+`documentCount`, and diagnostics. Warnings do not fail the command; errors do.
 
 ### `generate`
 
@@ -375,6 +376,19 @@ remove those inbound references and delete the target in one mutation.
 Human output is the deleted task ID. JSON output contains `deleted: true`
 alongside the deleted task record.
 
+### `task program`
+
+```bash
+taskset task program <parent-id> [--json] [--cwd <path>]
+```
+
+Summarizes a parent task as a program rollup: child counts by status, open child
+IDs, blocked dependency edges, related open concerns, related research not yet
+accepted, parent checklist completion, and `closeoutReady`.
+
+Human output is one tab-separated summary line. JSON output is the full rollup
+object.
+
 ### `task migrate-ids`
 
 ```bash
@@ -403,7 +417,8 @@ sent to stderr.
 ## Document Commands
 
 `document` may be shortened to `doc`. Supported types are `story`, `flow`,
-`decision`, `research`, and `runbook`; `adr` and `dr` alias `decision`.
+`decision`, `research`, `runbook`, `lesson`, `concern`, and `audit`. Aliases:
+`adr` / `dr` → `decision`; `antipattern` → `lesson`.
 
 ```bash
 taskset document create <type> --title <title> [metadata options]
@@ -417,15 +432,19 @@ taskset document delete <document-id> [--type <type>] [--remove-dependencies] [-
 ```
 
 Create uses the type-specific template unless `--body` is supplied and accepts
-the same metadata options as `task create`. Import preserves the Markdown body
-and infers type from a recognized parent directory when possible. It copies by
-default; `--move` deletes the source only after the canonical document is
+the same metadata options as `task create`, plus lesson/concern options:
+`--severity`, repeatable `--related-skill`, repeatable `--pack`, `--class`, and
+`--cadence`. Lesson/concern/audit templates are validated for required headings.
+Import preserves the Markdown body and infers type from a recognized parent
+directory when possible (`lessons/`, `concerns/`, `audits/` included). It copies
+by default; `--move` deletes the source only after the canonical document is
 written successfully.
 
 List, show, update, status, and delete mirror the task commands, including
 search, filters, sort, impact, derived relationships, clear flags, and
-guarded deletion. Document statuses are `draft`, `ready`, `active`, `accepted`,
-`superseded`, and `archived`.
+guarded deletion. Document list also accepts `--class` and `--severity`. Document
+statuses are `draft`, `ready`, `active`, `accepted`, `superseded`, and
+`archived`.
 
 Batch manifests contain an array of `create`, `import`, `update`, and `export`
 operations. Work is paced with bounded concurrency, results preserve manifest

package/docs/configuration.md

@@ -16,6 +16,9 @@ Add `taskset.config.ts` when you need at least one of these:
 - A repository `project.name`
 - Different task creation defaults
 - A reduced or reordered status or priority vocabulary
+- Closeout gates for parent/child completion, open concerns, or required lessons
+- Taxonomy allowlists for labels, projects, or concern classes
+- Extra doctor checks for ownerless concerns or stale research
 
 Create one during init:
 
@@ -41,6 +44,19 @@ export default defineConfig({
 		statuses: ['todo', 'doing', 'blocked', 'done', 'canceled'],
 		priorities: ['low', 'medium', 'high', 'urgent'],
 	},
+	closeout: {
+		enforceChildCompletion: false,
+		blockDoneWithOpenConcerns: false,
+		requireLessonWhenLabeled: [],
+	},
+	taxonomy: {
+		// omit allowlists for permissive behavior
+		mode: 'error',
+	},
+	doctor: {
+		activeConcernRequiresOwner: false,
+		// staleResearchDays: 14,
+	},
 })
 ```
 
@@ -51,10 +67,14 @@ export default defineConfig({
 - `tasks.statuses` selects and orders the active status vocabulary from Taskset’s canonical values
 - `tasks.priorities` selects and orders the active priority vocabulary from Taskset’s canonical values
 - `urgent` is the highest supported priority
+- `closeout.*` defaults to off / empty so existing repositories keep current done transitions
+- `taxonomy.labels`, `projects`, and `concernClasses` are optional allowlists; omit them to stay permissive
+- `taxonomy.mode` is `error` or `warn` when an allowlist is configured
+- `doctor.activeConcernRequiresOwner` and `doctor.staleResearchDays` add optional diagnostics
 - Unknown fields, invalid enum values, empty names, and duplicate default labels or vocabulary values are rejected
 - The config file is trusted project TypeScript and may use erasable syntax supported by your Node version
 
-The config identifies behavior. It is not task storage. Canonical task state remains under `.taskset/tasks/`.
+The config identifies behavior. It is not task storage. Canonical task and document state remains under `.taskset/`.
 
 ## Discovery
 

package/docs/document-types.md

@@ -1,13 +1,13 @@
 ---
 title: Choose a Taskset document type
-description: Canonical stories, flows, decisions, research, and runbooks.
+description: Canonical stories, flows, decisions, research, runbooks, lessons, concerns, and audits.
 contentType: Conceptual
 navLabel: Document Types
 ---
 
 # Choose a Taskset document type
 
-Documents are how Taskset keeps product and engineering memory: what to build, what you learned, what you decided, and how to recover. Use them when the material should outlive a single task. Each type has strict common frontmatter and a body template suited to its purpose. Documents share planning, people, path, and relationship fields with tasks, and use document-specific statuses.
+Documents are how Taskset keeps product, engineering, and operational memory: what to build, what you learned, what you decided, how to recover, which mistakes not to repeat, and which residual risks remain open. Use them when the material should outlive a single task. Each type has strict common frontmatter and a body template suited to its purpose. Documents share planning, people, path, and relationship fields with tasks, and use document-specific statuses.
 
 | Type | Directory | Template focus |
 | --- | --- | --- |
@@ -16,6 +16,9 @@ Documents are how Taskset keeps product and engineering memory: what to build, w
 | `decision` (`adr`, `dr`) | `.taskset/decisions/` | context, decision, alternatives, consequences |
 | `research` | `.taskset/research/` | question, sources, findings, recommendation |
 | `runbook` | `.taskset/runbooks/` | symptoms, checks, actions, rollback, escalation |
+| `lesson` (`antipattern`) | `.taskset/lessons/` | trigger, incorrect/correct pattern, severity, prevention |
+| `concern` | `.taskset/concerns/` | summary, class, trust boundary, residual risk, cadence |
+| `audit` | `.taskset/audits/` | scope, method, findings, residual items, follow-ups |
 
 Create a document from its template:
 
@@ -23,15 +26,33 @@ Create a document from its template:
 taskset document create story --title "Member signs in via SSO"
 taskset document create flow --title "Recover a delayed deposit"
 taskset document create adr --title "Use transactional outbox"
-taskset document create research --title "Evaluate queue providers" --related your_task_id_here
+taskset document create research --title "Evaluate cloud providers" --related your_task_id_here
 taskset document create runbook --title "Recover consumer lag"
+taskset document create lesson --title "Capability flags are enablement only" --severity high --related your_task_id_here
+taskset document create concern --title "Telegram capability must not grant CASL" --class authz --cadence on-release
+taskset document create audit --title "Public route inventory"
 ```
 
 Document IDs are immutable 5-6 character lowercase hex values. Filenames keep a
 per-type display sequence and title slug, for example
 `.taskset/flows/0000001-member-signs-in-via-sso-a1b2c3.md`. Agents and commands
-reference the short `id`. Disposable metadata indexes for that kind live beside
-the files in `.taskset/flows/.generated/`.
+use the short `id` in CLI flags and frontmatter relationships. The sequence
+prefix is display metadata only. Markdown hyperlinks to the file must use the
+repository-relative filepath. Disposable metadata indexes for that kind live
+beside the files in `.taskset/flows/.generated/`.
+
+Default statuses: `decision` → `accepted`; `runbook`, `lesson`, and `concern` →
+`active`; other kinds → `draft`.
+
+## Kind-specific metadata
+
+| Kind | Options |
+| --- | --- |
+| `lesson` | `--severity low\|medium\|high\|critical`, repeatable `--related-skill`, repeatable `--pack` |
+| `concern` | `--class security\|privacy\|money\|authz\|concurrency\|ops\|compliance\|other`, `--cadence <value>` |
+
+Clear lesson/concern scalars and arrays on update with `--clear-severity`,
+`--clear-related-skills`, `--clear-packs`, `--clear-class`, and `--clear-cadence`.
 
 ## Query And Mutation
 
@@ -39,6 +60,8 @@ Documents support the same command surface as tasks:
 
 ```bash
 taskset document list research --search "queue" --owner platform --impact
+taskset document list concern --directory apps/foo --status active --class authz --json
+taskset document list lesson --search "casl" --severity high --json
 taskset document show <document-id> --type research --include-derived --json
 taskset document update <document-id> --status ready --label infra --file packages/core
 taskset document status <document-id> accepted --type decision
@@ -52,21 +75,23 @@ Statuses are `draft`, `ready`, `active`, `accepted`, `superseded`, and
 ## Import Existing Markdown
 
 Use `document import` when a repository already has material under paths such
-as `docs/stories`, `docs/flows`, `docs/adr`, `docs/research`, or
-`docs/runbooks`:
+as `docs/stories`, `docs/flows`, `docs/adr`, `docs/research`, `docs/runbooks`,
+`docs/lessons`, `docs/concerns`, or `docs/audits`:
 
 ```bash
 taskset document import docs/flows/0001-sign-in.md
 taskset document import docs/architecture/use-postgres.md --type decision
+taskset document import docs/lessons/capability.md --move
 taskset document import docs/runbooks/consumer-lag.md --move
 ```
 
 The type is inferred from recognized parent directory names when `--type` is
 omitted. `adr`, `dr`, `decision`, and `decisions` all normalize to `decision`.
-The first H1 supplies the title unless `--title` is passed. Existing
-frontmatter is replaced with Taskset's canonical metadata while the Markdown
-body is preserved. Import copies by default; `--move` removes the source only
-after the canonical file has been written successfully.
+`antipattern` / `lessons` normalize to `lesson`. The first H1 supplies the title
+unless `--title` is passed. Existing frontmatter is replaced with Taskset's
+canonical metadata while the Markdown body is preserved. Import copies by
+default; `--move` removes the source only after the canonical file has been
+written successfully.
 
 Use `document list [type]`, `document show <id>`, and `--json` for inspection
 and automation. Sequences are per type, so pass `--type` to `document show`
@@ -98,6 +123,7 @@ migrates legacy task and document IDs to short hex IDs, normalizes
 `{sequence}-{slug}-{id}.md` filenames, repairs duplicate sequence prefixes by
 `createdAt`, rewrites repository text references, refreshes data `.gitignore`
 rules for scoped `.generated/` directories, removes legacy global
-`.taskset/generated/`, and rebuilds generated views. Build outputs,
-dependencies, caches, snapshots, and Git internals are excluded from reference
-rewriting.
+generated directories, and rebuilds disposable views.
+
+For the chooser between task bodies and document kinds, see
+[Memory model](memory-model.md).

package/docs/getting-started.md

@@ -74,7 +74,10 @@ taskset task list
 taskset document list --json
 ```
 
-You can read every file directly in the editor without the CLI. Cite entities by short hex `id`, never by filename sequence prefixes.
+You can read every file directly in the editor without the CLI. Use short hex
+`id` values in commands and `--related`. Filename sequence prefixes are display
+metadata only. Markdown hyperlinks to entity or docs files must use the
+repository-relative filepath (for example [document types](document-types.md)).
 
 ## Query and validate the graph
 
@@ -100,7 +103,9 @@ Completed and canceled tasks are terminal. Deletion fails while another task dep
 ## Next
 
 - [Choose a document type](document-types.md)
+- [Choose memory layers](memory-model.md)
 - [Understand task files](task-files.md)
 - [Configure defaults](configuration.md)
 - [Use the complete CLI reference](cli-reference.md)
 - [Follow the agent guide](agents/index.md)
+- [Query recipes for agents](agents/query-recipes.md)

package/docs/index.md

@@ -1,13 +1,13 @@
 ---
 title: Keep the whole delivery story beside the code
-description: Taskset stores plans, research, decisions, runbooks, and tasks as Markdown in your repository for agents and humans.
+description: Taskset stores plans, research, decisions, runbooks, lessons, concerns, audits, and tasks as Markdown in your repository for agents and humans.
 contentType: Landing
 navLabel: Overview
 ---
 
 # Keep the whole delivery story beside the code
 
-Taskset is a local-first delivery workspace. You keep stories, research, decisions, flows, runbooks, and executable tasks as Markdown under `.taskset/`, so agents and humans share one reviewable source of truth.
+Taskset is a local-first delivery workspace. You keep stories, research, decisions, flows, runbooks, lessons, concerns, audits, and executable tasks as Markdown under `.taskset/`, so agents and humans share one reviewable source of truth.
 
 Install the CLI as `@taskset/cli` from npm. Run it with `npx`, `pnpm dlx`, `yarn dlx`, `bunx`, a project dependency, or a global install.
 
@@ -17,6 +17,7 @@ Install the CLI as `@taskset/cli` from npm. Run it with `npx`, `pnpm dlx`, `yarn
 - **Learn**: research that captures evidence and recommendations
 - **Decide**: decisions and ADRs that lock lasting choices
 - **Operate**: runbooks that make recovery safe to repeat
+- **Remember**: lessons, concerns, and audits for recurring patterns and residual risk
 - **Deliver**: tasks that carry ownership, status, dependencies, and code impact
 
 Documents preserve memory. Tasks move work. Relationships keep the graph honest.
@@ -37,7 +38,12 @@ The CLI initializes repositories, manages optional configuration, creates and qu
 
 - [Start a Taskset repository](getting-started.md)
 - [Choose a document type](document-types.md)
+- [Choose memory layers](memory-model.md)
+- [Track security and compliance](security-compliance-tracking.md)
+- [Follow the agent closeout contract](agent-closeout.md)
+- [Control taxonomy](taxonomy-cookbook.md)
 - [Understand task files](task-files.md)
 - [Configure defaults when you need them](configuration.md)
 - [Look up every CLI command](cli-reference.md)
 - [Read agent workflows and contracts](agents/index.md)
+- [Copy-paste agent query recipes](agents/query-recipes.md)

package/docs/maintainers/product/vision.md

@@ -61,7 +61,9 @@ The current surface includes:
 
 - repository initialization and optional configuration
 - tasks with lifecycle, dependencies, search, and impact queries
-- stories, flows, decisions, research, and runbooks with the same query and mutation family
+- 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
 

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)