@erclx/canon 4.0.0

package/src/worktree.ts

@@ -0,0 +1,143 @@
+import { $ } from 'bun'
+import { gitEnv } from '@/git-env'
+
+/**
+ * Resolves the root of the checkout the caller is standing in, which is the
+ * linked worktree rather than the main one when a session is inside one.
+ *
+ * A tracked tree differs per worktree, so a verb reading one answers about the
+ * files the session has edited only if it resolves the root this way. The
+ * working directory is not a substitute, since a caller invoking from a
+ * subdirectory would resolve a root holding none of the trees a verb reads.
+ */
+export async function currentWorktreeRoot(): Promise<string> {
+  const result = await $`git rev-parse --show-toplevel`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
+  if (result.exitCode !== 0) return process.cwd()
+
+  return result.stdout.toString().trim() || process.cwd()
+}
+
+/**
+ * Resolves the root every shared-scratch folder lives under. `git worktree
+ * list` puts the main worktree first, and trusting the working directory
+ * instead would write a second board nothing else reads, or validate a linked
+ * worktree's empty folder and report it clean.
+ *
+ * A caller reaching this from a linked worktree is the case it exists for: the
+ * file-editing tools refuse a main-root path there, so a verb resolving the
+ * root in-process is the route a skill body has.
+ */
+export async function mainWorktreeRoot(): Promise<string> {
+  const result = await $`git worktree list --porcelain`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
+  if (result.exitCode !== 0) return process.cwd()
+
+  const line = result.stdout
+    .toString()
+    .split('\n')
+    .find((entry) => entry.startsWith('worktree '))
+
+  return line ? line.slice('worktree '.length).trim() : process.cwd()
+}
+
+export interface WorktreeEntry {
+  readonly path: string
+  readonly branch: string | null
+}
+
+export interface RefReport {
+  /** False when the ref read itself failed, so an empty `refs` says nothing about whether the branch exists. */
+  readonly readable: boolean
+  readonly refs: readonly string[]
+}
+
+/**
+ * Reports which of the local head and the `origin` remote-tracking ref already
+ * name a branch, separating an absent branch from a read that failed.
+ *
+ * `git for-each-ref` is what carries that separation. `git show-ref --verify`
+ * handed the same two ref paths exits 128 when one of them is missing, which is
+ * the code it also exits when the directory is no repository, so a caller
+ * cannot tell a half match from an unreadable tree. `for-each-ref` exits zero
+ * with empty output for absent and non-zero only for a failed read.
+ *
+ * A ref path is a pattern here rather than an exact name, so `refs/heads/x`
+ * also matches `refs/heads/x/y`. Git forbids both existing at once, so the
+ * over-match names the branch that blocks the candidate rather than a wrong
+ * one.
+ *
+ * The remote-tracking ref is read at whatever the last fetch left, so a branch
+ * pushed from another machine since then is invisible here. Closing that needs
+ * `git ls-remote`, measured at 0.438s against 0.001s for a local read.
+ */
+export async function branchRefs(
+  branch: string,
+  cwd: string = process.cwd(),
+): Promise<RefReport> {
+  // Every argument is interpolated rather than written inline, since Bun's
+  // shell parses the bare parentheses in `%(refname)` as syntax of its own.
+  const args = [
+    '--format=%(refname)',
+    `refs/heads/${branch}`,
+    `refs/remotes/origin/${branch}`,
+  ]
+
+  const result = await $`git -C ${cwd} for-each-ref ${args}`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
+  if (result.exitCode !== 0) return { readable: false, refs: [] }
+
+  return {
+    readable: true,
+    refs: result.stdout
+      .toString()
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0),
+  }
+}
+
+/**
+ * Parses `git worktree list --porcelain`, which emits one block per worktree
+ * separated by a blank line. A detached worktree carries no `branch` line,
+ * reported here as `null` rather than a guessed name.
+ */
+export async function listWorktrees(
+  cwd: string = process.cwd(),
+): Promise<readonly WorktreeEntry[]> {
+  const result = await $`git -C ${cwd} worktree list --porcelain`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
+  if (result.exitCode !== 0) return []
+
+  const entries: WorktreeEntry[] = []
+  let path: string | undefined
+  let branch: string | null = null
+
+  for (const line of result.stdout.toString().split('\n')) {
+    if (line.startsWith('worktree ')) {
+      if (path !== undefined) entries.push({ path, branch })
+      path = line.slice('worktree '.length).trim()
+      branch = null
+      continue
+    }
+
+    if (line.startsWith('branch ')) {
+      const ref = line.slice('branch '.length).trim()
+      branch = ref.startsWith('refs/heads/')
+        ? ref.slice('refs/heads/'.length)
+        : ref
+    }
+  }
+
+  if (path !== undefined) entries.push({ path, branch })
+
+  return entries
+}

