@erclx/aitk 0.63.1 → 0.64.0

package/src/tasks/record.ts

@@ -0,0 +1,311 @@
+import { existsSync } from 'node:fs'
+import { readFile, writeFile } from 'node:fs/promises'
+import { basename, join, relative } from 'node:path'
+import {
+  fenceMask,
+  listTaskStems,
+  OUTCOME_PATTERN,
+  readPlanTarget,
+  tasksDir,
+} from '@/tasks/archive'
+
+/**
+ * Lines a task carries above its outcomes naming where the work came from. The
+ * `Pull request:` line joins them, so the last one present is the anchor.
+ */
+const ORIGIN_PREFIXES = ['Plan:', 'Groundwork:', 'Intake:', 'Issue:'] as const
+
+/**
+ * `bad-input` is separated from the board-state reasons on purpose. `git-pr`
+ * swallows `no-board`, `no-match`, and `ambiguous`, because each is a case where
+ * a guessed write would archive the wrong task. A caller that passed a
+ * malformed argument has a defect nobody would otherwise hear about, so it
+ * reports rather than joining the swallowed set.
+ */
+export const RECORD_REFUSALS = [
+  'no-board',
+  'no-match',
+  'ambiguous',
+  'no-outcomes',
+  'out-of-range',
+  'bad-input',
+] as const
+
+export type RecordRefusal = (typeof RECORD_REFUSALS)[number]
+
+export interface RecordRefused {
+  readonly ok: false
+  readonly reason: RecordRefusal
+  readonly message: string
+  readonly detail: readonly string[]
+}
+
+export type RecordSelector =
+  | { readonly kind: 'stem'; readonly stem: string }
+  | { readonly kind: 'plan'; readonly plan: string }
+
+export type LineAction = 'added' | 'corrected' | 'unchanged'
+
+export interface PullRequestRecorded {
+  readonly ok: true
+  readonly stem: string
+  readonly path: string
+  readonly number: number
+  readonly action: LineAction
+}
+
+export type PullRequestOutcome = PullRequestRecorded | RecordRefused
+
+export interface OutcomesClosed {
+  readonly ok: true
+  readonly stem: string
+  readonly path: string
+  readonly closed: readonly string[]
+  readonly alreadyClosed: readonly string[]
+}
+
+export type CloseOutcome = OutcomesClosed | RecordRefused
+
+function refuse(
+  reason: RecordRefusal,
+  message: string,
+  detail: readonly string[] = [],
+): RecordRefused {
+  return { ok: false, reason, message, detail }
+}
+
+/**
+ * Reduces a plan reference to the token both spellings share. A task's `Plan:`
+ * line carries a path, a caller carries the branch slug, and the two differ by
+ * the folder, the extension, and the `feature-` prefix the filename adds.
+ */
+function planKey(reference: string): string {
+  const stem = basename(reference).replace(/\.md$/, '')
+  return stem.startsWith('feature-') ? stem.slice('feature-'.length) : stem
+}
+
+/**
+ * Places the `Pull request:` line under the origin lines the task already
+ * carries, and corrects the number in place when the line exists. A task with
+ * no origin line takes it under the H1, which is the only other anchor the
+ * board format guarantees.
+ */
+export function writePullRequestLine(
+  text: string,
+  number: number,
+): { readonly text: string; readonly action: LineAction } {
+  const line = `Pull request: #${number}`
+  const lines = text.split('\n')
+  const existing = lines.findIndex((entry) => entry.startsWith('Pull request:'))
+
+  if (existing !== -1) {
+    if (lines[existing] === line) return { text, action: 'unchanged' }
+    lines[existing] = line
+    return { text: lines.join('\n'), action: 'corrected' }
+  }
+
+  const origin = lastOriginLine(lines)
+  if (origin !== undefined) {
+    lines.splice(origin + 1, 0, line)
+    return { text: lines.join('\n'), action: 'added' }
+  }
+
+  const heading = lines.findIndex((entry) => entry.startsWith('# '))
+  if (heading === -1) return { text: `${line}\n${text}`, action: 'added' }
+
+  lines.splice(heading + 1, 0, '', line)
+  return { text: lines.join('\n'), action: 'added' }
+}
+
+function lastOriginLine(lines: readonly string[]): number | undefined {
+  let found: number | undefined
+
+  for (const [index, line] of lines.entries()) {
+    if (ORIGIN_PREFIXES.some((prefix) => line.startsWith(prefix))) found = index
+  }
+
+  return found
+}
+
+/**
+ * Marks outcomes closed by their 1-based position in the task's outcome list,
+ * which is the order the board format writes them. A caller reads the file
+ * before deciding, so a position is what it already holds, while a text match
+ * would need the wording handed back exactly.
+ */
+export function closeOutcomeLines(
+  text: string,
+  positions: readonly number[],
+): {
+  readonly text: string
+  readonly closed: readonly string[]
+  readonly alreadyClosed: readonly string[]
+  readonly total: number
+} {
+  const wanted = new Set(positions)
+  const closed: string[] = []
+  const alreadyClosed: string[] = []
+  const lines = text.split('\n')
+  const fenced = fenceMask(lines)
+  let seen = 0
+
+  const rewritten = lines.map((line, index) => {
+    if (fenced[index]) return line
+
+    const match = OUTCOME_PATTERN.exec(line)
+    if (!match) return line
+
+    seen += 1
+    if (!wanted.has(seen)) return line
+
+    const [, box, body] = match
+    if (box !== ' ') {
+      alreadyClosed.push(body.trim())
+      return line
+    }
+
+    closed.push(body.trim())
+    return body ? `- [x] ${body}` : '- [x]'
+  })
+
+  return { text: rewritten.join('\n'), closed, alreadyClosed, total: seen }
+}
+
+async function matchByPlan(
+  dir: string,
+  stems: readonly string[],
+  plan: string,
+): Promise<string[]> {
+  const key = planKey(plan)
+
+  const read = await Promise.all(
+    stems.map(async (stem) => ({
+      stem,
+      target: readPlanTarget(await readFile(join(dir, `${stem}.md`), 'utf8')),
+    })),
+  )
+
+  return read
+    .filter(
+      (entry) => entry.target !== undefined && planKey(entry.target) === key,
+    )
+    .map(({ stem }) => stem)
+}
+
+async function resolveStem(
+  dir: string,
+  selector: RecordSelector,
+): Promise<string | RecordRefused> {
+  const stems = await listTaskStems(dir)
+
+  if (selector.kind === 'stem') {
+    if (!stems.includes(selector.stem)) {
+      return refuse(
+        'no-match',
+        `No task named ${selector.stem} on the board.`,
+        stems,
+      )
+    }
+    return selector.stem
+  }
+
+  const matched = await matchByPlan(dir, stems, selector.plan)
+
+  if (matched.length === 0) {
+    return refuse('no-match', `No task names plan ${selector.plan}.`)
+  }
+
+  if (matched.length > 1) {
+    return refuse(
+      'ambiguous',
+      `${matched.length} tasks name plan ${selector.plan}. One task, one plan.`,
+      matched,
+    )
+  }
+
+  return matched[0]
+}
+
+async function openTask(
+  root: string,
+  selector: RecordSelector,
+): Promise<{ readonly stem: string; readonly path: string } | RecordRefused> {
+  const dir = tasksDir(root)
+
+  if (!existsSync(dir)) {
+    return refuse('no-board', `No task board at ${relative(root, dir)}.`)
+  }
+
+  const resolved = await resolveStem(dir, selector)
+  if (typeof resolved !== 'string') return resolved
+
+  return { stem: resolved, path: join(dir, `${resolved}.md`) }
+}
+
+/**
+ * Records a pull request number on the task the branch closes. `git-pr` runs
+ * this from a linked worktree, where an in-place edit through the file-editing
+ * tools is refused and a shell stream editor is banned, so the write has to
+ * resolve the board root in-process.
+ */
+export async function recordPullRequest(
+  root: string,
+  selector: RecordSelector,
+  number: number,
+): Promise<PullRequestOutcome> {
+  const opened = await openTask(root, selector)
+  if ('ok' in opened) return opened
+
+  const { stem, path } = opened
+  const { text, action } = writePullRequestLine(
+    await readFile(path, 'utf8'),
+    number,
+  )
+
+  if (action !== 'unchanged') await writeFile(path, text)
+
+  return { ok: true, stem, path, number, action }
+}
+
+/**
+ * Marks the named outcomes `[x]` in place. `claude-docs` runs this against a
+ * board it can read and cannot edit from a linked worktree, and the positions
+ * come from the read it already made.
+ */
+export async function closeOutcomes(
+  root: string,
+  selector: RecordSelector,
+  positions: readonly number[],
+): Promise<CloseOutcome> {
+  const opened = await openTask(root, selector)
+  if ('ok' in opened) return opened
+
+  const { stem, path } = opened
+  const result = closeOutcomeLines(await readFile(path, 'utf8'), positions)
+
+  if (result.total === 0) {
+    return refuse('no-outcomes', `${stem} carries no outcomes to close.`)
+  }
+
+  const beyond = positions.filter(
+    (position) => position < 1 || position > result.total,
+  )
+
+  if (beyond.length > 0) {
+    return refuse(
+      'out-of-range',
+      `${stem} carries ${result.total} outcome(s), so ${beyond.join(', ')} names nothing.`,
+      beyond.map(String),
+    )
+  }
+
+  if (result.closed.length > 0) await writeFile(path, result.text)
+
+  return {
+    ok: true,
+    stem,
+    path,
+    closed: result.closed,
+    alreadyClosed: result.alreadyClosed,
+  }
+}

