@erclx/aitk 0.63.0 → 0.63.2

package/src/commands/tasks.ts

@@ -1,7 +1,14 @@
 import { relative } from 'node:path'
-import { $ } from 'bun'
 import type { Command } from 'commander'
 import { type ArchiveOutcome, archiveTask } from '@/tasks/archive'
+import {
+  type CloseOutcome,
+  closeOutcomes,
+  type PullRequestOutcome,
+  type RecordRefused,
+  type RecordSelector,
+  recordPullRequest,
+} from '@/tasks/record'
 import {
   type Finding,
   type ValidateOutcome,
@@ -18,6 +25,7 @@ import {
   outro,
   pipeOutput,
 } from '@/ui'
+import { mainWorktreeRoot } from '@/worktree'
 
 /** Returned when the board carries a finding, which is the gating result. */
 const EXIT_FINDINGS = 2
@@ -33,22 +41,17 @@ interface ValidateCommandOptions {
   readonly root?: string
 }
 
-/**
- * The board is shared scratch at the main worktree root, and `git worktree
- * list` puts that root first. A pull inside a linked worktree fires the same
- * hook, so trusting the working directory would write a second board nothing
- * else reads.
- */
-async function mainWorktreeRoot(): Promise<string> {
-  const result = await $`git worktree list --porcelain`.quiet().nothrow()
-  if (result.exitCode !== 0) return process.cwd()
-
-  const line = result.stdout
-    .toString()
-    .split('\n')
-    .find((entry) => entry.startsWith('worktree '))
+interface PullRequestCommandOptions {
+  readonly json?: boolean
+  readonly plan?: string
+  readonly root?: string
+}
 
-  return line ? line.slice('worktree '.length).trim() : process.cwd()
+interface OutcomeCommandOptions {
+  readonly close?: readonly string[]
+  readonly json?: boolean
+  readonly plan?: string
+  readonly root?: string
 }
 
 export function register(program: Command): void {
@@ -121,6 +124,298 @@ export function register(program: Command): void {
     .action(async (opts: ValidateCommandOptions) => {
       process.exitCode = await runValidate(opts)
     })
+
+  tasks
+    .command('pull-request')
+    .description('Record a pull request number on the task a branch closes')
+    .argument('<number>', 'Pull request number, without the #')
+    .argument('[task]', 'Task filename stem, as in v28.1-trigger-escalation')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--plan <slug>', 'Select the task whose Plan line names this plan')
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Board root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the line was added, corrected, or already correct',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'It adds Pull request: #NNN under the origin lines the task carries,',
+        'and corrects the number in place when the line exists. The board is',
+        'shared scratch, so a linked worktree records against the same board.',
+        '',
+        'Examples:',
+        '  aitk tasks pull-request 673 v28.1-trigger-escalation',
+        '  aitk tasks pull-request 673 --plan worktree-scratch-routing --json',
+        '',
+      ].join('\n'),
+    )
+    .action(
+      async (
+        number: string,
+        task: string | undefined,
+        opts: PullRequestCommandOptions,
+      ) => {
+        process.exitCode = await runPullRequest(number, task, opts)
+      },
+    )
+
+  tasks
+    .command('outcome')
+    .description('Mark outcomes closed on a task by their position')
+    .argument('[task]', 'Task filename stem, as in v28.1-trigger-escalation')
+    .helpOption('-h, --help', 'Show this help message')
+    .option(
+      '--close <position>',
+      'Outcome to mark [x], 1-based, repeatable',
+      collectPosition,
+      [] as string[],
+    )
+    .option('--plan <slug>', 'Select the task whose Plan line names this plan')
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Board root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  every named outcome is closed',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Positions count every outcome checkbox in file order, starting at 1.',
+        'An outcome already closed is reported rather than refused, so a rerun',
+        'against the same positions is safe.',
+        '',
+        'Examples:',
+        '  aitk tasks outcome v28.1-trigger-escalation --close 1 --close 3',
+        '  aitk tasks outcome --plan worktree-scratch-routing --close 2 --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (task: string | undefined, opts: OutcomeCommandOptions) => {
+      process.exitCode = await runOutcome(task, opts)
+    })
+}
+
+function collectPosition(value: string, previous: string[]): string[] {
+  return [...previous, value]
+}
+
+/**
+ * Both record verbs name a task the same two ways, and naming it neither way or
+ * both ways is the same refusal in each. Both are `bad-input` rather than
+ * `ambiguous` or `no-match`, since those two describe the board and these
+ * describe the command line that reached it.
+ */
+function selectorFor(
+  task: string | undefined,
+  plan: string | undefined,
+): RecordSelector | RecordRefused {
+  if (task && plan) {
+    return {
+      ok: false,
+      reason: 'bad-input',
+      message: 'Name a task or a plan, not both.',
+      detail: [],
+    }
+  }
+
+  if (task) return { kind: 'stem', stem: task }
+  if (plan) return { kind: 'plan', plan }
+
+  return {
+    ok: false,
+    reason: 'bad-input',
+    message: 'No task named. Pass a filename stem or --plan <slug>.',
+    detail: [],
+  }
+}
+
+async function runPullRequest(
+  number: string,
+  task: string | undefined,
+  opts: PullRequestCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  const selector = selectorFor(task, opts.plan)
+
+  if ('ok' in selector) {
+    return reportRecord(
+      'aitk tasks pull-request',
+      selector,
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  if (!/^\d+$/.test(number)) {
+    return reportRecord(
+      'aitk tasks pull-request',
+      {
+        ok: false,
+        reason: 'bad-input',
+        message: `Not a pull request number: ${number}`,
+        detail: [],
+      },
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const outcome = await recordPullRequest(root, selector, Number(number))
+
+  return reportPullRequest(outcome, emitJson, root)
+}
+
+async function runOutcome(
+  task: string | undefined,
+  opts: OutcomeCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  const selector = selectorFor(task, opts.plan)
+
+  if ('ok' in selector) {
+    return reportRecord('aitk tasks outcome', selector, emitJson, process.cwd())
+  }
+
+  const raw = opts.close ?? []
+
+  if (raw.length === 0) {
+    return reportRecord(
+      'aitk tasks outcome',
+      {
+        ok: false,
+        reason: 'bad-input',
+        message: 'No outcome named. Pass --close <position>.',
+        detail: [],
+      },
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const invalid = raw.filter((value) => !/^\d+$/.test(value))
+
+  if (invalid.length > 0) {
+    return reportRecord(
+      'aitk tasks outcome',
+      {
+        ok: false,
+        reason: 'bad-input',
+        message: `Not an outcome position: ${invalid.join(', ')}`,
+        detail: invalid,
+      },
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const outcome = await closeOutcomes(root, selector, raw.map(Number))
+
+  return reportOutcome(outcome, emitJson, root)
+}
+
+function reportRecord(
+  title: string,
+  refused: RecordRefused,
+  emitJson: boolean,
+  root: string,
+): number {
+  // The framed branch below already 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 reportPullRequest(
+  outcome: PullRequestOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    return reportRecord('aitk tasks pull-request', outcome, emitJson, root)
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        task: outcome.stem,
+        path: relative(root, outcome.path),
+        pullRequest: outcome.number,
+        action: outcome.action,
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro('aitk tasks pull-request')
+  logStep(outcome.action === 'unchanged' ? 'Already recorded' : 'Recorded')
+  logInfo(`${outcome.stem} names pull request #${outcome.number}`)
+  if (outcome.action !== 'unchanged') logAdd(relative(root, outcome.path))
+  outro()
+
+  return 0
+}
+
+function reportOutcome(
+  outcome: CloseOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    return reportRecord('aitk tasks outcome', outcome, emitJson, root)
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        task: outcome.stem,
+        path: relative(root, outcome.path),
+        closed: outcome.closed,
+        alreadyClosed: outcome.alreadyClosed,
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro('aitk tasks outcome')
+  logStep(outcome.closed.length > 0 ? 'Closed' : 'Nothing to close')
+
+  for (const closed of outcome.closed) logAdd(closed)
+  for (const already of outcome.alreadyClosed) logInfo(`${already} (already)`)
+
+  if (outcome.closed.length > 0) logInfo(relative(root, outcome.path))
+  outro()
+
+  return 0
 }
 
 async function runValidate(opts: ValidateCommandOptions): Promise<number> {
@@ -196,7 +491,7 @@ async function runArchive(
     return report(
       {
         ok: false,
-        reason: 'ambiguous',
+        reason: 'bad-input',
         message: 'Name a task or a pull request, not both.',
         detail: [],
       },
@@ -209,7 +504,7 @@ async function runArchive(
     return report(
       {
         ok: false,
-        reason: 'no-match',
+        reason: 'bad-input',
         message:
           'No task named. Pass a filename stem or --pull-request <number>.',
         detail: [],
@@ -225,7 +520,7 @@ async function runArchive(
     return report(
       {
         ok: false,
-        reason: 'no-match',
+        reason: 'bad-input',
         message: `Not a pull request number: ${opts.pullRequest}`,
         detail: [],
       },

package/src/context/audit.ts

@@ -3,7 +3,13 @@ import { relative } from 'node:path'
 import type { AuditedFolder } from '@/context/folders'
 import { isStubSeed } from '@/seed-marker'
 
-/** Checkpoints quoted from `standards/context.md`. Neither is a cap. */
+/**
+ * Checkpoints quoted from the standard stating each. Neither is a cap.
+ *
+ * Entry length rests on one entry per domain, which is a domain fact, so
+ * `standards/context.md` keeps it. Run depth reads the same over any markdown
+ * file, so `standards/markdown.md` states it at the attribute tier.
+ */
 export const LENGTH_CHECKPOINT = 150
 export const RUN_CHECKPOINT = 40
 
@@ -29,7 +35,7 @@ export const RENDER_WIDTH = 80
 export const PEER_BULLET_CHECKPOINT = 130
 
 /**
- * Characters a bullet carries before it holds more than the decision itself.
+ * Characters a top-level bullet carries before its overflow belongs in prose.
  *
  * Unlike the peer-list checkpoint above, this corpus has no gap behind the
  * number. Bullet weight decays smoothly from a median near 170 with the
@@ -95,25 +101,21 @@ const PROVENANCE: readonly { kind: ProvenanceKind; pattern: RegExp }[] = [
  *
  * `standards/context.md` opens its scope by handing diagrams and wireframes to
  * `diagrams.md` and `wireframes.md`, so a marker reported in either would cite
- * a rule that entry's own standard routes elsewhere. The length, depth, and
- * table checkpoints are quoted from the same standard and keep reaching every
- * audited folder, because a threshold on how far a reader travels generalizes
- * across entry types while a rule about what an entry may say does not.
+ * a rule that entry's own standard routes elsewhere. The length and table
+ * checkpoints are quoted from the same standard and keep reaching every audited
+ * folder, because a threshold on how far a reader travels generalizes across
+ * entry types while a rule about what an entry may say does not.
  *
- * Bullet weight sits on this side of the split with provenance, which the
- * measure alone would not predict. What decides it is whether the remedy is
- * actionable: subdividing a run and splitting a file mean something in any
- * entry, while moving an incident out of a bullet and keeping the decision
- * means nothing in a folder whose entries carry no decisions to keep. No
- * diagram entry declares `## Decisions` or `## Gotchas`, so the scope of the
- * rule is what narrows the finding rather than the shape of the number.
+ * What gates here is a rule only this standard states. Bullet weight does not,
+ * since `standards/markdown.md` owns that checkpoint across document types and
+ * its remedy sends the overflow to prose, which any entry type can act on.
+ * `standards/context.md` specializes that remedy for an entry carrying
+ * decisions, and specializing a rule narrows the advice rather than the measure.
  *
- * Restating the exclusion in the sibling standards was the alternative. It
- * duplicates one knowledge item across three surfaces, which the root
- * instruction file forbids, and pointing is not available because the surface
- * they would point at is the one disclaiming them. Should a diagram entry ever
- * accumulate narration, the escalation is an attribute standard owning the rule
- * across document types, not restoring this reach without an owner.
+ * Restating the exclusion in the sibling standards was the alternative for what
+ * gates here. It duplicates one knowledge item across three surfaces, which the
+ * root instruction file forbids, and pointing is not available because the
+ * surface they would point at is the one disclaiming them.
  */
 export const PROVENANCE_FOLDER = 'context'
 
@@ -159,7 +161,7 @@ export interface EntryReport {
   readonly catalogTables: readonly TableFinding[]
   /** Empty for an entry no standard bans a change narrative in. */
   readonly provenance: readonly ProvenanceFinding[]
-  /** Empty for the same reason `provenance` is, and under the same folder. */
+  /** Measured in every audited folder, since an attribute standard states it. */
   readonly heavyBullets: readonly BulletFinding[]
   /**
    * Required sections this entry declares, in the standard's order, and empty
@@ -549,7 +551,7 @@ export function measureEntry(
     longestRunLine: run.line,
     catalogTables: catalogTables(lines),
     provenance: governsContent ? provenance(lines) : [],
-    heavyBullets: governsContent ? heavyBullets(lines) : [],
+    heavyBullets: heavyBullets(lines),
     sections: governsContent ? declaredSections(lines) : [],
     stub: isStubSeed(source),
   }

package/src/tasks/archive.ts

@@ -15,6 +15,12 @@ const PLANS_DIR = join('.claude', 'plans')
  */
 export const RESERVED_STEMS = ['index', 'priority', 'session'] as const
 
+/**
+ * `bad-input` describes the command line rather than the board, which is the
+ * split `record.ts` draws for the same reason. A caller naming two selectors
+ * answered as `ambiguous` sends a session to repair a task citation that is
+ * fine, so the three task verbs answer one mistake one way.
+ */
 export const ARCHIVE_REFUSALS = [
   'no-board',
   'no-match',
@@ -22,6 +28,7 @@ export const ARCHIVE_REFUSALS = [
   'no-outcomes',
   'open-outcomes',
   'plan-unswept',
+  'bad-input',
 ] as const
 
 export type ArchiveRefusal = (typeof ARCHIVE_REFUSALS)[number]
@@ -61,6 +68,26 @@ export function archiveDir(root: string): string {
   return join(root, ARCHIVE_DIR)
 }
 
+export const OUTCOME_PATTERN = /^- \[([ xX])\] ?(.*)$/
+
+/**
+ * Marks the lines sitting inside a fenced block, the fence delimiters included.
+ * A checkbox in a sample a task displays is not an outcome the task claims, and
+ * counting one shifts every position after it. Every reader of the outcome list
+ * shares this so none of them can disagree about what the list holds.
+ */
+export function fenceMask(lines: readonly string[]): boolean[] {
+  let inside = false
+
+  return lines.map((line) => {
+    if (/^\s*(?:```|~~~)/.test(line)) {
+      inside = !inside
+      return true
+    }
+    return inside
+  })
+}
+
 /**
  * Splits a task's outcome list by checkbox state. The board format puts every
  * outcome at the top level of `## Outcomes`, so an anchored match is enough and
@@ -69,9 +96,13 @@ export function archiveDir(root: string): string {
 export function readOutcomes(text: string): TaskOutcomes {
   const open: string[] = []
   const closed: string[] = []
+  const lines = text.split('\n')
+  const fenced = fenceMask(lines)
+
+  for (const [index, line] of lines.entries()) {
+    if (fenced[index]) continue
 
-  for (const line of text.split('\n')) {
-    const match = /^- \[([ xX])\] ?(.*)$/.exec(line)
+    const match = OUTCOME_PATTERN.exec(line)
     if (!match) continue
 
     const [, box, body] = match
@@ -157,7 +188,7 @@ function isLivePlan(target: string, dir: string, root: string): boolean {
   )
 }
 
-async function listTaskStems(dir: string): Promise<string[]> {
+export async function listTaskStems(dir: string): Promise<string[]> {
   const entries = await readdir(dir)
   const reserved: readonly string[] = RESERVED_STEMS