@erclx/canon 5.9.0 → 5.11.0

package/src/claude/cases/misc.ts

@@ -69,6 +69,11 @@ export const MISC_CASES: readonly SkillCase[] = [
       "The e2e folder has specs and helpers mixed together and I'm adding two more, where should they go?",
     expect: 'codebase-layout',
   },
+  {
+    prompt:
+      "I'm adding a field to the JSON this command prints and renaming one flag, anything to watch?",
+    expect: 'api-design',
+  },
   {
     prompt: 'Does our github about text still match what the readme says?',
     expect: 'repo-metadata',

package/src/claude/skills-audit.ts

@@ -35,6 +35,8 @@ export const PRACTICE_SKILLS: readonly string[] = [
   join(SHIPPED_CORPUS, 'codebase-layout'),
   join(SHIPPED_CORPUS, 'test-craft'),
   join(SHIPPED_CORPUS, 'review-craft'),
+  join(SHIPPED_CORPUS, 'systematic-debugging'),
+  join(SHIPPED_CORPUS, 'api-design'),
 ]
 
 /** The closing H2s a practice skill carries, matched exactly outside fences. */

package/src/commands/gate.ts

@@ -5,7 +5,6 @@ import {
   commandRunner,
   exitCodeFor,
   type GateContext,
-  repairBareFlag,
   type StageResult,
   type Summary,
   runStages,
@@ -24,6 +23,7 @@ import {
   pipeOutput,
   plural,
 } from '@/ui'
+import { repairBareFlag } from '@/worktrees/bare-flag'
 
 interface RunCommandOptions {
   readonly all?: boolean
@@ -97,7 +97,8 @@ async function runGate(opts: RunCommandOptions): Promise<number> {
 
   if (!emitJson && !nested) intro('canon gate run')
 
-  await repairBareFlag(root)
+  const repair = await repairBareFlag(root)
+  if (repair.message !== null) logWarn(repair.message)
 
   const changed = opts.all
     ? { scoped: false, files: [] }

package/src/commands/pr.ts

@@ -32,6 +32,8 @@ import {
   findEvidenceLocal,
   findEvidencePreview,
   groupEvidence,
+  hasMarkedEvidenceComment,
+  readOwed,
   renderEvidenceBody,
 } from '@/pr/evidence'
 import { type HeadRefusal, resolveHead, resolveTip } from '@/pr/head'
@@ -88,6 +90,7 @@ interface EvidenceOptions extends ReadOptions {
   readonly preview?: string
   readonly checklist?: string
   readonly local?: string
+  readonly check?: boolean
 }
 
 interface LocalOptions extends ReadOptions {
@@ -172,6 +175,7 @@ const PULL_REFUSALS: Record<PullRefusal | HeadRefusal, string> = {
  * one `identity.head` owns (`no-object-head`).
  */
 type EvidenceRefusal =
+  | 'check-writes'
   | 'gh-failed'
   | 'no-base'
   | 'unreadable-changes'
@@ -179,6 +183,8 @@ type EvidenceRefusal =
   | 'would-empty'
 
 const EVIDENCE_REFUSALS: Record<EvidenceRefusal, string> = {
+  'check-writes':
+    '--check is a read and renders no body, so it takes none of --preview, --local, or --checklist. Run the check and the render as two calls.',
   'gh-failed':
     'gh could not answer for this repository. Name the pull request number.',
   'unreadable-checklist':
@@ -425,6 +431,10 @@ export function register(program: Command): void {
       '--local <url>',
       "Add this worktree's running server under any preview line, from canon pr local",
     )
+    .option(
+      '--check',
+      'Report which post-pull-request steps the thread is still owed, rendering nothing',
+    )
     .addHelpText(
       'after',
       [
@@ -478,8 +488,19 @@ export function register(program: Command): void {
         'record reports none of the three for it. An unread thread refuses as',
         'gh-failed on both reasons rather than reporting the fields absent.',
         '',
+        '--check reads the same changed set and thread, renders no body, and',
+        'reports what the ship chain still owes the pull request:',
+        '  settled  nothing is owed',
+        '  owed     `owed` lists evidence, preview, or both, in that order',
+        'evidence is owed when an evidence image changed and no comment carries',
+        'the marker. preview is owed when either holds, a deploy workflow in',
+        "this checkout resolves, and the marked comment's first line is no",
+        '**Preview:** line. A failed deploy reads the same as a skipped one.',
+        'The record carries `owed` and the same marked fields. --check refuses',
+        'with --preview, --local, or --checklist as check-writes.',
+        '',
         'Exit codes:',
-        '  0  read, whether it produced a body or reported no-evidence',
+        '  0  read, whether it produced a body, reported no-evidence, or checked',
         '  1  refused, with the reason on stderr or in the JSON record',
         '',
         'Examples:',
@@ -488,6 +509,7 @@ export function register(program: Command): void {
         '  canon pr evidence 1341 --preview https://feat-x.site.pages.dev --json',
         '  canon pr evidence 1341 --checklist .canon/tmp/handoff/ui-checklist/x.md --json',
         '  canon pr evidence 1341 --local http://localhost:5173 --json',
+        '  canon pr evidence 1341 --check --json',
         '',
       ].join('\n'),
     )
@@ -1368,7 +1390,7 @@ async function listPullFiles(
     '--paginate',
     `repos/{owner}/{repo}/pulls/${number}/files`,
     '--jq',
-    '.[] | "\(.status)\t\(.filename)"',
+    '.[] | [.status, .filename] | @tsv',
   ])
   if (stdout === null) return undefined
   const files = new Map<string, boolean>()
@@ -1417,9 +1439,24 @@ async function runEvidence(
 ): Promise<number> {
   const root = resolve(opts.root ?? process.cwd())
   const emitJson = opts.json ?? false
+  const isCheck = opts.check ?? false
 
   intro('canon pr evidence')
 
+  if (
+    isCheck &&
+    (opts.preview !== undefined ||
+      opts.local !== undefined ||
+      opts.checklist !== undefined)
+  ) {
+    return refuseWith(
+      'check-writes',
+      EVIDENCE_REFUSALS['check-writes'],
+      emitJson,
+      root,
+    )
+  }
+
   // Read ahead of anything else, so a bad path refuses before a `gh` round
   // trip rather than after one.
   let suppliedChecklist: string | undefined
@@ -1461,9 +1498,13 @@ async function runEvidence(
     )
   }
 
+  // The check never reads the merge base, so it skips the compare call and
+  // a failed one cannot hold a draft lift for a reason the check never had.
   const [pullFiles, base] = await Promise.all([
     listPullFiles(root, identity.number),
-    readPullMergeBase(root, identity.number, identity.head),
+    isCheck
+      ? undefined
+      : readPullMergeBase(root, identity.number, identity.head),
   ])
   if (pullFiles === undefined) {
     return refuseWith(
@@ -1473,9 +1514,6 @@ async function runEvidence(
       root,
     )
   }
-  if (base === undefined) {
-    return refuseWith('no-base', EVIDENCE_REFUSALS['no-base'], emitJson, root)
-  }
 
   const grouped = await groupEvidence(
     [...pullFiles.keys()],
@@ -1533,6 +1571,40 @@ async function runEvidence(
     ...(carriedChecklist !== undefined && { checklist: carriedChecklist }),
   }
 
+  if (isCheck) {
+    const owed = readOwed({
+      hasEvidenceChange: grouped.kind === 'read',
+      hasMarkedComment: hasMarkedEvidenceComment(comments),
+      carriedPreview: carriedPreview !== undefined,
+      deployWorkflowFound:
+        findDeployWorkflow(await readWorkflows(root)).kind === 'found',
+    })
+    logStep(owed.length === 0 ? 'Settled' : 'Owed')
+    logInfo(
+      owed.length === 0
+        ? 'Nothing the ship chain posts after the pull request is missing.'
+        : `missing ${owed.join(', ')}`,
+    )
+    outro()
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          number: identity.number,
+          reason: owed.length === 0 ? 'settled' : 'owed',
+          owed,
+          ...(commentId !== undefined && { commentId }),
+          ...carried,
+        })}\n`,
+      )
+    }
+    return 0
+  }
+
+  if (base === undefined) {
+    return refuseWith('no-base', EVIDENCE_REFUSALS['no-base'], emitJson, root)
+  }
+
   // A local address rides on a checklist or a hosted preview and never opens
   // a comment alone, so a docs-only branch with a server up posts nothing.
   const hasChecklistAndLocal =

package/src/commands/tasks.ts

@@ -114,6 +114,7 @@ interface PullRequestCommandOptions {
 }
 
 interface PlanLinkCommandOptions {
+  readonly add?: boolean
   readonly json?: boolean
   readonly root?: string
 }
@@ -454,6 +455,10 @@ export function register(program: Command): void {
     .argument('<task>', 'Task filename stem, as in v28.1-trigger-escalation')
     .argument('<plan>', 'Plan path or its slug, as in dispatch-answer-gate')
     .helpOption('-h, --help', 'Show this help message')
+    .option(
+      '--add',
+      'Append the plan to the line, for a task sliced over plans',
+    )
     .option('--json', 'Emit a machine-readable record on stdout')
     .option('--root <path>', 'Board root, defaulting to the main worktree')
     .addHelpText(
@@ -461,7 +466,7 @@ export function register(program: Command): void {
       [
         '',
         'Exit codes:',
-        '  0  the line was added, corrected, or already correct',
+        '  0  the line was added, appended to, corrected, or already correct',
         '  1  refused, including several-plans for a line linking more than one',
         '     plan, with the reason on stderr or in the JSON record',
         '',
@@ -471,8 +476,13 @@ export function register(program: Command): void {
         'tasks plan-answers does. Safe from a linked worktree, since it',
         'resolves the board root in-process.',
         '',
+        'With --add it keeps every link in order and appends the plan, so a',
+        'sliced task links one plan per slice. It reports unchanged when the',
+        'plan is already listed and is allowed on a line holding several.',
+        '',
         'Examples:',
         '  canon tasks plan-link v28.1-trigger-escalation dispatch-answer-gate',
+        '  canon tasks plan-link v28.1-trigger-escalation second-slice --add',
         '  canon tasks plan-link v28.1-trigger-escalation .canon/plans/feature-dispatch-answer-gate.md --json',
         '',
       ].join('\n'),
@@ -725,7 +735,7 @@ async function runPlanLink(
 ): Promise<number> {
   const emitJson = opts.json ?? false
   const root = opts.root ?? (await mainWorktreeRoot())
-  const outcome = await recordPlan(root, task, plan)
+  const outcome = await recordPlan(root, task, plan, opts.add ?? false)
 
   return reportPlanLink(outcome, emitJson, root)
 }

package/src/commands/tooling.ts

@@ -34,7 +34,7 @@ import {
   select,
 } from '@/ui'
 
-const PASS_THROUGH_VERBS = ['create', 'verify'] as const
+const PASS_THROUGH_VERBS = ['verify'] as const
 
 interface SyncOptions {
   readonly skip?: string
@@ -71,7 +71,7 @@ type Prepared =
 export function register(program: Command): void {
   const tooling = program
     .command('tooling')
-    .description('Manage tooling stacks (sync, reference, create)')
+    .description('Manage tooling stacks (sync, reference)')
     .helpOption('-h, --help', 'Show this help message')
 
   tooling

package/src/commands/worktrees.ts

@@ -17,6 +17,7 @@ import {
   type WorktreeVerdict,
 } from '@/worktrees/reclaim'
 import { mainWorktreeRoot } from '@/worktree'
+import { repairBareFlag } from '@/worktrees/bare-flag'
 import {
   removeReclaimable,
   type RemovalOutcome,
@@ -27,6 +28,11 @@ interface ListCommandOptions {
   readonly json?: boolean
 }
 
+interface RepairBareFlagOptions {
+  readonly root?: string
+  readonly json?: boolean
+}
+
 interface ReclaimCommandOptions {
   readonly dryRun?: boolean
   readonly json?: boolean
@@ -208,6 +214,37 @@ export function register(program: Command): void {
     .action(async (opts: ReclaimCommandOptions) => {
       process.exitCode = await runReclaim(opts)
     })
+
+  worktrees
+    .command('repair-bare-flag', { hidden: true })
+    .description('Clear a core.bare flag that worktree entry left set')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Repository to repair', '.')
+    .option('--json', 'Print the record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  always, since the caller is a hook that must never fail a tool call',
+        '',
+        'Called by .claude/hooks/bare-flag-repair.sh, the one caller that is not',
+        'a person, so no help listing shows it. A repository whose common dir is',
+        'not named .git keeps its flag, since that is a genuinely bare one.',
+        '',
+        'Examples:',
+        '  canon worktrees repair-bare-flag --root . --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: RepairBareFlagOptions) => {
+      const record = await repairBareFlag(opts.root ?? '.')
+      if (opts.json === true) {
+        process.stdout.write(`${JSON.stringify(record)}\n`)
+      } else if (record.message !== null) {
+        logWarn(record.message)
+      }
+    })
 }
 
 /**

package/src/counts/catalogs.ts

@@ -25,14 +25,14 @@ const REGISTER_IMPORT = /^import \{ register as /gm
 /**
  * Every top-level `canon` command, read off the CLI entry point rather than a
  * catalog verb, because a command carries no `--json` listing of its own
- * siblings. `regen-hero.sh` reads its own `COMMAND_COUNT` through `gov counts`
+ * siblings. `regen-hero.ts` imports this reader for its `COMMAND_COUNT`
  * rather than a second regex on `src/cli.ts`, so this is the one place that
  * pattern is written.
  *
  * This is the one catalog with no meaning outside this repository, the way
- * `regen-hero.sh` documents itself as clone-only for the same reason.
+ * `regen-hero.ts` documents itself as clone-only for the same reason.
  */
-function countCommands(root: string): number | undefined {
+export function countCommands(root: string): number | undefined {
   const cli = join(root, 'src', 'cli.ts')
   if (!existsSync(cli)) return undefined
   return [...readFileSync(cli, 'utf8').matchAll(REGISTER_IMPORT)].length

package/src/design/tokens.ts

@@ -99,7 +99,7 @@ export const TOKENS: DesignTokens = {
     '',
     'The values below are the system rather than a reading of one. Until 2026-09-01 this record transcribed two surfaces and agreed with nothing else, which is what made a change to it reach nobody. The slide theme, the token preview, and a teach workspace stylesheet now read the module this file is rendered from, so a value changed there changes what all three render.',
     '',
-    'The two rendered captures read it as well. `scripts/core/regen-hero.sh` fills `assets/captures/hero.html.tmpl` and `assets/captures/install.html.tmpl` with what `canon design css --no-components` emits, so both frames now carry the custom properties rather than their own copies of the hex, and a value moved here moves what the next capture renders.',
+    'The two rendered captures read it as well. `scripts/core/regen-hero.ts` fills `assets/captures/hero.html.tmpl` and `assets/captures/install.html.tmpl` with what `canon design css --no-components` emits, so both frames now carry the custom properties rather than their own copies of the hex, and a value moved here moves what the next capture renders.',
     '',
     'The terminal framing is the one surface left holding its own values, and that is a decision rather than a gap. `scripts/lib/ui.sh` and `src/ui.ts` each spell six escape constants, and `canon/context/scripts/framing.md` records one color source per language with a check behind each, so generating a third spelling from here would break the rule those two checks enforce. What the record is still incomplete about is the other half of those six: `WHITE` and `GREY` name no role below, so the terminal palette is described here in part rather than in whole.',
   ].join('\n'),

package/src/gate/sequencer.ts

@@ -377,23 +377,3 @@ async function spawn(
     spawnError: code === 'ENOENT' ? `${file} is not on PATH` : undefined,
   }
 }
-
-/**
- * Repairs `core.bare`, which Claude Code's worktree entry leaves set in the
- * shared config and nothing restores.
- *
- * It runs ahead of every stage rather than as one of them, because the flag
- * breaks the git reads that scope the run. The rule itself stays in
- * `scripts/lib/worktree.sh`, which is the one bash function under test, so this
- * calls it rather than restating the guard that spares a genuinely bare
- * repository.
- */
-export async function repairBareFlag(root: string): Promise<void> {
-  await execa('bash', [join(root, 'scripts/core/repair-bare-flag.sh')], {
-    cwd: root,
-    reject: false,
-    stdio: 'inherit',
-    env: { ...gitEnv(), PROJECT_ROOT: root },
-    extendEnv: false,
-  })
-}

package/src/gate/stages.ts

@@ -99,7 +99,6 @@ export const TEST_CORPORA_PATTERNS = [
   '^standards/markdown\\.md$',
   '^tooling/base/reference\\.md$',
   '^tooling/web/configs/scripts/worktree-port\\.sh$',
-  '^scripts/lib/worktree\\.sh$',
   '^scripts/core/check-ignore-parity\\.sh$',
 ]
 
@@ -203,7 +202,7 @@ export const STAGES: readonly Stage[] = [
     checks: [
       {
         kind: 'command',
-        argv: ['bash', 'scripts/core/regen-hero.sh', '--check'],
+        argv: ['bun', 'scripts/core/regen-hero.ts', '--check'],
         failure: 'Hero regen health check failed',
       },
       { kind: 'measure', measure: captureStamps },

package/src/help.ts

@@ -95,7 +95,6 @@ const EXAMPLES = [
   'canon standards markdown',
   'canon init ../my-app',
   'canon tooling sync base',
-  'canon tooling create',
   'canon claude init',
   'canon indexes regen',
   'canon indexes regen --dry-run --json',

package/src/pr/evidence.ts

@@ -215,6 +215,41 @@ function hasEvidenceMarker(body: string): boolean {
   return (lines[index] ?? '').trim().startsWith(MARKER_PREFIX)
 }
 
+/** Whether any comment carries the evidence marker, url or not. */
+export function hasMarkedEvidenceComment(
+  comments: readonly EvidenceComment[],
+): boolean {
+  return comments.some((comment) => hasEvidenceMarker(comment.body))
+}
+
+/** A post-pull-request step of the ship chain that never landed on the thread. */
+export type OwedStep = 'evidence' | 'preview'
+
+export interface OwedInput {
+  readonly hasEvidenceChange: boolean
+  readonly hasMarkedComment: boolean
+  readonly carriedPreview: boolean
+  readonly deployWorkflowFound: boolean
+}
+
+/**
+ * The steps a pull request is still owed, read off the pull request rather
+ * than off any session's account of what it ran. The thread cannot tell a
+ * skipped preview from one whose deploy failed, so both read as owed.
+ */
+export function readOwed(input: OwedInput): OwedStep[] {
+  const owed: OwedStep[] = []
+  if (input.hasEvidenceChange && !input.hasMarkedComment) owed.push('evidence')
+  if (
+    (input.hasMarkedComment || input.hasEvidenceChange) &&
+    input.deployWorkflowFound &&
+    !input.carriedPreview
+  ) {
+    owed.push('preview')
+  }
+  return owed
+}
+
 /**
  * The REST id of the comment this module already posted, read off its `url`
  * field, since `gh pr view --json comments` reports only a GraphQL id there

package/src/tasks/archive.ts

@@ -417,6 +417,33 @@ export function retargetPlanLine(
   return lines.join('\n')
 }
 
+/**
+ * Appends a link to a located `Plan:` line right after its last target, so
+ * trailing prose and a line ending stay where they were. A bare target is
+ * rewritten as a link on the way, since the reader takes bare paths only when
+ * no link sits on the line and the appended one would otherwise hide them.
+ */
+export function appendPlanLink(line: string, target: string): string {
+  const tokens = planTokens(line)
+  if (tokens.length === 0) {
+    const trailing = /\s*$/.exec(line)?.[0] ?? ''
+    return `${line.slice(0, line.length - trailing.length)} ${planLink(target)}${trailing}`
+  }
+
+  let rewritten = ''
+  let at = 0
+  for (const token of tokens) {
+    const isLink = line[token.start] === '['
+    rewritten += line.slice(at, token.start)
+    rewritten += isLink
+      ? line.slice(token.start, token.end)
+      : planLink(token.target)
+    at = token.end
+  }
+
+  return `${rewritten}, ${planLink(target)}${line.slice(at)}`
+}
+
 /** The `Ready:` line in either form, the link's target captured ahead of the bare path. */
 const READY_PATTERN = /^Ready:[ \t]*(?:\[[^\]]*\]\(([^)]+)\)|(\S+))[ \t]*$/m
 

package/src/tasks/record.ts

@@ -3,6 +3,7 @@ import { readFile, writeFile } from 'node:fs/promises'
 import { basename, join, relative } from 'node:path'
 import { planCandidates } from '@/tasks/answers'
 import {
+  appendPlanLink,
   describeUnmatchedStem,
   fenceMask,
   linkTo,
@@ -240,12 +241,33 @@ export type PlanLineWrite =
  * A line already linking several plans is refused whole, even when one of them
  * is the target, since overwriting it drops links the caller never named and
  * reporting it unchanged hides a line that breaks the one-plan rule.
+ *
+ * `add` is the sliced task's writer, which links one plan per slice. It keeps
+ * every link in order and appends the target, reports `unchanged` when the
+ * target is already listed, and so never refuses a line holding several.
  */
-export function writePlanLine(text: string, target: string): PlanLineWrite {
+export function writePlanLine(
+  text: string,
+  target: string,
+  add = false,
+): PlanLineWrite {
   const line = planLine(target)
   const lines = text.split('\n')
   const existing = planLineIndex(lines)
 
+  if (existing !== -1 && add) {
+    if (readPlanTargets(lines[existing]).includes(target)) {
+      return { ok: true, text, action: 'unchanged', replaced: undefined }
+    }
+    lines[existing] = appendPlanLink(lines[existing], target)
+    return {
+      ok: true,
+      text: lines.join('\n'),
+      action: 'appended',
+      replaced: undefined,
+    }
+  }
+
   if (existing !== -1) {
     const targets = readPlanTargets(lines[existing])
     if (targets.length > 1) return { ok: false, targets }
@@ -449,6 +471,7 @@ export async function recordPlan(
   root: string,
   stem: string,
   reference: string,
+  add = false,
 ): Promise<PlanOutcome> {
   const opened = await openTask(root, { kind: 'stem', stem })
   if ('ok' in opened) return opened
@@ -464,7 +487,7 @@ export async function recordPlan(
   }
 
   const target = linkTo(dir, plan)
-  const written = writePlanLine(await readFile(path, 'utf8'), target)
+  const written = writePlanLine(await readFile(path, 'utf8'), target, add)
 
   if (!written.ok) {
     return refuse(

package/src/worktrees/bare-flag.ts

@@ -0,0 +1,83 @@
+import { basename } from 'node:path'
+import { execa } from 'execa'
+import { gitEnv } from '@/git-env'
+
+/** Why a run wrote nothing. The three are different states a caller can tell apart. */
+export type BareFlagSkip =
+  | 'flag-unset'
+  | 'common-dir-unreadable'
+  | 'genuinely-bare'
+  | 'write-failed'
+
+/**
+ * What the repair did, or the reason it left the configuration alone.
+ *
+ * `message` is non-null whenever the flag is still set and a caller should say
+ * so, which is a repair and a failed write. The three quiet skips carry none.
+ */
+export type BareFlagRecord =
+  | { readonly repaired: true; readonly reason: null; readonly message: string }
+  | {
+      readonly repaired: false
+      readonly reason: BareFlagSkip
+      readonly message: string | null
+    }
+
+export const REPAIRED_MESSAGE =
+  "Repaired core.bare, which worktree entry left set. Recovery is 'git config core.bare false'."
+
+export const WRITE_FAILED_MESSAGE =
+  "core.bare is set and the repair could not write the config, which a lock file or a read-only config causes. Recovery is 'git config core.bare false'."
+
+const skipped = (reason: BareFlagSkip): BareFlagRecord => ({
+  repaired: false,
+  reason,
+  message: null,
+})
+
+/**
+ * Repairs `core.bare`, which Claude Code's worktree entry leaves set in the
+ * shared config and nothing restores.
+ *
+ * The flag strands the main worktree and breaks the git reads that scope a
+ * verification run, so the gate runs this ahead of every stage. Every git call
+ * drops the repository-resolution variables a git hook exports, so the root
+ * the caller names is the repository that gets read and written.
+ *
+ * A genuinely bare repository keeps its objects at the root and has no `.git`
+ * directory, so its common dir fails the basename test and keeps its flag. That
+ * test is the one case where an unguarded repair does damage.
+ */
+export async function repairBareFlag(root: string): Promise<BareFlagRecord> {
+  const git = (...args: string[]) =>
+    execa('git', ['-C', root, ...args], {
+      env: gitEnv(),
+      extendEnv: false,
+      reject: false,
+    })
+
+  const flag = await git('config', '--get', 'core.bare')
+  if (flag.exitCode !== 0 || flag.stdout.trim() !== 'true') {
+    return skipped('flag-unset')
+  }
+
+  const common = await git(
+    'rev-parse',
+    '--path-format=absolute',
+    '--git-common-dir',
+  )
+  if (common.exitCode !== 0) return skipped('common-dir-unreadable')
+  if (basename(common.stdout.trim()) !== '.git')
+    return skipped('genuinely-bare')
+
+  const write = await git('config', 'core.bare', 'false')
+  if (write.exitCode !== 0) {
+    return {
+      repaired: false,
+      reason: 'write-failed',
+      message: WRITE_FAILED_MESSAGE,
+    }
+  }
+
+  return { repaired: true, reason: null, message: REPAIRED_MESSAGE }
+}

package/standards/tasks.md

@@ -124,9 +124,9 @@ An intake folder answers that direction at folder scope rather than item scope.
 
 A project that archived plans before the folder nested under `.canon/plans/` holds closed tasks pointing at `../plans-archive/` or `../.tmp/plans-archive/`. Leave those pointers where they are, since each resolves against the files it names and a task retargeted without its plan moving leads nowhere.
 
-One plan per task. A plan cited by two tasks is a misfile rather than a shape to design for.
+One plan per task, or one per slice on a sliced task. A plan cited by two tasks is a misfile rather than a shape to design for.
 
-`canon tasks plan-link <task> <plan>` writes or corrects the `Plan:` line, so the line is a mechanical write rather than hand-edited markdown.
+`canon tasks plan-link <task> <plan>` writes or corrects the `Plan:` line, and `--add` appends a slice's plan, so the line is never hand-edited.
 
 `Groundwork:` points at `../groundwork/<slug>/`, the folder `plan-groundwork` fills. It names the surface it points at the way `Plan:` does. Use this key alone. `Research record` and `Decision record` are earlier spellings of the same thing and both convert to it.