@erclx/aitk 0.79.0 → 0.81.0

package/src/records/backup.ts

@@ -0,0 +1,394 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { $ } from 'bun'
+import { gitEnv } from '@/git-env'
+
+/**
+ * The folders a backup carries, relative to `.claude/`. They are the `# Claude`
+ * group in `.gitignore` minus `.claude/.tmp`, which is defined as deletable
+ * without loss, and `.claude/worktrees/`, whose contents belong to the
+ * enclosing repository already. The list is spelled out rather than read off
+ * that group so adding an ignore entry cannot silently enlarge the payload.
+ *
+ * `RECORD_KINDS` in `validate.ts` names four of these. The two lists differ on
+ * purpose: one is what a standard governs, this is what a disk loss would take.
+ */
+export const BACKED_FOLDERS = [
+  'groundwork',
+  'intake',
+  'memory',
+  'plans',
+  'plans-archive',
+  'review',
+  'task-archive',
+  'tasks',
+] as const
+
+/** Holds the records history beside the folders it tracks, ignored by the enclosing repository. */
+const RECORDS_GIT_DIR = join('.claude', '.records.git')
+
+const WORK_TREE = '.claude'
+
+/** Both directions name the branch, so a machine whose `init.defaultBranch` differs still lands on it. */
+const RECORDS_BRANCH = 'main'
+
+/**
+ * The records history is machine-written and nobody reads its authorship, so a
+ * fixed identity keeps `push` from failing inside a git hook on a machine where
+ * `user.email` was never configured.
+ */
+const COMMIT_IDENTITY = ['-c', 'user.name=aitk', '-c', 'user.email=aitk@local']
+
+export const BACKUP_REFUSALS = [
+  'no-repository',
+  'no-remote',
+  'remote-unreadable',
+  'remote-shared',
+  'no-remote-records',
+  'local-changes',
+  'local-ahead',
+  'git-failed',
+] as const
+
+export type BackupRefusal = (typeof BACKUP_REFUSALS)[number]
+
+export interface BackupRefused {
+  readonly ok: false
+  readonly reason: BackupRefusal
+  readonly message: string
+}
+
+export interface PushReport {
+  readonly ok: true
+  readonly root: string
+  readonly folders: readonly string[]
+  readonly changed: number
+  readonly commit?: string
+  readonly pushed: boolean
+}
+
+export interface PullReport {
+  readonly ok: true
+  readonly root: string
+  readonly folders: readonly string[]
+  readonly commit: string
+  readonly files: number
+}
+
+export type PushOutcome = PushReport | BackupRefused
+export type PullOutcome = PullReport | BackupRefused
+
+interface GitResult {
+  readonly ok: boolean
+  readonly text: string
+  readonly stderr: string
+}
+
+/**
+ * Runs one git command against the records history.
+ *
+ * Both flags go on every call. `git --git-dir=<path> init` writes
+ * `core.bare = true`, and an explicit `--work-tree` is what overrides it, so
+ * dropping the flag on a single call reads the enclosing project as the tree
+ * and stages everything in it.
+ */
+async function records(root: string, args: string[]): Promise<GitResult> {
+  const gitDir = join(root, RECORDS_GIT_DIR)
+  const workTree = join(root, WORK_TREE)
+
+  const result =
+    await $`git --git-dir=${gitDir} --work-tree=${workTree} ${args}`
+      .env(gitEnv())
+      .quiet()
+      .nothrow()
+
+  return {
+    ok: result.exitCode === 0,
+    text: result.stdout.toString().trim(),
+    stderr: result.stderr.toString().trim(),
+  }
+}
+
+function refuse(reason: BackupRefusal, message: string): BackupRefused {
+  return { ok: false, reason, message }
+}
+
+function failed(action: string, result: GitResult): BackupRefused {
+  return refuse(
+    'git-failed',
+    `git ${action} failed against the records history: ${result.stderr || 'no output'}.`,
+  )
+}
+
+/**
+ * Reduces a remote URL to `host/path`, so every spelling of one repository
+ * compares equal.
+ *
+ * Transport is what the reduction drops. `git@github.com:owner/repo.git` and
+ * `https://github.com/owner/repo` name the same repository, and comparing them
+ * as written passes a records origin that publishes the payload through the
+ * other protocol.
+ */
+function remoteIdentity(url: string): string {
+  return url
+    .trim()
+    .toLowerCase()
+    .replace(/^[a-z+]+:\/\//, '')
+    .replace(/^[^@/]+@/, '')
+    .replace(/^([^/:]+):/, '$1/')
+    .replace(/\/+$/, '')
+    .replace(/\.git$/, '')
+    .replace(/\/+$/, '')
+}
+
+/**
+ * Lists every remote of the enclosing project, or undefined when git cannot
+ * answer.
+ *
+ * The caller refuses on undefined rather than smoothing it into an empty list.
+ * An empty list clears the gate below for every URL, so a git that failed for
+ * any reason would publish the payload to whatever origin the records history
+ * happens to name. A project with no remotes answers `0` with an exit of zero,
+ * so the two states stay distinguishable.
+ */
+async function enclosingRemoteUrls(
+  root: string,
+): Promise<string[] | undefined> {
+  const result = await $`git -C ${root} remote -v`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
+  if (result.exitCode !== 0) return undefined
+
+  return result.stdout
+    .toString()
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => line.split(/\s+/)[1] ?? '')
+    .filter(Boolean)
+    .map(remoteIdentity)
+}
+
+/**
+ * Clears the four gates both verbs share and returns the records remote URL.
+ *
+ * The last two are the ones the payload depends on. This repository is public,
+ * so a records branch on any of its remotes serves the memory pen and the
+ * groundwork trails to anyone who fetches all refs. Comparing the configured
+ * URL against every remote of the enclosing repository is what keeps a
+ * misconfigured `origin` from publishing them, and refusing when that list
+ * cannot be read is what keeps a failed comparison from reading as a pass.
+ */
+async function resolveRemote(root: string): Promise<string | BackupRefused> {
+  if (!existsSync(join(root, RECORDS_GIT_DIR))) {
+    return refuse(
+      'no-repository',
+      [
+        `No records history at ${RECORDS_GIT_DIR}. Create it once, against a private repository:`,
+        `  git --git-dir=${join(root, RECORDS_GIT_DIR)} init`,
+        `  git --git-dir=${join(root, RECORDS_GIT_DIR)} remote add origin <private-repo-url>`,
+      ].join('\n'),
+    )
+  }
+
+  const remote = await records(root, ['remote', 'get-url', 'origin'])
+  if (!remote.ok || remote.text.length === 0) {
+    return refuse(
+      'no-remote',
+      [
+        'The records history has no origin. Point it at a private repository:',
+        `  git --git-dir=${join(root, RECORDS_GIT_DIR)} remote add origin <private-repo-url>`,
+      ].join('\n'),
+    )
+  }
+
+  const enclosing = await enclosingRemoteUrls(root)
+  if (!enclosing) {
+    return refuse(
+      'remote-unreadable',
+      `Cannot read the remotes of the project at ${root}, so the records origin cannot be checked against them. Records carry the memory pen and the groundwork trails, and an unchecked origin risks publishing them.`,
+    )
+  }
+
+  const url = remoteIdentity(remote.text)
+  if (enclosing.includes(url)) {
+    return refuse(
+      'remote-shared',
+      `The records origin ${remote.text} is a remote of this project. Records carry the memory pen and the groundwork trails, so they need a repository of their own.`,
+    )
+  }
+
+  return url
+}
+
+/**
+ * The subset of the eight a pathspec can name: on disk, or already in the
+ * records index.
+ *
+ * A pathspec matching neither fails the whole `add`, which is why the subset
+ * exists. The index half is what covers a folder deleted in full. Reading disk
+ * alone drops it from the pathspec, so its deletion never stages, the remote
+ * keeps it forever, and a later `pull` restores it past the gate that refuses
+ * every other unpushed deletion.
+ */
+async function scopedFolders(root: string): Promise<string[]> {
+  const tracked = await records(root, ['ls-files'])
+  const indexed = new Set(
+    tracked.ok ? tracked.text.split('\n').filter(Boolean).map(topSegment) : [],
+  )
+
+  return BACKED_FOLDERS.filter(
+    (folder) =>
+      existsSync(join(root, WORK_TREE, folder)) || indexed.has(folder),
+  )
+}
+
+function topSegment(path: string): string {
+  return path.split('/')[0]
+}
+
+/** What a report names, which is the folders a reader can go and open. */
+function presentFolders(root: string): string[] {
+  return BACKED_FOLDERS.filter((folder) =>
+    existsSync(join(root, WORK_TREE, folder)),
+  )
+}
+
+function countLines(text: string): number {
+  return text.split('\n').filter(Boolean).length
+}
+
+/**
+ * Stages the backed folders, commits when any of them changed, and pushes.
+ *
+ * The push runs whether or not this call committed, because a previous run can
+ * have committed and then failed to reach the network. Skipping it would leave
+ * that commit on one disk, which is the state the whole verb exists to end.
+ */
+export async function pushRecords(root: string): Promise<PushOutcome> {
+  const remote = await resolveRemote(root)
+  if (typeof remote !== 'string') return remote
+
+  const scope = await scopedFolders(root)
+
+  if (scope.length > 0) {
+    // `-f` is what carries the payload: every backed folder is ignored by the
+    // enclosing repository, and the pathspecs are the whole list, so nothing
+    // outside them can enter the index however the ignore rules read.
+    const staged = await records(root, ['add', '-A', '-f', '--', ...scope])
+    if (!staged.ok) return failed('add', staged)
+  }
+
+  const diff = await records(root, [
+    'diff',
+    '--cached',
+    '--name-only',
+    '--',
+    ...scope,
+  ])
+  if (!diff.ok) return failed('diff', diff)
+
+  const changed = countLines(diff.text)
+
+  if (changed > 0) {
+    const stamp = new Date().toISOString().replace('T', ' ').slice(0, 16)
+    const commit = await records(root, [
+      ...COMMIT_IDENTITY,
+      'commit',
+      '--quiet',
+      '-m',
+      `records: ${changed} changed at ${stamp}`,
+    ])
+    if (!commit.ok) return failed('commit', commit)
+  }
+
+  const folders = presentFolders(root)
+  const head = await records(root, ['rev-parse', '--short', 'HEAD'])
+  if (!head.ok) {
+    return { ok: true, root, folders, changed, pushed: false }
+  }
+
+  const pushed = await records(root, [
+    'push',
+    'origin',
+    `HEAD:refs/heads/${RECORDS_BRANCH}`,
+  ])
+  if (!pushed.ok) return failed('push', pushed)
+
+  return { ok: true, root, folders, changed, commit: head.text, pushed: true }
+}
+
+/**
+ * Fetches the records history and writes it into the backed folders.
+ *
+ * The two directions are not symmetric. A push only ever adds, while a pull
+ * onto a machine holding work that never reached the remote would discard it,
+ * so both gates below refuse rather than choosing a merge strategy. A person
+ * resolves by pushing first or by moving the local folders aside.
+ */
+export async function pullRecords(root: string): Promise<PullOutcome> {
+  const remote = await resolveRemote(root)
+  if (typeof remote !== 'string') return remote
+
+  const fetched = await records(root, [
+    'fetch',
+    '--quiet',
+    'origin',
+    `refs/heads/${RECORDS_BRANCH}`,
+  ])
+  if (!fetched.ok) {
+    // A missing branch and an unreachable remote both fail the fetch, and only
+    // the first is an ordinary state a person resolves by pushing once.
+    if (fetched.stderr.includes("couldn't find remote ref")) {
+      return refuse(
+        'no-remote-records',
+        `The records origin carries no ${RECORDS_BRANCH} branch yet. Run aitk records push from the machine holding the records.`,
+      )
+    }
+    return failed('fetch', fetched)
+  }
+
+  const target = await records(root, ['rev-parse', 'FETCH_HEAD'])
+  if (!target.ok) return failed('rev-parse', target)
+
+  const scope = await scopedFolders(root)
+
+  if (scope.length > 0) {
+    const dirty = await records(root, ['status', '--porcelain', '--', ...scope])
+    if (!dirty.ok) return failed('status', dirty)
+
+    if (dirty.text.length > 0) {
+      return refuse(
+        'local-changes',
+        `${countLines(dirty.text)} local record(s) are not in the records history. Run aitk records push first, or move them aside.`,
+      )
+    }
+  }
+
+  const head = await records(root, ['rev-parse', '--verify', '--quiet', 'HEAD'])
+  if (head.ok && head.text.length > 0) {
+    const ahead = await records(root, ['rev-list', `${target.text}..HEAD`])
+    if (!ahead.ok) return failed('rev-list', ahead)
+
+    if (ahead.text.length > 0) {
+      return refuse(
+        'local-ahead',
+        `${countLines(ahead.text)} local commit(s) have not reached the records origin. Run aitk records push first.`,
+      )
+    }
+  }
+
+  const reset = await records(root, ['reset', '--hard', '--quiet', target.text])
+  if (!reset.ok) return failed('reset', reset)
+
+  const files = await records(root, ['ls-files'])
+  if (!files.ok) return failed('ls-files', files)
+
+  return {
+    ok: true,
+    root,
+    folders: presentFolders(root),
+    commit: target.text.slice(0, 7),
+    files: countLines(files.text),
+  }
+}

