@erclx/aitk 3.6.0 → 3.7.0

package/docs/ai-workflow.md

@@ -71,7 +71,7 @@ When features are independent, run them in parallel instead of sequentially. Use
 
 - Create a worktree per feature, then start a Claude Code session in each
 - Invoke `aitk:claude-feature` in each session. Plans land at the main worktree root as `.claude/plans/feature-<slug>.md`, one per feature, no collisions. Small features stay in chat and skip the file.
-- Implement, verify, and review each feature independently. `claude-review` and `claude-ui-test` write per-branch files at the main worktree root (`review-<slug>.md`, `ui-checklist-<slug>.md`), so parallel sessions do not overwrite each other. The slug is the branch name with any leading type segment dropped, so `feat/jwt-expiration` and the plan at `feature-jwt-expiration.md` meet on one name
+- Implement, verify, and review each feature independently. `claude-review` and `claude-ui-test` write per-branch files at the main worktree root (`review/branch/review-<slug>.md`, `review/ui-checklist-<slug>.md`), so parallel sessions do not overwrite each other. The slug is the branch name with any leading type segment dropped, so `feat/jwt-expiration` and the plan at `feature-jwt-expiration.md` meet on one name
 - Ship each worktree separately with `aitk:git-ship`
 - For full autonomy per worktree, invoke `aitk:claude-autoship` instead of the manual chain. Approve the plan, walk away, come back to draft PRs.
 
@@ -93,15 +93,17 @@ An execution that picks other than the suggestion rewrites the `- Suggested:` li
 
 `aitk records validate plans` reports where a plan and that standard disagree: a filename that is not `feature-<slug>.md`, a missing required section, a files-to-touch entry naming no file, and a question carrying a suggestion with no answer slot. The same verb takes `groundwork`, `intake`, `memory`, and `teach`, which are governed the same way and were unreachable for the same reason. Nothing fires it automatically, because all five folders are gitignored and every check the repository runs reads changed files from git. It reports and never writes, since the folders are per-machine scratch with no history to recover a wrong repair from.
 
-`aitk records push` carries these folders off the disk they live on, and `aitk records pull` brings them back. Ten of them are backed: `groundwork`, `intake`, `memory`, `plans`, `plans-archive`, `review`, `review-archive`, `task-archive`, `tasks`, and `teach`. The history lives in a second git directory at `.claude/.records.git` with `.claude/` as its work tree, so every path a task file cites stays where it is.
+`aitk records push` carries these folders off the disk they live on, and `aitk records pull` brings them back. Seven of them are backed: `groundwork`, `intake`, `memory`, `plans`, `review`, `tasks`, and `teach`, each carrying whatever it has archived inside it. The history lives in a second git directory at `.claude/.records.git` with `.claude/` as its work tree, so every path a task file cites stays where it is.
 
 A person points it at a private repository once and both verbs refuse until they have, and `push` refuses when that origin is also a remote of the project, since the payload is the memory pen and the groundwork trails. `.husky/post-merge` runs the push after its archive loop, on every merge rather than only on one that closed a task. See [records](agents/records.md) for the refusal table.
 
 `aitk records size` reports what each of these folders holds, heaviest first, along with `.claude/.tmp`. Each row carries the file count, the bytes, how many files were written in the last 7 and 30 days, and the dates of the least and most recently written one. Nothing fails on a number, because a record folder has no correct size. What the verb replaces is a reading somebody had to remember to take: the memory pen went from 44 entries to 236 between two counts made by hand a fortnight apart, and nothing reported the rate in between.
 
