@erclx/canon 5.45.0 → 5.46.0

package/src/tasks/closes.ts

@@ -0,0 +1,136 @@
+import { readFile } from 'node:fs/promises'
+import {
+  fenceMask,
+  readOutcomes,
+  readPendingBranches,
+  readPullRequest,
+} from '@/tasks/archive'
+import {
+  openTask,
+  type RecordRefused,
+  type RecordSelector,
+} from '@/tasks/record'
+
+/**
+ * Why a task does or does not close its issues. `last-slice` is the only
+ * reason that closes. The rest mirror the conditions `archiveTask` applies at
+ * merge time, so an issue closes exactly when the task archives.
+ */
+export type ClosingReason =
+  | 'earlier-slice'
+  | 'last-slice'
+  | 'lookup-failed'
+  | 'no-issues'
+  | 'no-outcomes'
+  | 'open-outcomes'
+  | 'pending-branch'
+
+export interface Closure {
+  readonly issues: readonly number[]
+  readonly closing: boolean
+  readonly reason: ClosingReason
+}
+
+export interface TaskClosure extends Closure {
+  readonly ok: true
+  readonly stem: string
+  readonly path: string
+}
+
+export type ClosureOutcome = TaskClosure | RecordRefused
+
+const ISSUE_LINE = /^Issue:[ \t]*(#\d+(?:[ \t]*,[ \t]*#\d+)*)[ \t]*$/
+
+/**
+ * Reads every `Issue:` line outside a fence, each a bare `#NNN` or a comma
+ * list of them. A line carrying anything else, such as the older bare-path
+ * form, names no issue rather than the numbers that happened to parse, since a
+ * wrong number would close an unrelated issue.
+ */
+export function readIssues(text: string): readonly number[] {
+  const lines = text.split('\n')
+  const fenced = fenceMask(lines)
+  const issues = new Set<number>()
+
+  for (const [index, line] of lines.entries()) {
+    if (fenced[index]) continue
+
+    const match = ISSUE_LINE.exec(line)
+    if (!match) continue
+
+    for (const entry of match[1].split(',')) {
+      issues.add(Number(entry.trim().slice(1)))
+    }
+  }
+
+  return [...issues]
+}
+
+/**
+ * Decides whether the pull request for `branches` closes the task's issues.
+ * `branches` is the working branch and every name it carried, since a rename
+ * leaves the `Pending branch:` marker under the old one. Any other pending
+ * branch is a slice still to ship, so the task stays open behind it.
+ */
+export function decideClosing(
+  text: string,
+  branches: readonly string[],
+  pulls: readonly number[] | null = [],
+): Closure {
+  const issues = readIssues(text)
+  if (issues.length === 0) {
+    return { issues, closing: false, reason: 'no-issues' }
+  }
+
+  const listed = readPullRequest(text)
+  const last = listed.at(-1)
+
+  // A failed lookup cannot rule out that this branch is an earlier slice, and
+  // closing early is the unsafe direction. With nothing recorded yet there is
+  // no earlier slice to confuse it with, so that case still closes.
+  if (pulls === null && listed.length > 0) {
+    return { issues, closing: false, reason: 'lookup-failed' }
+  }
+
+  if (
+    last !== undefined &&
+    pulls !== null &&
+    !pulls.includes(last) &&
+    pulls.some((number) => listed.includes(number))
+  ) {
+    return { issues, closing: false, reason: 'earlier-slice' }
+  }
+
+  const others = readPendingBranches(text).filter(
+    (branch) => !branches.includes(branch),
+  )
+  if (others.length > 0) {
+    return { issues, closing: false, reason: 'pending-branch' }
+  }
+
+  const { open, closed, cut } = readOutcomes(text)
+  if (open.length > 0) {
+    return { issues, closing: false, reason: 'open-outcomes' }
+  }
+
+  if (closed.length === 0 && cut.length === 0) {
+    return { issues, closing: false, reason: 'no-outcomes' }
+  }
+
+  return { issues, closing: true, reason: 'last-slice' }
+}
+
+/** Resolves the task through the same selector `pull-request` takes. */
+export async function readClosure(
+  root: string,
+  selector: RecordSelector,
+  branches: readonly string[],
+  pulls: readonly number[] | null = [],
+): Promise<ClosureOutcome> {
+  const opened = await openTask(root, selector)
+  if ('ok' in opened) return opened
+
+  const text = await readFile(opened.path, 'utf8')
+
+  return { ok: true, ...opened, ...decideClosing(text, branches, pulls) }
+}

package/src/tasks/record.ts

@@ -400,7 +400,7 @@ async function resolveStem(
   return matched[0]
 }
 
-async function openTask(
+export async function openTask(
   root: string,
   selector: RecordSelector,
 ): Promise<{ readonly stem: string; readonly path: string } | RecordRefused> {

package/src/worktrees/reclaim.ts

@@ -37,7 +37,11 @@ export type Refusal =
   | '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'
+export type Unreadable =
+  | 'gh-missing'
+  | 'gh-failed'
+  | 'sessions-unreadable'
+  | 'sessions-unchecked'
 
 /**
  * Which removal shape applies. `session` removes the background session and its
@@ -395,6 +399,17 @@ export async function reclaimReport(
     }
   }
 
+  // A foreign-namespace record whose socket is gone reads dead, but a reader
+  // that cannot see the pid may also be unable to see the socket, so it may be
+  // a live holder. The roster drops it, and a removal on that reading is final.
+  if (sessions.foreignDead > 0) {
+    return {
+      kind: 'unreadable',
+      reason: 'sessions-unchecked',
+      detail: `${sessions.foreignDead} session records come from another pid namespace and no socket answers for them, so nothing was read about whether they still hold a worktree.`,
+    }
+  }
+
   const byBranch = new Map(
     merged.merged.map((request) => [request.branch, request.number]),
   )

package/tooling/base/configs/scripts/verify.ts

@@ -323,7 +323,7 @@ function checkMarkdownBans(): void {
     case 2:
       pipeOutput(output)
       fail(
-        'Markdown prose carries a banned character, or a relative link resolves to nothing on disk',
+        'Markdown prose carries a banned character, a relative link resolves to nothing on disk, or a gated path breaks a density limit',
       )
       break
     case 3:

package/tooling/claude/seeds/.claude/hooks/board-validate.sh

@@ -51,7 +51,7 @@ fi
 # Exit 2 carries findings, so the status is read off the record rather than
 # the exit code.
 record=$(canon tasks validate --json --root "$root" 2>/dev/null)
-ok=$(printf '%s' "$record" | jq -r '.ok // empty' 2>/dev/null)
+ok=$(printf '%s' "$record" | jq -r '.ok | tostring' 2>/dev/null)
 
 if [ "$ok" = false ]; then
   report "canon tasks validate refused the board after this edit: $(printf '%s' "$record" | jq -r '.message // .reason')"

package/tooling/claude/seeds/CLAUDE.md

@@ -4,14 +4,14 @@
 
 ## Context
 
-- Before non-trivial work in a domain read `canon/context/<domain>.md`. Pick which from the index anchor below.
+- Before non-trivial work in a domain, read its entry under `canon/context/`. Find it from the index anchor below.
 
 @canon/REQUIREMENTS.md
 @canon/context/index.md
 
 ## Commands
 
-- [Command to run before committing]
+- Run `bun run check` to verify and `bun run format` to fix before committing. The pre-push hook runs `check`, which writes nothing.
 
 ## Key paths
 

package/governance/rules/canon/task-scope.md

@@ -1,12 +0,0 @@
----
-description: Scope, size, and link a task file correctly
----
-
-# Tasks standards
-
-## Task files
-
-- Only create a task for work that spans multiple sessions or has real dependencies. Handle small edits immediately without a task entry.
-- Do not add tasks retroactively for work already completed. Completed work is visible in git.
-- Write a plan in `.canon/plans/` when a task needs execution detail beyond its own file, and link it from the task's intro paragraph.
-- Write that plan in the same session as the task, since the executing session would otherwise re-derive the reasoning behind it.