package/standards/context.md

@@ -83,6 +83,7 @@ Only the `development` entry carries this section. It is not a general-purpose h
 - Decisions specific to the domain. Broader cross-domain decisions belong in `.claude/ARCHITECTURE.md`.
 - Constraints, gotchas, things tried and rejected
 - Domain-specific conventions that do not fit a `paths:`-scoped rule
+- A reference to another entry, spelled as the path that entry sits at rather than as its bare filename. A bare name resolves against whichever folder the reader is already in, so a domain that splits into subfolders strands every inbound reference and the break surfaces nowhere. A reference to a seed, a standard, or a file the project owns elsewhere keeps the form its own surface uses.
 
 ## What does not go in
 

package/standards/prose.md

@@ -5,7 +5,9 @@ description: Voice, language, and frontmatter wording for reference markdown
 
 # Prose reference
 
-Applies to markdown reference docs, READMEs, and inline documentation in repos. It is the default voice for `.md` files and yields to any surface with its own voice, such as blogs, emails, changelogs, or commit messages. It also yields wherever another standard states the voice for the surface it governs, which is how a surface claims the exemption without this file having to name it. The yield covers voice alone. The language rules below stay in force on every surface, including the surfaces no automated check reaches, as do the mechanics in `markdown.md`.
+Applies to markdown reference docs, READMEs, and inline documentation in repos. It is the default voice for `.md` files and yields to any surface with its own voice, such as blogs, emails, changelogs, or commit messages. It also yields wherever another standard states the voice for the surface it governs, which is how a surface claims the exemption without this file having to name it.
+
+The yield covers voice alone. The language rules below stay in force on every surface, including the surfaces no automated check reaches, as do the mechanics in `markdown.md`.
 
 ## Scope
 