-A plan that ships is archived, never deleted. `aitk:claude-docs` moves it to `.claude/plans-archive/` and retargets the task file's `Plan:` line at the new location, so a completed task still leads to the reasoning behind it. Both folders are gitignored, which is why a deleted plan had no recovery path. A plan cited by more than one task stays put until the last of them closes, since moving it early would strand every other pointer.
+A plan that ships is archived, never deleted. `aitk:claude-docs` moves it to `.claude/plans/archive/` and retargets the task file's `Plan:` line at the new location, so a completed task still leads to the reasoning behind it. An archive sits inside the record folder it archives rather than beside it, so one ignore entry and one backed-folder entry cover a record and everything it has retired. The folder is gitignored, which is why a deleted plan had no recovery path. A plan cited by more than one task stays put until the last of them closes, since moving it early would strand every other pointer.
 
-The sweep reads the whole board rather than the tasks the session touched. It is the one place the skill reaches past its own rule against editing a task file the session did not change, because a task that closed while an earlier run missed its archive is exactly what the sweep exists to clear. Reaching it is safe: the archive moves the plan and retargets the pointer in the same pass, so an untouched task ends up with a working link rather than a broken one.
+A branch review report takes the other route and is swept rather than archived. `claude-review` writes it to `.claude/review/branch/`, the session addressing it reads it once, and the durable record of what a review found is the comment `claude-pr-review` posts on the pull request, so `claude-docs` deletes the report at ship and any report whose branch is gone. What that loses is a local-only review on a branch that never opened a pull request, which is why the report says so where a reader meets it.
+
+The plans sweep reads the whole board rather than the tasks the session touched. It is the one place the skill reaches past its own rule against editing a task file the session did not change, because a task that closed while an earlier run missed its archive is exactly what the sweep exists to clear. Reaching it is safe: the archive moves the plan and retargets the pointer in the same pass, so an untouched task ends up with a working link rather than a broken one.
 
 `aitk:claude-docs` decides which task closed by reading the diff rather than the conversation. It resolves a merge base against `origin/main`, unions the committed diff with the working tree and untracked files, then matches unchecked outcomes on the board against what shipped. A task that shipped without ever being discussed still gets marked. Requirements, architecture, and design stay session-sourced, because a diff cannot carry a judgment.
 
@@ -111,7 +113,7 @@ The sweep reads the whole board rather than the tasks the session touched. It is
 
 `aitk tasks validate` checks what those rows claim against what the tree holds: every plan pointer resolves, every task file is named by a board row or a backlog line and never by both, no task sits in two groups, and no two rows marked ready touch the same file. One check across both surfaces is what lets a task move between the board and the backlog without the move reading as a dropped file. That fourth check is the half a reader cannot run by eye, and it is what keeps two workers from being handed colliding work. A fifth re-takes what a parked row waits on, reporting one whose cited task reached the trunk and one whose cited file nothing running still holds. A cited task settles the row by being archived, or by closing every outcome and naming a pull request the trunk carries, since the checkbox alone is marked while the branch is still in review. Both halves read a citation out of the blocker cell, so a row citing neither is reported as untested rather than counted clean, and so is a cited task the trunk could not answer for. It reports and never writes, because a row is the orchestrator's claim and a validator repairing one would assert the claim it exists to test. Nothing fires it automatically, since the board is gitignored per-machine scratch with no shared moment to hang a hook on, so the orchestrator's sweep calls it at the point the readiness claim is made and follows it with the parked re-test.
 
-`aitk:claude-tasks` owns the two operations that bracket a task's life. It creates the file, holding the filename convention and the frontmatter contract so a malformed write cannot break the index for every sibling, and it moves a shipped task to `.claude/task-archive/`. Creation is where the origin invariant is enforced: every task names a plan, a groundwork folder, an intake folder, or an issue, since a task with no origin is either lost context or work nobody decided to do.
+`aitk:claude-tasks` owns the two operations that bracket a task's life. It creates the file, holding the filename convention and the frontmatter contract so a malformed write cannot break the index for every sibling, and it moves a shipped task to `.claude/tasks/archive/`. Creation is where the origin invariant is enforced: every task names a plan, a groundwork folder, an intake folder, or an issue, since a task with no origin is either lost context or work nobody decided to do.
 
 Archiving a task leaves its plan alone, because `aitk:claude-docs` owns the plans sweep and already holds the last-live-citation rule. That makes the order load-bearing, so the archive verb refuses the last task pointing at a live plan. The sweep only reaches tasks still in the live folder, and archiving that task first would strand the plan there with nothing citing it. A task whose plan a sibling still cites archives freely, because the sweep is correct to leave that plan where it is and a gate reading the folder instead would park every task sharing one plan behind a sweep that will never move it.
 

