@erclx/aitk 0.79.0 → 0.81.0

package/src/commands/context.ts

@@ -4,6 +4,7 @@ import {
   type EntryReport,
   governsContent,
   LENGTH_CHECKPOINT,
+  matchesSiblings,
   measureFolders,
   missingSections,
   PROVENANCE_FOLDER,
@@ -60,7 +61,7 @@ export function register(program: Command): void {
   context
     .command('audit')
     .description(
-      'Report required sections, entry length, citations, catalog tables, provenance, superseded-decision narration, and index drift',
+      'Report required sections, entry length, citations, reference form, catalog tables, provenance, superseded-decision narration, and index drift',
     )
     .argument('[path]', 'Project root, defaulting to the current directory')
     .helpOption('-h, --help', 'Show this help message')
@@ -85,8 +86,9 @@ export function register(program: Command): void {
         '',
         'An unresolved citation always gates. --gate widens the gate to the',
         'other two findings that are facts rather than judgments: a missing',
-        'required section and index drift. Length, table, provenance, and',
-        'narration findings are judgments and stay advisory under both.',
+        'required section and index drift. Length, reference form, table,',
+        'provenance, and narration findings are judgments and stay advisory',
+        'under both.',
         '',
         'Depth and bullet weight are stated over every markdown file rather',
         'than over a context entry, so `aitk markdown audit` measures them.',
@@ -205,6 +207,7 @@ async function runAudit(
     intro('aitk context audit')
     reportScope(folders, unresolved)
     reportCitations(citations, cited)
+    reportReferenceForm(entries, folders)
     reportSections(sections, folders)
     reportLength(entries)
     reportTables(entries)
@@ -370,6 +373,65 @@ function reportCitations(
   )
 }
 
+/**
+ * Reports the references naming a sibling entry by bare filename.
+ *
+ * This prints beside the citation check rather than among the readability
+ * measures, since the two read the same thing: one resolves a path a reference
+ * spells and this one finds the references that spell none. The reach line
+ * names the split folders rather than the governed folder alone, because a run
+ * whose only context folder is flat measures nothing here and would otherwise
+ * print the same clean line as a run that measured every split.
+ */
+function reportReferenceForm(
+  entries: readonly EntryReport[],
+  folders: readonly AuditedFolder[],
+): void {
+  logStep('Reference form')
+
+  const scoped = folders.filter(matchesSiblings)
+  if (scoped.length === 0) {
+    logInfo(
+      `Out of scope. A bare name is matched against the siblings of a domain split into a folder, and no audited folder under .claude/${PROVENANCE_FOLDER}/ is one.`,
+    )
+    return
+  }
+
+  logInfo(
+    `Covers ${plural(scoped.length, 'split folder')} under .claude/${PROVENANCE_FOLDER}/, whose standard asks a reference to spell its path.`,
+  )
+  logInfo(
+    'The flat folder is out of reach, since a domain filename there is shared by seeds and other trees.',
+  )
+
+  const carrying = entries
+    .filter((entry) => entry.bareReferences.length > 0)
+    .sort((a, b) => b.bareReferences.length - a.bareReferences.length)
+
+  if (carrying.length === 0) {
+    logInfo('Every reference to a sibling entry spells its path.')
+    return
+  }
+
+  const total = carrying.reduce(
+    (sum, entry) => sum + entry.bareReferences.length,
+    0,
+  )
+  logWarn(
+    `${plural(total, 'bare name')} across ${carrying.length} ${carrying.length === 1 ? 'entry' : 'entries'}`,
+  )
+  pipeOutput(
+    carrying
+      .map(
+        (entry) =>
+          `${entry.rel}  ${plural(entry.bareReferences.length, 'bare name')}\n${entry.bareReferences
+            .map((found) => `  :${found.line}  ${found.name}`)
+            .join('\n')}`,
+      )
+      .join('\n'),
+  )
+}
+
 /**
  * Names the path each finding belongs to, which is an entry in the folder named
  * under `.claude/` and the folder itself in a domain split across one. States

package/src/commands/records.ts

@@ -1,4 +1,11 @@
 import type { Command } from 'commander'
+import {
+  BACKED_FOLDERS,
+  type PullOutcome,
+  pullRecords,
+  type PushOutcome,
+  pushRecords,
+} from '@/records/backup'
 import {
   type Finding,
   isRecordKind,
@@ -6,7 +13,15 @@ import {
   type ValidateOutcome,
   validateRecords,
 } from '@/records/validate'
-import { intro, logError, logInfo, logStep, logWarn, outro } from '@/ui'
+import {
+  intro,
+  logError,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  pipeOutput,
+} from '@/ui'
 import { mainWorktreeRoot } from '@/worktree'
 
 /** Returned when a record carries a finding, which is the gating result. */
@@ -17,10 +32,14 @@ interface ValidateCommandOptions {
   readonly root?: string
 }
 
+type BackupCommandOptions = ValidateCommandOptions
+
 export function register(program: Command): void {
   const records = program
     .command('records')
-    .description('Check the gitignored session records under .claude/')
+    .description(
+      'Check and back up the gitignored session records under .claude/',
+    )
     .helpOption('-h, --help', 'Show this help message')
 
   records
@@ -58,6 +77,145 @@ export function register(program: Command): void {
     .action(async (kind: string, opts: ValidateCommandOptions) => {
       process.exitCode = await runValidate(kind, opts)
     })
+
+  records
+    .command('push')
+    .description(
+      'Commit the backed record folders and push them to the records remote',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--root <path>', 'Project root, defaulting to the main worktree')
+    .addHelpText('after', backupHelp('push'))
+    .action(async (opts: BackupCommandOptions) => {
+      process.exitCode = await runPush(opts)
+    })
+
+  records
+    .command('pull')
+    .description(
+      'Fetch the records remote and write it into the backed record folders',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--root <path>', 'Project root, defaulting to the main worktree')
+    .addHelpText('after', backupHelp('pull'))
+    .action(async (opts: BackupCommandOptions) => {
+      process.exitCode = await runPull(opts)
+    })
+}
+
+function backupHelp(verb: 'push' | 'pull'): string {
+  const direction =
+    verb === 'push'
+      ? [
+          'It commits nothing outside the folders above and leaves the project working',
+          'tree untouched. The push runs even when this call committed nothing, since a',
+          'previous run can have committed and then failed to reach the network.',
+        ]
+      : [
+          'It refuses rather than discarding local records that never reached the remote,',
+          'so a machine holding uncommitted or unpushed records is told to push first.',
+        ]
+
+  return [
+    '',
+    'Backed folders under .claude/:',
+    `  ${BACKED_FOLDERS.join(', ')}`,
+    '',
+    'Exit codes:',
+    '  0  the records remote and this machine agree',
+    '  1  refused, with the reason on stderr or in the JSON record',
+    '',
+    ...direction,
+    '',
+    'The history lives in a second git directory at .claude/.records.git, pointed at a',
+    'private repository a person creates once. The verbs refuse with the setup command',
+    'when it is absent, and refuse when its origin is also a remote of this project.',
+    '',
+    'Examples:',
+    `  aitk records ${verb}`,
+    `  aitk records ${verb} --json`,
+    '',
+  ].join('\n')
+}
+
+async function runPush(opts: BackupCommandOptions): Promise<number> {
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const outcome = await pushRecords(root)
+
+  if (!outcome.ok)
+    return reportRefusal('aitk records push', outcome, opts.json ?? false)
+
+  if (opts.json ?? false) {
+    process.stdout.write(`${JSON.stringify(outcome)}\n`)
+    return 0
+  }
+
+  intro('aitk records push')
+  logStep('Staged')
+  logInfo(
+    `${outcome.folders.length} folder(s), ${outcome.changed} path(s) changed`,
+  )
+  logStep(outcome.pushed ? 'Pushed' : 'Nothing to push')
+  logInfo(
+    outcome.commit
+      ? `records at ${outcome.commit}`
+      : 'no records committed yet',
+  )
+  outro()
+  return 0
+}
+
+async function runPull(opts: BackupCommandOptions): Promise<number> {
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const outcome = await pullRecords(root)
+
+  if (!outcome.ok)
+    return reportRefusal('aitk records pull', outcome, opts.json ?? false)
+
+  if (opts.json ?? false) {
+    process.stdout.write(`${JSON.stringify(outcome)}\n`)
+    return 0
+  }
+
+  intro('aitk records pull')
+  logStep('Fetched')
+  logInfo(`records at ${outcome.commit}`)
+  logStep('Written')
+  logInfo(`${outcome.files} file(s) across ${outcome.folders.length} folder(s)`)
+  outro()
+  return 0
+}
+
+function reportRefusal(
+  banner: string,
+  outcome: Extract<PushOutcome | PullOutcome, { ok: false }>,
+  emitJson: boolean,
+): number {
+  if (emitJson) {
+    process.stderr.write(`${outcome.message}\n`)
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: false,
+        reason: outcome.reason,
+        message: outcome.message,
+      })}\n`,
+    )
+    return 1
+  }
+
+  // The setup refusals carry the commands to run on their own lines. A marker
+  // beside a command reads as a result rather than as something to copy, so the
+  // remainder goes out unmarked.
+  const [reason, ...rest] = outcome.message.split('\n')
+
+  intro(banner)
+  logStep('Refused')
+  logError(reason)
+  if (rest.length > 0) pipeOutput(rest.join('\n'))
+  outro()
+  return 1
 }
 
 async function runValidate(

package/src/context/audit.ts

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises'
-import { relative } from 'node:path'
+import { basename, relative } from 'node:path'
+import { BARE_NAME, IGNORE_MARKER } from '@/context/citations'
 import type { AuditedFolder } from '@/context/folders'
 import type { NarrationTerms } from '@/context/narration'
 import { type BodyLine, bodyLines, maskDisplayed } from '@/markdown/scan'
@@ -109,6 +110,12 @@ export interface ProvenanceFinding {
   readonly text: string
 }
 
+export interface BareReferenceFinding {
+  readonly line: number
+  /** The name as written, so a report says which reference to respell. */
+  readonly name: string
+}
+
 export interface NarrationFinding {
   readonly line: number
   /** The opening that points back at the bullet above. */
@@ -141,6 +148,12 @@ export interface EntryReport {
    * since an empty list here is silent about which one produced it.
    */
   readonly narration: readonly NarrationFinding[]
+  /**
+   * References naming a sibling entry by bare filename, and empty for a caller
+   * that passed no sibling names. Which entries have siblings worth matching is
+   * the caller's judgment, stated where it builds the list.
+   */
+  readonly bareReferences: readonly BareReferenceFinding[]
   /**
    * Required sections this entry declares, in the standard's order, and empty
    * outside the folder whose standard names them. What the folder is short of
@@ -397,18 +410,62 @@ function declaredSections(lines: readonly BodyLine[]): string[] {
   return REQUIRED_SECTIONS.filter((section) => found.has(section))
 }
 
+/**
+ * Finds the references naming a sibling entry by bare filename.
+ *
+ * The standard asks for the path because a bare name resolves against whichever
+ * folder the reader is in, so a folder split strands every inbound reference
+ * and nothing reads the break. A path is checkable and a bare name is not,
+ * which is what makes this the one form rule worth measuring.
+ *
+ * Matching stops at the sibling set, which reaches less than the rule does. The
+ * standard governs a reference to any other entry, so a split entry naming one
+ * that sits in a different folder is a violation this never sees. What the set
+ * buys is that a name resolving inside the folder is a reference by
+ * construction, where a bare filename matched anywhere would report every
+ * sentence that happens to name a file. The entry's own name is out of the set
+ * on separate grounds, since naming itself points at nothing a split can strand.
+ *
+ * Fenced blocks are skipped for the reason the scans above skip them, and a line
+ * carrying the citation ignore marker is skipped because that marker already
+ * means the line displays a name rather than pointing at one.
+ */
+function bareReferences(
+  lines: readonly BodyLine[],
+  siblings: readonly string[],
+): BareReferenceFinding[] {
+  if (siblings.length === 0) return []
+
+  const named = new Set(siblings)
+  const findings: BareReferenceFinding[] = []
+
+  for (const line of lines) {
+    if (line.fenced || line.text.includes(IGNORE_MARKER)) continue
+
+    for (const match of line.text.matchAll(BARE_NAME)) {
+      if (named.has(match[1])) {
+        findings.push({ line: line.number, name: match[1] })
+      }
+    }
+  }
+
+  return findings
+}
+
 /**
  * Measures one entry, scanning for provenance only when a standard claims it.
  *
  * The caller passes jurisdiction rather than deriving it from `rel`, because a
  * path prefix hardcodes what `--folder` exists to override and misses a domain
- * split into `context/<sub-area>/`.
+ * split into `context/<sub-area>/`. Sibling names arrive the same way and for
+ * the same reason, since the folder an entry sits in is what holds them.
  */
 export function measureEntry(
   rel: string,
   source: string,
   governsContent = true,
   terms?: NarrationTerms,
+  siblings: readonly string[] = [],
 ): EntryReport {
   const lines = bodyLines(source)
 
@@ -421,6 +478,7 @@ export function measureEntry(
     catalogTables: catalogTables(lines),
     provenance: governsContent ? provenance(lines) : [],
     narration: governsContent && terms ? narration(lines, terms) : [],
+    bareReferences: bareReferences(lines, siblings),
     sections: governsContent ? declaredSections(lines) : [],
     stub: isStubSeed(source),
   }
@@ -442,13 +500,20 @@ export async function measureFolders(
   const reports: EntryReport[] = []
 
   for (const folder of folders) {
+    const names = matchesSiblings(folder)
+      ? folder.entries.map((path) => basename(path))
+      : []
+
     for (const path of folder.entries) {
+      const self = basename(path)
+
       reports.push(
         measureEntry(
           relative(root, path),
           await readFile(path, 'utf8'),
           governsContent(folder),
           terms,
+          names.filter((name) => name !== self),
         ),
       )
     }
@@ -462,6 +527,26 @@ export function governsContent(folder: AuditedFolder): boolean {
   return folder.name === PROVENANCE_FOLDER
 }
 
+/**
+ * Reports whether a bare sibling name here is a reference by construction.
+ *
+ * A split folder's entries are named for sub-areas of one domain, so a bare
+ * name matching one of them points at it and nothing else. The folder named
+ * under `.claude/` is where that stops holding, since its entries are named for
+ * whole domains and a domain name is a common noun that a seed, a script, or
+ * another tree spells the same way. Both false positives this measure was tuned
+ * against sat there, naming a seed that shares a filename with the entry beside
+ * them, and no signal in the name separates the two.
+ *
+ * What the exemption costs is the references a future split of the named folder
+ * would strand, which are the ones this measure would most like to hold. It is
+ * taken because a report firing on correct prose is what teaches a reader to
+ * stop reading the section.
+ */
+export function matchesSiblings(folder: AuditedFolder): boolean {
+  return governsContent(folder) && folder.nested
+}
+
 /**
  * Names what does not declare the sections the standard requires.
  *

package/src/context/citations.ts

@@ -49,6 +49,23 @@ export function citationPattern(folders: readonly string[]): RegExp {
   )
 }
 
+/**
+ * A backticked filename carrying no folder, the form a reference takes when it
+ * names a sibling rather than a path.
+ *
+ * `citationPattern` spells the `.claude/` prefix and cannot see this shape at
+ * all, which is the reason the form rule exists. Widening that expression to
+ * admit a bare name was the alternative and it puts one match in the position of
+ * answering two questions, since a spelled path is a reference by construction
+ * and a bare name is a candidate whichever caller found it still has to test
+ * against the folder it sits in.
+ *
+ * The backticks are required rather than incidental. A filename written into
+ * running prose without them is not a reference a reader follows, and matching
+ * one would report every sentence that happens to name a file.
+ */
+export const BARE_NAME = /`([A-Za-z0-9._-]+\.md)`/g
+
 /**
  * Pulls the cited paths out of one file's text.
  *