package/standards/rule.md

@@ -7,7 +7,9 @@ description: Rule frontmatter, body shape, and voice for .claude/rules files
 
 ## Overview
 
-Rules give Claude Code coding constraints scoped to file paths. Claude Code discovers `.claude/rules/**/*.md` at session start. A rule with no `paths:` field always applies, at the same priority as `CLAUDE.md`. A rule with `paths:` applies when Claude reads a file matching the glob. Author one rule per topic so the scope stays precise.
+Rules give Claude Code coding constraints scoped to file paths. Claude Code discovers `.claude/rules/**/*.md` at session start.
+
+A rule with no `paths:` field always applies, at the same priority as `CLAUDE.md`. A rule with `paths:` applies when Claude reads a file matching the glob. Author one rule per topic so the scope stays precise.
 
 ## Scope
 

package/standards/tasks.md

@@ -5,7 +5,9 @@ description: Folder layout, filename convention, readiness groups, and content r
 
 # Tasks reference
 
-Applies to `.claude/tasks/`. Tracks what is being built and why, at the level of features and outcomes. One file per task. Update when a task starts, completes, or changes scope. When to open a task at all is project policy, not a shape rule, and lives in `CLAUDE.md`.
+Applies to `.claude/tasks/`. Tracks what is being built and why, at the level of features and outcomes. One file per task.
+
+Update when a task starts, completes, or changes scope. When to open a task at all is project policy, not a shape rule, and lives in `CLAUDE.md`.
 
 The folder is gitignored. Board state changes when work ships rather than when a branch is written, so committing it would put a claim about the future into the diff of an unrelated pull request. The git log records what shipped.
 
