@erclx/aitk 0.89.1 → 0.90.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.89.1",
+  "version": "0.90.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-groundwork/SKILL.md

@@ -97,7 +97,7 @@ Do not close while an open question quietly fails an outcome. Resolve it, or rec
 
 ## Output
 
-Emit the full relative path from the project root for every file written or updated. Bare filenames are not clickable.
+Emit the full relative path from the project root for every file written or updated. A bare filename names a file the reader cannot open.
 
 Open and resume:
 

package/claude/skills/claude-intake/SKILL.md

@@ -101,7 +101,14 @@ A file the pass only read gets no line, which is what keeps the block short.
 
 **Open questions:** <N> awaiting your call
 
-Next: answer the `You:` slots, then /claude-tasks to promote what is ready
+Next: /claude-intake-answer to answer the `You:` slots from here, or type them
+into the files, then /claude-tasks to promote what is ready
 ```
 
 Use `📂 Resumed` in place of `📂 Opened` on a resume pass.
+
+## Answering what this pass wrote
+
+The slots this pass leaves empty are answered by editing each cluster file, or from chat through `claude-intake-answer`, which walks the unread items in batches and writes each selection back onto the item it answers. Name that route in the closing line so the operator finds it where they look for it.
+
+Do not invoke it from here. It is operator-triggered, and a pass that files a dump and answers it in the same run decides items on silence.

package/claude/skills/claude-intake-answer/REQUIREMENT.md

@@ -0,0 +1,48 @@
+---
+name: claude-intake-answer
+description: Scope boundary for answering a filed intake from chat, and the write-back contract that keeps the file rather than the conversation as the record
+---
+
+# Claude intake answer requirement
+
+## Gap
+
+Without this skill, an operator answers a filed intake by opening each cluster file and typing under each item, so a dump spanning six clusters is six files navigated in turn and the cost scales with how well the pass split the domains. The folders that go unanswered are the large ones, which are the ones a breadth pass exists to produce.
+
+A session asked to help with that fails in shapes the intake standard already names. It reads an empty slot as agreement and reports items decided that nobody reached. It writes an answer into the conversation and never into the file, so the record still reads as unread and the next session re-asks. It types the answer into `00-overview.md`, where retrieval walks item headings and finds nothing. It overwrites a slot the operator already filled, discarding a decision already made.
+
+The write itself fails a fourth way that no prose rule prevents. Every worker runs in a linked worktree where the file-editing tools refuse a main-root path, and a stream editor expands an unescaped ampersand in the replacement to the whole match and exits zero when it matches nothing. A body instructing either route reports success and loses the answer.
+
+The batching fails a fifth way. A folder holding thirty unread items put as thirty questions is unanswerable, and put as one flat batch it hides which cluster the operator is in and leaves a file half answered when attention runs out.
+
+## Must
+
+- Offer every item carrying an empty answer slot, not only the ones carrying an open question, since the standard's one-token accept exists for a verdict with no question attached
+- Batch by cluster in the folder's own numbering, so the operator has a stopping point that leaves whole clusters unread rather than a file half answered
+- Cap a batch at four items, which is what a structured question tool takes
+- Rank the item's own suggestion or verdict first and give every option what it costs, since the pass already made a recommendation and burying it asks the operator to re-derive it
+- Land every selection through a verb that resolves the root in-process and rewrites the whole line, which is the only route that works from a linked worktree
+- Write one cluster per call, since concurrent calls against one file race on the read and keep only the last answer
+- Carry the cluster and the label together, because items are labeled per file and a label alone names an item in every cluster at once
+- Pass a label exactly as its heading spells it, letter suffix included, since a pass that splits a finding after the fact labels the halves rather than renumbering the file
+- Report what stays unread by count after each cluster
+
+## Must not
+
+- Fill a slot the operator did not answer, including the remainder of a batch they abandoned
+- Infer an answer from the conversation having happened, which is the inversion the intake standard states against the plan standard
+- Overwrite a slot already carrying an answer, which is a decision already made
+- Write anywhere in the folder but an item's answer slot, and never into the index, which carries none
+
+## Guards
+
+- No intake folder at all, stop and name the skill that files one
+- The named folder carrying no unread item, stop rather than re-asking answered items
+
+## Out of scope
+
+- Filing a dump and writing the items, which is `claude-intake` and owns every other write into the folder
+- Promoting an answered item onto the board, which is `claude-tasks` and runs after the answers land
+- The item format, the answer contract, and retrieval, which `standards/intake.md` owns and this skill cites
+- The comparable answer slots in groundwork and feature plans, which carry their own contracts and are a separate measurement
+- Deciding when to fire. The skill is user-invoked through `disable-model-invocation`, so answering is the operator's call rather than a description match.

package/claude/skills/claude-intake-answer/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: claude-intake-answer
+description: Walks an intake folder's unread items and puts them as batched questions in chat, writing each selection back onto the item it answers. Use when asked to "answer the intake", "work through the open items", "answer my intake questions", "go through the dump", or "let me answer these from here". Do NOT use to file a dump or write new items, which is `claude-intake`.
+disable-model-invocation: true
+---
+
+# Claude intake answer
+
+Put an intake folder's unread items as batched questions, then land each selection in the slot it answers.
+
+A folder is answered by opening each cluster file and typing under the item, which on a dump spanning six clusters means navigating to each in turn. This walks the same items in chat and writes the answers back, so the file rather than the conversation stays the record.
+
+Read `.claude/standards/intake.md` from the project root before writing anything, or `${CLAUDE_SKILL_DIR}/../../standards/intake.md` when the project does not have it. It holds the item format and the answer contract this skill is bound by.
+
+## Guards
+
+- If `aitk intake list --json` reports no folder, stop: `❌ No intake to answer. Run /claude-intake to file a dump first.`
+- If the named folder has no unread item, stop: `❌ Every item in <slug> carries an answer. Nothing to ask.`
+- Never fill a slot the operator did not answer. An abandoned batch leaves every unreached item unread, which is what the empty slot already means.
+- Never infer an answer from the conversation having happened. A selection reaches the file through the verb or not at all.
+- Do not promote an item, edit a verdict, or write outside the answer slots. Promoting runs through `claude-tasks` after the answers land.
+
+## Step 1: pick the folder
+
+Run `aitk intake list --json` and read the per-folder counts. With one folder carrying unread items, take it. With several, put the folders as one question carrying each slug and its unread count, and let the operator pick.
+
+Never guess from the topic of the conversation. A session resuming against the wrong folder answers items nobody asked about.
+
+## Step 2: collect one cluster
+
+Run `aitk intake list <slug> --unread --json`. It returns the unread items grouped by the cluster file holding them, each carrying its label, title, open question, and suggestion.
+
+Work one cluster at a time, in the order the folder numbers them. A dump of six clusters holding five items each is thirty questions, and a surface putting all of them at once is unusable. The cluster boundary is also where an operator who runs out of attention stops cleanly, leaving whole clusters unread rather than one file half answered.
+
+## Step 3: put the batch
+
+Cap each batch at four items, which is what a structured question tool takes. A cluster carrying more than four unread items takes several batches in file order.
+
+Every item with an empty slot is offered, not only the ones carrying an open question. An item with a verdict and no question is still asking whether the verdict stands, and the standard's one-token accept exists for exactly that case.
+
+Shape each question from what the item carries:
+
+- The item's label and title name the question, so the operator knows which item is being asked about
+- An item carrying `Open:` puts that question with its `Suggested:` line ranked first and marked as the suggestion
+- An item carrying no `Open:` puts its verdict, with accepting it ranked first as `ok` and the alternatives drawn from what the verdict could otherwise be
+
+Give every option what it means and what it costs. An option with no stated cost is not an option, since the operator picks it without knowing what the other one buys.
+
+Send the whole batch in one turn. When the session runs on a surface carrying a structured question tool, such as `AskUserQuestion` in Claude Code, send it through one call with one entry per item. Otherwise write it as a numbered list in one message with the suggestion marked.
+
+## Step 4: write the batch back
+
+Land every answered item in the cluster with one call:
+
+```bash
+aitk intake answer <slug> --cluster <file> --set <label>=<answer> --set <label>=<answer>
+```
+
+One call per cluster, never one per item. Items are labeled per cluster file, so the label alone does not identify an item and the cluster travels with it. Four separate calls against one file also race on the read and drop every answer but the last.
+
+Pass the label exactly as the heading spells it, including a letter suffix such as `3a`. Write the operator's selection as the answer, using `ok` for a verdict accepted as it stands.
+
+The verb refuses an item that already carries an answer rather than overwriting it, and refuses the whole batch when any item in it is filled. A filled slot is a decision already made. On that refusal, drop the named item from the batch and send the rest.
+
+An item the operator left unanswered is omitted from the call entirely. Do not pass it with an empty value, which writes a slot that reads as answered.
+
+## Step 5: continue or stop
+
+After each cluster, state how many clusters still carry unread items and continue to the next. Stop when the operator says to stop, and report what is left rather than pressing on.
+
+Answers are on disk as each cluster completes, so a session ending mid-folder loses nothing.
+
+## Output
+
+Report per cluster as it lands, then close with the folder's state:
+
+```plaintext
+✅ <N> answered in <file>
+<label>. <answer>
+
+📋 <N> cluster(s) still carrying unread items in <slug>
+```
+
+Close the run with the path so the reader can open what changed:
+
+```plaintext
+✅ <N> answered across <N> cluster(s) in <slug>
+<M> item(s) left unread
+.claude/intake/<slug>/
+```

package/claude/skills/claude-tasks/SKILL.md

@@ -97,7 +97,7 @@ The command drops the task's row from `.claude/tasks/priority.md` and leaves pro
 
 ## Output
 
-Emit the full relative path from the project root for every file written or moved. Bare filenames are not clickable.
+Emit the full relative path from the project root for every file written or moved. A bare filename names a file the reader cannot open.
 
 Create:
 

package/claude/skills/toolkit-feedback/SKILL.md

@@ -58,7 +58,7 @@ cat <<'EOF' | aitk feedback
 EOF
 ```
 