package/src/worktree.ts

@@ -0,0 +1,23 @@
+import { $ } from 'bun'
+
+/**
+ * Resolves the root every shared-scratch folder lives under. `git worktree
+ * list` puts the main worktree first, and trusting the working directory
+ * instead would write a second board nothing else reads, or validate a linked
+ * worktree's empty folder and report it clean.
+ *
+ * A caller reaching this from a linked worktree is the case it exists for: the
+ * file-editing tools refuse a main-root path there, so a verb resolving the
+ * root in-process is the route a skill body has.
+ */
+export 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 '))
+
+  return line ? line.slice('worktree '.length).trim() : process.cwd()
+}

package/standards/context.md

@@ -100,13 +100,8 @@ Only the `development` entry carries this section. It is not a general-purpose h
 ## Length
 
 - Aim for one entry per domain. There is no hard cap. Length is a symptom, not the defect.
-- Past roughly 150 rendered lines, check three things before adding more: whether the entry still covers a single domain, whether it has filled with content `ls` or `--help` reproduces, and whether it has accumulated the history of its own changes. Fix whichever is true rather than trimming to hit a number.
-- Past roughly 40 rendered lines with no heading of any level breaking them, add a subheading at the seam. Measure the longest such run rather than everything under one `##`, and exclude fenced code blocks. The number is a checkpoint like the 150 above, not a cap.
-- Both checkpoints count rendered lines, so wrap each source line at 80 columns and sum the heights. Source lines undercount an entry authored one line per bullet, where a block of fifteen paragraph-bullets occupies fifteen lines and renders past sixty. Counting the two checkpoints in different units would put a file measured one way beside a run measured another.
-- Exempt a block whose lines are all list items at one level averaging under roughly 130 characters. A flat list of short peers is already navigable, and a subheading dropped into it splits a set that belongs together. Bullet count says nothing on its own, since a catalog of one-liners and a stack of paragraphs reach the same count and read nothing alike, so weight is what decides. Mixing prose with the list, or nesting levels inside it, ends the exemption at any weight.
-- Exempt a block whose lines are all table rows, at any length. The peer list above is exempt because it is already navigable, and a table because the remedy does not exist: a subheading dropped inside one splits the table rather than the run, so no edit short of rewriting it as a list clears the checkpoint. Prose either side of the table ends the exemption, since that block has a seam and a heading breaks it there.
-- Past roughly 400 characters in one top-level bullet, counting the lines that continue it and excluding any bullet nested under it, check whether the incident that motivated the decision sits beside the decision itself. Keep the current design and the alternative that lost, and move the incident to the change that introduced it, the issue that tracked it, or the research record behind it. The number is a checkpoint like the two above, and a bullet reading well past it means the number is wrong rather than the rule.
-- Collapse a stack of bullets narrating one subsystem into a single `###` subsection carrying one narrative. Splitting a heavy bullet into three light ones satisfies the checkpoint above and leaves the reader no better off, and subdividing a block does not lighten the bullets inside it, so the two rules answer different defects.
+- Past roughly 150 rendered lines, check three things before adding more: whether the entry still covers a single domain, whether it has filled with content `ls` or `--help` reproduces, and whether it has accumulated the history of its own changes. Fix whichever is true rather than trimming to hit a number. Rendered lines count as `markdown.md` defines them.
+- Where a bullet sits past the weight checkpoint `markdown.md` states, the overflow to move is the incident that motivated the decision, which specializes that rule's instruction to send the overflow to prose. Keep the current design and the alternative that lost, and send the incident to the change that introduced it, the issue that tracked it, or the research record behind it.
 - Never cut a `## Decisions` or `## Gotchas` entry to shorten a file. Cut a `## Layout` or `## CLI` section instead.
 - Retire a decision or gotcha once its subject is gone, rewriting the bullet to state the current design rather than leaving the narration of what it replaced beside it. A rejected alternative is not a retired one, so what was tried and why it lost stays whatever its age. The rule above protects content whose subject is live, and this one releases content whose subject is not.
 - Rewrite a decision a later one replaced rather than appending the replacement beside it. The subject is still live, so the rule above does not reach it, and two bullets on one subject leave a reader to work out which of them is current. State the design that stands and keep the superseded reasoning only where it is the alternative that lost.