package/docs/operating-model.md

@@ -101,13 +101,22 @@ closed clean and then went stale still rebases when the skill is invoked. The
 re-read costs a full pass rather than a delta, since the prior reviewed commit no
 longer reaches the head, and `claude-pr-review` detects that itself.
 
-The heading carries the state rather than the pass number. A pass carrying a
-finding at any severity takes `## Review` and a pass carrying nothing takes
+The heading carries the state rather than the pass number. A pass carrying
+anything owed takes `## Review` and a pass carrying nothing takes
 `## Review closed`, so a thread can be scanned for what still owes work without
 opening a comment. One threshold governs the heading and the dispatch alike, and
 `claude-pr-review` is where it is stated, so every other surface cites that skill
-rather than restating the grades. The merge decision comes off the counts on the
-summary line, since an open heading now covers a minor as well as a critical.
+rather than restating the grades.
+
+The merge decision comes off the counts on the summary line, since an open
+heading now covers a minor as well as a critical. One thing the pass posts sits
+outside those counts and inside the threshold anyway. It reads the description's
+Testing section against what the repository can drive, and asks about a box left
+unchecked for a person where a harness already covers the run. The question
+takes no severity, because whether a human is required is a judgment the author
+may hold a reason for, and it still opens the heading and sends the dispatch,
+because the author is the only party who can answer it.
+
 A minor the worker declines goes to the findings of the task the
 branch closes, since a thread does not survive the merge. The feedback
 becomes a durable artifact both sessions read, survives a session ending, and

package/governance/rules/claude/558-plan.md

@@ -2,7 +2,6 @@
 description: Route .claude/plans/ edits to the plan standard for sections, the answer contract, and the archive move
 paths:
   - '.claude/plans/**'
-  - '.claude/plans-archive/**'
 ---
 
 # Plan standards
@@ -15,7 +14,7 @@ paths:
 
 ## Archiving
 
-- Move a shipped plan to `.claude/plans-archive/`. Never delete one.
+- Move a shipped plan to `.claude/plans/archive/`. Never delete one.
 - Amend a plan in place when a decision changes. Do not append a second passage narrating the change.
 
 ## Authority

package/governance/rules/lib/300-testing-ts.md

@@ -22,6 +22,7 @@ paths:
 - Use Playwright for end-to-end tests.
 - Place all Playwright tests within the `e2e/` directory.
 - Never place Playwright tests inside `src/`.