package/src/worktrees/reclaim.ts

@@ -0,0 +1,306 @@
+import { $ } from 'bun'
+import { execa } from 'execa'
+import { gitEnv } from '@/git-env'
+import {
+  repositoryOf,
+  type ResolvedSession,
+  resolveSessions,
+  type SessionReport,
+} from '@/sessions/resolve'
+import { listWorktrees, type WorktreeEntry } from '@/worktree'
+
+const GH_TIMEOUT_MS = 30_000
+
+/**
+ * How many merged pull requests one read covers. A worktree older than this
+ * many merges reads as having none and is refused, which is the safe direction:
+ * the failure keeps a directory rather than removing one.
+ */
+const MERGED_LIMIT = 200
+
+/** Why one worktree cannot be reclaimed, one entry per failing condition. */
+export type Refusal =
+  | 'main-worktree'
+  | 'detached-head'
+  | 'no-merged-pull-request'
+  | 'uncommitted-changes'
+  | 'unreadable-worktree'
+  | 'held-by-session'
+
+/** Why the whole reading was refused, so no verdict was produced at all. */
+export type Unreadable = 'gh-missing' | 'gh-failed' | 'sessions-unreadable'
+
+/**
+ * Which removal shape applies. `session` removes the background session and its
+ * worktree together, and `worktree` removes a directory whose session has
+ * ended. Picking the wrong one strands state, so this is reported rather than
+ * assumed.
+ */
+export type Route = 'session' | 'worktree'
+
+/** No removal shape reaches the main worktree, which is what `null` says. */
+export type RemovalRoute = Route | null
+
+export interface WorktreeVerdict {
+  readonly path: string
+  readonly branch: string | null
+  readonly reclaimable: boolean
+  /** Every failing condition, so a reader sees what to fix rather than a bare refusal. */
+  readonly refusals: readonly Refusal[]
+  /** The pull request that retired the branch, so a report can name what it read. */
+  readonly pullRequest: number | null
+  /** The names of the live sessions holding this worktree, which is what `claude rm` takes. */
+  readonly sessions: readonly string[]
+  readonly route: RemovalRoute
+}
+
+export interface MergedPullRequest {
+  readonly branch: string
+  readonly number: number
+}
+
+export type MergedReport =
+  | { readonly kind: 'read'; readonly merged: readonly MergedPullRequest[] }
+  | {
+      readonly kind: 'unreadable'
+      readonly reason: Extract<Unreadable, 'gh-missing' | 'gh-failed'>
+      readonly detail: string
+    }
+
+export interface StatusReport {
+  /** False when the status read itself failed, so a clean `dirty` says nothing. */
+  readonly readable: boolean
+  readonly dirty: boolean
+}
+
+export type ReclaimReport =
+  | {
+      readonly kind: 'unreadable'
+      readonly reason: Unreadable
+      readonly detail: string
+    }
+  | { readonly kind: 'read'; readonly worktrees: readonly WorktreeVerdict[] }
+
+export interface ReclaimOptions {
+  readonly cwd?: string
+  readonly listWorktrees?: (cwd: string) => Promise<readonly WorktreeEntry[]>
+  readonly mergedPullRequests?: (cwd: string) => Promise<MergedReport>
+  readonly worktreeStatus?: (path: string) => Promise<StatusReport>
+  readonly resolve?: () => Promise<SessionReport>
+}
+
+/**
+ * Reads the pull request state for the whole repository in one call.
+ *
+ * One call rather than one per worktree, since the per-worktree shape is a
+ * network round trip inside a loop and the branches being matched are already
+ * known before any of them runs.
+ */
+async function mergedPullRequests(cwd: string): Promise<MergedReport> {
+  if (Bun.which('gh') === null) {
+    return {
+      kind: 'unreadable',
+      reason: 'gh-missing',
+      detail: 'gh is not on the path, so no merge state could be read.',
+    }
+  }
+
+  const args = [
+    'pr',
+    'list',
+    '--state',
+    'merged',
+    '--limit',
+    String(MERGED_LIMIT),
+    '--json',
+    'headRefName,number',
+  ]
+
+  try {
+    // `gh` resolves its repository through git, so it reads the same
+    // resolution variables a hook exports and they take precedence over `cwd`.
+    // A run from inside one would answer with another repository's merged
+    // branches, and a branch name that recurs across repositories would then
+    // match a merge that happened somewhere else and read a live worktree as
+    // reclaimable, which is the unsafe direction on an unrecoverable removal.
+    const result = await execa('gh', args, {
+      cwd,
+      timeout: GH_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+    })
+    const rows = JSON.parse(result.stdout) as readonly {
+      headRefName: string
+      number: number
+    }[]
+
+    return {
+      kind: 'read',
+      merged: rows.map((row) => ({
+        branch: row.headRefName,
+        number: row.number,
+      })),
+    }
+  } catch (error) {
+    return {
+      kind: 'unreadable',
+      reason: 'gh-failed',
+      detail: error instanceof Error ? error.message : String(error),
+    }
+  }
+}
+
+/**
+ * Reports whether a worktree holds work no history is behind.
+ *
+ * Untracked files count, since a worktree is gitignored scratch and a directory
+ * removed with them takes them nowhere recoverable. A failed read is separated
+ * from a clean tree, because the two produce the same empty output and only one
+ * of them is safe to act on.
+ */
+async function worktreeStatus(path: string): Promise<StatusReport> {
+  const result = await $`git -C ${path} status --porcelain`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
+  if (result.exitCode !== 0) return { readable: false, dirty: false }
+
+  return { readable: true, dirty: result.stdout.toString().trim().length > 0 }
+}
+
+/**
+ * Names the live sessions holding one worktree.
+ *
+ * The path match is the direct reading and the branch match is what survives a
+ * path spelled differently on either side, such as a symlinked temporary
+ * directory. The branch half is scoped to the repository, since a branch name
+ * identifies a branch inside one and nothing across a machine.
+ */
+function holders(
+  entry: WorktreeEntry,
+  sessions: readonly ResolvedSession[],
+  repository: string | null,
+): readonly string[] {
+  return sessions
+    .filter(
+      (candidate) =>
+        candidate.worktree === entry.path ||
+        (entry.branch !== null &&
+          candidate.branch === entry.branch &&
+          candidate.repository === repository),
+    )
+    .map((candidate) => candidate.name)
+}
+
+function verdict(
+  entry: WorktreeEntry,
+  isMain: boolean,
+  status: StatusReport,
+  merged: ReadonlyMap<string, number>,
+  sessions: readonly ResolvedSession[],
+  repository: string | null,
+): WorktreeVerdict {
+  const held = holders(entry, sessions, repository)
+  const pullRequest =
+    entry.branch === null ? null : (merged.get(entry.branch) ?? null)
+  const refusals: Refusal[] = []
+
+  if (isMain) refusals.push('main-worktree')
+  if (entry.branch === null) refusals.push('detached-head')
+  else if (pullRequest === null) refusals.push('no-merged-pull-request')
+
+  if (!status.readable) refusals.push('unreadable-worktree')
+  else if (status.dirty) refusals.push('uncommitted-changes')
+
+  if (held.length > 0) refusals.push('held-by-session')
+
+  return {
+    path: entry.path,
+    branch: entry.branch,
+    reclaimable: refusals.length === 0,
+    refusals,
+    pullRequest,
+    sessions: held,
+    // No removal shape reaches the main worktree, and reporting one there
+    // offers a command whose only effect is to break the checkout. Deciding it
+    // here rather than in the reporter keeps the record and the framed output
+    // answering the same way, since the two consumers act on different halves.
+    route: isMain ? null : held.length > 0 ? 'session' : 'worktree',
+  }
+}
+
+/**
+ * Reports which worktrees are reclaimable and which are not, with the reason on
+ * each.
+ *
+ * Reclaimable means all three of a merged pull request, a clean working tree,
+ * and no live session holding the directory. Each alone has a case where
+ * removal loses something, and removal is unrecoverable here since a worktree
+ * is gitignored and no history stands behind it.
+ *
+ * The pull request is what decides the first condition rather than git
+ * ancestry. A repository that squash merges never makes a merged branch an
+ * ancestor of its trunk, so the ancestry reading calls shipped work unmerged
+ * and calls an abandoned branch sitting at a release commit merged, which is
+ * wrong in the one direction that removes a directory.
+ *
+ * An unreadable input refuses the whole reading rather than producing verdicts
+ * around it. An absent merge state and a branch with no merged pull request
+ * produce the same empty answer, as do an absent session roster and a worktree
+ * nobody holds, and reporting the second when it was the first is a false clean
+ * that ends in a removal.
+ */
+export async function reclaimReport(
+  opts: ReclaimOptions = {},
+): Promise<ReclaimReport> {
+  const cwd = opts.cwd ?? process.cwd()
+  const listAll = opts.listWorktrees ?? listWorktrees
+  const readMerged = opts.mergedPullRequests ?? mergedPullRequests
+  const readStatus = opts.worktreeStatus ?? worktreeStatus
+  const resolve = opts.resolve ?? resolveSessions
+
+  const [entries, merged, sessions, repository] = await Promise.all([
+    listAll(cwd),
+    readMerged(cwd),
+    resolve(),
+    repositoryOf(cwd),
+  ])
+
+  if (merged.kind === 'unreadable') {
+    return {
+      kind: 'unreadable',
+      reason: merged.reason,
+      detail: merged.detail,
+    }
+  }
+
+  if (sessions.kind !== 'resolved') {
+    return {
+      kind: 'unreadable',
+      reason: 'sessions-unreadable',
+      detail: `No session registry at ${sessions.dir}, so nothing was read about which worktrees are still held.`,
+    }
+  }
+
+  const byBranch = new Map(
+    merged.merged.map((request) => [request.branch, request.number]),
+  )
+  const statuses = await Promise.all(
+    entries.map((entry) => readStatus(entry.path)),
+  )
+
+  // `git worktree list` puts the main worktree first, which is the only signal
+  // separating it from a linked one in the porcelain output.
+  const worktrees = entries.map((entry, index) =>
+    verdict(
+      entry,
+      index === 0,
+      statuses[index] ?? { readable: false, dirty: false },
+      byBranch,
+      sessions.sessions,
+      repository,
+    ),
+  )
+
+  return { kind: 'read', worktrees }
+}

