@erclx/aitk 0.66.1 → 0.68.0

package/scripts/core/verify.sh

@@ -272,6 +272,40 @@ main() {
   run_check "cd $PROJECT_ROOT && bun src/cli.ts context audit --citations-only" "A cited context path does not resolve. Run bun src/cli.ts context audit."
   log_info "Context citations resolve"
 
+  # A banned character, word, or spelling is a fact rather than a threshold, so
+  # it fails the push while bullet, paragraph, and depth weight stay advisory
+  # for the reason the stage above leaves its own thresholds so.
+  #
+  # The whole corpus is measured rather than the changed files, because a
+  # `Do not use` bullet added to a standard bans a token retroactively and no
+  # file in the push that adds it was edited.
+  #
+  # `--json` sends the record to stdout and the frame to stderr, so a passing
+  # run stays silent and a failing one is re-run for its frame rather than
+  # parsed out of a stream this script would have to strip. `bun src/cli.ts`
+  # rather than `aitk` for the reason the stage above uses it.
+  log_step "Markdown bans"
+  local ban_status=0 ban_frame
+  (cd "$PROJECT_ROOT" && bun src/cli.ts markdown audit --json >/dev/null 2>&1) || ban_status=$?
+  case $ban_status in
+  0)
+    log_info "No banned character, word, or spelling"
+    ;;
+  1)
+    log_warn "Skipped, the markdown audit refused and measured nothing"
+    ;;
+  2)
+    # `|| true` because the re-run exits non-zero by construction, and `set -e`
+    # would take the script down before log_error names the remedy.
+    ban_frame=$(cd "$PROJECT_ROOT" && bun src/cli.ts markdown audit 2>&1 || true)
+    echo "$ban_frame" | pipe_output
+    log_error "Markdown prose carries a banned character, word, or spelling. Rewrite the sentence, and reach for a code span only where the token is genuinely an identifier under discussion."
+    ;;
+  *)
+    log_error "The markdown audit exited $ban_status, which is neither a pass nor a finding."
+    ;;
+  esac
+
   # The stage above audits this repository. Its seed tree ships into every
   # scaffolded project, so a seed breaking the standard it seeds propagates
   # instead of sitting still, and no rule path reaches the tree to report it.

package/src/commands/markdown.ts

@@ -3,6 +3,7 @@ import { resolve } from 'node:path'
 import type { Command } from 'commander'
 import { type BanReport, banReport, loadStandards } from '@/markdown/bans'
 import { resolveMarkdown } from '@/markdown/files'