+- Scope the three rules above to tests the Playwright runner executes. A Vitest test importing a browser driver to exercise project code stays beside its module, where Vitest looks for it.
 
 ## Timers and async
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {
@@ -46,6 +46,7 @@
   "dependencies": {
     "commander": "^13.1.0",
     "execa": "^9.5.2",
+    "playwright-core": "1.59.1",
     "pptxgenjs": "^4.0.1"
   },
   "devDependencies": {
@@ -53,7 +54,7 @@
     "@astrojs/react": "^5.0.4",
     "@commitlint/cli": "^20.4.1",
     "@commitlint/config-conventional": "^20.4.1",
-    "@playwright/test": "^1.59.1",
+    "@playwright/test": "1.59.1",
     "@tailwindcss/vite": "^4.2.4",
     "@testing-library/jest-dom": "^6.9.1",
     "@types/bun": "^1.2.10",

package/src/cli.ts

@@ -15,6 +15,7 @@ import { register as docs } from '@/commands/docs'
 import { register as design } from '@/commands/design'
 import { register as slides } from '@/commands/slides'
 import { register as capture } from '@/commands/capture'
+import { register as demo } from '@/commands/demo'
 import { register as feedback } from '@/commands/feedback'
 import { register as transcripts } from '@/commands/transcripts'
 import { register as tasks } from '@/commands/tasks'
@@ -56,7 +57,8 @@ function showHelp(): void {
     `${GREY}│${NC}    design [cmd]       ${GREY}# Design system commands (render)${NC}`,
     `${GREY}│${NC}    slides [cmd]       ${GREY}# Slide deck commands (render, list)${NC}`,
     `${GREY}│${NC}    capture [source]   ${GREY}# Render HTML capture sources to PNG${NC}`,
-    `${GREY}│${NC}    feedback           ${GREY}# Write toolkit feedback from stdin to .claude/review/${NC}`,
+    `${GREY}│${NC}    demo [cmd]         ${GREY}# Record a running app (compile, run)${NC}`,
+    `${GREY}│${NC}    feedback           ${GREY}# Write toolkit feedback from stdin to .claude/review/feedback/${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}`,
@@ -147,6 +149,7 @@ docs(program)
 design(program)
 slides(program)
 capture(program)
+demo(program)
 feedback(program)
 transcripts(program)
 tasks(program)

package/src/commands/demo.ts

@@ -0,0 +1,373 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { basename, dirname, extname, join, relative, resolve } from 'node:path'
+import type { Command } from 'commander'
+import { parseDraft } from '@/demo/beats'
+import { compilePlan, parsePlan, unresolved } from '@/demo/compile'
+import { DEFAULT_CURSORS } from '@/demo/cursors'
+import { loadCursorTheme } from '@/demo/theme'
+import { intro, logError, logInfo, logStep, logWarn, outro, plural } from '@/ui'
+
+const DEFAULT_OUT = 'demos'
+const INSTALL_BROWSER = 'bunx playwright install chromium'
+
+/**
+ * Holds wiring only. Every browser reference sits behind `loadDriver`, because
+ * `src/cli.ts` imports this module at startup and resolving the engine there
+ * would put a browser launch in front of every other command.
+ */
+type Driver = typeof import('@/demo/drive')
+
+interface CompileOptions {
+  readonly out: string
+  readonly slug?: string
+  readonly force?: boolean
+  readonly json?: boolean
+}
+
+interface RunOptions {
+  readonly out?: string
+  readonly cursor?: string
+  readonly video: boolean
+  readonly still: boolean
+  readonly json?: boolean
+}
+
+export function register(program: Command): void {
+  const demo = program
+    .command('demo')
+    .description('Drive a running application and record what it did')
+    .helpOption('-h, --help', 'Show this help message')
+
+  demo
+    .command('compile')
+    .description('Turn a screencast draft into a plan a run can drive')
+    .argument('<draft>', 'Screencast draft written by claude-screencast')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('-o, --out <dir>', 'Directory the plan is written to', DEFAULT_OUT)
+    .option('-s, --slug <slug>', 'Plan name, defaulting to the draft filename')
+    .option('--force', 'Overwrite a plan that already exists')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'The plan is committed rather than scratch. It carries the target, the',
+        'wait condition, and the timing a beat lacks, and the timing is a',
+        'starting point you tune, which is why a recompile refuses to overwrite.',
+        '',
+        'Exit codes:',
+        '  0  a plan was written',
+        '  1  refused, with the reason on stderr',
+        '',
+        'Examples:',
+        '  aitk demo compile .claude/.tmp/screencast/inline-edit.md',
+        '  aitk demo compile draft.md --out demos --force',
+        '',
+      ].join('\n'),
+    )
+    .action(async (draft: string, opts: CompileOptions) => {
+      process.exitCode = runCompile(draft, opts)
+    })
+
+  demo
+    .command('run')
+    .description('Drive the application a plan names and write the recording')
+    .argument('<plan>', 'Plan written by aitk demo compile')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('-o, --out <dir>', 'Directory to write into, overriding the plan')
+    .option(
+      '-c, --cursor <dir>',
+      'Cursor theme folder to draw the pointer from',
+    )
+    .option('--no-video', 'Skip the recording and write only the still')
+    .option('--no-still', 'Skip the still and write only the recording')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Needs a browser binary. Install it with:',
+        `  ${INSTALL_BROWSER}`,
+        '',
+        'Exit codes:',
+        '  0  the recording and the still were written',
+        '  1  refused, with the reason on stderr',
+        '',
+        'Examples:',
+        '  aitk demo run demos/inline-edit.json',
+        '  aitk demo run demos/inline-edit.json --cursor ~/cursors/theme',
+        '',
+      ].join('\n'),
+    )
+    .action(async (plan: string, opts: RunOptions) => {
+      process.exitCode = await runDrive(plan, opts)
+    })
+}
+
+function runCompile(draftPath: string, opts: CompileOptions): number {
+  intro('aitk demo compile')
+
+  const source = resolve(process.cwd(), draftPath)
+  if (!existsSync(source)) {
+    logStep('Draft')
+    logError(`${draftPath} not found`)
+    outro()
+    emit(opts.json, { draft: source, reason: 'draft-missing' })
+    return 1
+  }
+
+  const parsed = parseDraft(readFileSync(source, 'utf8'))
+  if (parsed.status === 'failed') {
+    logStep('Draft')
+    logError(`${display(source)}: ${parsed.reason}`)
+    outro()
+    emit(opts.json, {
+      draft: source,
+      reason: 'draft-unreadable',
+      message: parsed.reason,
+    })
+    return 1
+  }
+
+  const slug = opts.slug ?? basename(source, extname(source))
+  const target = resolve(process.cwd(), opts.out, `${slug}.json`)
+
+  if (existsSync(target) && !opts.force) {
+    logStep('Plan')
+    logError(`${display(target)} already exists`)
+    // Stated rather than implied, because the value at risk is timing the
+    // operator tuned by watching a recording and the draft cannot reproduce it.
+    logWarn('Pass --force to overwrite it, losing any timing tuned by hand.')
+    outro()
+    emit(opts.json, { plan: target, reason: 'plan-exists' })
+    return 1
+  }
+
+  const plan = compilePlan(parsed.draft, { slug, outDir: opts.out })
+  mkdirSync(dirname(target), { recursive: true })
+  writeFileSync(target, `${JSON.stringify(plan, null, 2)}\n`)
+
+  logStep('Draft')
+  logInfo(`${display(source)}  ${plural(parsed.draft.beats.length, 'beat')}`)
+
+  logStep('Plan')
+  logInfo(display(target))
+
+  const outstanding = unresolved(plan)
+  logStep('Outstanding')
+  if (outstanding.length === 0) {
+    logInfo('Nothing to fill, so the plan runs as written.')
+  } else {
+    logWarn(
+      `${plural(outstanding.length, 'field')} the draft could not supply:`,
+    )
+    for (const field of outstanding) logWarn(`  ${field}`)
+  }
+  outro()
+
+  emit(opts.json, {
+    draft: source,
+    plan: target,
+    beats: parsed.draft.beats.length,
+    unresolved: outstanding,
+  })
+  return 0
+}
+
+async function runDrive(planPath: string, opts: RunOptions): Promise<number> {
+  intro('aitk demo run')
+
+  const source = resolve(process.cwd(), planPath)
+  if (!existsSync(source)) {
+    logStep('Plan')
+    logError(`${planPath} not found`)
+    outro()
+    emit(opts.json, { plan: source, reason: 'plan-missing' })
+    return 1
+  }
+
+  const parsed = parsePlan(readFileSync(source, 'utf8'))
+  if (parsed.status === 'failed') {
+    logStep('Plan')
+    logError(`${display(source)}: ${parsed.reason}`)
+    outro()
+    emit(opts.json, {
+      plan: source,
+      reason: 'plan-unreadable',
+      message: parsed.reason,
+    })
+    return 1
+  }
+
+  if (!opts.video && !opts.still) {
+    logStep('Output')
+    logError('--no-video and --no-still together leave nothing to write')
+    outro()
+    emit(opts.json, { plan: source, reason: 'no-output-requested' })
+    return 1
+  }
+
+  const outstanding = unresolved(parsed.plan)
+  if (outstanding.length) {
+    logStep('Plan')
+    logError(
+      `${display(source)} has ${plural(outstanding.length, 'field')} to fill`,
+    )
+    for (const field of outstanding) logWarn(`  ${field}`)
+    outro()
+    emit(opts.json, {
+      plan: source,
+      reason: 'plan-unresolved',
+      unresolved: outstanding,
+    })
+    return 1
+  }
+
+  logStep('Plan')
+  logInfo(`${display(source)}  ${plural(parsed.plan.steps.length, 'step')}`)
+
+  const cursors = resolveCursors(opts.cursor)
+  if (cursors.status === 'failed') {
+    logError(cursors.reason)
+    outro()
+    emit(opts.json, { plan: source, reason: 'cursor-unreadable' })
+    return 1
+  }
+  logInfo(cursors.label)
+
+  const driver = await loadDriver()
+  if (!driver) {
+    logStep('Browser')
+    logError('the browser engine is not installed in this project')
+    logWarn(`Install it with: ${INSTALL_BROWSER}`)
+    outro()
+    emit(opts.json, {
+      plan: source,
+      reason: 'engine-missing',
+      install: INSTALL_BROWSER,
+    })
+    return 1
+  }
+
+  logStep('Recording')
+  const result = await driver.drive({
+    plan: parsed.plan,
+    cursors: cursors.value,
+    ...(opts.video
+      ? { videoPath: outputPath(parsed.plan.output.video, opts.out) }
+      : {}),
+    ...(opts.still
+      ? { stillPath: outputPath(parsed.plan.output.still, opts.out) }
+      : {}),
+  })
+
+  if (result.status === 'failed') {
+    logError(result.message.split('\n')[0] ?? 'the run failed')
+    if (result.reason === 'browser-missing') {
+      logWarn(`Install the browser binary with: ${INSTALL_BROWSER}`)
+    }
+    outro()
+    emit(opts.json, {
+      plan: source,
+      reason: result.reason,
+      message: result.message,
+      ...(result.reason === 'browser-missing'
+        ? { install: INSTALL_BROWSER }
+        : {}),
+    })
+    return 1
+  }
+
+  if (result.videoPath) logInfo(display(result.videoPath))
+  if (result.stillPath) logInfo(`${display(result.stillPath)}  still`)
+  logInfo(
+    `${result.steps} steps in ${Math.round(result.durationMs / 100) / 10}s`,
+  )
+  outro()
+
+  emit(opts.json, {
+    plan: source,
+    video: result.videoPath ?? null,
+    still: result.stillPath ?? null,
+    steps: result.steps,
+    durationMs: result.durationMs,
+  })
+  return 0
+}
+
+type CursorChoice =
+  | { status: 'ready'; value: typeof DEFAULT_CURSORS; label: string }
+  | { status: 'failed'; reason: string }
+
+/**
+ * A theme contributes per state rather than per folder, so a folder carrying an
+ * arrow and no hand still supplies its arrow and the bundled artwork covers the
+ * rest.
+ */
+function resolveCursors(dir: string | undefined): CursorChoice {
+  if (!dir) {
+    return {
+      status: 'ready',
+      value: DEFAULT_CURSORS,
+      label: 'pointer drawn from the bundled artwork',
+    }
+  }
+
+  const loaded = loadCursorTheme(resolve(process.cwd(), dir), DEFAULT_CURSORS)
+  if (loaded.status === 'failed')
+    return { status: 'failed', reason: loaded.reason }
+
+  return {
+    status: 'ready',
+    value: loaded.cursors,
+    label: `pointer drawn from ${display(resolve(process.cwd(), dir))} for ${loaded.states.join(', ')}`,
+  }
+}
+
+/**
+ * Reports absence only when the module or its engine cannot be resolved, which
+ * is the case a target hits before installing the browser package. Any other
+ * import failure is a defect inside the driver and propagates, rather than
+ * being reported as a missing dependency.
+ */
+async function loadDriver(): Promise<Driver | undefined> {
+  try {
+    return await import('@/demo/drive')
+  } catch (error) {
+    if (isModuleNotFound(error)) return undefined
+    throw error
+  }
+}
+
+function isModuleNotFound(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    error.code === 'ERR_MODULE_NOT_FOUND'
+  )
+}
+
+/**
+ * Resolves where one artifact lands. `--out` replaces the directory the plan
+ * names rather than acting as a root the plan's own directory hangs off, which
+ * would nest the output path inside itself on every run that passes both.
+ */
+function outputPath(planned: string, out: string | undefined): string {
+  const relativePath = out ? join(out, basename(planned)) : planned
+  return resolve(process.cwd(), relativePath)
+}
+
+function emit(json: boolean | undefined, record: unknown): void {
+  if (json) process.stdout.write(`${JSON.stringify(record)}\n`)
+}
+
+/**
+ * Keeps a path clickable in the operator's terminal. A path outside the project
+ * reports absolute, since a relative path to it is a run of `..` segments no
+ * editor resolves.
+ */
+function display(path: string): string {
+  const fromCwd = relative(process.cwd(), path)
+  return fromCwd.startsWith('..') ? path : fromCwd
+}