package/standards/architecture.md

@@ -0,0 +1,72 @@
+---
+title: Architecture reference
+description: Shape and content rules for .claude/ARCHITECTURE.md
+---
+
+# Architecture reference
+
+Applies to `.claude/ARCHITECTURE.md`. Describes the system shape and the decisions behind it, not a tutorial, setup guide, or implementation walkthrough. Pair it with `CLAUDE.md`: principles live there, patterns and decisions live here. Update when a decision is made or a risk is resolved.
+
+## Scope
+
+Governs the system-shape document at `.claude/ARCHITECTURE.md`: the overview, the decision entries, and the open risks.
+
+Does not govern:
+
+- Per-domain structure and narrative: `context.md`
+- Setup commands and install instructions: `readme.md`
+- Product scope, goals, and non-goals: `requirements.md`
+
+## What goes in
+
+- A high-level overview of how the system is structured and why
+- Key technical decisions as named H3 entries: what was chosen and why over the alternatives, including stack and library choices
+- Risks and open questions still unresolved
+
+## What does not go in
+
+- How individual functions work line by line. The code carries its own behavior.
+- Full type definitions. They live in code. Reference the shape conceptually if needed.
+
+## Sections
+
+Use `## Overview`, `## Key technical decisions` with one named H3 per decision, and `## Risks / open questions`. Name each decision and give the reasoning, especially for non-obvious choices. Skip entries where the rationale is self-evident.
+
+## Verification anchors
+
+A decision's reasoning stays correct while the numbers it cites move. The anchor records what a measured claim was read against, so a reader can tell a number that was checked and held from one nobody has looked at since.
+
+- Close a decision entry whose reasoning cites a measured number with a trailing sentence naming the short commit SHA and the ISO date that number was read: `Measured at <short-sha> on <YYYY-MM-DD>.`
+- Anchor on the number alone. A decision citing none takes no anchor whatever its reasoning rests on, because a marker over a claim nobody can re-measure is one no reader can falsify.
+- Anchor a decision when writing it or when amending its reasoning. Leave an entry written before the rule unanchored rather than dating it by blame, which is archaeology for a marker nothing reads back.
+- Read an absent anchor as unchecked rather than as current. On an entry citing no number there is nothing to check. On one citing a number the number is due a read.
+- Do not edit a claim in the pass that first anchors it. The anchor states what the claim was measured against, so changing both at once leaves nothing to check the anchor against.
+- Refresh the anchor whenever the number is re-read, whether or not it moved. A confirmed number and an unread one are the same text without the date.
+
+## Length
+
+Every session pays for this file before any work starts, so it carries a budget. The budget counts decisions rather than lines, because a bare line total is satisfied by merging paragraph pairs and the merged paragraphs then fail the weight checkpoint in `markdown.md`. A file over budget is carrying too many decisions, not decisions written too long.
+
+- Budget six lines per decision entry, being the H3, two paragraphs, and the blank lines separating them.
+- Budget the frame outside `## Key technical decisions` separately, covering the H1, the overview, and the risks. State the number the project takes where it records the budget, since a frame carries no fixed structure to derive one from.
+- Read the ceiling as the frame plus six lines against the decision count, rather than as the total the two multiply out to.
+- Bring an over-budget file back by merging two decisions or retiring one, never by compressing a decision's prose.
+- Yield the budget to the paragraph weight checkpoint when the two disagree. A paragraph past the checkpoint is a defect no budget licenses.
+
+## Template
+
+The anchor sentence closes a decision whose reasoning cites a measured number and is absent from one that cites none.
+
+```markdown
+# Architecture
+
+## Overview
+
+## Key technical decisions
+
+### Decision name
+
+Reasoning and tradeoffs, carrying the measured number the choice rested on. Measured at <short-sha> on <YYYY-MM-DD>.
+
+## Risks / open questions
+```

