@taskset/cli 5.1.0 → 6.1.0

package/skills/taskset/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: taskset
-description: Taskset workflow guidance for agents that plan and track work with tasks, stories, user flows, decisions, research, and runbooks 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
 
-Use this skill when working in a repository that uses Taskset to store work as human-readable Markdown beside the code.
+Use this skill when working in a repository that uses Taskset to store plans, research, decisions, runbooks, and executable tasks as human-readable Markdown beside the code. Tasks move delivery. Documents preserve the memory that makes delivery coherent.
 
 ## Packaged Docs And Skills
 
@@ -18,7 +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/` | User docs: getting started, configuration, CLI reference, task files, document types |
+| `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
@@ -27,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`
@@ -43,19 +47,24 @@ package root.
 
 - Treat `.taskset/tasks/` as the canonical task source of truth and the sibling
   document-kind directories as the canonical durable project-document source.
-- Treat `taskset.config.ts` as the repository entrypoint for Taskset behavior and defaults.
+- Treat the nearest `.taskset/` directory as the repository marker. Optional
+  `taskset.config.ts` at that root overlays defaults; built-in defaults apply
+  when it is absent.
 - Do not create a second task store, hidden database, or alternate sync layer.
 - Use Taskset commands to inspect and mutate tasks instead of editing canonical task files by hand when a command exists.
-- Prefer `pnpm taskset` in project repositories; use the repo root `pnpm taskset` script when available.
+- Invoke Taskset with whatever runner the environment provides:
+  `npx @taskset/cli`, `pnpm dlx @taskset/cli`, `yarn dlx @taskset/cli`,
+  `bunx @taskset/cli`, `pnpm exec taskset`, or a global `taskset` binary. Do not
+  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
 
-1. Confirm the repository root and Taskset config.
-2. Inspect repository health with `taskset config --json` and `taskset doctor`.
+1. Confirm the repository root with `taskset config --json` (look for `.taskset/`, not a required config file).
+2. Inspect repository health with `taskset doctor --json`.
 3. List or show tasks and check their owner and assignees before changing or executing them.
 4. Resolve whether the current Git user is authorized to take the selected task; obtain confirmation when another person is responsible and the request does not already authorize that specific takeover.
 5. Create, update, execute, or close tasks with Taskset commands.
@@ -75,24 +84,28 @@ For ownership-gate scenarios, read [owner and assignee examples](references/task
 ## Common Commands
 
 ```bash