package/standards/markdown.md

@@ -9,7 +9,7 @@ Applies to markdown reference docs, READMEs, and inline documentation in repos.
 
 ## Scope
 
-Governs the markdown mechanics of every markdown file: headings, paragraph and list structure, code spans and fences, punctuation, emphasis, and file references. It is an attribute standard rather than a document-type one, so it applies over documents whose shape another standard sets, and it carries no template because mechanics are written across every document and have none of their own to shape.
+Governs the markdown mechanics of every markdown file: headings, paragraph and list structure, code spans and fences, punctuation, emphasis, and file references. It is an attribute standard rather than a document-type one, so it applies over documents whose shape another standard sets, and it carries no template because mechanics are written across every document and have no shape of their own.
 
 Does not govern:
 
@@ -23,12 +23,20 @@ Does not govern:
 - H1 for document title, H2 for main sections, H3 for subsections
 - Use sentence case for all headings (H1, H2, H3)
 - Proper nouns and product names retain their casing in headings
+- Past roughly 40 rendered lines with no heading of any level breaking them, add a subheading at the seam. Measure the longest such run rather than everything under one `##`, and exclude fenced code blocks. The number is a checkpoint, not a cap.
+- Count rendered lines rather than source lines, wrapping each source line at 80 columns and summing the heights. Source lines undercount a file authored one line per bullet, where a block of fifteen paragraph-bullets occupies fifteen lines and renders past sixty. A checkpoint another standard states counts the same unit, so a file measured one way never sits beside a run measured another.
+- Exempt a block whose lines are all list items at one level averaging under roughly 130 characters. A flat list of short peers is already navigable, and a subheading dropped into it splits a set that belongs together. Bullet count says nothing on its own, since a catalog of one-liners and a stack of paragraphs reach the same count and read nothing alike, so weight is what decides.
+- Mixing prose with that list, or nesting levels inside it, ends the exemption at any weight.
+- Exempt a block whose lines are all table rows, at any length. The peer list above is exempt because it is already navigable, and a table because the remedy does not exist: a subheading dropped inside one splits the table rather than the run, so no edit short of rewriting it as a list clears the checkpoint.
+- Prose either side of the table ends that exemption, since the block has a seam and a heading breaks it there.
 
 ## Paragraphs and lists
 
 - Use prose by default. Reserve bullets for discrete, unrelated items.
 - Keep paragraphs to four sentences or fewer. Split longer blocks at the next logical boundary.