package/standards/branch.md

@@ -0,0 +1,59 @@
+---
+title: Branch reference
+description: Branch naming format and type conventions
+---
+
+# Branch reference
+
+## Scope
+
+Governs a git branch name: its structure, its length, and the type vocabulary it draws from.
+
+Does not govern:
+
+- Commit subject format, which shares the type vocabulary: `commit.md`
+- Pull request title and body: `pr.md`
+- Whether a phase label may appear in a branch name: `versioning.md`
+- Deriving a slug from a branch name for use in an output filename: `slug.md`
+
+## Format
+
+- Structure: `<type>/<description>` or `<type>/<ticket>-<description>`
+- Length: 50 characters maximum
+- Casing: kebab-case only, no underscores or camelCase
+- Description: 2 words maximum, 3 only when genuinely needed for specificity
+- Capture the core change, not the commit message verbatim
+- For branches with multiple commits, use the unifying concern as the description.
+- Do not duplicate type in description (e.g., `feat/feature-login`)
+
+## Types
+
+- `feat`: new feature or capability
+- `fix`: bug fix
+- `refactor`: structural changes (not a fix or feature)
+- `docs`: documentation only (README)
+- `chore`: maintenance tasks (deps, tooling, configs)
+- `perf`: performance improvements
+- `test`: add or modify tests
+- `style`: code formatting (whitespace, semicolons)
+- `build`: build system changes (webpack, npm scripts)
+- `ci`: CI/CD pipeline changes (GitHub Actions)
+- `revert`: revert a previous commit
+
+## Examples
+
+### Correct
+
+```plaintext
+feat/jwt-expiration                    # clear feature scope
+fix/AUTH-123-connection-pool           # includes ticket ID
+refactor/remove-deprecated-endpoints   # clear refactor intent
+```
+
+### Incorrect
+
+```plaintext
+feature/auth_stuff                                        # wrong type + underscore
+feat/feature-add-login                                    # duplicates type in description
+fix/DB-456-fix-the-database-connection-pool-memory-leak   # exceeds 50 chars + verbatim message
+```