-pnpm taskset config --json
-pnpm taskset doctor
-pnpm taskset task list
-pnpm taskset task show <task-id>
-pnpm taskset task create --title "Describe the work"
-pnpm taskset task update <task-id> --status doing
-pnpm taskset task status <task-id> done
-pnpm taskset task delete <task-id>
-pnpm taskset task list --search "multiple terms"
-pnpm taskset task list --file packages/core --impact
-pnpm taskset document create story --title "Describe the user outcome"
-pnpm taskset document create research --title "Evaluate options" --related <task-id>
-pnpm taskset document update <document-id> --status ready --type research
-pnpm taskset document list research --search "queue" --impact
-pnpm taskset document show <document-id> --type research --include-derived --json
-pnpm taskset document import docs/adr/0001-example.md --type adr --move
-pnpm taskset document batch taskset-documents.json --concurrency 4 --json
-pnpm taskset sync
+taskset config --json
+taskset doctor --json
+taskset task list --json
+taskset task show your_task_id_here --json
+taskset task create --title "Describe the work"
+taskset task update your_task_id_here --status doing
+taskset task status your_task_id_here done
+taskset task delete your_task_id_here
+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
 ```
 
 ## Practical Guidance
@@ -113,24 +126,33 @@ pnpm taskset sync
   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,
-  migrate legacy IDs and repository text references, refresh data `.gitignore`
-  patterns for scoped `.generated/` directories, and rebuild views.
+  migrate legacy IDs to short hex IDs, normalize filenames, repair duplicate
+  sequence prefixes, rewrite repository text references, refresh data
+  `.gitignore` patterns for scoped `.generated/` directories, and rebuild views.
 - 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 use `0000001-short-title` naming. Use
-  `task migrate-ids` for legacy task repositories; do not rename task 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
@@ -161,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).
 
@@ -217,11 +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.
+- 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

@@ -85,9 +85,9 @@ listed in Preserve Product Invariants, the invariant takes precedence. Explain
 the conflict to the user and request an explicit override with rationale before
 proceeding.
 
-The repository is currently an early scaffold. Do not turn accidental manifest
-mistakes, empty packages, or placeholder dependencies into conventions. Report
-them and follow the intended `@taskset/<directory-name>` ownership model.
+Do not turn accidental manifest mistakes, empty packages, or placeholder
+dependencies into conventions. Report them and follow the intended
+`@taskset/<directory-name>` ownership model.
 
 ## Preserve Product Invariants
 
@@ -117,29 +117,38 @@ 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
-  manifest result order, and serialize writes that allocate sequential IDs.
+  manifest result order, and serialize writes that allocate short hex IDs plus
+  filename display sequences.
 - Disposable metadata indexes live in each entity folder's `.generated/`
   directory (for example `.taskset/tasks/.generated/` and
   `.taskset/research/.generated/`), not a global `.taskset/generated/` tree.
 - Repository sync is the maintenance entrypoint: ensure canonical `.taskset/`
-  directories, migrate task IDs and repository text references atomically,
+  directories, migrate task and document IDs to immutable short hex IDs,
+  normalize `{sequence}-{slug}-{id}.md` filenames, repair duplicate sequence
+  prefixes by `createdAt`, rewrite repository text references atomically,
   refresh data `.gitignore` rules for scoped generated output, remove legacy
   global generated directories, then rebuild disposable generated views.
-- `taskset.config.ts` marks the repository root and configures validated project
-  metadata and task creation defaults. It never relocates canonical
-  `.taskset/` data or becomes a second task store.
-- Taskset is developed using its own root config, CLI, and canonical task
-  files. Keep that dogfooding workflow operational when changing core, CLI,
-  workspace commands, or persisted contracts.
+- The nearest `.taskset/` directory marks the repository root. Optional
+  `taskset.config.ts` at that root configures validated project metadata and
+  task creation defaults. Missing config uses built-in defaults. Config never
+  relocates canonical `.taskset/` data or becomes a second task store.
+- Taskset is developed using its own `.taskset/` data, optional root config,
+  CLI, and canonical task files. Keep that dogfooding workflow operational when
+  changing core, CLI, workspace commands, or persisted contracts.
+- Public docs split three audiences: humans (`docs/`), agents (`docs/agents/`
+  plus `skills/` and root `AGENTS.md`), and maintainers (`docs/maintainers/`).
 
 ## Organize by Ownership
 

package/skills/taskset-implement/references/architecture/documentation-and-generated.md

@@ -31,7 +31,9 @@ Recommended website stack:
 Register blog posts in the app-local post registry so static export can
 enumerate `/posts/[slug]`. Keep blog posts in plain Markdown by default with
 `title`, `description`, and `date` frontmatter. Do not merge docs and blog theme
-wrappers in the global MDX component map.
+wrappers in the global MDX component map. Agent operating pages live under
+`docs/agents/` and appear in usage navigation; maintainer pages stay under
+`/maintainers`.
 
 Keep architectural decisions under
 `docs/maintainers/architecture/decisions/`.

package/skills/taskset-implement/references/architecture/ownership-and-dependencies.md

@@ -39,7 +39,8 @@ surfaces such as package names, the CLI command, `taskset.config.ts`, and
 `.taskset/`.
 
 Taskset dogfoods these boundaries. The root workspace installs core and CLI,
-loads `taskset.config.ts`, and stores its own planned work in `.taskset/tasks/`.
+may load optional `taskset.config.ts`, and stores its own planned work in
+`.taskset/tasks/`.
 
 ## Dependency Flow
 

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

@@ -4,13 +4,13 @@ Product direction and the canonical source-of-truth model.
 
 ## Product Direction
 
-Taskset began as an offline, inline, AI-friendly, human-readable task manager
-designed to accelerate software delivery and give development teams immediate
-awareness of the work surrounding their code.
+Taskset began as an offline, inline, AI-friendly, human-readable delivery
+workspace: not only tasks, but the plans, research, decisions, flows, and
+runbooks that make delivery coherent.
 
-It grows from that core into a Git-native software delivery platform. Tasks,
-stories, flows, decisions, research, runbooks, and related project knowledge
-live beside the code as human-readable Markdown.
+It is a Git-native software delivery platform. Stories, flows, decisions,
+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.
 
@@ -31,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
 
@@ -51,6 +54,12 @@ Canonical project state lives under `.taskset/`.
 │   └── .generated/
 ├── runbooks/
 │   └── .generated/
+├── lessons/
+│   └── .generated/
+├── concerns/
+│   └── .generated/
+├── audits/
+│   └── .generated/
 ├── snapshots/
 └── cache/
 ```
