@erclx/aitk 3.51.1 → 3.52.1

package/src/gate/stages.ts

@@ -0,0 +1,412 @@
+import {
+  auditSet,
+  heroStamp,
+  markdownBans,
+  type Measure,
+  pluginManifests,
+  sandboxCoverage,
+  seedStandards,
+  standardCriteria,
+  unreferencedRules,
+} from '@/gate/measures'
+
+/**
+ * One thing a stage does, as an argument vector rather than a shell line.
+ *
+ * The script this replaces held every check as text and handed it to `eval`,
+ * which made each stage a quoting question: whether the string wanted a shell
+ * or was an argument list that should never see one. Nothing in the set turned
+ * out to depend on expansion once the drift assertion stopped being a shell
+ * line, so the whole table is vectors and the hazard is gone rather than
+ * carried forward.
+ */
+export type Check =
+  /** Any binary on PATH, or a script named by path under the project root. */
+  | {
+      readonly kind: 'command'
+      readonly argv: readonly string[]
+      readonly failure: string
+    }
+  /** This checkout's own CLI, so a worktree gate never reads the main tree. */
+  | {
+      readonly kind: 'cli'
+      readonly argv: readonly string[]
+      readonly failure: string
+    }
+  /**
+   * A regenerated surface asserted against the index and the working tree.
+   *
+   * Both halves are read, since a regen emitting a file nobody ever committed
+   * satisfies a diff and fails here. The pathspec is one argument rather than a
+   * shell word, which is what git already receives: `*` matches a slash in a
+   * pathspec, so `*index.md` reaches a nested index the way it always did.
+   */
+  | {
+      readonly kind: 'drift'
+      readonly pathspec: string
+      readonly failure: string
+    }
+  /** A reading whose verdict is a comparison rather than an exit code. */
+  | { readonly kind: 'measure'; readonly measure: Measure }
+
+export interface Stage {
+  readonly id: string
+  /** The heading this stage prints, matching the frame it replaces. */
+  readonly label: string
+  /**
+   * The changed-file pattern this stage needs before it runs. Absent means the
+   * stage always runs, which is correct wherever the input is diffuse enough
+   * that no path predicts it.
+   */
+  readonly scope?: RegExp
+  /** What a scoped-out stage says, so a skip never reads as a pass. */
+  readonly skipped?: string
+  /**
+   * Whether this stage belongs in the run at all, read off the write grant
+   * rather than the changed set. Absent means it always belongs.
+   */
+  readonly when?: (options: { readonly write: boolean }) => boolean
+  readonly checks: readonly Check[]
+  /** The line a clean stage prints, where the checks emit none of their own. */
+  readonly success?: string
+}
+
+/**
+ * Corpora a `src/` test asserts over from outside `src/`, censused in
+ * `.claude/context/development/verification.md`. This list and that census are
+ * two copies of one set with nothing comparing them, so a corpus joining the
+ * census joins this list in the same change. The first four are directory
+ * prefixes because their tests walk the tree whole, which is what reaches a
+ * rule or a skill a branch adds rather than edits.
+ */
+export const TEST_CORPORA_PATTERNS = [
+  '^claude/skills/',
+  '^governance/rules/',
+  '^\\.claude/hooks/',
+  '^tooling/claude/seeds/\\.claude/hooks/',
+  '^standards/markdown\\.md$',
+  '^tooling/base/reference\\.md$',
+  '^tooling/web/configs/scripts/worktree-port\\.sh$',
+  '^\\.cspell/banned-spellings\\.txt$',
+  '^scripts/lib/worktree\\.sh$',
+  '^scripts/core/check-ignore-parity\\.sh$',
+]
+
+const TESTS_SCOPE = new RegExp(
+  [
+    '^src/',
+    '^vitest\\.config\\.ts$',
+    '^tsconfig\\.json$',
+    '^package\\.json$',
+    ...TEST_CORPORA_PATTERNS,
+  ].join('|'),
+)
+
+const script = (name: string, failure: string): Check => ({
+  kind: 'command',
+  argv: ['bash', `scripts/core/${name}`],
+  failure,
+})
+
+/**
+ * Every stage the gate runs, in the order it runs them.
+ *
+ * Order is the product here rather than an accident of the file. The four
+ * regenerating stages run before anything reads what they wrote, the stages
+ * calling this checkout's CLI sit together so a reader meets one group rather
+ * than the same kind of stage at intervals, and the three scoped stages sit
+ * last where a skip costs the run nothing it already paid for.
+ *
+ * A stage halts the run when one of its checks fails, so clearing a
+ * regenerate-then-assert stage reveals the next one behind it rather than the
+ * whole set at once.
+ */
+export const STAGES: readonly Stage[] = [
+  {
+    id: 'format',
+    label: 'Formatting',
+    when: ({ write }) => write,
+    checks: [
+      {
+        kind: 'command',
+        argv: ['bun', 'run', 'format'],
+        failure: 'Format failed',
+      },
+    ],
+    success: 'Format applied',
+  },
+  {
+    id: 'format-check',
+    label: 'Format check',
+    when: ({ write }) => !write,
+    checks: [
+      {
+        kind: 'command',
+        argv: ['bun', 'run', 'check:format'],
+        failure: 'Format check failed',
+      },
+    ],
+    success: 'Format check passed',
+  },
+  {
+    id: 'indexes',
+    label: 'Indexes',
+    checks: [
+      script('regen-indexes.sh', 'Index regen failed'),
+      {
+        kind: 'drift',
+        pathspec: '*index.md',
+        failure:
+          'Indexes drifted. Run bun run check and commit the updated index files.',
+      },
+    ],
+    success: 'Indexes clean',
+  },
+  {
+    id: 'consumed-copies',
+    label: 'Consumed copies',
+    checks: [
+      script('regen-claude-copies.sh', 'Consumed-copy regen failed'),
+      {
+        kind: 'drift',
+        pathspec: '.claude/rules',
+        failure:
+          'Consumed copies drifted. Run bun run check and commit .claude/rules.',
+      },
+    ],
+    success: 'Consumed copies clean',
+  },
+  {
+    // Only the markup is asserted for drift. The image beside it is a chromium
+    // render whose bytes move with the browser version, so a drift check over it
+    // would fail on a machine whose chromium differs rather than on a stale
+    // count. The stamp measure below is what covers the image instead.
+    id: 'hero',
+    label: 'Hero',
+    checks: [
+      script('regen-hero.sh', 'Hero regen failed'),
+      {
+        kind: 'drift',
+        pathspec: 'assets/hero.html',
+        failure:
+          'Hero counts drifted. Run bun run check, then aitk capture assets/hero.html, and commit assets/hero.html with assets/hero.png and assets/hero.stamp.',
+      },
+      { kind: 'measure', measure: heroStamp },
+    ],
+    success: 'Hero clean',
+  },
+  {
+    id: 'tooling-paths',
+    label: 'Tooling paths',
+    checks: [
+      script('regen-tooling-paths.sh', 'Tooling-path regen failed'),
+      {
+        kind: 'drift',
+        pathspec: 'claude/skills/aitk-cli/SKILL.md',
+        failure:
+          'The overwrite contract drifted from what the stacks hold. Run bun run check and commit claude/skills/aitk-cli/SKILL.md.',
+      },
+    ],
+    success: 'Tooling paths clean',
+  },
+  {
+    // The claude manifest is the only route a target's ignore set travels, and
+    // it is hand-maintained beside this repository's own `.gitignore` with
+    // nothing comparing the two. A drift between them reaches every target on
+    // the next `aitk tooling sync` and surfaces to nobody, which is why this
+    // gates rather than reports. It is not a drift assert: no generator
+    // produces either list, so there is nothing to regenerate and diff.
+    id: 'ignore-parity',
+    label: 'Ignore parity',
+    checks: [
+      script(
+        'check-ignore-parity.sh',
+        "The ignore set a target receives disagrees with this repository's own.",
+      ),
+    ],
+    success: 'Ignore parity clean',
+  },
+  {
+    id: 'skill-paths',
+    label: 'Skill paths',
+    checks: [
+      script(
+        'check-skill-paths.sh',
+        'Shipped skills reference a repo-local path.',
+      ),
+    ],
+    success: 'Skill paths clean',
+  },
+  {
+    id: 'plugin-boundary',
+    label: 'Plugin boundary',
+    checks: [
+      script(
+        'check-plugin-boundary.sh',
+        'Plugin ships toolkit-internal content.',
+      ),
+    ],
+    success: 'Plugin boundary clean',
+  },
+  {
+    // Seed prose is installed into every scaffolded project and read there as
+    // instruction about that project, so a line naming this repository's CLI
+    // hands a target a verb it may not be able to run. This gates for the
+    // reason the seed-standards stage below gates: a defect authored once
+    // propagates into every project scaffolded after it.
+    id: 'seed-independence',
+    label: 'Seed independence',
+    checks: [
+      script('check-seed-independence.sh', 'Seed prose cites the toolkit CLI.'),
+    ],
+    success: 'Seed prose cites no toolkit CLI',
+  },
+  {
+    // A stack entry naming a rule folder takes every rule in it, which is what
+    // stops a new rule from needing a second edit to reach a target. The
+    // failure it leaves open is a rule authored into a folder no stack names,
+    // which `aitk gov install` never reaches on its own.
+    id: 'unreferenced-rules',
+    label: 'Unreferenced rules',
+    checks: [{ kind: 'measure', measure: unreferencedRules }],
+  },
+  {
+    // Only the citation half of the audit gates. Length, depth, table, and
+    // index findings are judgment thresholds, and failing a push on one would
+    // make the stage something to route around.
+    id: 'context-citations',
+    label: 'Context citations',
+    checks: [
+      {
+        kind: 'cli',
+        argv: ['context', 'audit', '--citations-only'],
+        failure:
+          'A cited context path does not resolve. Run bun src/cli.ts context audit.',
+      },
+    ],
+    success: 'Context citations resolve',
+  },
+  {
+    // A rule citing a file that moved fails silently. The consumed-copy drift
+    // stage passes an authored rule and its copy that are wrong together, and
+    // nothing else resolves the path until a session opens it. A rule whose
+    // frontmatter glob names a directory that moved fails the same way, by
+    // never firing again. The classes where absence is correct are separated
+    // inside the verb rather than left as a threshold here.
+    id: 'rule-citations',
+    label: 'Rule citations',
+    checks: [
+      {
+        kind: 'cli',
+        argv: ['gov', 'citations'],
+        failure:
+          'A path a rule cites, or an internal frontmatter glob, does not resolve. Run bun src/cli.ts gov citations.',
+      },
+    ],
+    success: 'Rule citations resolve',
+  },
+  {
+    id: 'markdown-bans',
+    label: 'Markdown bans',
+    checks: [{ kind: 'measure', measure: markdownBans }],
+  },
+  {
+    id: 'seed-standards',
+    label: 'Seed standards',
+    checks: [{ kind: 'measure', measure: seedStandards }],
+  },
+  {
+    // Presence of a required file is a fact, so it gates. The name,
+    // description, folder, and requirement-section measures beside it report
+    // and are read from a bare run.
+    id: 'skill-requirements',
+    label: 'Skill requirements',
+    checks: [
+      {
+        kind: 'cli',
+        argv: ['claude', 'skills', 'audit', '--requirements-only'],
+        failure:
+          'A skill folder carries no REQUIREMENT.md. Run bun src/cli.ts claude skills audit.',
+      },
+    ],
+    success: 'Skill requirements present',
+  },
+  {
+    id: 'standard-criteria',
+    label: 'Standard success criteria',
+    checks: [{ kind: 'measure', measure: standardCriteria }],
+  },
+  {
+    id: 'sandbox-coverage',
+    label: 'Sandbox coverage',
+    checks: [{ kind: 'measure', measure: sandboxCoverage }],
+  },
+  {
+    id: 'audit-set',
+    label: 'Audit set',
+    checks: [{ kind: 'measure', measure: auditSet }],
+  },
+  {
+    id: 'plugin-manifests',
+    label: 'Plugin manifests',
+    checks: [{ kind: 'measure', measure: pluginManifests }],
+  },
+  {
+    id: 'spelling',
+    label: 'Spelling',
+    checks: [
+      {
+        kind: 'command',
+        argv: ['bun', 'run', 'check:spell'],
+        failure: 'Spell check failed',
+      },
+    ],
+    success: 'Spell check passed',
+  },
+  {
+    id: 'shell',
+    label: 'Shell',
+    scope: /\.sh$|^package\.json$/,
+    skipped: 'Skipped, no shell changes',
+    checks: [
+      {
+        kind: 'command',
+        argv: ['bun', 'run', 'check:shell'],
+        failure: 'Shell check failed',
+      },
+      script(
+        'check-color-source.sh',
+        'A color escape is defined outside scripts/lib/ui.sh.',
+      ),
+    ],
+    success: 'Shell check passed',
+  },
+  {
+    id: 'types',
+    label: 'Types',
+    scope: /^src\/|^tsconfig\.json$|^package\.json$/,
+    skipped: 'Skipped, no TypeScript changes',
+    checks: [
+      {
+        kind: 'command',
+        argv: ['bun', 'run', 'check:types'],
+        failure: 'Typecheck failed',
+      },
+    ],
+    success: 'Typecheck passed',
+  },
+  {
+    id: 'tests',
+    label: 'Tests',
+    scope: TESTS_SCOPE,
+    skipped: 'Skipped, no TypeScript or asserted-corpus changes',
+    checks: [
+      {
+        kind: 'command',
+        argv: ['bun', 'run', 'test'],
+        failure: 'Tests failed',
+      },
+    ],
+    success: 'Tests passed',
+  },
+]