-Report the printed path back to the user on its own line so the terminal makes it clickable.
+Report the printed path back to the user on its own line, in the form the project's instruction file sets under `## Output`.
 
 For a durable, cross-machine report instead of local scratch, add `--github`. The CLI opens a GitHub issue on the toolkit repo and prints the issue URL. It needs `gh` authenticated, and falls back to local scratch with a warning when `gh` is absent.
 

package/claude/skills/youtube-transcripts/REQUIREMENT.md

@@ -16,7 +16,7 @@ Two smaller failures follow the fetch. A video with no captions produces a file
 ## Must
 
 - Run the CLI, which owns the fetch, the caption cleanup, and the frontmatter
-- Surface the written path as a full relative path so the terminal makes it clickable
+- Surface the written path as a full relative path, in the form the project's instruction file sets under `## Output`
 - Report a video with no captions as a fact about the video, since the file still exists and carries its metadata
 - Name the missing external binary and stop, leaving the install to the user
 

package/claude/skills/youtube-transcripts/SKILL.md

@@ -26,7 +26,7 @@ aitk transcripts <url>
 
 - Pass `--keep-timestamps` when the user wants `[mm:ss]` markers per line instead of prose.
 - Pass `--out <dir>` to override the output directory. The default is `transcripts/` in the current directory.
-- The written file path prints to stdout. Surface it back to the user as a full relative path so it is clickable.
+- The written file path prints to stdout. Surface it back to the user as a full relative path, in the form the project's instruction file sets under `## Output`.
 
 ## After the fetch
 