@@ -58,8 +67,10 @@ Canonical project state lives under `.taskset/`.
 Rules:
 
 - Entity Markdown files are authoritative persisted state.
-- `taskset.config.ts` is the discoverable repository usage configuration. It
-  controls validated behavior and defaults, not canonical entity state.
+- The nearest `.taskset/` directory is the discoverable repository marker.
+  Optional `taskset.config.ts` at that root overlays validated behavior and
+  defaults. Missing config uses built-in defaults. Config never owns entity
+  state.
 - YAML frontmatter contains structured metadata. Markdown bodies contain
   durable human context.
 - Do not store the same field independently in frontmatter and body.
@@ -73,8 +84,8 @@ Rules:
   state, or another hidden store as an undeclared authority.
 - Git is the versioning and collaboration layer around the files. Do not assume
   it provides database transactions or conflict-free identifiers.
-- Repository discovery walks upward for exactly `taskset.config.ts`; canonical
-  storage remains fixed under `.taskset/`.
+- Repository discovery walks upward for `.taskset/`; canonical storage remains
+  fixed under that directory.
 
 Any persisted format change must define validation, compatibility, migration,
 and failure behavior before implementation.

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 IDs immutable. Do not adopt sequential IDs without a documented
-  branch-collision strategy.
+- 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.

package/skills/taskset-implement/references/conventions/naming-and-packages.md

@@ -55,7 +55,7 @@ taskset task list --file packages/core --impact
 taskset context-bundle
 ```
 
-The root usage configuration is exactly `taskset.config.ts`. Export a
+Optional root usage configuration is exactly `taskset.config.ts`. Export a
 versionless object, preferably through `defineConfig` from `@taskset/core`.
 Keep configuration fields behavioral; never use config to redirect canonical
 entity storage outside `.taskset/`.

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

@@ -8,7 +8,7 @@ Use YAML frontmatter for machine metadata and Markdown for human context:
 
 ```markdown
 ---
-id: 0000001-add-task-validation
+id: a1b2c3
 title: Add task validation
 status: doing
 priority: high
@@ -31,6 +31,8 @@ Describe why the work exists.
 - [ ] Invalid statuses produce an actionable diagnostic.
 ```
 
+Filename: `0000001-add-task-validation-a1b2c3.md`
+
 Rules:
 
 - Require `id`, `title`, `status`, `createdAt`, and `updatedAt`.
@@ -53,9 +55,12 @@ Rules:
   reading the documented legacy ISO 8601 UTC form until a compatibility change
   explicitly removes it.
 - Keep IDs immutable and compare them exactly.
-- Format new task IDs as a seven-digit sequence plus a lowercase title slug.
-  Keep legacy `TS-` ULIDs readable only so `task migrate-ids` can rewrite them
-  and all canonical relationships atomically.
+- Format new task and document IDs as 5-6 character lowercase hex values.
+  Store display order in the filename as `{sequence}-{slug}-{id}.md`. Keep
+  legacy `TS-` ULIDs and sequential `0000001-title` IDs readable only so
+  `sync` / `task migrate-ids` can rewrite them, normalize filenames, repair
+  duplicate sequence prefixes by `createdAt`, and update canonical
+  relationships atomically.
 - Preserve user-authored body text and meaningful list order.
 - Use stable key ordering and one final newline in generated output.
 - Generated metadata indexes cover supported non-ID metadata fields, group

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

@@ -96,9 +96,10 @@ must remain available. Root-only architecture tests run once after Turbo rather
 than being duplicated inside every package. There is no `transit` script;
 Turbo's dependency traversal is orchestration, not another test suite.
 
-`taskset.config.ts` is loaded as trusted project code using Node's native
-erasable TypeScript support. Keep it free of syntax that requires TypeScript
-code generation.
+Optional `taskset.config.ts` is loaded as trusted project code using Node's
+native erasable TypeScript support when present. Keep it free of syntax that
+requires TypeScript code generation. Repository discovery uses `.taskset/`, not
+the config file.
 
 If Turbo reports duplicate workspace names, fix the incorrect package manifest.
 Do not work around the graph with directory filters or aliases.