@erclx/aitk 0.24.0 → 0.25.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/setup-init/SKILL.md

@@ -63,7 +63,7 @@ Before executing, output:
 
 ## Execute
 
-Run the chain in order. Each step's permission dialog is the confirmation gate. Run from the target project's current directory.
+Run the chain in order, starting immediately after the preview. Each step's permission dialog is the confirmation gate. Do not pause for additional confirmation. Run from the target project's current directory.
 
 Step 1: `aitk init` installs base tooling, claude seeds, governance rules, standards, snippets, and wiki.
 

package/docs/agents.md

@@ -163,8 +163,16 @@ matches what the toolkit installed, `customized` when the project edited it,
 when the project authored it, or `drifted` when no stamp covers it. Use `--json`
 for the machine-readable report and `--exit-code` to fail a CI job. Orphaned
 files are excluded from that exit code, since a project-authored rule never
-converges. Attribution needs `.claude/aitk.json`, which every install and sync
-writes. Without it, every difference reports as `drifted`.
+converges. Attribution reads `.claude/aitk.json`, which every install and sync
+writes.
+
+A target installed before stamping shipped has no such file, and the report
+falls back to the toolkit's own git history. Installed content matching any
+version that history ever published proves the file is untouched, so it reports
+`stale` naming the commit it came from, and content matching no published
+version stays `drifted`. A toolkit reached outside a git clone, which is what a
+registry install is, cannot run that fallback and reports
+`historyUnavailable` alongside the unattributed files.
 
 Each domain carries its own toolkit anchor in that file, so syncing one domain
 never advances the revision another measures from, and each reports the upstream
@@ -238,7 +246,7 @@ The record carries every scenario with the arms that declare, plus `totalScenari
 
 `--skills` answers what the scenario count cannot, which is whether anything can fail a given skill. It adds `skills`, `totalSkills`, `asserted`, `shouldBeAsserted`, `exempt`, `staleExemptions`, and `supersededExemptions` to the record, and keeps the scenario view rather than replacing it. The two denominators disagree on purpose: an armed scenario under `infra/` or `tooling/` exercises a CLI domain and pairs with no skill at all.
 
-A skill pairs to a scenario by filename, `<category>-<command>` first and bare `<command>` second, so `claude/setup-init.sh` reaches the `setup-init` skill. `should-be-asserted` is the default and is the work queue for writing arms. `exempt` means no arm should be written and holds only with a reason, declared in `scripts/sandbox/exempt.toml` and limited to a harness limit the checker cannot reach past or a skill that writes no artifact. An armed arm outranks an exemption. An exemption naming no shipped skill, or naming one an arm now asserts, exits 1 without `--strict`. Each armed arm reports as `<category>:<command>/<arm>`, so two same-named arms under different scenarios stay distinct.
+A skill pairs to a scenario by filename, `<category>-<command>` first and bare `<command>` second, so `claude/setup-init.sh` reaches the `setup-init` skill. `should-be-asserted` is the default rather than a queue to drain, and which of those skills earns an arm is a project decision the census does not make. `exempt` means no arm should be written and holds only with a reason, declared in `scripts/sandbox/exempt.toml` and limited to a harness limit the checker cannot reach past or a skill that writes no artifact. An armed arm outranks an exemption. An exemption naming no shipped skill, or naming one an arm now asserts, exits 1 without `--strict`. Each armed arm reports as `<category>:<command>/<arm>`, so two same-named arms under different scenarios stay distinct.
 
 `scripts/sandbox/run.sh` calls this after a headless run and merges the verdict into the envelope it prints. It also writes that merged record to `.claude/.tmp/sandbox-runs/<target>-<arm>-<timestamp>.json` with a `writes` array appended, and logs the path on stderr. Both fields are what a later re-score needs, since `--envelope` and `--writes` read files the run deletes on exit. Stdout carries the same bytes it did before the record existed.
 

package/docs/target-projects.md

@@ -100,7 +100,9 @@ When the toolkit updates, target projects pull changes per domain. There is one
 
 `aitk sync --check <path>` reports what has drifted without writing anything. It splits each difference by cause, which is the question that decides what to do next. A `stale` file still matches what the toolkit installed, so the update is mechanical. A `customized` file carries local edits, so taking the upstream version is a decision and `aitk:claude-seed-sync` is the tool for it. A `stranded` file sits where an older toolkit installed it and the toolkit has since moved, which is what `aitk:migration-standards` handles.
 
-That attribution comes from `.claude/aitk.json`, a stamp every install and sync writes recording a hash per installed file. Each domain holds its own toolkit commit, so syncing governance today does not move the revision standards measures against, and each domain reports the upstream commits touching its own source path. A project that has never synced under a toolkit new enough to write a stamp reports every difference as `drifted`, the unattributed verdict. Running any sync stamps that domain, and the report names the ones still unstamped.
+That attribution comes from `.claude/aitk.json`, a stamp every install and sync writes recording a hash per installed file. Each domain holds its own toolkit commit, so syncing governance today does not move the revision standards measures against, and each domain reports the upstream commits touching its own source path. Running any sync stamps that domain, and the report names the ones still unstamped.
+
+A project that has never synced under a toolkit new enough to write a stamp falls back to the toolkit's own git history. Installed content matching any version that history published proves the file untouched, so it reports `stale` naming the commit it came from, and content matching no published version stays `drifted`. That fallback needs the toolkit as a git checkout. Installed from the registry it ships source without history, and the report says attribution was unavailable rather than reading every file as a local edit.
 
 Add `--json` for the machine-readable report, and `--exit-code` to fail a CI job when a target falls behind. Files the project authored itself never count toward that exit code.
 
@@ -110,7 +112,7 @@ Tooling is not covered by the stamp. Reconcile those configs with `aitk tooling
 
 `aitk sync <path>` runs every installed domain's sync in sequence. Safe to run on a cadence. It never touches user-owned seed files. Governance rules in `.claude/rules/`, tooling configs, and reference docs refresh in place. Stale `.claude/GOV.md` from earlier installs is removed.
 