package/src/commands/feedback.ts

@@ -32,13 +32,20 @@ function isToolkitSource(): boolean {
   return existsSync(join(PROJECT_ROOT, '.claude'))
 }
 
+/**
+ * One producer, one subfolder. The review folder carries the output of four
+ * unrelated producers, and the filename prefix was doing the folder's job by
+ * hand, so each writes under its own name and the enclosing folder keeps the
+ * single ignore entry and the single backed-folder entry it already had.
+ */
 function writeLocal(body: string): string {
-  const reviewDir = join(PROJECT_ROOT, '.claude', 'review')
+  const relativeDir = join('.claude', 'review', 'feedback')
+  const reviewDir = join(PROJECT_ROOT, relativeDir)
   mkdirSync(reviewDir, { recursive: true })
   const filename = `feedback-${deriveSlug(body)}-${timestamp()}.md`
   const filePath = join(reviewDir, filename)
   writeFileSync(filePath, `${body}\n`, 'utf8')
-  frameSuccess('aitk feedback', `.claude/review/${filename}`)
+  frameSuccess('aitk feedback', join(relativeDir, filename))
   return filePath
 }
 
@@ -46,7 +53,7 @@ export function register(program: Command): void {
   program
     .command('feedback')
     .description(
-      'Write toolkit feedback from stdin to .claude/review/, or open a GitHub issue with --github',
+      'Write toolkit feedback from stdin to .claude/review/feedback/, or open a GitHub issue with --github',
     )
     .option(
       '--github',

package/src/commands/tasks.ts

@@ -151,7 +151,7 @@ export function register(program: Command): void {
         'Locations:',
         '  unstated  the task carries no Plan: line',
         '  live      the target resolves inside .claude/plans/',
-        '  archived  the target resolves inside .claude/plans-archive/',
+        '  archived  the target resolves inside .claude/plans/archive/',
         '  outside   the target resolves somewhere else',
         '',
         'Exit codes:',