package/src/sessions/registry.ts

@@ -21,6 +21,23 @@ export interface SessionRecord {
   readonly sessionId: string | undefined
   readonly kind: string | undefined
   readonly status: string | undefined
+  /**
+   * The epoch millisecond the client last changed `status`. Measured against
+   * the live registry, 23 of 341 usable records carry it, and the one record
+   * that has ever carried `status: "waiting"` is not among them, so its
+   * absence tracks a client version rather than a record's age alone.
+   * Declared here rather than read opportunistically off the parsed object,
+   * since this file is what states what the domain reads and an undeclared
+   * field read anyway is the drift this domain exists downstream of.
+   */
+  readonly statusUpdatedAt: number | undefined
+  /**
+   * The epoch millisecond the client last wrote the record at all, a coarser
+   * stamp than `statusUpdatedAt` that a client writes whether or not it also
+   * stamps the status change itself. Declared as the fallback dwell source
+   * for a record predating the narrower field, per the same reasoning above.
+   */
+  readonly updatedAt: number | undefined
   readonly startedAt: number | undefined
   /**
    * The process start time the client stamped at launch, compared against the

package/src/sessions/resolve.ts

@@ -23,6 +23,25 @@ export interface ResolvedSession {
   readonly kind: string
   readonly status: string
   readonly startedAt: string | null
+  /**
+   * The stamp the record carries beside `status`, kept alongside the dwell it
+   * computes below for a caller comparing two sessions rather than reading the
+   * age of one.
+   */
+  readonly statusUpdatedAt: string | null
+  /**
+   * Elapsed milliseconds since `statusUpdatedAt`, falling back to the coarser
+   * `updatedAt` when the record predates the narrower field, computed once at
+   * read time so three callers do not each convert the raw stamp and each get
+   * the clock-skew case wrong. The one record ever measured carrying
+   * `status: "waiting"` has exactly this shape: no `statusUpdatedAt`, an
+   * `updatedAt` beside it, so a caller reading this field alone would report
+   * the single real instance as unmeasured rather than as stalled.
+   * Clamped at zero rather than reported negative: a record stamped
+   * by a clock running ahead of this one is a skew to absorb, not a session
+   * that has not started waiting yet.
+   */
+  readonly statusDwellMs: number | null
   /**
    * The shared git directory every worktree of one repository resolves to,
    * which is what identifies the repository a row belongs to. A branch name is
@@ -52,6 +71,8 @@ export interface ResolveOptions {
   readonly dir?: string
   readonly probes?: LivenessProbes
   readonly locate?: (cwd: string) => Promise<Located>
+  /** The instant the dwell is computed against. Defaults to `Date.now`. */
+  readonly now?: () => number
 }
 
 export interface Located {
@@ -123,6 +144,17 @@ export async function repositoryOf(cwd: string): Promise<string | null> {
   return resolved.length > 0 ? resolved : null
 }
 
+/**
+ * Falls back to `updatedAt` when `statusUpdatedAt` is absent, since the
+ * narrower field is the newer of the two and a record predating it still
+ * carries the coarser one. The one record measured with `status: "waiting"`
+ * takes exactly this path: no `statusUpdatedAt`, an `updatedAt` beside it.
+ */
+function dwellMs(record: SessionRecord, now: number): number | null {
+  const stamp = record.statusUpdatedAt ?? record.updatedAt
+  return stamp === undefined ? null : Math.max(0, now - stamp)
+}
+
 /**
  * An absent field is rendered as an absence rather than as a value.
  *
@@ -131,7 +163,11 @@ export async function repositoryOf(cwd: string): Promise<string | null> {
  * for data. Null says the record did not carry it, which is the same
  * distinction the registry draws between an absent folder and an empty one.
  */
-function present(record: SessionRecord, located: Located): ResolvedSession {
+function present(
+  record: SessionRecord,
+  located: Located,
+  now: number,
+): ResolvedSession {
   return {
     name: record.name,
     pid: record.pid,
@@ -143,6 +179,11 @@ function present(record: SessionRecord, located: Located): ResolvedSession {
       record.startedAt === undefined
         ? null
         : new Date(record.startedAt).toISOString(),
+    statusUpdatedAt:
+      record.statusUpdatedAt === undefined
+        ? null
+        : new Date(record.statusUpdatedAt).toISOString(),
+    statusDwellMs: dwellMs(record, now),
     repository: located.repository,
     worktree: located.worktree,
     branch: located.branch,
@@ -167,6 +208,7 @@ export async function resolveSessions(
 ): Promise<SessionReport> {
   const probes = opts.probes ?? SYSTEM_PROBES
   const find = opts.locate ?? locate
+  const now = opts.now?.() ?? Date.now()
   const registry = readRegistry(opts.dir)
 
   if (registry.kind === 'absent') return { kind: 'absent', dir: registry.dir }
@@ -182,7 +224,7 @@ export async function resolveSessions(
   }
 
   const sessions = await Promise.all(
-    live.map(async (record) => present(record, await find(record.cwd))),
+    live.map(async (record) => present(record, await find(record.cwd), now)),
   )
 
   return { kind: 'resolved', dir: registry.dir, confidence, sessions }