@erclx/canon 5.27.0 → 5.29.0

package/src/sync/workflow.ts

@@ -22,7 +22,7 @@ import {
   palette,
   pipeOutput,
   select,
-} from '@/ui'
+} from '@/cli/ui'
 
 const PROTECTED_BRANCHES: readonly string[] = ['main', 'master']
 

package/src/targets/validate.ts

@@ -1,7 +1,7 @@
 import { statSync } from 'node:fs'
 import { resolve } from 'node:path'
-import { checkoutMismatchWarning } from '@/project-root'
-import { logError, logWarn, outro } from '@/ui'
+import { checkoutMismatchWarning } from '@/roots/project'
+import { logError, logWarn, outro } from '@/cli/ui'
 
 export function isDirectory(path: string): boolean {
   try {

package/src/tasks/answers.ts

@@ -2,7 +2,7 @@ import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { isAbsolute, relative, resolve } from 'node:path'
 import { isUnder } from '@/tasks/paths'
-import { recordDir, recordDirs } from '@/record-root'
+import { recordDir, recordDirs } from '@/roots/record'
 import {
   hasStagedBatches,
   normalizeOperatorCall,

package/src/tasks/archive.ts

@@ -3,7 +3,7 @@ import { mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises'
 import { basename, dirname, join, relative, resolve, sep } from 'node:path'
 import { regenOne } from '@/indexes/regen'
 import { isUnder } from '@/tasks/paths'
-import { recordDir, recordDirs } from '@/record-root'
+import { recordDir, recordDirs } from '@/roots/record'
 
 const TASKS = 'tasks'
 const PLANS = 'plans'

package/src/tasks/label.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs'
 import { mkdir, readdir } from 'node:fs/promises'
 import { relative } from 'node:path'
-import { recordDir } from '@/record-root'
+import { recordDir } from '@/roots/record'
 import {
   archiveDir,
   declinedDir,

package/src/tasks/reach.ts

@@ -2,7 +2,7 @@ import { existsSync } from 'node:fs'
 import { readdir, readFile } from 'node:fs/promises'
 import { basename, join } from 'node:path'
 import { listChangedFiles, resolveBaseRef } from '@/git/files'
-import { recordDir } from '@/record-root'
+import { recordDir } from '@/roots/record'
 import { splitPlanSections } from '@/records/validate'
 import { type AnswersRefused, resolvePlanReference } from '@/tasks/answers'
 import { orderingPath, readBoard } from '@/tasks/validate'

package/src/tasks/validate.ts

@@ -50,7 +50,6 @@ export const FINDING_KINDS = [
   'row-misordered',
   'row-unranked',
   'touches-unstated',
-  'touches-collided',
   'blocker-settled',
   'blocker-unresolved',
   'blocker-declined',
@@ -89,6 +88,20 @@ export interface FolderClaim {
   readonly message: string
 }
 
+/**
+ * A path two `## Run now` rows both name in their `Touches` cells. A shared
+ * file is no hold, since the dispatch gate starts both rows and the branch
+ * merging second rebases, so the pair reports beside the findings and moves no
+ * exit code. It stays listed because merge order reads it, and because it is
+ * the candidate list a dispatcher reads for the dependency, contract,
+ * relocation, and sweep holds a `Touches` cell cannot state.
+ */
+export interface SharedFiles {
+  readonly group: BoardGroup
+  readonly subject: string
+  readonly message: string
+}
+
 /**
  * A code span in a board cell that the markdown preview cannot break, so it
  * pushes the table past the pane and makes it scroll sideways. Either the
@@ -151,6 +164,7 @@ export interface ValidateReport {
   readonly findings: readonly Finding[]
   readonly untested: readonly Untested[]
   readonly claims: readonly FolderClaim[]
+  readonly shared: readonly SharedFiles[]
   readonly wide: readonly WideToken[]
   readonly unplaced: readonly Unplaced[]
 }
@@ -892,17 +906,16 @@ function planPath(target: string, dir: string, root: string): string {
 }
 
 /**
- * The half of the `## Run now` test a person cannot check by eye. Two rows a
- * worker may be handed at once must touch disjoint files, and the `Touches`
- * column is the only place either set is written down.
+ * Reports a `## Run now` row stating no file set. The `Touches` column is the
+ * only place a row's set is written down, so a row stating none drops out of
+ * every pair `checkSharedFiles` reads, and its merge order and reach go unread.
  */
-function checkCollisions(rows: readonly BoardRow[]): Finding[] {
+function checkTouches(rows: readonly BoardRow[]): Finding[] {
   const findings: Finding[] = []
-  const ready = rows.filter((row) => row.group === 'Run now')
 
-  for (const row of ready) {
-    // An absent column and an unreadable one both leave the row untested by
-    // the loop below, so reporting only the second would pass a board whose
+  for (const row of rows.filter((candidate) => candidate.group === 'Run now')) {
+    // An absent column and an unreadable one both leave the row out of every
+    // pair, so reporting only the second would pass a board whose
     // `## Run now` table declares no file set at all.
     if (!row.touches || row.touches.length === 0) {
       findings.push({
@@ -914,6 +927,17 @@ function checkCollisions(rows: readonly BoardRow[]): Finding[] {
     }
   }
 
+  return findings
+}
+
+/**
+ * Lists every path two `## Run now` rows both name, one entry per pair of
+ * rows. It reports rather than fails, since sharing a file holds nothing.
+ */
+function checkSharedFiles(rows: readonly BoardRow[]): SharedFiles[] {
+  const pairs: SharedFiles[] = []
+  const ready = rows.filter((row) => row.group === 'Run now')
+
   for (let i = 0; i < ready.length; i += 1) {
     for (let j = i + 1; j < ready.length; j += 1) {
       const left = ready[i]
@@ -929,8 +953,7 @@ function checkCollisions(rows: readonly BoardRow[]): Finding[] {
 
       if (shared.length === 0) continue
 
-      findings.push({
-        kind: 'touches-collided',
+      pairs.push({
         group: 'Run now',
         subject: `${subjectOf(left)} and ${subjectOf(right)}`,
         message: `both touch ${joinShared(shared)}.`,
@@ -938,7 +961,7 @@ function checkCollisions(rows: readonly BoardRow[]): Finding[] {
     }
   }
 
-  return findings
+  return pairs
 }
 
 function subjectOf(row: BoardRow): string {
@@ -982,7 +1005,7 @@ function joinShared(clauses: readonly string[]): string {
  * the row does rewrite the directory, so this states the reach rather than
  * calling it a defect.
  *
- * The scan takes `## Run now` alone, where `checkCollisions` takes it. A cell in
+ * The scan takes `## Run now` alone, where `checkSharedFiles` takes it. A cell in
  * another group describes work nobody has planned, so it is written as a
  * sentence and rewritten at planning time, and a claim read off one reports on
  * prose rather than on a file set. That is the shape that teaches a reader to
@@ -1377,7 +1400,7 @@ export async function validateBoard(
     ...checkPlans(rows, dir, root),
     ...(await checkPlanAgreement(rows, dir, root)),
     ...(await checkGroupClaims(rows, dir, root)),
-    ...checkCollisions(rows),
+    ...checkTouches(rows),
     ...checkOrdering(rows),
     ...parked.findings,
   ]
@@ -1391,6 +1414,7 @@ export async function validateBoard(
     findings,
     untested: parked.untested,
     claims: checkFolderClaims(rows, root),
+    shared: checkSharedFiles(rows),
     wide: checkWideTokens(rows),
     unplaced: checkUnplaced(rows, backlog, stems),
   }

package/src/teach/nav.ts

@@ -9,7 +9,7 @@ import { buildDesignCss } from '@/design/css'
 import { FAVICON_COLORS, faviconLink, renderFavicon } from '@/design/favicon'
 import { stripFrontmatter } from '@/markdown/frontmatter'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
-import { PROJECT_ROOT } from '@/project-root'
+import { PROJECT_ROOT } from '@/roots/project'
 import { compileScript } from '@/teach/browser/compile'
 import { dismiss } from '@/teach/browser/dismiss'
 import { focusLine } from '@/teach/browser/focus-line'

package/src/teach/workspace.ts

@@ -5,7 +5,7 @@ import { TEACH_STYLESHEET_COMPONENTS } from '@/design/components'
 import { buildDesignCss } from '@/design/css'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 import { type BodyLine, bodyLines } from '@/markdown/scan'
-import { recordDir } from '@/record-root'
+import { recordDir } from '@/roots/record'
 import { TEACH_FONT_FACES } from '@/teach/fonts'
 import { writeIfChanged } from '@/teach/write-if-changed'
 

package/src/tooling/inject.ts

@@ -4,7 +4,7 @@ import { dirname, join, relative } from 'node:path'
 import { $ } from 'bun'
 import { copyPreservingMode } from '@/sync/copy'
 import { rewritesOnInstall, stripSeedMarker } from '@/tooling/seed-marker'
-import { resolveSurfacePath } from '@/surface-root'
+import { resolveSurfacePath } from '@/roots/surface'
 import { mergeSections, pruneSections } from '@/tooling/gitignore'
 import {
   ancestorsFirst,
@@ -27,7 +27,7 @@ import {
   SUBFOLDER_SPELL_CONFIG,
   subfolderSpellConfig,
 } from '@/tooling/subfolder'
-import { logAdd, logRemove, logStep, logWarn } from '@/ui'
+import { logAdd, logRemove, logStep, logWarn } from '@/cli/ui'
 
 export async function injectConfigs(
   chain: readonly Manifest[],

package/src/tooling/read.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
-import { PROJECT_ROOT } from '@/project-root'
+import { PROJECT_ROOT } from '@/roots/project'
 
 /**
  * Spells the package root in a report where every other root spells a

package/src/tooling/scan.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
-import { resolveSurfacePath } from '@/surface-root'
+import { resolveSurfacePath } from '@/roots/surface'
 import { mergeSections } from '@/tooling/gitignore'
 import {
   ancestorsFirst,

package/src/tooling/verify-stack.ts

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs'
 import { join } from 'node:path'
 import { execa, type Options } from 'execa'
 import { isStackExcluded, loadManifest } from '@/tooling/manifest'
-import { intro, logError, logInfo, logStep, logWarn, outro } from '@/ui'
+import { intro, logError, logInfo, logStep, logWarn, outro } from '@/cli/ui'
 
 const SCREENSHOT_TIMEOUT_MS = 60_000
 const TAIL_LINES = 20

package/src/version/installed.ts

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
-import { PROJECT_ROOT } from '@/project-root'
+import { PROJECT_ROOT } from '@/roots/project'
 
 /** What a reader prints in place of a field the manifest did not carry. */
 export const UNKNOWN_LABEL = 'unknown'

package/src/version/skew.ts

@@ -1,4 +1,4 @@
-import { PROJECT_ROOT } from '@/project-root'
+import { PROJECT_ROOT } from '@/roots/project'
 import { compareVersions, parseVersion } from '@/version/compare'
 import {
   type InstalledPackage,

package/standards/board.md

@@ -21,7 +21,7 @@ Does not govern:
 
 A board works when a session reading it alone can answer:
 
-- Which task can a worker be handed now, and which files would it collide on?
+- Which task can a worker be handed now, and which files does it share with work already running?
 - What is each blocked task waiting on, and what would clear it?
 - Which task gets planned next, and what is it ranked against?
 
@@ -49,7 +49,7 @@ Group tasks by readiness rather than by status, one row per task, under the colu
 
 Readiness is three groups under fixed headings, `## Run now`, `## Up next`, and `## Needs a plan`, in that order. The names are the contract rather than a suggestion, because a board grouped by readiness under names of its own satisfies every other rule here and still reads as empty to anything counting rows under a heading. Add no fourth group. A task belongs to exactly one, and the tests are read in order.
 
-- `## Run now`: a written plan covers every open outcome, and the task carries no reason it cannot start. A collision against the files something already running touches is one such reason, and the `Touches` column is what states it. A worker is handed a task from this group alone.
+- `## Run now`: a written plan covers every open outcome, and the task carries no reason it cannot start. A collision with running work is one such reason only where no merge settles it, being a contract, a relocation, or a sweep. A shared file alone is none, since the branch merging second rebases. The `Touches` column states the set to read. A worker is handed a task from this group alone.
 - `## Up next`: a written plan exists, and the task carries a stated reason it cannot start. The `Waiting on` column names that reason.
 - `## Needs a plan`: everything else. The task has no plan, or the plan it carries no longer describes the work.
 
@@ -69,7 +69,7 @@ Position alone carries it, and no rank column exists. A number beside each row i
 
 The `Waiting on` column under `## Up next` carries that reason in one of three forms. `## Needs a plan` states no file set at all, because a task with no plan has no bounded one to state. A group with no rows keeps its heading and its header row.
 
-Under `## Up next` a collision names the file held by the task already running, a sibling task names that task, and an external condition names both the condition and what would satisfy it. Naming what would satisfy it is what separates a blocked row from one nobody has examined, so a cell stating a condition with no way out of it fails the test. The header text is the contract the way the group names are, because anything reading the cell resolves the column by header rather than by position.
+Under `## Up next` a collision names the file held by the task already running and which hold it is: a contract, a relocation, or a sweep. A sibling task names that task, and an external condition names both the condition and what would satisfy it. Naming what would satisfy it is what separates a blocked row from one nobody has examined, so a cell stating a condition with no way out of it fails the test. The header text is the contract the way the group names are, because anything reading the cell resolves the column by header rather than by position.
 
 Under `## Needs a plan` the cell carries two halves and each takes one clause: what the task needs before it can be planned, then why it sits at this position. The second clause is comparative, and it names what the row is ranked against in one of two forms: a sibling row, or the class of rows it sits in. The row `leads`, `heads`, `opens`, `closes`, `trails`, `precedes`, `follows`, or `outranks` whichever it names, or `sits under`, `above`, or `below` it. Either form puts something other than this row in the clause, which is what makes the position readable by anyone but its author.
 

package/standards/plan.md

@@ -18,6 +18,8 @@ Applies to a feature plan at `.canon/plans/feature-<slug>.md`. One file holds on
 
 The folder is gitignored, and backed by `canon records push` wherever a records remote is configured. Nothing backs a plan deleted before a push, which is why the archive step is a move rather than a cleanup.
 
+<!-- canon-length-exempt: the constraint forms and the answer contract share one reader, and a split into a second standard is queued as its own change -->
+
 ## Scope
 
 Governs a feature plan under `.canon/plans/feature-<slug>.md`: the filename, the required sections, what each holds, and the suggested-and-answer contract.
@@ -40,7 +42,7 @@ A plan works when a session holding none of the conversation that produced it ca
 - What is being built, and which files does it change?
 - Which decisions are already settled, and which are still open?
 - For each open decision, what happens when nobody answers it?
-- What is likely to go wrong, and where does the work collide with something already in flight?
+- What is likely to go wrong, what does the work share with something already in flight, and what must it wait on?
 - How is each outcome proven, and which input would break it?
 
 A plan failing these is non-conforming even when it satisfies every shape rule below.
@@ -81,20 +83,22 @@ The document opens with `# Feature: <short title>` and one paragraph stating wha
 
 ### Constraints
 
-A constraint naming a surface to leave alone says which of two acts it forbids, rather than leaving the executing session to guess.
+Work in flight reaches a plan as a hold or as a shared path. A hold leaves a surface alone and says which of two acts it forbids, rather than leaving the executing session to guess. Neither act is forbidden over a shared path.
 
+- Write a hold only for a dependency, a contract the other track consumes, a relocation, or a sweep, which a rebase cannot settle mechanically. A bare shared file is none of these, and forbidding it sends a worker to concede a file the change needs.
 - Forbid conforming that surface to whatever shape the change introduces, which keeps the branch to one concern.
 - Never forbid retargeting a pointer the change breaks. A rename, a split, or a deletion that leaves a citation behind ships a dangling reference, so repairing it is required work rather than scope creep.
-- Decide both acts for every surface the constraint names, not for one file among its siblings.
+- Decide both acts for every surface a hold names, not for one file among its siblings.
+- Write a shared path as the track, the path, and the branch that rebases, being the one merging second. The executing session edits the file and keeps both sides on the rebase.
 
-A constraint measured against work in flight expires when that work merges, so stamp the block with what it was measured against.
+A constraint measured against work in flight expires when that work merges, as a shared-path line does, so stamp the block with what it was measured against.
 
 - Give the stamp its own leading bullet, written as Measured against `<commit>` on <YYYY-MM-DD>. One stamp covers the whole block.
 - Stamp the commit rather than the track names or a date alone. The constraint already names each track, and a date does not separate two plans written on either side of a merge.
-- Re-test a stamped constraint before honoring it with `git fetch origin main --quiet && git log <commit>..origin/main --oneline -- <the paths the constraint names>`. Any commit it reports means the track landed and the constraint is dead. Fetch in the same command and scope the log to the paths, since a stale remote-tracking ref reads a dead constraint as live and a squashed subject names no track.
+- Re-test a stamped constraint before honoring it with `git fetch origin main --quiet && git log <commit>..origin/main --oneline -- <the paths the constraint names>`. Any commit it reports means the track landed and the constraint is dead. Fetch and scope the log to the paths in the same command, since a stale ref reads a dead constraint as live and a squashed subject names no track.
 - Read an unstamped constraint as unverified rather than as live, and confirm it against the open pull request list for the named paths.
 
-A constraint naming a `.canon/ready/` folder is a third shape beside the two above. It makes that folder's files the verbatim source for the paths this plan's `**Files to touch:**` lists, per `ready.md`, so the executing session copies those paths rather than authoring them.
+A constraint naming a `.canon/ready/` folder is a third shape beside the hold and the shared path. It makes that folder's files the verbatim source for the paths this plan's `**Files to touch:**` lists, per `ready.md`, so the executing session copies those paths rather than authoring them.
 
 ### Verification
 
@@ -106,6 +110,7 @@ A constraint naming a `.canon/ready/` folder is a third shape beside the two abo
 
 - Name the collision rather than the category. A risk a reader cannot act on is padding.
 - Where the work establishes a resource with more than one consumer, list the consumers and mark each one read or write. A policy stated over that resource has to hold for the writers and not only for the consumer that prompted it.
+- Where the work changes a contract another track consumes, such as an exported signature, a verb's flags or record, or a config key, name the contract and list each consumer. The dispatcher reads this bullet for the contract hold, so a change left out reaches it as a clean shared file.
 
 ### Review focus
 
@@ -161,7 +166,8 @@ This contract inverts the one an intake folder keeps, where an empty slot means
 **Constraints:**
 
 - Measured against `<commit>` on <YYYY-MM-DD>
-- <the work in flight, its file set, and which of the two acts the constraint forbids>
+- <a hold: the work in flight, its file set, and which of the two acts the constraint forbids>
+- <a shared path: the work in flight, the path, and which branch rebases>
 - <durable rule the work must respect>
 
 **Files to touch:**

package/tsconfig.json

@@ -11,5 +11,5 @@
       "@/*": ["./src/*"]
     }
   },
-  "include": ["src", "claude/skills/*/scripts/**/*.ts"]
+  "include": ["src", "claude/skills/*/scripts/**/*.ts", "sandbox/*/*.ts"]
 }