+import { isGating } from '@/markdown/gate'
 import { type BanFinding, bodyLines, scanBans } from '@/markdown/scan'
 import {
   type Checkpoints,
@@ -20,6 +21,8 @@ import {
   plural,
 } from '@/ui'
 
+const EXIT_GATE = 2
+
 interface AuditCommandOptions {
   readonly json?: boolean
 }
@@ -39,7 +42,7 @@ export function register(program: Command): void {
   markdown
     .command('audit')
     .description(
-      'Report the character bans, the word bans, and bullet, paragraph, and depth weight',
+      'Fail on a banned character, word, or spelling, and report bullet, paragraph, and depth weight',
     )
     .argument(
       '[path...]',
@@ -52,12 +55,18 @@ export function register(program: Command): void {
       [
         '',
         'Exit codes:',
-        '  0  the audit completed',
+        '  0  the audit completed with no gating finding',
         '  1  refused, with the reason on stderr',
+        '  2  a banned character, word, or spelling is present',
+        '',
+        'A ban hit is a fact and gates unconditionally. Bullet, paragraph, and',
+        'depth weight are judgments a reader settles, so all three report and',
+        'none of them fails a run.',
         '',
-        'Every finding reports and none gates. A banned character is a fact and',
-        'will gate once the corpus has been measured and fixed, which is the',
-        'follow-up rather than this command.',
+        'Rewrite the sentence carrying a hit rather than swapping the token for',
+        'a near-synonym. A code span clears the report and is the answer only',
+        'where the token is genuinely an identifier under discussion, which is',
+        'what markdown.md reserves the span for.',
         '',
         'Bans and checkpoints are read from markdown.md and prose.md, resolved',
         'under .claude/standards/ then standards/. No folder has to resolve and',
@@ -156,7 +165,12 @@ async function runAudit(
     )
   }
 
-  return 0
+  const gating = isGating({
+    bans: reports.flatMap((report) => report.bans),
+    structure: reports.map((report) => report.structure),
+  })
+
+  return gating ? EXIT_GATE : 0
 }
 
 function refuse(message: string): number {
@@ -218,6 +232,13 @@ function reportBans(reports: readonly FileReport[], bans: BanReport): void {
 
   const total = carrying.reduce((sum, report) => sum + report.bans.length, 0)
   logWarn(`${plural(total, 'hit')} across ${plural(carrying.length, 'file')}`)
+  logWarn('This fails the run. Every other check below reports.')
+  logInfo(
+    'Rewrite the sentence rather than swapping the token for a near-synonym.',
+  )
+  logInfo(
+    'A code span clears the report and is the answer only where the token is genuinely an identifier under discussion, which is what markdown.md reserves the span for.',
+  )
   pipeOutput(
     carrying
       .map(

package/src/commands/sync.ts

@@ -3,9 +3,13 @@ import { join } from 'node:path'
 import type { Command } from 'commander'
 import { cliPath, cliRun } from '@/cli-run'
 import { PROJECT_ROOT } from '@/exec'
-import { buildCheckReport, type CheckReport, hasDrift } from '@/sync/check'
+import {
+  buildCheckReport,
+  type CheckReport,
+  hasDrift,
+  SCANNED_DOMAINS,
+} from '@/sync/check'
 import { createGitRunner, createPullRequestOpener, hasGh } from '@/sync/git'
-import { STAMP_DOMAINS } from '@/sync/stamp'
 import {
   detectDomains,
   installedDomains,
@@ -133,6 +137,8 @@ function renderCheck(report: CheckReport): void {
     }
   }
 
+  renderTooling(report)
+
   for (const entry of report.unmigrated) {
     logStep(`${entry.domain} (not migrated)`)
     logWarn(
@@ -157,17 +163,56 @@ function renderCheck(report: CheckReport): void {
   }
 
   outro()
+  // Scanned domains only. Tooling renders a section on every managed target, so
+  // naming it here repeats what that section already said under a second
+  // remedy, where a scanned domain nobody installed has no section at all and
+  // this line is the only place it appears.
   const unmigrated = report.unmigrated.map((entry) => entry.domain)
-  const uncovered = STAMP_DOMAINS.filter(
+  const uncovered = SCANNED_DOMAINS.filter(
     (domain) => !report.covers.includes(domain) && !unmigrated.includes(domain),
   )
-  const unstamped =
-    uncovered.length === 0 ? '' : `Unstamped: ${uncovered.join(', ')}. `
+  if (uncovered.length === 0) return
+
   process.stderr.write(
-    `${GREY}${unstamped}Tooling is never stamped, run \`aitk tooling\` to reconcile configs.${NC}\n`,
+    `${GREY}Unstamped: ${uncovered.join(', ')}. Run the matching sync to record one.${NC}\n`,
   )
 }
 
+/**
+ * Tooling prints whether it was measured before it prints any count, because a
+ * target with no chain recorded produces the same zero a current target does.
+ * Naming the state is the whole reason the section exists.
+ */
+function renderTooling(report: CheckReport): void {
+  const { tooling } = report
+  logStep('tooling')
+
+  if (!tooling.measured) {
+    logWarn(
+      tooling.chain.length === 0
+        ? 'Not stamped. No chain recorded, so tooling drift is unmeasured.'
+        : `Recorded chain names no stack this toolkit ships: ${tooling.chain.join(' < ')}.`,
+    )
+    logInfo('Run `aitk tooling sync <stack>` to record what this target holds.')
+    return
+  }
+
+  logInfo(`Chain: ${tooling.chain.join(' < ')}`)
+  if (tooling.commit !== undefined) {
+    logInfo(`Synced from ${tooling.commit} on ${tooling.syncedAt}`)
+  }
+
+  if (tooling.changes === 0) {
+    logInfo('up to date')
+    return
+  }
+
+  for (const [category, count] of Object.entries(tooling.counts)) {
+    if (count > 0) logWarn(`${count} ${category}`)
+  }
+  logInfo('Run `aitk tooling sync` to reconcile these.')
+}
+
 /**
  * Seeds print their own section because no sync command applies them. A `stale`
  * seed is safe to take whole and a `drifted` one holds edits, which is the split

package/src/commands/tooling.ts

@@ -18,6 +18,7 @@ import {
   stackExists,
 } from '@/tooling/manifest'
 import { scan, type ScanResult } from '@/tooling/scan'
+import { recordToolingChain } from '@/tooling/stamp'
 import { intro, logAdd, logInfo, logStep, logWarn, outro, select } from '@/ui'
 
 const GREEN = '\x1b[0;32m'
@@ -219,6 +220,7 @@ async function runSync(
   report(result, includeReferences)
 
   if (result.totalChanges === 0) {
+    await stampChain(prepared.chain, prepared.target)
     outro()
     process.stderr.write(`${GREEN}✓ Everything up to date${NC}\n`)
     return 0
@@ -255,11 +257,35 @@ async function runSync(
     await applyReferences(prepared.chain, prepared.target, pending)
   }
 
+  await stampChain(prepared.chain, prepared.target)
+
   outro()
   process.stderr.write(`${GREEN}✓ Tooling sync complete${NC}\n`)
   return 0
 }
 
+/**
+ * Writes the chain after the copies land, so a partial apply that throws leaves
+ * the previous record rather than a claim the target does not meet.
+ */
+async function stampChain(chain: Manifest[], target: string): Promise<void> {
+  const recorded = await recordToolingChain(
+    PROJECT_ROOT,
+    target,
+    chain,
+    new Date(),
+  )
+
+  if (recorded) {
+    logInfo(`Recorded chain: ${chain.map((entry) => entry.name).join(' < ')}`)
+    return
+  }
+
+  logWarn(
+    'Workspace root: no chain recorded. Tooling reports unmeasured because the answer differs per package.',
+  )
+}
+
 async function runInject(
   stack: string,
   target: string,
@@ -290,6 +316,15 @@ async function runInject(
     await injectGitignore(prepared.chain, prepared.target)
   }
 
+  // Only a whole-stack inject records the chain. A flag-scoped run installs one
+  // category, and a chain recorded from it would send the report scanning for
+  // configs and deps the caller never asked to install. The claude stack is
+  // excluded here rather than in `prepare`, which is what keeps `aitk claude`
+  // able to drive injection while its stack stays out of the tooling record.
+  if (applyAll && !isStackExcluded(stack)) {
+    await stampChain(prepared.chain, prepared.target)
+  }
+
   if (framed) outro()
   return 0
 }

package/src/markdown/gate.ts

@@ -0,0 +1,28 @@
+import type { BanFinding } from '@/markdown/scan'
+import type { StructureReport } from '@/markdown/structure'
+
+export interface GateInput {
+  /** Every ban hit across every file measured, flattened. */
+  readonly bans: readonly BanFinding[]
+  /**
+   * Every structural measure the run made, read by nothing here.
+   *
+   * Naming it is what makes the split checkable: bullet, paragraph, and depth
+   * weight are judgments a reader settles, and a push failing on one teaches a
+   * contributor to route around the stage. A signature taking the ban list
+   * alone states the same rule and leaves no place to assert it.
+   */
+  readonly structure: readonly StructureReport[]
+}
+
+/**
+ * Whether the audit found something that should fail the caller.
+ *
+ * A banned character, word, or spelling is a fact rather than a threshold, so
+ * it gates unconditionally and there is no widened mode to reach for. The
+ * standards decide what counts as banned, which keeps this answering how many
+ * rather than which.
+ */
+export function isGating({ bans }: GateInput): boolean {
+  return bans.length > 0
+}

package/src/sync/check.ts

@@ -13,32 +13,47 @@ import {
 import { buildSeedsReport, type SeedsReport } from '@/sync/seeds-report'
 import {
   readStamp,
-  STAMP_DOMAINS,
   type Stamp,
+  stampedChain,
   stampedCommit,
   type StampDomain,
 } from '@/sync/stamp'
 import { createStandardsAdapter } from '@/standards/adapter'
 import { isDirectory } from '@/target'
+import { loadManifest } from '@/tooling/manifest'
+import { scan } from '@/tooling/scan'
+
+/**
+ * Domains the sync engine walks file by file. Tooling is a stamp domain without
+ * being one of these, because `src/tooling/` never calls `planSync`, so the
+ * three lookups below have no entry to offer it.
+ */
+export const SCANNED_DOMAINS = [
+  'standards',
+  'snippets',
+  'governance',
+] as const satisfies readonly StampDomain[]
+
+export type ScannedDomain = (typeof SCANNED_DOMAINS)[number]
 
 /**
  * The toolkit path whose commits change what each domain holds. `claude/skills/`
  * is deliberately absent: skills load live from the plugin directory, so they
  * never go stale and belong in the read-only section instead.
  */
-const SYNCED_SOURCES: Record<StampDomain, string> = {
+const SYNCED_SOURCES: Record<ScannedDomain, string> = {
   standards: 'standards/',
   snippets: 'snippets/',
   governance: 'governance/rules/',
 }
 
-const ADAPTERS: Record<StampDomain, (root: string) => SyncAdapter> = {
+const ADAPTERS: Record<ScannedDomain, (root: string) => SyncAdapter> = {
   standards: createStandardsAdapter,
   snippets: createSnippetsAdapter,
   governance: createGovAdapter,
 }
 
-const INSTALL_MARKERS: Record<StampDomain, readonly string[]> = {
+const INSTALL_MARKERS: Record<ScannedDomain, readonly string[]> = {
   standards: ['.claude', 'standards'],
   snippets: ['.claude', 'snippets'],
   governance: ['.claude', 'rules'],
@@ -54,7 +69,7 @@ export interface StateCounts {
 }
 
 export interface DomainReport {
-  readonly domain: StampDomain
+  readonly domain: ScannedDomain
   readonly stamped: boolean
   /** This domain's own anchor, not the target's most recent sync. */
   readonly commit?: string
@@ -74,11 +89,60 @@ export interface UpstreamCommit {
   readonly subject: string
 }
 
+/** Pending changes per category, from the same scan `aitk tooling sync` reads. */
+export interface ToolingCounts {
+  readonly configs: number
+  readonly seeds: number
+  readonly scripts: number
+  readonly deps: number
+  readonly gitignore: number
+  readonly references: number
+}
+
+/**
+ * Tooling's own section. `measured` is the field the report exists for: without
+ * it a target that never installed tooling and a target whose tooling is current
+ * both render as zero changes, which is a claim rather than an absence of one.
+ */
+export interface ToolingReport {
+  readonly measured: boolean
+  /**
+   * Stack names the install resolved, nearest first. Carried even when the
+   * report is unmeasured, so a chain naming stacks this toolkit no longer ships
+   * stays distinguishable from a target that recorded none.
+   */
+  readonly chain: readonly string[]
+  readonly commit?: string
+  readonly syncedAt?: string
+  readonly counts: ToolingCounts
+  readonly changes: number
+}
+
+const UNMEASURED_TOOLING: ToolingReport = {
+  measured: false,
+  chain: [],
+  counts: {
+    configs: 0,
+    seeds: 0,
+    scripts: 0,
+    deps: 0,
+    gitignore: 0,
+    references: 0,
+  },
+  changes: 0,
+}
+
 export interface CheckReport {
   readonly covers: readonly StampDomain[]
   /** False when the target is not a toolkit project, so every section stays empty. */
   readonly managed: boolean
   readonly domains: readonly DomainReport[]
+  /**
+   * Reported beside the domains rather than as one of them, because tooling
+   * carries no per-file entries and no upstream range, so it fills almost none
+   * of `DomainReport`.
+   */
+  readonly tooling: ToolingReport
   /**
    * Reported beside the domains rather than as one of them, because seeds carry
    * no stamp and produce no change. See `@/sync/seeds-report`.
@@ -89,12 +153,58 @@ export interface CheckReport {
   readonly newSkills: readonly string[]
 }
 
-export function installedStampDomains(target: string): StampDomain[] {
-  return STAMP_DOMAINS.filter((domain) =>
+export function installedStampDomains(target: string): ScannedDomain[] {
+  return SCANNED_DOMAINS.filter((domain) =>
     isDirectory(join(target, ...INSTALL_MARKERS[domain])),
   )
 }
 
+/**
+ * Reads the chain the install recorded and scans against those stacks rather
+ * than re-resolving from the leaf. A run that passed `--skip` installed fewer
+ * layers than the leaf's own chain reproduces, so re-resolving would report
+ * drift against a layer the target deliberately does not carry.
+ *
+ * A recorded stack the toolkit no longer ships resolves to nothing, and a chain
+ * where none resolve reads as unmeasured. Scanning the survivors would measure
+ * against a chain neither side agrees on.
+ */
+export function buildToolingReport(
+  toolkitRoot: string,
+  target: string,
+  stamp: Stamp | undefined,
+): ToolingReport {
+  const chain = stampedChain(stamp)
+  const manifests = chain
+    .map((name) => loadManifest(toolkitRoot, name))
+    .filter((manifest) => manifest !== undefined)
+
+  if (manifests.length === 0) return { ...UNMEASURED_TOOLING, chain }
+
+  const result = scan(manifests, target, { includeReferences: true })
+  const record = stamp?.domains.tooling
+
+  return {
+    measured: true,
+    chain,
+    commit: record?.commit,
+    syncedAt: record?.syncedAt,
+    counts: {
+      configs: result.configs.filter((entry) => entry.state !== 'matching')
+        .length,
+      seeds: result.seeds.filter((entry) => entry.state === 'missing').length,
+      scripts: result.scripts.filter((entry) => entry.state !== 'matching')
+        .length,
+      deps: result.deps.filter((entry) => entry.state === 'missing').length,
+      gitignore: result.gitignore.filter((entry) => entry.state === 'missing')
+        .length,
+      references: result.references.filter((entry) => entry.state === 'pending')
+        .length,
+    },
+    changes: result.totalChanges,
+  }
+}
+
 /**
  * Whether the target is a toolkit-managed project at all. Seeds are enumerated
  * from the source rather than from what a target installed, so without this gate
@@ -143,6 +253,11 @@ export function countStates(entries: readonly ScanEntry[]): StateCounts {
  * the user can move content they wrote, so failing a job on it leaves the job
  * red with no mechanical remedy. Seeds are excluded on the same grounds, since
  * every seed a project edits would otherwise fail the check forever.
+ *
+ * Tooling is excluded on exactly the seeds grounds: a golden config is one the
+ * project is expected to edit, so a job counting it stays red with no remedy.
+ * Being unmeasured is not what excludes it, since an unmeasured report carries
+ * zero changes and would pass a count either way.
  */
 export function hasDrift(report: CheckReport): boolean {
   if (report.unmigrated.length > 0) return true
@@ -186,6 +301,7 @@ export async function buildCheckReport(
       covers: [],
       managed,
       domains: [],
+      tooling: UNMEASURED_TOOLING,
       seeds: { entries: [], historyUnavailable: false },
       superseded: [],
       unmigrated: [],
@@ -197,6 +313,7 @@ export async function buildCheckReport(
     covers: stamp?.covers ?? [],
     managed,
     domains,
+    tooling: buildToolingReport(toolkitRoot, target, stamp),
     seeds: buildSeedsReport(toolkitRoot, target),
     superseded: collectSuperseded(target),
     unmigrated,
@@ -208,7 +325,7 @@ async function buildDomainReport(
   toolkitRoot: string,
   target: string,
   stamp: Stamp | undefined,
-  domain: StampDomain,
+  domain: ScannedDomain,
 ): Promise<DomainReport> {
   const plan = planSync(ADAPTERS[domain](toolkitRoot), target)
   const record = stamp?.domains[domain]

package/src/sync/stamp.ts

@@ -5,10 +5,16 @@ import { dirname, join, sep } from 'node:path'
 import { execa } from 'execa'
 
 /**
- * Domains the stamp can attribute. Tooling runs its own inject and manifest
- * machinery rather than the sync engine, so it is absent by design.
+ * Domains the stamp can record. The first three attribute file by file through
+ * the sync engine. Tooling runs its own inject and manifest machinery, so it
+ * records the stack chain it resolved instead and carries no file hashes.
  */
-export const STAMP_DOMAINS = ['standards', 'snippets', 'governance'] as const
+export const STAMP_DOMAINS = [
+  'standards',
+  'snippets',
+  'governance',
+  'tooling',
+] as const
 
 export type StampDomain = (typeof STAMP_DOMAINS)[number]
 
@@ -31,6 +37,13 @@ export interface DomainStamp {
   readonly commit?: string
   readonly syncedAt: string
   readonly files: DomainHashes
+  /**
+   * Stack names the install resolved, nearest stack first. Present only for
+   * tooling. An ordered chain rather than the leaf name, because a stack that
+   * extends another cannot be reinstalled from its leaf alone, and a `--skip`
+   * run installs fewer layers than the leaf's own chain would reproduce.
+   */
+  readonly chain?: readonly string[]
 }
 
 export interface Stamp {
@@ -91,6 +104,15 @@ export function stampedHashes(
   return stamp.domains[domain]?.files ?? {}
 }
 
+/**
+ * The stack chain tooling last installed. An empty result is the state every
+ * target predating the tooling record sits in, and the report reads it as
+ * unmeasured rather than as clean.
+ */
+export function stampedChain(stamp: Stamp | undefined): readonly string[] {
+  return stamp?.domains.tooling?.chain ?? []
+}
+
 /**
  * Replaces one domain's record and leaves the others untouched, because domains
  * install and sync independently but share the one file.
@@ -100,6 +122,34 @@ export async function writeStamp(
   source: StampSource,
   hashes: DomainHashes,
   now: Date,
+): Promise<void> {
+  await putDomain(target, source, { files: sortKeys(hashes) }, now)
+}
+
+/**
+ * Records what tooling installed. `files` stays empty because `src/tooling/`
+ * never runs the sync engine, so there is no per-file attribution to store and
+ * the chain is the whole record.
+ */
+export async function writeChainStamp(
+  target: string,
+  toolkitRoot: string,
+  chain: readonly string[],
+  now: Date,
+): Promise<void> {
+  await putDomain(
+    target,
+    { domain: 'tooling', toolkitRoot },
+    { files: {}, chain: [...chain] },
+    now,
+  )
+}
+
+async function putDomain(
+  target: string,
+  source: StampSource,
+  payload: Pick<DomainStamp, 'files' | 'chain'>,
+  now: Date,
 ): Promise<void> {
   const previous = readStamp(target)
   const commit = await toolkitCommit(source.toolkitRoot)
@@ -107,7 +157,7 @@ export async function writeStamp(
   const record: DomainStamp = {
     ...(commit === undefined ? {} : { commit }),
     syncedAt: now.toISOString(),
-    files: sortKeys(hashes),
+    ...payload,
   }
 
   const domains = sortDomains({
@@ -187,16 +237,26 @@ function isStamp(value: unknown): value is Stamp {
   )
 }
 
+/**
+ * `chain` is optional, which is what keeps a stamp written before tooling
+ * joined the domains readable rather than parsing as corrupt and discarding
+ * the three records it does carry.
+ */
 function isDomainStamp(value: unknown): value is DomainStamp {
   if (!isRecord(value) || !isRecord(value.files)) return false
   if (typeof value.syncedAt !== 'string') return false
   if (value.commit !== undefined && typeof value.commit !== 'string') {
     return false
   }
+  if (value.chain !== undefined && !isStringArray(value.chain)) return false
 
   return Object.values(value.files).every((hash) => typeof hash === 'string')
 }
 
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string')
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }

package/src/tooling/stamp.ts

@@ -0,0 +1,44 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { writeChainStamp } from '@/sync/stamp'
+import type { Manifest } from '@/tooling/manifest'
+import { readPackage } from '@/tooling/package'
+
+/**
+ * Whether the target is a workspace root, where every package resolves its own
+ * stack. `package.json` covers bun, npm, and yarn, and pnpm declares the same
+ * fact in its own file instead.
+ */
+export function isWorkspaceRoot(target: string): boolean {
+  if (existsSync(join(target, 'pnpm-workspace.yaml'))) return true
+
+  const workspaces = readPackage(join(target, 'package.json'))?.workspaces
+  return Array.isArray(workspaces) || isRecord(workspaces)
+}
+
+/**
+ * Records the chain an install resolved, and returns whether it wrote one. A
+ * workspace root is the single refusal: one chain recorded there would be a
+ * guess at what its packages hold, and the report reading tooling as unmeasured
+ * is the true answer rather than a clean one.
+ */
+export async function recordToolingChain(
+  toolkitRoot: string,
+  target: string,
+  chain: readonly Manifest[],
+  now: Date,
+): Promise<boolean> {
+  if (isWorkspaceRoot(target)) return false
+
+  await writeChainStamp(
+    target,
+    toolkitRoot,
+    chain.map((manifest) => manifest.name),
+    now,
+  )
+  return true
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}