-- Keep bullets tight. If a bullet needs more than a couple of sentences, it belongs in prose.
+- Past roughly 400 characters in one paragraph, folding in the lines that wrap it, split at the next logical boundary as well. The sentence cap alone is satisfied by writing fewer and longer sentences, and measured across this corpus 344 paragraphs sit inside four sentences and past this number, so a count on its own passes every one of them.
+- Keep bullets tight. Past roughly 400 characters in one top-level bullet, counting the lines that continue it and excluding any bullet nested under it, the overflow belongs in prose. The number is a checkpoint rather than a cap, and a bullet reading well past it means the number is wrong rather than the rule.
+- Collapse a stack of bullets narrating one subsystem into a single `###` subsection carrying one narrative. Splitting a heavy bullet into three light ones satisfies the checkpoint above and leaves the reader no better off, and subdividing a block does not lighten the bullets inside it, so the two rules answer different defects.
 - Use dashes (`-`) not asterisks (`*`) for bulleted lists
 - Do not end single-sentence or fragment bullets with a period. Use periods when a bullet has two or more sentences.
 - For key path lists, use colon format: `- \`src/\`: description`. Never use an em dash.

package/tooling/claude/seeds/CLAUDE.md

@@ -87,3 +87,4 @@
 - From a linked worktree, every `Edit` or `Write` to a tracked file (source, docs) must use a path starting with `pwd`.
 - From a linked worktree, `Edit` and `Write` are refused for every main-root path, session scratch included. The refusal names session isolation and points at the worktree copy, which is a second gitignored file no later session reads, so never take that redirect.
 - `Read` resolves against the main root normally from a linked worktree. A main-root write reaches it only through `Bash`, as one plain command rather than a compound one, which is refused for complexity.
+- Route a main-root write by what it does to the file. Creating a whole file goes out as one plain `Bash` command carrying a heredoc. Changing a line inside a file that already exists goes through an `aitk` verb, which resolves the main root in-process, because the shell route for that case is the stream editor this file bans.