package/standards/commit.md

@@ -0,0 +1,72 @@
+---
+title: Commit reference
+description: Commit message format and type conventions
+---
+
+# Commit message reference
+
+## Scope
+
+Governs a git commit message: subject structure, the type and scope vocabulary, and the body.
+
+Does not govern:
+
+- Branch naming, which shares the type vocabulary: `branch.md`
+- Pull request title and body, which share the subject form: `pr.md`
+- Whether a phase label or a semver tag may appear in a subject: `versioning.md`
+
+## Format
+
+- Structure: `<type>(<scope>): <subject>`
+- Casing: lowercase for `<type>`, `<scope>`, and first word of `<subject>`
+- Subject: 72 characters maximum, no trailing period
+
+## Types
+
+- `feat`: new feature or capability
+- `fix`: bug fix
+- `refactor`: structural changes (not a fix or feature)
+- `docs`: documentation only (README)
+- `chore`: maintenance tasks (deps, tooling, configs)
+- `perf`: performance improvements
+- `test`: add or modify tests
+- `style`: code formatting (whitespace, semicolons)
+- `build`: build system changes (webpack, npm scripts)
+- `ci`: CI/CD pipeline changes (GitHub Actions)
+- `revert`: revert a previous commit
+
+## Scope vocabulary
+
+- Single lowercase word representing a system component
+- Prefer single word
+- Use kebab-case only when two words are genuinely needed for specificity
+- Do not use specific filenames as scopes
+- Do not use a scope that duplicates the type
+- Write scopes for release readability. They surface in `changelogithub` release notes.
+
+## Subject
+
+- Use imperative mood (`add` not `added`)
+- Describe the actual technical change, not that something changed
+- Do not use vague verbs (`improve`, `refine`, `enhance`)
+- Do not repeat the scope in the subject line
+- Use single quotes if quoting
+- No backslash escaping or internal double quotes
+- No conversational filler or introductory phrases
+
+## Examples
+
+### Correct
+
+```plaintext
+feat(api): add retry logic for failed webhooks       # specific verb + clear change
+fix(auth): update 'UserSession' validation logic     # scoped + imperative + single quotes
+```
+
+### Incorrect
+
+```plaintext
+fix(user-auth): Fixed the redirect loop.    # wrong casing + period + multi-word scope
+docs(docs): update the readme.              # duplicate scope + period
+docs(api): improve documentation            # vague verb + lacks specificity
+```