@erclx/canon 4.72.1 → 4.74.0

package/src/sync/stamp.ts

@@ -84,17 +84,30 @@ export function retiredNameStampPath(target: string): string {
   return join(target, '.claude', 'aitk', 'config.json')
 }
 
+/**
+ * The stamp path under the new surface root, `canon/config/config.json`.
+ *
+ * Read ahead of `stampPath`, extending the same mechanism rather than adding a
+ * new one: a target that has moved reads its config from the root it moved
+ * to, and one that has not falls through to the spellings below unchanged.
+ * The write destination does not move to it in this batch.
+ */
+function surfaceStampPath(target: string): string {
+  return join(target, 'canon', 'config', 'config.json')
+}
+
 /**
  * Every spelling a stamp has been written under, current first. The order is
  * the read order, so a target carrying more than one resolves to the newest.
  *
- * The fallback carries no end date. It costs two path reads on a command that
- * already touches the filesystem, and dropping it later is a second breaking
- * change aimed at exactly the targets that were slowest to migrate the first
- * time.
+ * The fallback carries no end date. It costs three path reads on a command
+ * that already touches the filesystem, and dropping any of them later is a
+ * second breaking change aimed at exactly the targets that were slowest to
+ * migrate the first time.
  */
 export function stampPaths(target: string): readonly string[] {
   return [
+    surfaceStampPath(target),
     stampPath(target),
     retiredNameStampPath(target),
     legacyStampPath(target),
@@ -107,7 +120,9 @@ export function stampPaths(target: string): readonly string[] {
  * there is nothing to migrate off of.
  */
 export function isLegacyStamped(target: string): boolean {
-  if (existsSync(stampPath(target))) return false
+  if (existsSync(surfaceStampPath(target)) || existsSync(stampPath(target))) {
+    return false
+  }
   return (
     existsSync(retiredNameStampPath(target)) ||
     existsSync(legacyStampPath(target))

package/src/tasks/answers.ts

@@ -4,6 +4,7 @@ import { isAbsolute, relative, resolve } from 'node:path'
 import { isUnder } from '@/paths'
 import { recordDir, recordDirs } from '@/record-root'
 import {
+  hasStagedBatches,
   normalizeOperatorCall,
   OPERATOR_CALL,
   readQuestions,
@@ -219,9 +220,17 @@ export async function planAnswers(
   const resolved = resolvePlanReference(root, reference)
   if (!resolved.ok) return resolved
 
-  const sections = splitPlanSections(await readFile(resolved.path, 'utf8'))
+  const text = await readFile(resolved.path, 'utf8')
+  const sections = splitPlanSections(text)
   const open = openQuestions(sections.get('Questions') ?? [])
 
+  if (hasStagedBatches(text)) {
+    open.push({
+      label: 'Batch staging',
+      why: 'stages a batch inside one file and must split into one plan file per batch before it can dispatch.',
+    })
+  }
+
   return {
     ok: true,
     plan: resolved.plan,

package/src/transcripts/fetch.ts

@@ -1,4 +1,5 @@
 import {
+  existsSync,
   mkdirSync,
   mkdtempSync,
   readdirSync,
@@ -81,13 +82,42 @@ interface WriteOptions {
   readonly fetchedAt: string
 }
 
+const INDEX_FILE = 'index.md'
+
+/**
+ * Writes a minimal index.md stub if the output directory carries none yet,
+ * so `canon indexes regen` has frontmatter to render entries against. Left
+ * alone once present, since a project may have customized it.
+ */
+function ensureIndex(outDir: string): void {
+  const indexPath = join(outDir, INDEX_FILE)
+  if (existsSync(indexPath)) return
+
+  const content = [
+    '---',
+    'title: Transcripts',
+    'subtitle: YouTube transcripts fetched by canon transcripts, one file per video.',
+    '---',
+    '',
+    '# Transcripts',
+    '',
+    'YouTube transcripts fetched by canon transcripts, one file per video.',
+    '',
+    'This folder is machine-written. Run canon indexes regen here to refresh its entries.',
+    '',
+  ].join('\n')
+
+  writeFileSync(indexPath, content)
+}
+
 export function writeTranscript(
   metadata: VideoMetadata,
   subPath: string | null,
   { outDir, keepTimestamps, fetchedAt }: WriteOptions,
 ): string {
   mkdirSync(outDir, { recursive: true })
-  const slug = `${slugify(metadata.title)}--${metadata.videoId}`
+  ensureIndex(outDir)
+  const slug = `${fetchedAt}--${slugify(metadata.title)}--${metadata.videoId}`
   const target = join(outDir, `${slug}.md`)
 
   const hasTranscript = subPath !== null

package/standards/groundwork.md

@@ -25,7 +25,7 @@ Does not govern:
 ## Folder name
 
 - Name the folder `<nn>-<slug>`, a two-digit zero-padded ordinal followed by a kebab-case slug.
-- Take the ordinal from the highest one already present across both `.canon/groundwork/` and `.canon/intake/`, incremented. A listing then sorts by when each folder opened rather than alphabetically, and the count includes both kinds because the two share one creation-order line.
+- Claim the ordinal through `canon records ordinal groundwork <slug> --claim`, which reads the highest one already present across both `.canon/groundwork/` and `.canon/intake/` and creates the folder in the same atomic act, closing the race a read-then-create sequence leaves open between two sessions opening at once. A listing then sorts by when each folder opened rather than alphabetically, and the count includes both kinds because the two share one creation-order line.
 - With neither folder holding an entry, the first one opened takes `01`. Do not read this off the numbering inside a track, which starts at `00` on a large one and disagrees with intake's own first file.
 - Never renumber an existing folder. The ordinal is the order it opened, and a later reader cites it by that name.
 

package/standards/intake.md

@@ -25,7 +25,7 @@ Does not govern:
 ## Folder name
 
 - Name the folder `<nn>-<slug>`, a two-digit zero-padded ordinal followed by a kebab-case slug. This is the folder's own ordinal, distinct from the `NN-<domain>.md` numbering a cluster file carries inside it.
-- Take the ordinal from the highest one already present across both `.canon/intake/` and `.canon/groundwork/`, incremented. A listing then sorts by when each folder opened rather than alphabetically, and the count includes both kinds because the two share one creation-order line.
+- Claim the ordinal through `canon records ordinal intake <slug> --claim`, which reads the highest one already present across both `.canon/intake/` and `.canon/groundwork/` and creates the folder in the same atomic act, closing the race a read-then-create sequence leaves open between two sessions opening at once. A listing then sorts by when each folder opened rather than alphabetically, and the count includes both kinds because the two share one creation-order line.
 - With neither folder holding an entry, the first one opened takes `01`. Do not read this off the numbering inside a dump, which starts at `00` and disagrees with groundwork's own first required file.
 - Never renumber an existing folder. The ordinal is the order it opened, and a later reader cites it by that name.
 

package/standards/plan.md

@@ -38,6 +38,7 @@ A plan failing these is non-conforming even when it satisfies every shape rule b
 
 - Name the file `feature-<slug>.md`, with `<slug>` two to four kebab-case words naming the concern.
 - Write one concern per file. A request spanning two independent concerns takes two plans rather than one bundling both, since a bundled plan cannot be executed by two sessions or abandoned by half.
+- A staged batch is a concern of its own and takes its own file rather than a `**Batch N**` sub-heading inside one plan's `**Files to touch:**`. `canon tasks plan-branch` derives one branch from one plan filename, so every batch sharing a file has nothing left to open a pull request against once an earlier batch merges under that name. State a batch's dependency on the ones before it in its own `**Constraints:**`.
 - Derive the slug from the concern rather than from a branch, because the plan is written before the branch exists.
 - Give the branch that executes the plan the same slug. A later surface finds the plan from the branch name and finds nothing when the two spellings differ.
 

package/tooling/base/configs/.husky/post-merge

@@ -59,3 +59,30 @@ done
 printf '\n📋 %s archive candidate(s) on the board:\n%s\n' "$count" "$closed"
 printf 'Outcomes are marked on the branch, so each still needs its work confirmed\n'
 printf 'on main. Run /task-board, which checks that and sweeps the plan first.\n\n'
+
+# The gitignored record folders live on one disk and nowhere else, and a merge
+# is the event that changes them most. This runs on every merge rather than
+# only on one that closes a task, since a review report and a memory entry
+# both land on runs that archive nothing.
+#
+# Sits last so a slow or unreachable remote delays no candidate announcement,
+# and inside an `if` so a push failing offline, or a machine that never ran
+# the one-time setup, still leaves this hook exiting zero. Guarded by its own
+# `command -v canon` check, since this file carries none above it.
+if command -v canon >/dev/null 2>&1; then
+  if backup=$(canon records push --root "$root" --json 2>/dev/null); then
+    changed=$(printf '%s' "$backup" | sed -n 's/.*"changed":\([0-9][0-9]*\).*/\1/p')
+    if [ -n "$changed" ] && [ "$changed" != "0" ]; then
+      printf '\n🗄️  Backed up %s record path(s).\n\n' "$changed"
+    fi
+  else
+    reason=$(printf '%s' "$backup" | sed -n 's/.*"reason":"\([^"]*\)".*/\1/p')
+
+    # No records history on this machine, which is every checkout that never
+    # ran the one-time setup. Nothing to report.
+    if [ "$reason" != "no-repository" ]; then
+      printf '\n🗄️  Records not backed up: %s\n' "${reason:-unknown}"
+      printf 'Run canon records push when the remote is reachable.\n\n'
+    fi
+  fi
+fi

package/tooling/claude/seeds/.claude/hooks/tasks-index.sh

@@ -34,11 +34,12 @@ case "$file_path" in
 esac
 
 # The board index covers the live folder alone. A shell pattern's wildcard
-# crosses a separator, so the guard above matches an archived task as well and
-# a regen fired on one would rebuild the index the archive was taken out of.
+# crosses a separator, so the guard above matches an archived or declined task
+# as well, and a regen fired on one would rebuild the index that task was
+# taken out of.
 case "$file_path" in
-*/.claude/tasks/index.md | */.claude/tasks/archive/*) exit 0 ;;
-*/.canon/tasks/index.md | */.canon/tasks/archive/*) exit 0 ;;
+*/.claude/tasks/index.md | */.claude/tasks/archive/* | */.claude/tasks/declined/*) exit 0 ;;
+*/.canon/tasks/index.md | */.canon/tasks/archive/* | */.canon/tasks/declined/*) exit 0 ;;
 esac
 
 # The walk-up boundary has to come from the path, not from the session. Shared