package/docs/agents/commands.md

@@ -30,6 +30,8 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 | `aitk tasks pull-request`  | Record a pull request number on the task a branch closes, by stem or `--plan` (`--json`)                                                  |
 | `aitk tasks outcome`       | Mark outcomes `[x]` on a task by position, repeating `--close` (`--json`)                                                                 |
 | `aitk tasks validate`      | Report board rows whose plan, task file, group, or file set does not hold (`--json`)                                                      |
+| `aitk intake list`         | Report intake folder counts, or one folder's items, keeping what is unread with `--unread` (`--json`)                                     |
+| `aitk intake answer`       | Write selections into one cluster's answer slots, repeating `--set <item>=<answer>` (`--json`)                                            |
 | `aitk records validate`    | Report a session record against the standard governing it, per kind (`--json`)                                                            |
 | `aitk records push`        | Commit the eight backed record folders and push them to a private records remote (`--json`)                                               |
 | `aitk records pull`        | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`)                                   |
@@ -54,6 +56,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 | `design`    | `render`                                                                    |
 | `slides`    | `render`, `list`                                                            |
 | `tasks`     | `archive`, `validate`                                                       |
+| `intake`    | `list`, `answer`                                                            |
 | `comments`  | `scan`                                                                      |
 | `context`   | `audit`                                                                     |
 | `markdown`  | `audit`                                                                     |

package/docs/agents/index.md

@@ -16,6 +16,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Docs](docs.md): How aitk docs resolves the toolkit's own reference surface from an install root, and how a split domain is named
 - [Indexes](indexes.md): Flags, exit codes, and JSON shape for aitk indexes regen, plus when it auto-stages what it rewrote
 - [Install and sync](install-and-sync.md): What each install and sync verb writes, refuses, or leaves alone, and how drift is attributed in a target project
+- [Intake](intake.md): Reading intake folder counts and items, the three read states an item can be in, landing a batch of selections in one cluster, the refusal reasons, and why a call is scoped to one file
 - [Markdown audit](markdown-audit.md): Running the audit over any markdown path, where its bans and checkpoints are read from, what each check reports, and why the ban half gates while the structural half reports
 - [Output shape](output-shape.md): Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead

package/docs/agents/intake.md

@@ -0,0 +1,77 @@
+---
+title: Intake
+description: Reading intake folder counts and items, the three read states an item can be in, landing a batch of selections in one cluster, the refusal reasons, and why a call is scoped to one file
+---
+
+# Intake
+
+## List
+
+`aitk intake list` reports the intake folders under `.claude/intake/`, or the items one folder holds. It reads and never writes, because an answer belongs to the operator and a verb that filled one would decide what the folder exists to ask.
+
+```bash
+aitk intake list
+aitk intake list toolkit-overview --unread --json
+```
+
+| Option          | Behavior                                                                  |
+| --------------- | ------------------------------------------------------------------------- |
+| `--unread`      | Keep only what is unread: folders carrying one, or a folder's empty slots |
+| `--json`        | Emit a machine-readable record on stdout                                  |
+| `--root <path>` | Intake root, defaulting to the main worktree                              |
+
+With no slug it reports per-folder counts. With one it reports every item grouped by the cluster file holding it, each carrying its label, title, open question, suggestion, and answer.
+
+An item sits in one of three read states, and the counts keep them apart:
+
+| State     | What it means                                           |
+| --------- | ------------------------------------------------------- |
+| unread    | The slot is present and empty, so nobody has reached it |
+| answered  | The slot carries text, which is a decision already made |
+| malformed | The item carries no slot, so no verb here can answer it |
+
+The third is counted apart from both rather than folded into either. Counted as answered it hides a file that needs fixing behind a folder reading as fully worked through, and counted as unread it joins a list whose every entry `answer` then refuses.
+
+The index is skipped, since it points at items and answers nothing itself. So is any item a file displays inside a fence, which is how a folder copying the item format into its own overview is read as the sample it is rather than as an item offering a slot no reader owns.
+
+## Answer
+
+`aitk intake answer` writes selections into the answer slots of one cluster file.
+
+```bash
+aitk intake answer toolkit-overview --cluster 05-coverage.md --set 3=ok
+aitk intake answer toolkit-overview --cluster 11-intake-skill.md --set 3d=ok --set 9="not worth it" --json
+```
+
+| Option                | Behavior                                              |
+| --------------------- | ----------------------------------------------------- |
+| `--cluster <file>`    | Cluster file the items live in, with or without `.md` |
+| `--set <item=answer>` | Answer to land on an item, repeatable                 |
+| `--json`              | Emit a machine-readable record on stdout              |
+| `--root <path>`       | Intake root, defaulting to the main worktree          |
+
+Items are labeled per cluster file, so a selection names the cluster and the label together. A label alone names an item in every cluster at once.
+
+A label may carry a letter suffix, as in `3a` beside `3`, which is how a pass records a finding split after the fact rather than renumbering every item below it. Pass it exactly as the heading spells it.
+
+One call writes one cluster. A call per selection is the alternative, and several of those against the same file read it before any of them writes, so every answer but the last is lost with nothing reporting it. The selections split on the first `=`, so an answer carrying its own survives intact.
+
+An item already carrying an answer refuses rather than being overwritten, and one filled item refuses the whole batch, so a partly applied write never lands. Drop the named item and send the rest.
+
+Exit codes: `0` every named item now carries its answer, `1` refused. The `reason` field carries `no-intake`, `no-folder`, `no-cluster`, `no-item`, `answered`, or `bad-input`.
+
+`bad-input` covers a malformed command line: no cluster, no selection, a selection that parses to no label and answer, an empty answer, an answer carrying a line break, or two answers for one item. It is separate from the reasons describing the folder, so a caller that mistyped a flag is not sent to repair a file that is fine.
+
+An empty answer refuses rather than writing an empty slot. The slot means unread while it is empty, so writing one back would report an item as answered that nobody decided.
+
+An answer occupies one line, and one carrying a line break refuses before anything is read. Writing it splices a bare continuation into the item that matches none of the patterns the reader tests, so the slot reads back as the text before the break while the item counts as answered, and the refusal on an already-answered item then leaves hand-editing the file as the only correction. The whole batch refuses, so a good selection beside a broken one never lands half applied.
+
+The folder is shared scratch at the main worktree root, so `--root` defaults to the first entry of `git worktree list` rather than the working directory. The write is an edit inside a file that already exists, which `Edit` and `Write` refuse from a linked worktree and a shell stream editor may not do, so the verb resolves the root in-process and rewrites whole lines.
+
+Skills branch on the reason rather than on the exit code:
+
+```bash
+aitk intake list toolkit-overview --unread --json | jq -r '.clusters[] | .cluster'
+```
+
+For the folder layout, the item format, the answer contract, and retrieval, see `.claude/standards/intake.md`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.89.1",
+  "version": "0.90.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/cli.ts

@@ -20,6 +20,7 @@ import { register as capture } from '@/commands/capture'
 import { register as feedback } from '@/commands/feedback'
 import { register as transcripts } from '@/commands/transcripts'
 import { register as tasks } from '@/commands/tasks'
+import { register as intake } from '@/commands/intake'
 import { register as comments } from '@/commands/comments'
 import { register as context } from '@/commands/context'
 import { register as markdown } from '@/commands/markdown'
@@ -53,6 +54,7 @@ function showHelp(): void {
     `${GREY}│${NC}    feedback           ${GREY}# Write toolkit feedback from stdin to .claude/review/${NC}`,
     `${GREY}│${NC}    transcripts <url>  ${GREY}# Fetch a YouTube transcript with metadata frontmatter${NC}`,
     `${GREY}│${NC}    tasks [cmd]        ${GREY}# Task board commands (archive)${NC}`,
