@erclx/aitk 3.52.1 → 3.54.0

package/src/commands/sandbox.ts

@@ -76,6 +76,8 @@ const CLEAN_ENVELOPE: RunEnvelope = { isError: false, turns: 0, denials: 0 }
 interface CheckOptions {
   readonly envelope?: string
   readonly writes?: string
+  readonly escapes?: string
+  readonly escapesWatched?: boolean
   readonly json?: boolean
   readonly strict?: boolean
 }
@@ -152,11 +154,13 @@ function readEnvelope(path: string | undefined): RunEnvelope | undefined {
 }
 
 /**
- * Undefined when no file was given, which is not the same as a run that wrote
- * nothing. The write-scope assertion needs that distinction: an empty list is a
- * finding, an absent list is a gap in what the caller supplied.
+ * Shared by `--writes` and `--escapes`, which are both a newline-delimited
+ * path list written by `run.sh`. Undefined when no file was given, which is
+ * not the same as a run that produced no paths. Write scope and escape scope
+ * both need that distinction: an empty list is a finding, an absent list is a
+ * gap in what the caller supplied.
  */
-function readWrites(path: string | undefined): string[] | undefined {
+function readPathList(path: string | undefined): string[] | undefined {
   if (path === undefined) return undefined
   if (!existsSync(path)) return []
 
@@ -360,7 +364,12 @@ function runCheck(
     expectFilePath(PROJECT_ROOT, parsed.category, parsed.command, arm ?? ''),
     {
       sandboxDir,
-      writes: readWrites(options.writes),
+      writes: readPathList(options.writes),
+      escapes: readPathList(options.escapes),
+      escapesWatched:
+        options.escapes === undefined
+          ? undefined
+          : options.escapesWatched === true,
       envelope: readEnvelope(options.envelope),
     },
   )
@@ -404,6 +413,14 @@ export function register(program: Command): void {
     .helpOption('-h, --help', 'Show this help message')
     .option('--envelope <file>', 'Run envelope JSON from claude -p')
     .option('--writes <file>', 'Newline-delimited paths the session wrote')
+    .option(
+      '--escapes <file>',
+      'Newline-delimited paths written to a watched toolkit root, for escape scope',
+    )
+    .option(
+      '--escapes-watched',
+      'At least one watched root held a target this run, so a zero-escape file is a clean watch rather than one with nothing to watch',
+    )
     .option('--json', 'Emit the verdict as JSON on stdout')
     .option('--strict', 'Exit non-zero when the arm declares no expectation')
     .addHelpText(

package/src/pr/bijection.ts

@@ -0,0 +1,145 @@
+import { extractKeyChangePaths, KEY_CHANGES, type PathClaim } from '@/pr/paths'
+
+/**
+ * Why the comparison produced no reading.
+ *
+ * The three are apart because each names a different repair. `no-section` is a
+ * body missing the heading, `no-claims` is the extractor failing over a section
+ * full of prose, and `no-changes` is a pull request with no files. Folding any
+ * of them into a clean pass is the failure this check exists to prevent, since
+ * a reader cannot tell a check that found nothing from one that read nothing.
+ */
+export type BijectionRefusal = 'no-section' | 'no-claims' | 'no-changes'
+
+export interface BijectionReport {
+  readonly kind: 'measured'
+  /** The commit the changed set was read at, which a finding has to name. */
+  readonly head: string | undefined
+  readonly changed: readonly string[]
+  readonly claims: readonly PathClaim[]
+  /**
+   * Anchored claims no changed file answers, which is the graded direction. A
+   * bullet naming an untouched file is wrong more often than not, and this
+   * corpus reported zero of them across 23 correct bodies.
+   */
+  readonly unmet: readonly PathClaim[]
+  /**
+   * Claims whose first segment names no entry in the tree, so the comparison
+   * could not judge them either way. Reported so a run says what it declined
+   * rather than counting a partial spelling as met.
+   */
+  readonly unresolved: readonly PathClaim[]
+  /**
+   * Changed files no claim reaches. Reported without a severity, since the
+   * class covers a real omission and equally a lockfile, a generated asset, or
+   * a regenerated index that legitimately earns no bullet.
+   */
+  readonly unnamed: readonly string[]
+}
+
+export type Bijection =
+  | BijectionReport
+  | { readonly kind: 'refused'; readonly reason: BijectionRefusal }
+
+export interface BijectionInput {
+  readonly body: string
+  readonly changed: readonly string[]
+  /** Top-level entries the tree holds, which decides what counts as anchored. */
+  readonly roots: ReadonlySet<string>
+  readonly head?: string
+  readonly title?: string
+}
+
+/**
+ * Whether one changed path is the file, or a file under the folder, a claim
+ * names.
+ *
+ * An unanchored claim matches on a segment-anchored suffix, which is what lets
+ * `claude-worker/SKILL.md` credit `claude/skills/claude-worker/SKILL.md`. That
+ * asymmetry is deliberate: a partial spelling can confirm a changed file was
+ * named and never accuse one of being absent, because nothing here separates a
+ * path written short from a path written wrong.
+ */
+function covers(claim: PathClaim, path: string): boolean {
+  if (claim.directory) {
+    return claim.anchored
+      ? path.startsWith(claim.path)
+      : path.includes(`/${claim.path}`)
+  }
+  if (path === claim.path) return true
+  return !claim.anchored && path.endsWith(`/${claim.path}`)
+}
+
+/**
+ * Compares what a pull request body claims to have changed against what it
+ * actually changed, in both directions.
+ *
+ * The two directions are reported apart because they want different
+ * tolerances. A claim nobody made good on is a defect in the record that
+ * squash-merges onto the trunk, and a changed file nobody recorded is often
+ * correct. Merging them into one count would either grade the second or excuse
+ * the first.
+ *
+ * Pure, so the whole judgment is testable against a fixture. The caller reads
+ * the body, the changed set, and the tree roots and hands all three in.
+ */
+export function compareKeyChanges(input: BijectionInput): Bijection {
+  if (input.changed.length === 0)
+    return { kind: 'refused', reason: 'no-changes' }
+
+  const read = extractKeyChangePaths(
+    input.body,
+    input.roots,
+    input.title ?? KEY_CHANGES,
+  )
+  if (read.kind === 'no-section')
+    return { kind: 'refused', reason: 'no-section' }
+  if (read.claims.length === 0) return { kind: 'refused', reason: 'no-claims' }
+
+  const unmet: PathClaim[] = []
+  const unresolved: PathClaim[] = []
+  const named = new Set<string>()
+
+  for (const claim of read.claims) {
+    const hits = input.changed.filter((path) => covers(claim, path))
+    for (const path of hits) named.add(path)
+    if (hits.length > 0) continue
+    if (claim.anchored) unmet.push(claim)
+    else unresolved.push(claim)
+  }
+
+  return {
+    kind: 'measured',
+    head: input.head,
+    changed: [...input.changed],
+    claims: read.claims,
+    unmet,
+    unresolved,
+    unnamed: input.changed.filter((path) => !named.has(path)),
+  }
+}
+
+/**
+ * The top-level folders a claim may be anchored on: the first segment of every
+ * path the tree holds, plus the first segment of every changed path.
+ *
+ * The changed half is what admits a folder this branch created. Reading the
+ * tree alone would mark every claim under a new top-level directory unanchored,
+ * and an unanchored claim never accuses, so the first branch to open one would
+ * silently lose the graded direction.
+ *
+ * A path with no folder above it contributes nothing, since a claim carrying no
+ * slash never reaches the extractor's output and no root would ever be read
+ * against it.
+ */
+export function treeRoots(
+  tracked: readonly string[],
+  changed: readonly string[],
+): Set<string> {
+  const roots = new Set<string>()
+  for (const path of [...tracked, ...changed]) {
+    const at = path.indexOf('/')
+    if (at > 0) roots.add(path.slice(0, at))
+  }
+  return roots
+}

package/src/pr/paths.ts

@@ -0,0 +1,335 @@
+/**
+ * The heading whose bullets state what a branch changed.
+ *
+ * Read alone, and never widened to a sibling section. `## Technical Context`
+ * legitimately names files a branch never touched, such as an install stamp
+ * inside a target, so a reader that took the whole body would manufacture a
+ * finding out of every argument the author made for the change.
+ */
+export const KEY_CHANGES = 'Key Changes'
+
+/** What one bullet claimed, kept with its bullet so a finding can quote it. */
+export interface PathClaim {
+  /** Repository-relative, with a trailing slash kept on a directory claim. */
+  readonly path: string
+  /** True when the span named a folder, which covers every file beneath it. */
+  readonly directory: boolean
+  /**
+   * True when the first segment names an entry the tree actually holds.
+   *
+   * An unanchored claim is a path written partially, such as
+   * `claude-worker/SKILL.md` for a file under `claude/skills/`. It can confirm
+   * that a changed file was named and can never accuse one of being absent,
+   * because the comparison has no way to tell a partial spelling from a
+   * genuinely wrong one.
+   */
+  readonly anchored: boolean
+  /** The span exactly as the body wrote it, before the line suffix came off. */
+  readonly span: string
+  /** One-based index of the bullet inside the section. */
+  readonly bullet: number
+  /** The bullet, trimmed, so a finding names the sentence it came from. */
+  readonly preview: string
+}
+
+export type KeyChangeRead =
+  | {
+      readonly kind: 'read'
+      readonly claims: readonly PathClaim[]
+      /** Bullets the section carried, so an empty claim set is separable. */
+      readonly bullets: number
+    }
+  | { readonly kind: 'no-section' }
+
+/** The longest bullet a claim carries forward, matching the citation sweep. */
+const PREVIEW_LIMIT = 200
+
+/** A backticked span, the only carrier this corpus writes a path in. */
+const BACKTICKED = /`([^`\n]+)`/g
+
+/** A list item at any indent, in either bullet spelling or as an ordinal. */
+const BULLET = /^\s*(?:[-*+]|\d+\.)\s+(.*)$/
+
+const FENCE = /^\s*(?:```|~~~)/
+
+const HEADING = /^(#{1,6})\s+(.+?)\s*$/
+
+/**
+ * A `file.ts:42` or `file.ts:42-58` suffix, which is a reader's click target
+ * rather than part of the name.
+ */
+const LINE_SUFFIX = /:\d+(?:-\d+)?$/
+
+/**
+ * A character that puts the span outside a path this comparison resolves.
+ *
+ * Whitespace separates a backticked command from a backticked path, and it is
+ * the whole answer to one of the four observed false-positive classes:
+ * `aitk markdown audit .claude/rules --json` carries a slash and names no file.
+ * Angle brackets answer a second, since `.claude/plans/feature-<slug>.md`
+ * describes a shape rather than naming a file. A glob and a caret describe a
+ * shape too, `^src/` being a grep pattern one body spelled in Key Changes, and
+ * a leading anchor names something outside this repository.
+ *
+ * Deliberately not shared with `classifySpan` in `@/gov/citations`, which asks
+ * a different question. That sweep resolves what a rule points a reader at,
+ * against the filesystem, with a sibling resolving inside the citing rule's own
+ * folder. This one resolves what a bullet claims to have changed, against a
+ * changed-file list, and it admits a folder where that sweep declines one.
+ */
+function isNotRepositoryPath(span: string): boolean {
+  if (/[\s<>$*|?^]/.test(span)) return true
+  if (span.includes('://')) return true
+  return /^[/~@#!]/.test(span)
+}
+
+/**
+ * Whether the span's last segment carries a file extension.
+ *
+ * The extension has to start with a letter, which is what keeps `127.0.0.1`
+ * out. A bare dotted number reaching the comparison is the shape that put
+ * `src/serve/127.0.0.1` in a report over a body that was correct.
+ */
+function hasExtension(span: string): boolean {
+  const segment = span.slice(span.lastIndexOf('/') + 1)
+  return /\.[A-Za-z][A-Za-z0-9]*$/.test(segment)
+}
+
+/** Blanks every backticked span so a cue search never fires inside one. */
+function maskSpans(text: string): string {
+  return text.replace(/`[^`\n]*`/g, (span) => ' '.repeat(span.length))
+}
+
+/**
+ * The part of a bullet that asserts a change, which ends at its first comma.
+ *
+ * This is the one lever that separates a claim from a mention, and it was
+ * chosen by measurement rather than by grammar. Over the 23 merged pull
+ * requests in this repository that carry the section, reading whole bullets
+ * reported 16 paths as claimed-but-untouched and every one of them was a file
+ * the body named for context. Cutting at the comma left 110 claims of the
+ * original 149 and took the false reports to 2. A list of clause-opening words
+ * tried beside it (`which`, `since`, `because`, `rather than`, and eleven more)
+ * removed nothing the comma had not already removed, because this corpus
+ * punctuates every one of them.
+ *
+ * What it costs is a claim in a second coordinated clause, as in "Add `x` to
+ * `a.ts`, and delete the old inline `y` from `b.ts`", where `b.ts` stops being
+ * claimed and falls to the unnamed direction instead. That direction reports
+ * without grading, so the cost lands where it does no damage.
+ */
+function claimRegion(bullet: string): string {
+  const at = maskSpans(bullet).indexOf(',')
+  return at === -1 ? bullet : bullet.slice(0, at)
+}
+
+/**
+ * A claim region that asserts nothing changed.
+ *
+ * A body writes such a bullet to record a decision it declined, and the path it
+ * names is the file it deliberately did not touch, which is the exact inverse
+ * of a claim. `#1274` opens one with "Leave `...expect.toml` untouched" and the
+ * path sits ahead of the first comma, so the region cut cannot reach it: a
+ * stricter cut would not catch this and a looser one would find more.
+ *
+ * The marker rather than the leading verb decides it, because `keep` and
+ * `leave` both open a real claim often enough and neither is safe alone. The
+ * set is deliberately three words. `in place` was measured and dropped, since
+ * rewriting a file in place is an ordinary claim, and `no other line` was
+ * dropped because `#1269` writes "as one insertion that touches no other line"
+ * about a change it did make. `alone` was in the set and came out on review:
+ * every occurrence across the 40-pull-request corpus sits past the first
+ * comma, where the region cut already excludes it, so the word caught nothing
+ * real there. Kept, it turns restrictive on a comma-free bullet, which is this
+ * repository's more common use of the word: "Move the threshold read into
+ * `src/gate/stages.ts` alone." asserts an edit and voided to an empty claim
+ * set while the word was in the set, unlike the other three, which disclaim
+ * wherever they land.
+ */
+const NO_CHANGE =
+  /\b(?:untouched|unchanged)\b|\bas written\b|^\s*(?:do not|don't|never)\b/i
+
+function disclaimsChange(region: string): boolean {
+  return NO_CHANGE.test(maskSpans(region))
+}
+
+/**
+ * The lines under a heading, ending at the next heading of the same level or
+ * higher. Undefined when the body carries no such heading, which the caller
+ * reports rather than reading as an empty section.
+ */
+export function readSection(body: string, title: string): string | undefined {
+  const lines = body.replace(/\r\n/g, '\n').split('\n')
+  const wanted = title.toLowerCase()
+
+  let start = -1
+  let level = 0
+  let fenced = false
+
+  for (const [index, line] of lines.entries()) {
+    if (FENCE.test(line)) {
+      fenced = !fenced
+      continue
+    }
+    if (fenced) continue
+    const heading = line.match(HEADING)
+    if (heading === null) continue
+    if ((heading[2] ?? '').toLowerCase() !== wanted) continue
+    start = index + 1
+    level = (heading[1] ?? '').length
+    break
+  }
+
+  if (start === -1) return undefined
+
+  const out: string[] = []
+  fenced = false
+  for (const line of lines.slice(start)) {
+    if (FENCE.test(line)) fenced = !fenced
+    const heading = fenced ? null : line.match(HEADING)
+    if (heading !== null && (heading[1] ?? '').length <= level) break
+    out.push(line)
+  }
+
+  return out.join('\n')
+}
+
+/**
+ * Splits a section into bullets, folding a wrapped continuation line into the
+ * bullet above it and starting a new one at every list marker.
+ *
+ * A nested bullet is its own bullet rather than part of its parent, which keeps
+ * one claim region per claim a reader sees.
+ */
+function splitBullets(section: string): string[] {
+  const bullets: string[] = []
+  let current: string[] | undefined
+  let fenced = false
+
+  for (const line of section.split('\n')) {
+    if (FENCE.test(line)) {
+      fenced = !fenced
+      current?.push(line)
+      continue
+    }
+
+    const marker = fenced ? null : line.match(BULLET)
+    if (marker !== null) {
+      if (current !== undefined) bullets.push(current.join(' '))
+      current = [marker[1] ?? '']
+      continue
+    }
+
+    if (current === undefined) continue
+    if (!fenced && line.trim() === '') {
+      bullets.push(current.join(' '))
+      current = undefined
+      continue
+    }
+    current.push(line.trim())
+  }
+
+  if (current !== undefined) bullets.push(current.join(' '))
+  return bullets
+}
+
+/** What one span resolved to, or nothing when it names no comparable path. */
+interface ResolvedSpan {
+  readonly path: string
+  readonly directory: boolean
+}
+
+function resolveSpan(span: string): ResolvedSpan | undefined {
+  if (span === '' || isNotRepositoryPath(span)) return undefined
+
+  // A bare name is the fourth observed false-positive class and it drops
+  // outright. Resolved as a sibling of a path earlier in the bullet it produced
+  // seven wrong paths across this corpus against two right ones, because a
+  // compound bullet names a sibling folder as often as a sibling file. Dropping
+  // it under-reports in the unnamed direction and never fires in the other.
+  if (!span.includes('/')) return undefined
+
+  if (span.endsWith('/')) {
+    // A single top-level folder is never a claim. Nobody reports having changed
+    // the whole of `src/`, and every body that spelled one was naming where
+    // something lives.
+    return span.indexOf('/') === span.length - 1
+      ? undefined
+      : { path: span, directory: true }
+  }
+
+  return hasExtension(span) ? { path: span, directory: false } : undefined
+}
+
+/**
+ * Every path the `## Key Changes` section claims a change to.
+ *
+ * `roots` names the entries the tree holds at its top level, which is what
+ * separates a whole path from one written partially. It is passed in rather
+ * than read here so the extractor stays a pure function of the body, and there
+ * is no default: an absent set would silently mark every claim anchored, which
+ * is the direction that accuses.
+ *
+ * Reports `no-section` rather than an empty read when the heading is absent,
+ * and an empty claim set with a bullet count when the heading is there and
+ * nothing resolved. The caller needs those apart. A body with no section states
+ * nothing, a section that produced no claim is this extractor failing over
+ * prose, and only a section that produced claims supports a comparison. An
+ * empty extraction read as a clean pass is the failure shape this repository
+ * has already recorded twice.
+ */
+export function extractKeyChangePaths(
+  body: string,
+  roots: ReadonlySet<string>,
+  title: string = KEY_CHANGES,
+): KeyChangeRead {
+  const section = readSection(body, title)
+  if (section === undefined) return { kind: 'no-section' }
+
+  const bullets = splitBullets(section)
+  const claims: PathClaim[] = []
+  const seen = new Set<string>()
+
+  for (const [index, bullet] of bullets.entries()) {
+    const trimmed = bullet.trim()
+    const preview =
+      trimmed.length > PREVIEW_LIMIT
+        ? `${trimmed.slice(0, PREVIEW_LIMIT)}…`
+        : trimmed
+    const region = claimRegion(trimmed)
+    if (disclaimsChange(region)) continue
+
+    let claimed = false
+
+    for (const match of region.matchAll(BACKTICKED)) {
+      const span = match[1] ?? ''
+      const bare = span.replace(LINE_SUFFIX, '')
+
+      // A `file:line` span following another claim in the same bullet is a
+      // citation into a file being described rather than a second claim, which
+      // is what "the stages at `verify.sh:634` and `:642`" is doing inside a
+      // bullet whose claim is the context entry that describes them. Leading
+      // its bullet it is an ordinary claim, which is how a body names the exact
+      // line it rewrote.
+      const cited = bare !== span
+      if (cited && claimed) continue
+
+      const resolved = resolveSpan(bare)
+      if (resolved === undefined) continue
+      claimed = true
+      if (seen.has(resolved.path)) continue
+      seen.add(resolved.path)
+
+      claims.push({
+        path: resolved.path,
+        directory: resolved.directory,
+        anchored: roots.has(resolved.path.slice(0, resolved.path.indexOf('/'))),
+        span,
+        bullet: index + 1,
+        preview,
+      })
+    }
+  }
+
+  return { kind: 'read', claims, bullets: bullets.length }
+}