-Standards are the exception inside that run, and the stamp narrows it. A standard the project customized is reported and left alone rather than overwritten. A standard still matching what was installed carries no local edits to lose, so a headless run updates it. On an unstamped project the old blanket rule holds and every drifted standard is left alone. To take the upstream version of a customized file, run `aitk standards sync <path>` interactively, or use `aitk:claude-seed-sync` below to merge section by section.
+Standards are the exception inside that run, and the stamp narrows it. A standard the project customized is reported and left alone rather than overwritten. A standard still matching what was installed carries no local edits to lose, so a headless run updates it. An unstamped project reaches the same split through the history fallback, so a headless run updates every standard it can prove untouched and refuses while any file resists attribution. To take the upstream version of a customized file, run `aitk standards sync <path>` interactively, or use `aitk:claude-seed-sync` below to merge section by section.
 
 ### Targeted
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/commands/sync.ts

@@ -99,7 +99,11 @@ function renderCheck(report: CheckReport): void {
     logStep(domain.domain)
 
     if (domain.commit === undefined) {
-      logWarn('Not stamped. Drift below is reported unattributed.')
+      logWarn(
+        domain.historyUnavailable
+          ? 'Not stamped, and this toolkit has no git history. Drift below is reported unattributed.'
+          : 'Not stamped. Drift below is attributed from toolkit history.',
+      )
     } else {
       logInfo(`Synced from ${domain.commit} on ${domain.syncedAt}`)
     }

package/src/sync/check.ts

@@ -54,6 +54,11 @@ export interface DomainReport {
   readonly counts: StateCounts
   readonly entries: readonly ScanEntry[]
   readonly upstream: readonly UpstreamCommit[]
+  /**
+   * Separates a toolkit that could not attribute from one that attributed and
+   * found a local edit. Only the first is a capability the install lacks.
+   */
+  readonly historyUnavailable: boolean
 }
 
 export interface UpstreamCommit {
@@ -145,6 +150,7 @@ async function buildDomainReport(
     syncedAt: record?.syncedAt,
     counts: countStates(plan.entries),
     entries: plan.entries,
+    historyUnavailable: plan.historyUnavailable,
     upstream:
       since === undefined
         ? []

package/src/sync/engine.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from 'node:fs'
 import { rm } from 'node:fs/promises'
 import { isAbsolute, relative, resolve } from 'node:path'
 import { copyPreservingMode } from '@/copy'
+import { findInstalledOrigin, readHistoryIndex } from '@/sync/history'
 import {
   type DomainHashes,
   hashFile,
@@ -74,12 +75,16 @@ export type EntryState =
 export interface ScanEntry {
   readonly state: EntryState
   readonly rel: string
+  /** Toolkit revision this file's content came from, when history proved it. */
+  readonly since?: string
 }
 
 export interface SyncPlan {
   readonly entries: readonly ScanEntry[]
   readonly retired: readonly RetiredSurface[]
   readonly changes: readonly SyncChange[]
+  /** Set when a file needed history to attribute it and this toolkit has none. */
+  readonly historyUnavailable: boolean
 }
 
 /**
@@ -156,6 +161,7 @@ export function listInstalled(root: string, target: string): InstalledFile[] {
 export function planSync(adapter: SyncAdapter, target: string): SyncPlan {
   const entries: ScanEntry[] = []
   const changes: SyncChange[] = []
+  const unattributed: UnattributedFile[] = []
 
   const hashes = stampedHashes(readStamp(target), adapter.stamp?.domain)
   const walked = new Set<string>()
@@ -176,7 +182,12 @@ export function planSync(adapter: SyncAdapter, target: string): SyncPlan {
       continue
     }
 
-    entries.push({ state: attribute(hashes, file), rel: file.rel })
+    const state = attribute(hashes, file)
+    if (state === 'drifted') {
+      unattributed.push({ index: entries.length, source, path: file.path })
+    }
+
+    entries.push({ state, rel: file.rel })
     changes.push({
       kind: 'copy',
       source,
@@ -185,6 +196,8 @@ export function planSync(adapter: SyncAdapter, target: string): SyncPlan {
     })
   }
 
+  const historyUnavailable = recoverAttribution(adapter, entries, unattributed)
+
   entries.push(...strandedByRelocation(target, hashes, walked))
 
   const retired = adapter.collectRetired?.(target) ?? []
@@ -192,7 +205,53 @@ export function planSync(adapter: SyncAdapter, target: string): SyncPlan {
     changes.push({ kind: 'delete', dest: surface.path, rel: surface.rel })
   }
 
-  return { entries, retired, changes }
+  return { entries, retired, changes, historyUnavailable }
+}
+
+interface UnattributedFile {
+  readonly index: number
+  readonly source: string
+  readonly path: string
+}
+
+/**
+ * Second pass over the files the stamp could not attribute, which is every file
+ * in a target installed before stamping shipped. Matching the installed content
+ * against the toolkit's own history recovers the fact a stamp would have held,
+ * and a file matching no published version stays unattributed.
+ *
+ * Runs as one git call for the whole domain rather than one per file, and only
+ * when the first pass left something to attribute. Reports whether history was
+ * readable at all, so a registry install can say why it fell short instead of
+ * reporting every file as a local edit.
+ */
+function recoverAttribution(
+  adapter: SyncAdapter,
+  entries: ScanEntry[],
+  unattributed: readonly UnattributedFile[],
+): boolean {
+  const toolkitRoot = adapter.stamp?.toolkitRoot
+  if (toolkitRoot === undefined || unattributed.length === 0) return false
+
+  const index = readHistoryIndex(
+    toolkitRoot,
+    unattributed.map((file) => relative(toolkitRoot, file.source)),
+  )
+
+  if (index === undefined) return true
+
+  for (const file of unattributed) {
+    const since = findInstalledOrigin(
+      index,
+      relative(toolkitRoot, file.source),
+      file.path,
+    )
+
+    if (since === undefined) continue
+    entries[file.index] = { ...entries[file.index], state: 'stale', since }
+  }
+
+  return false
 }
 
 export async function applyChanges(
@@ -314,7 +373,12 @@ function report(adapter: SyncAdapter, plan: SyncPlan): void {
   for (const entry of plan.entries) {
     if (entry.state === 'matching') logInfo(entry.rel)
     else if (entry.state === 'drifted') logWarn(entry.rel)
-    else if (entry.state === 'stale') logWarn(`${entry.rel} (toolkit updated)`)
+    else if (entry.state === 'stale')
+      logWarn(
+        entry.since === undefined
+          ? `${entry.rel} (toolkit updated)`
+          : `${entry.rel} (toolkit updated since ${entry.since.slice(0, 7)})`,
+      )
     else if (entry.state === 'customized')
       logWarn(`${entry.rel} (locally customized)`)
     else if (entry.state === 'stranded')
@@ -325,6 +389,12 @@ function report(adapter: SyncAdapter, plan: SyncPlan): void {
   for (const surface of plan.retired) {
     logWarn(surface.notice)
   }
+
+  if (plan.historyUnavailable) {
+    logWarn(
+      'Attribution unavailable: this toolkit has no git history to match against.',
+    )
+  }
 }
 
 function sameContent(left: string, right: string): boolean {

package/src/sync/history.ts

@@ -0,0 +1,123 @@
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { sep } from 'node:path'
+import { execaSync } from 'execa'
+import { gitEnv } from '@/git-env'
+
+/** Blob SHA to the newest commit whose post-image for that path held it. */
+export type PathHistory = ReadonlyMap<string, string>
+
+/** Source path relative to the toolkit root, to that path's known blobs. */
+export type HistoryIndex = ReadonlyMap<string, PathHistory>
+
+const EMPTY_BLOB = '0000000000000000000000000000000000000000'
+
+/**
+ * Git's own object name for a file's contents: sha1 over `blob <len>\0` and the
+ * bytes. Computed here rather than shelled out to `git hash-object`, which would
+ * cost a process per file inside the attribution pass.
+ *
+ * A repository normalizing line endings on checkout stores a blob the working
+ * tree never holds, so this returns a name that matches no historical version.
+ * The caller treats an unmatched file as unattributed, which is the safe label.
+ */
+export function gitBlobHash(content: Buffer): string {
+  const header = Buffer.from(`blob ${content.length}\0`, 'utf8')
+  return createHash('sha1').update(header).update(content).digest('hex')
+}
+
+/**
+ * Reads `--raw` log output into blob-to-commit maps, one per path.
+ *
+ * Reverse-chronological input means the first commit naming a blob is the
+ * newest that produced it, so an existing key is never overwritten. Content
+ * reverted and restored therefore reports the recent commit rather than the
+ * original, which is the one an operator can act on.
+ */
+export function parseRawLog(output: string): HistoryIndex {
+  const index = new Map<string, Map<string, string>>()
+  let commit = ''
+
+  for (const line of output.split('\n')) {
+    if (line === '') continue
+
+    if (!line.startsWith(':')) {
+      commit = line.trim()
+      continue
+    }
+
+    const [meta, path] = line.split('\t')
+    if (path === undefined || commit === '') continue
+
+    const blob = meta.trim().split(/\s+/)[3]
+    if (blob === undefined || blob === EMPTY_BLOB) continue
+
+    const blobs = index.get(path) ?? new Map<string, string>()
+    if (!blobs.has(blob)) blobs.set(blob, commit)
+    index.set(path, blobs)
+  }
+
+  return index
+}
+
+/**
+ * Every historical version of the given toolkit-relative paths, or `undefined`
+ * when this toolkit has no history to read. A package installed from the
+ * registry ships source without `.git`, so absence is an ordinary state rather
+ * than a failure, and the caller degrades to the unattributed path.
+ *
+ * Renames are disabled so a raw line always carries exactly one path. Detection
+ * would emit a two-path form that the parser would read as an unknown blob.
+ */
+export function readHistoryIndex(
+  toolkitRoot: string,
+  paths: readonly string[],
+): HistoryIndex | undefined {
+  if (paths.length === 0) return new Map()
+
+  const result = execaSync(
+    'git',
+    [
+      '-C',
+      toolkitRoot,
+      'log',
+      '--all',
+      '--raw',
+      '--no-renames',
+      '--no-abbrev',
+      '--relative',
+      '--format=%H',
+      '--',
+      ...paths.map(toRepoPath),
+    ],
+    { reject: false, env: gitEnv(), extendEnv: false },
+  )
+
+  return result.exitCode === 0 ? parseRawLog(result.stdout) : undefined
+}
+
+/**
+ * Git prints and accepts posix separators on every platform, so a Windows
+ * caller's `relative()` output has to be converted before it can match a path
+ * the log emitted.
+ */
+function toRepoPath(path: string): string {
+  return path.split(sep).join('/')
+}
+
+/**
+ * The commit whose version of `sourceRel` matches what sits at `installedPath`.
+ * A match proves the file is untouched since it was installed, so the toolkit is
+ * what moved. No match means the content matches nothing this toolkit ever
+ * published, which is a local edit and stays unattributed.
+ */
+export function findInstalledOrigin(
+  index: HistoryIndex,
+  sourceRel: string,
+  installedPath: string,
+): string | undefined {
+  const blobs = index.get(toRepoPath(sourceRel))
+  if (blobs === undefined) return undefined
+
+  return blobs.get(gitBlobHash(readFileSync(installedPath)))
+}