+    `${GREY}│${NC}    intake [cmd]       ${GREY}# Intake folders under .claude/intake/ (list, answer)${NC}`,
     `${GREY}│${NC}    comments [cmd]     ${GREY}# Measure comment density and trend (scan)${NC}`,
     `${GREY}│${NC}    context [cmd]      ${GREY}# Report context folder health (audit)${NC}`,
     `${GREY}│${NC}    markdown [cmd]     ${GREY}# Report markdown against the attribute standards (audit)${NC}`,
@@ -87,6 +89,7 @@ function showHelp(): void {
     `${GREY}│${NC}    pbpaste | aitk feedback`,
     `${GREY}│${NC}    aitk transcripts https://youtu.be/VIDEO_ID`,
     `${GREY}│${NC}    aitk tasks archive --pull-request 673 --json`,
+    `${GREY}│${NC}    aitk intake list toolkit-overview --unread --json`,
     `${GREY}│${NC}    aitk comments scan src --json`,
     `${GREY}│${NC}    aitk context audit --json`,
     `${GREY}│${NC}    aitk markdown audit .claude/rules --json`,
@@ -143,6 +146,7 @@ capture(program)
 feedback(program)
 transcripts(program)
 tasks(program)
+intake(program)
 comments(program)
 context(program)
 markdown(program)

package/src/commands/intake.ts

@@ -0,0 +1,406 @@
+import { relative } from 'node:path'
+import type { Command } from 'commander'
+import {
+  type AnswerOutcome,
+  answerItems,
+  type IntakeRefused,
+  type ListOutcome,
+  listFolders,
+  type ReadOutcome,
+  readFolder,
+  type Selection,
+} from '@/intake/folder'
+import { isUnread } from '@/intake/items'
+import {
+  intro,
+  logAdd,
+  logError,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  pipeOutput,
+} from '@/ui'
+import { mainWorktreeRoot } from '@/worktree'
+
+/**
+ * A selection as the command line spells it, splitting on the first `=`. The
+ * label accepts a letter suffix, matching the headings a cluster file carries,
+ * and everything after the separator is the answer, so one carrying its own
+ * `=` survives intact.
+ */
+const SELECTION = /^(\d+[a-z]*)=([\s\S]*)$/i
+
+interface ListCommandOptions {
+  readonly json?: boolean
+  readonly unread?: boolean
+  readonly root?: string
+}
+
+interface AnswerCommandOptions {
+  readonly cluster?: string
+  readonly json?: boolean
+  readonly root?: string
+  readonly set?: readonly string[]
+}
+
+export function register(program: Command): void {
+  const intake = program
+    .command('intake')
+    .description('Read and answer intake folders in .claude/intake/')
+    .helpOption('-h, --help', 'Show this help message')
+
+  intake
+    .command('list')
+    .description('List intake folders, or the items one folder holds')
+    .argument('[slug]', 'Intake folder name, as in toolkit-overview')
+    .helpOption('-h, --help', 'Show this help message')
+    .option(
+      '--unread',
+      'Keep only what is unread, as folders carrying one or as empty slots',
+    )
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Intake root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the folders or items were listed',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'With no slug it reports per-folder counts. With one it reports every',
+        'item grouped by the cluster file holding it. An empty answer slot',
+        'means unread and never agreement, so a count is the report and no',
+        'verb here decides one.',
+        '',
+        'An item carrying no answer slot is counted apart from both, since the',
+        'answer verb cannot reach it and folding it into either count hides a',
+        'file that needs fixing.',
+        '',
+        'Examples:',
+        '  aitk intake list',
+        '  aitk intake list toolkit-overview --unread --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (slug: string | undefined, opts: ListCommandOptions) => {
+      process.exitCode = await runList(slug, opts)
+    })
+
+  intake
+    .command('answer')
+    .description("Write selections into a cluster's answer slots")
+    .argument('<slug>', 'Intake folder name, as in toolkit-overview')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--cluster <file>', 'Cluster file the items live in')
+    .option(
+      '--set <item=answer>',
+      'Answer to land on an item, repeatable',
+      collectSelection,
+      [] as string[],
+    )
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Intake root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  every named item now carries its answer',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Items are numbered per cluster file, so a selection names the cluster',
+        'and the number together. One call writes one cluster, which is what',
+        'keeps a batch from racing on the file every selection shares.',
+        '',
+        'An item already carrying an answer is refused rather than overwritten.',
+        'A filled slot is a decision already made.',
+        '',
+        'Examples:',
+        '  aitk intake answer toolkit-overview --cluster 05-coverage.md --set 3=ok',
+        '  aitk intake answer toolkit-overview --cluster 05-coverage.md --set 3=ok --set 4="not worth it" --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (slug: string, opts: AnswerCommandOptions) => {
+      process.exitCode = await runAnswer(slug, opts)
+    })
+}
+
+function collectSelection(value: string, previous: string[]): string[] {
+  return [...previous, value]
+}
+
+async function runList(
+  slug: string | undefined,
+  opts: ListCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  const root = opts.root ?? (await mainWorktreeRoot())
+
+  if (slug === undefined) {
+    return reportList(
+      await listFolders(root),
+      emitJson,
+      root,
+      opts.unread ?? false,
+    )
+  }
+
+  return reportFolder(
+    await readFolder(root, slug),
+    emitJson,
+    root,
+    opts.unread ?? false,
+  )
+}
+
+async function runAnswer(
+  slug: string,
+  opts: AnswerCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+
+  if (!opts.cluster) {
+    return reportRefusal(
+      'aitk intake answer',
+      {
+        ok: false,
+        reason: 'bad-input',
+        message: 'No cluster named. Pass --cluster <file>.',
+        detail: [],
+      },
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const raw = opts.set ?? []
+
+  if (raw.length === 0) {
+    return reportRefusal(
+      'aitk intake answer',
+      {
+        ok: false,
+        reason: 'bad-input',
+        message: 'No selection given. Pass --set <item>=<answer>.',
+        detail: [],
+      },
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const selections: Selection[] = []
+  const invalid: string[] = []
+
+  for (const entry of raw) {
+    const match = SELECTION.exec(entry)
+    const answer = match?.[2].trim()
+
+    if (!match || !answer) {
+      invalid.push(entry)
+      continue
+    }
+
+    selections.push({ label: match[1].toLowerCase(), answer })
+  }
+
+  if (invalid.length > 0) {
+    return reportRefusal(
+      'aitk intake answer',
+      {
+        ok: false,
+        reason: 'bad-input',
+        message: `Not an item and answer: ${invalid.join(', ')}`,
+        detail: invalid,
+      },
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const duplicated = selections
+    .map((selection) => selection.label)
+    .filter((label, index, all) => all.indexOf(label) !== index)
+
+  if (duplicated.length > 0) {
+    return reportRefusal(
+      'aitk intake answer',
+      {
+        ok: false,
+        reason: 'bad-input',
+        message: `Two answers for item ${[...new Set(duplicated)].join(', ')}.`,
+        detail: [],
+      },
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const outcome = await answerItems(root, slug, opts.cluster, selections)
+
+  return reportAnswer(outcome, emitJson, root)
+}
+
+function reportRefusal(
+  title: string,
+  refused: IntakeRefused,
+  emitJson: boolean,
+  root: string,
+): number {
+  // The framed branch reaches stderr through logError, so the bare write is
+  // what keeps the JSON mode from reporting the reason on stdout alone.
+  if (emitJson) {
+    process.stderr.write(`${refused.message}\n`)
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: false,
+        root,
+        reason: refused.reason,
+        message: refused.message,
+        detail: refused.detail,
+      })}\n`,
+    )
+    return 1
+  }
+
+  intro(title)
+  logStep('Refused')
+  logError(refused.message)
+  if (refused.detail.length > 0) pipeOutput(refused.detail.join('\n'))
+  outro()
+
+  return 1
+}
+
+function reportList(
+  outcome: ListOutcome,
+  emitJson: boolean,
+  root: string,
+  unreadOnly: boolean,
+): number {
+  if (!outcome.ok) {
+    return reportRefusal('aitk intake list', outcome, emitJson, root)
+  }
+
+  // Malformed items are counted over every folder rather than the filtered
+  // set, since a folder whose only defect is an item nobody can answer carries
+  // no unread count to survive the filter and is exactly what the warning is
+  // for.
+  const listed = unreadOnly
+    ? outcome.folders.filter((folder) => folder.unread > 0)
+    : outcome.folders
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ ok: true, root, folders: listed })}\n`,
+    )
+    return 0
+  }
+
+  intro('aitk intake list')
+  logStep(listed.length > 0 ? 'Folders' : 'No folders')
+
+  for (const folder of listed) {
+    logInfo(
+      `${folder.slug}: ${folder.items} item(s), ${folder.open} open, ${folder.unread} unread`,
+    )
+  }
+
+  const malformed = outcome.folders.filter((folder) => folder.malformed > 0)
+
+  if (malformed.length > 0) {
+    logStep('Carrying no answer slot')
+    for (const folder of malformed) {
+      logWarn(
+        `${folder.slug}: ${folder.malformed} item(s), which none of these verbs can answer`,
+      )
+    }
+  }
+
+  outro()
+
+  return 0
+}
+
+function reportFolder(
+  outcome: ReadOutcome,
+  emitJson: boolean,
+  root: string,
+  unreadOnly: boolean,
+): number {
+  if (!outcome.ok) {
+    return reportRefusal('aitk intake list', outcome, emitJson, root)
+  }
+
+  const clusters = outcome.clusters
+    .map((cluster) => ({
+      cluster: cluster.cluster,
+      items: unreadOnly ? cluster.items.filter(isUnread) : cluster.items,
+    }))
+    .filter((cluster) => cluster.items.length > 0)
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ ok: true, root, slug: outcome.slug, clusters })}\n`,
+    )
+    return 0
+  }
+
+  intro('aitk intake list')
+
+  for (const cluster of clusters) {
+    logStep(cluster.cluster)
+    for (const item of cluster.items) {
+      const state = isUnread(item) ? 'unread' : (item.answer ?? 'no slot')
+      logInfo(`${item.label}. ${item.title} (${state})`)
+    }
+  }
+
+  if (clusters.length === 0) {
+    logStep(unreadOnly ? 'Nothing unread' : 'No items')
+  }
+
+  outro()
+
+  return 0
+}
+
+function reportAnswer(
+  outcome: AnswerOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    return reportRefusal('aitk intake answer', outcome, emitJson, root)
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        slug: outcome.slug,
+        cluster: outcome.cluster,
+        path: relative(root, outcome.path),
+        answered: outcome.answered,
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro('aitk intake answer')
+  logStep('Answered')
+
+  for (const entry of outcome.answered) {
+    logInfo(`${entry.label}. ${entry.answer}`)
+  }
+
+  logAdd(relative(root, outcome.path))
+  outro()
+
+  return 0
+}

package/src/intake/folder.ts

@@ -0,0 +1,280 @@
+import { existsSync } from 'node:fs'
+import { readdir, readFile, writeFile } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+import {
+  INDEX_FILE,
+  type IntakeItem,
+  isMalformed,
+  isUnread,
+  readItems,
+  writeAnswerLine,
+} from '@/intake/items'
+
+export const INTAKE_REFUSALS = [
+  'no-intake',
+  'no-folder',
+  'no-cluster',
+  'no-item',
+  'answered',
+  'bad-input',
+] as const
+
+export type IntakeRefusal = (typeof INTAKE_REFUSALS)[number]
+
+export interface IntakeRefused {
+  readonly ok: false
+  readonly reason: IntakeRefusal
+  readonly message: string
+  readonly detail: readonly string[]
+}
+
+export interface FolderSummary {
+  readonly slug: string
+  readonly items: number
+  readonly open: number
+  readonly unread: number
+  /** Items carrying no answer slot, which no route here can answer. */
+  readonly malformed: number
+}
+
+export interface ClusterItems {
+  readonly cluster: string
+  readonly items: readonly IntakeItem[]
+}
+
+export interface FolderListed {
+  readonly ok: true
+  readonly folders: readonly FolderSummary[]
+}
+
+export interface FolderRead {
+  readonly ok: true
+  readonly slug: string
+  readonly clusters: readonly ClusterItems[]
+}
+
+export interface AnswerWritten {
+  readonly ok: true
+  readonly slug: string
+  readonly cluster: string
+  readonly path: string
+  readonly answered: readonly Selection[]
+}
+
+export type ListOutcome = FolderListed | IntakeRefused
+export type ReadOutcome = FolderRead | IntakeRefused
+export type AnswerOutcome = AnswerWritten | IntakeRefused
+
+export interface Selection {
+  readonly label: string
+  readonly answer: string
+}
+
+function refuse(
+  reason: IntakeRefusal,
+  message: string,
+  detail: readonly string[] = [],
+): IntakeRefused {
+  return { ok: false, reason, message, detail }
+}
+
+export function intakeDir(root: string): string {
+  return join(root, '.claude', 'intake')
+}
+
+/**
+ * Cluster files in read order, which is the numbering the folder carries. The
+ * index is dropped because it answers nothing, so every remaining file is one a
+ * selection can land in.
+ */
+export async function listClusters(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true })
+
+  return entries
+    .filter(
+      (entry) =>
+        entry.isFile() &&
+        entry.name.endsWith('.md') &&
+        entry.name !== INDEX_FILE,
+    )
+    .map((entry) => entry.name)
+    .sort()
+}
+
+async function listSlugs(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true })
+
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+}
+
+async function openFolder(
+  root: string,
+  slug: string,
+): Promise<string | IntakeRefused> {
+  const dir = intakeDir(root)
+
+  if (!existsSync(dir)) {
+    return refuse('no-intake', `No intake at ${relative(root, dir)}.`)
+  }
+
+  const folder = join(dir, slug)
+
+  if (!existsSync(folder)) {
+    return refuse(
+      'no-folder',
+      `No intake folder named ${slug}.`,
+      await listSlugs(dir),
+    )
+  }
+
+  return folder
+}
+
+/** Counts per folder, which is what a session picks a folder to work from. */
+export async function listFolders(root: string): Promise<ListOutcome> {
+  const dir = intakeDir(root)
+
+  if (!existsSync(dir)) {
+    return refuse('no-intake', `No intake at ${relative(root, dir)}.`)
+  }
+
+  const slugs = await listSlugs(dir)
+
+  const folders = await Promise.all(
+    slugs.map(async (slug) => {
+      const clusters = await readClusters(join(dir, slug))
+      const items = clusters.flatMap((cluster) => cluster.items)
+
+      return {
+        slug,
+        items: items.length,
+        open: items.filter((item) => item.open !== undefined).length,
+        unread: items.filter(isUnread).length,
+        malformed: items.filter(isMalformed).length,
+      }
+    }),
+  )
+
+  return { ok: true, folders }
+}
+
+async function readClusters(folder: string): Promise<ClusterItems[]> {
+  const names = await listClusters(folder)
+
+  return Promise.all(
+    names.map(async (cluster) => ({
+      cluster,
+      items: readItems(await readFile(join(folder, cluster), 'utf8')),
+    })),
+  )
+}
+
+/** Every item in a folder, grouped by the cluster file that holds it. */
+export async function readFolder(
+  root: string,
+  slug: string,
+): Promise<ReadOutcome> {
+  const opened = await openFolder(root, slug)
+  if (typeof opened !== 'string') return opened
+
+  return { ok: true, slug, clusters: await readClusters(opened) }
+}
+
+/**
+ * Lands a batch of selections in one cluster file.
+ *
+ * The batch is scoped to a cluster and applied in one read-modify-write because
+ * the alternative is a call per selection, and four of those against the same
+ * file race on the read and drop every answer but the last.
+ */
+export async function answerItems(
+  root: string,
+  slug: string,
+  cluster: string,
+  selections: readonly Selection[],
+): Promise<AnswerOutcome> {
+  const opened = await openFolder(root, slug)
+  if (typeof opened !== 'string') return opened
+
+  const name = cluster.endsWith('.md') ? cluster : `${cluster}.md`
+
+  if (name === INDEX_FILE) {
+    return refuse(
+      'no-cluster',
+      `${INDEX_FILE} is the index and carries no answer slot.`,
+    )
+  }
+
+  const path = join(opened, name)
+
+  if (!existsSync(path)) {
+    return refuse(
+      'no-cluster',
+      `No cluster named ${name} in ${slug}.`,
+      await listClusters(opened),
+    )
+  }
+
+  const broken = selections.filter((selection) =>
+    /[\r\n]/.test(selection.answer),
+  )
+
+  if (broken.length > 0) {
+    return refuse(
+      'bad-input',
+      `An answer is one line, so item ${broken.map((entry) => entry.label).join(', ')} cannot carry a line break.`,
+      broken.map((entry) => entry.label),
+    )
+  }
+
+  let text = await readFile(path, 'utf8')
+  const items = readItems(text)
+
+  const find = (label: string) =>
+    items.find((item) => item.label === label.toLowerCase())
+
+  const missing = selections.filter(
+    (selection) => find(selection.label)?.answerLine === undefined,
+  )
+
+  if (missing.length > 0) {
+    return refuse(
+      'no-item',
+      `${name} carries no answer slot for item ${missing.map((entry) => entry.label).join(', ')}.`,
+      items.map((item) => `${item.label}. ${item.title}`),
+    )
+  }
+
+  const filled = selections.filter(
+    (selection) => find(selection.label)?.answer !== undefined,
+  )
+
+  if (filled.length > 0) {
+    return refuse(
+      'answered',
+      `${name} item ${filled.map((entry) => entry.label).join(', ')} already carries an answer.`,
+      filled.map(
+        (entry) => `${entry.label}. ${find(entry.label)?.answer ?? ''}`,
+      ),
+    )
+  }
+
+  for (const selection of selections) {
+    const item = find(selection.label)
+    if (item?.answerLine === undefined) continue
+    text = writeAnswerLine(text, item.answerLine, selection.answer)
+  }
+
+  await writeFile(path, text)
+
+  return {
+    ok: true,
+    slug,
+    cluster: name,
+    path,
+    answered: selections,
+  }
+}

package/src/intake/items.ts

@@ -0,0 +1,174 @@
+import { bodyLines } from '@/markdown/scan'
+
+/**
+ * The index points at items and answers nothing itself, so it carries no
+ * answer slot for this verb to reach. It also displays the item format inside a
+ * fence, which the fence walk already masks, so skipping it by name is about
+ * what the file is rather than about the block it holds.
+ */
+export const INDEX_FILE = '00-overview.md'
+
+/**
+ * An item heading, labeled per cluster file rather than per folder.
+ *
+ * The label carries an optional letter suffix because a pass that splits one
+ * finding after the fact numbers the halves `3a` and `3b` rather than
+ * renumbering every item below them. A pattern accepting digits alone parses
+ * such a file without complaint and drops those items, leaving them
+ * unanswerable through this verb with nothing reporting the gap.
+ */
+const HEADING = /^###\s+(\d+[a-z]*)\.\s*(.*)$/i
+
+/** A bolded field bullet, which is every line an item carries. */
+const FIELD = /^-\s+\*\*([^*]+):\*\*\s*(.*)$/
+
+/**
+ * Any heading, which ends the item above it.
+ *
+ * A numbered `###` is tested first and opens the next item, so what reaches
+ * here is a heading that is not an item and therefore closes the one open. The
+ * narrower test for `##` alone let a `### Notes` block stay inside the item
+ * above it, and the stray slot such a block carries then displaced the real
+ * one, leaving the item reading as answered while its own slot sat empty and
+ * sending a write into the wrong section.
+ */
+const SECTION = /^#{1,6}\s/
+
+export interface IntakeItem {
+  /** The label as the heading spells it, such as `3` or `3a`. */
+  readonly label: string
+  readonly title: string
+  /** Line the heading sits on, 1-based against the whole file. */
+  readonly line: number
+  /** Line the answer slot sits on, absent when the item carries no slot. */
+  readonly answerLine: number | undefined
+  /** Text in the slot, absent when the slot is empty and the item is unread. */
+  readonly answer: string | undefined
+  readonly open: string | undefined
+  readonly suggested: string | undefined
+  readonly worth: string | undefined
+}
+
+interface Draft {
+  label: string
+  title: string
+  line: number
+  answerLine: number | undefined
+  answer: string | undefined
+  open: string | undefined
+  suggested: string | undefined
+  worth: string | undefined
+}
+
+function seal(draft: Draft): IntakeItem {
+  return { ...draft }
+}
+
+/**
+ * Reads every item a cluster file holds, in file order.
+ *
+ * The walk runs over `bodyLines` rather than a raw split so the item format
+ * block a folder copies into its own files parses as the sample it is. A
+ * heading counted out of a fence shifts nothing on its own, but it offers an
+ * answer slot no reader owns and the write-back would land inside the sample.
+ */
+export function readItems(text: string): IntakeItem[] {
+  const items: IntakeItem[] = []
+  let draft: Draft | undefined
+
+  for (const line of bodyLines(text)) {
+    if (line.fenced) continue
+
+    const heading = HEADING.exec(line.text)
+
+    if (heading) {
+      if (draft) items.push(seal(draft))
+      draft = {
+        label: heading[1].toLowerCase(),
+        title: heading[2].trim(),
+        line: line.number,
+        answerLine: undefined,
+        answer: undefined,
+        open: undefined,
+        suggested: undefined,
+        worth: undefined,
+      }
+      continue
+    }
+
+    if (!draft) continue
+
+    if (SECTION.test(line.text)) {
+      items.push(seal(draft))
+      draft = undefined
+      continue
+    }
+
+    const field = FIELD.exec(line.text)
+    if (!field) continue
+
+    const value = field[2].trim()
+
+    switch (field[1].trim().toLowerCase()) {
+      case 'you':
+        draft.answerLine = line.number
+        draft.answer = value === '' ? undefined : value
+        break
+      case 'open':
+        draft.open = value
+        break
+      case 'suggested':
+        draft.suggested = value
+        break
+      case 'worth it':
+        draft.worth = value
+        break
+    }
+  }
+
+  if (draft) items.push(seal(draft))
+
+  return items
+}
+
+/**
+ * Puts a selection in one item's slot, leaving every other line as it was.
+ *
+ * The rewrite replaces the whole line rather than patching inside it, which is
+ * the reason this is a verb at all. A stream editor expands an unescaped
+ * ampersand in the replacement to the whole match and exits zero on a
+ * non-match, so an answer carrying one would rewrite the line it anchored to
+ * and a missed slot would report success with the answer lost.
+ *
+ * The answer occupies one line, and the caller owes that guarantee. A line
+ * break splices a bare continuation into the item matching none of the patterns
+ * the reader tests, so the slot reads back as the text before the break while
+ * the item counts as answered, which puts correcting it behind the refusal on
+ * an item that already carries one.
+ */
+export function writeAnswerLine(
+  text: string,
+  answerLine: number,
+  answer: string,
+): string {
+  const lines = text.split('\n')
+  lines[answerLine - 1] = `- **You:** ${answer}`
+  return lines.join('\n')
+}
+
+/** An item nobody has reached, which is an empty slot rather than a missing one. */
+export function isUnread(item: IntakeItem): boolean {
+  return item.answerLine !== undefined && item.answer === undefined
+}
+
+/**
+ * An item carrying no slot at all, which the format says ships on every one.
+ *
+ * Such an item is neither unread nor answered, and counting it as either hides
+ * it: as answered it drops out of the work a reader is told remains, and as
+ * unread it joins a list whose every entry the answer verb then refuses. It is
+ * reported on its own so the file gets fixed.
+ */
+export function isMalformed(item: IntakeItem): boolean {
+  return item.answerLine === undefined
+}

package/standards/intake.md

@@ -89,6 +89,7 @@ Where an item touches a task already on the board, say so in the index rather th
 ```
 
 - `Problem:`, `Fix:`, `Worth it:`, and the empty `You:` slot ship on every item. The other two are conditional.
+- Number items per cluster file, and give a finding split after the fact a letter suffix on the number it came from, as in `3a` beside `3`. Renumbering the items below it instead moves every label a reader or an answer already cited.
 - `Suggested:` is required whenever `Open:` is present. A bare question invites a bare answer, and `ok` against two defensible options carries no information. Where the answer is the operator's preference rather than a technical call, say so in that form rather than inventing a default.
 - `Overlaps:` never replaces `Worth it:`. The items where a live board task might be the thing that is wrong are exactly the ones whose verdict matters most.
 
@@ -106,10 +107,18 @@ That inverts the plan file's contract, where a blank answer slot means accept th
 
 Never fill a `You:` slot, and never infer a disposition from an empty one. On a resume pass, report unread items by count rather than deciding them.
 
+A slot is filled two ways. The operator types into the cluster file, or answers in chat and a verb lands the selection on the item. Both put the answer on the item, which is what keeps retrieval working, and neither lets a session decide one. An answer given in conversation and never written back leaves the item unread, since the file rather than the conversation is the record.
+
+An item already carrying an answer is refused rather than overwritten, whichever route the second answer arrives by. A filled slot is a decision already made, and revising one is the operator editing their own line.
+
 ## Retrieval
 
 Answers live on items, so one pass over the folder reports every touched slot.
 
+A session with the toolkit CLI on PATH reads the folder through `aitk intake list`, which reports per-folder counts bare and one folder's items with `--json`, and takes `--unread` to keep only the empty slots. It is the surface under test, and it skips the index and every fenced sample, which the greps below cannot do.
+
+The greps stay for a reader without the CLI, and they overcount by whatever the folder displays in a fence.
+
 ```bash
 awk '/^### /{h=FILENAME": "$0} /^- \*\*You:\*\*./{print h; print "   "$0}' *.md
 ```

package/standards/skill.md

@@ -208,7 +208,7 @@ Without this skill, a session <observed failure>, <observed failure>.
 
 ### Output and tuning
 
-- Skill success lines emit the full relative path from the project root (`<dir>/<file>`) for any file written, updated, or deleted. Bare filenames are not clickable in the terminal.
+- Skill success lines emit the full relative path from the project root (`<dir>/<file>`) for any file written, updated, or deleted. A bare filename names a file the reader cannot open. The `## Output` section of the project's instruction file sets the form that path takes, so a skill body states which path is emitted and leaves the form to that section.
 - Codify a skill's posted or generated output as a fenced template, and keep the body consistent with every capability the frontmatter description names.
 - When a skill gathers user input or pre-seeds a template, attach a concrete proposed default to every question, derived from project context. Accept "use defaults" as a bulk-confirm.
 - Separate correctness axes (routing, sourcing, escalation, decline) from shape axes (line count, formatting, variant sprawl) when tuning a skill. Tighten only on correctness regressions. Do not convert soft caps to hard caps for aesthetic drift when correctness passes.