@@ -108,7 +110,9 @@ description: Record what a target installed and report the delta against the too
 
 ## File format
 
-Two headings, `## Outcomes` and `## Findings`. Outcomes are future and checkable, findings are past and factual, and as flat bullets at the same indent they are visually identical. A heading separates them at no cost. Add no third heading. Status stays inline on an outcome rather than becoming an "In progress" section.
+Two headings, `## Outcomes` and `## Findings`. Outcomes are future and checkable, findings are past and factual, and as flat bullets at the same indent they are visually identical. A heading separates them at no cost.
+
+Add no third heading. Status stays inline on an outcome rather than becoming an "In progress" section.
 
 Size the outcomes so one pull request closes all of them. A task whose outcomes span two pull requests ships the first half and leaves the rest open, with nothing recording which outcomes the merged work covered, so the board reads as in-progress work that no branch is carrying. Split the task before handing it off rather than after. This is what `## Archiving` below depends on, since a task closes whole or not at all.
 
@@ -156,7 +160,11 @@ A task with no origin is either lost context or work nobody decided to do. The i
 
 Phase-label format and where labels may appear are governed by `standards/versioning.md`.
 
-`Plan:` points at `../plans/feature-<slug>.md` while the task is open. Once the task ships and the plan is archived, it points at `../plans-archive/feature-<slug>.md`. Retarget both halves of the link rather than dropping it, so a completed task still leads to the reasoning behind it. A project that archived plans before the folder moved out of `.claude/.tmp/` holds closed tasks pointing at `../.tmp/plans-archive/`, and both forms resolve against the files each names, so leave those pointers where they are. Nothing migrates them, and a task retargeted without its plan moving leads nowhere. One plan per task. A plan cited by two tasks is a misfile rather than a shape to design for, which is why the sweep counts citations before archiving: the count is a guard against the misfile stranding a pointer, not support for the shape.
+`Plan:` points at `../plans/feature-<slug>.md` while the task is open. Once the task ships and the plan is archived, it points at `../plans-archive/feature-<slug>.md`. Retarget both halves of the link rather than dropping it, so a completed task still leads to the reasoning behind it.
+
+A project that archived plans before the folder moved out of `.claude/.tmp/` holds closed tasks pointing at `../.tmp/plans-archive/`, and both forms resolve against the files each names, so leave those pointers where they are. Nothing migrates them, and a task retargeted without its plan moving leads nowhere.
+
+One plan per task. A plan cited by two tasks is a misfile rather than a shape to design for, which is why the sweep counts citations before archiving: the count is a guard against the misfile stranding a pointer, not support for the shape.
 
 `Groundwork:` points at `../groundwork/<slug>/`, the folder `claude-groundwork` fills. It names the surface it points at the way `Plan:` does. Use this key alone. `Research record` and `Decision record` are earlier spellings of the same thing and both convert to it.
 

package/standards/versioning.md

@@ -66,4 +66,6 @@ The surface publishing the text is the last gate on it. Where no automated check
 
 ## Why
 
-Phase labels keep planning conversations efficient. They make `git log`, PR titles, and the tag list unreadable when they leak in. A future reader cannot reconstruct what an internal label meant without the matching task file, which is gitignored. Semver tags carry meaning independent of conversation state and survive in git history. Keeping the two namespaces apart preserves both.
+Phase labels keep planning conversations efficient. They make `git log`, PR titles, and the tag list unreadable when they leak in. A future reader cannot reconstruct what an internal label meant without the matching task file, which is gitignored.
+
+Semver tags carry meaning independent of conversation state and survive in git history. Keeping the two namespaces apart preserves both.