@erclx/canon 5.69.0 → 5.71.0

package/src/tasks/record.ts

@@ -15,6 +15,9 @@ import {
   readPendingBranches,
   readPlanTargets,
   readPullRequest,
+  readSessions,
+  SESSION_ID_PATTERN,
+  SESSIONS_PREFIX,
   tasksDir,
 } from '@/tasks/archive'
 import { checkWaiting, type LinkPromotion, promoteOnLink } from '@/tasks/board'
@@ -34,6 +37,9 @@ const ORIGIN_PREFIXES = ['Plan:', 'Groundwork:', 'Intake:', 'Issue:'] as const
  *
  * `several-plans` answers a `Plan:` line that already links more than one plan.
  * `plan-link` cannot know which link to drop, so it writes nothing.
+ *
+ * `no-name` answers a session id the roster no longer lists, called with no
+ * name, since an id written alone reads as nobody to the next reader.
  */
 export const RECORD_REFUSALS = [
   'no-board',
@@ -44,6 +50,7 @@ export const RECORD_REFUSALS = [
   'no-plan',
   'several-plans',
   'bad-input',
+  'no-name',
 ] as const
 
 export type RecordRefusal = (typeof RECORD_REFUSALS)[number]
@@ -88,6 +95,18 @@ export interface PlanRecorded {
 
 export type PlanOutcome = PlanRecorded | RecordRefused
 
+export interface SessionRecorded {
+  readonly ok: true
+  readonly stem: string
+  readonly path: string
+  readonly sessionId: string
+  /** The name the line carries for the id, which a repeat call never renames. */
+  readonly name: string
+  readonly action: Exclude<LineAction, 'corrected'>
+}
+
+export type SessionOutcome = SessionRecorded | RecordRefused
+
 export interface OutcomesClosed {
   readonly ok: true
   readonly stem: string
@@ -228,6 +247,47 @@ export function clearPendingBranch(
   return { text: lines.join('\n'), changed: true }
 }
 
+/**
+ * Names a session on the `Sessions:` line, keyed on the id, so a dispatcher
+ * and `git-pr` recording the same worker write it once. The line sits below
+ * every other line a task carries above its outcomes, so a pull request
+ * recorded later lands above it.
+ */
+export function writeSessionsLine(
+  text: string,
+  name: string,
+  sessionId: string,
+): { readonly text: string; readonly action: SessionRecorded['action'] } {
+  const entry = `${name} (${sessionId})`
+  const lines = text.split('\n')
+  const existing = lines.findIndex((line) => line.startsWith(SESSIONS_PREFIX))
+
+  if (existing !== -1) {
+    if (lines[existing].includes(`(${sessionId})`)) {
+      return { text, action: 'unchanged' }
+    }
+    lines[existing] = `${lines[existing].trimEnd()}, ${entry}`
+    return { text: lines.join('\n'), action: 'appended' }
+  }
+
+  const line = `${SESSIONS_PREFIX} ${entry}`
+  const anchor = lastOriginLine(lines, [
+    ...ORIGIN_PREFIXES,
+    'Pull request:',
+    PENDING_PREFIX,
+  ])
+  if (anchor !== undefined) {
+    lines.splice(anchor + 1, 0, line)
+    return { text: lines.join('\n'), action: 'added' }
+  }
+
+  const heading = lines.findIndex((entry) => entry.startsWith('# '))
+  if (heading === -1) return { text: `${line}\n${text}`, action: 'added' }
+
+  lines.splice(heading + 1, 0, '', line)
+  return { text: lines.join('\n'), action: 'added' }
+}
+
 export type PlanLineWrite =
   | {
       readonly ok: true
@@ -566,6 +626,64 @@ export async function recordPlan(
   }
 }
 
+/**
+ * Records a session that worked a task on its `Sessions:` line. The caller
+ * resolves `name` from the roster or takes it from `--name`, and an undefined
+ * name refuses rather than writing a bare id. The id is checked first, since a
+ * malformed one is a caller defect and every later check would hide it.
+ */
+export async function recordSession(
+  root: string,
+  selector: RecordSelector,
+  sessionId: string,
+  name: string | undefined,
+): Promise<SessionOutcome> {
+  if (!SESSION_ID_PATTERN.test(sessionId)) {
+    return refuse(
+      'bad-input',
+      `Not a full sessionId: ${sessionId}. Pass the whole id canon sessions list --json carries.`,
+      [sessionId],
+    )
+  }
+
+  if (name === undefined) {
+    return refuse(
+      'no-name',
+      `No live session carries ${sessionId}, so its name cannot be read. Pass --name.`,
+      [sessionId],
+    )
+  }
+
+  const trimmed = name.trim()
+  if (trimmed.length === 0 || /[\r\n]/.test(trimmed)) {
+    return refuse('bad-input', 'A session name is one non-empty line.', [name])
+  }
+
+  const opened = await openTask(root, selector)
+  if ('ok' in opened) return opened
+
+  const { stem, path } = opened
+  const written = writeSessionsLine(
+    await readFile(path, 'utf8'),
+    trimmed,
+    sessionId,
+  )
+  if (written.action !== 'unchanged') await writeFile(path, written.text)
+
+  const listed = readSessions(written.text).find(
+    (entry) => entry.sessionId === sessionId,
+  )
+
+  return {
+    ok: true,
+    stem,
+    path,
+    sessionId,
+    name: listed?.name ?? trimmed,
+    action: written.action,
+  }
+}
+
 /**
  * Marks the named outcomes `[x]` in place. `task-complete` runs this against a
  * board it can read and cannot edit from a linked worktree, and the positions

package/src/tasks/validate.ts

@@ -10,7 +10,9 @@ import {
   readPendingBranches,
   readPlanTargets,
   readPullRequest,
+  readSessions,
   resolveLivePlan,
+  SESSIONS_PREFIX,
   tasksDir,
 } from '@/tasks/archive'
 import {
@@ -66,6 +68,7 @@ export const FINDING_KINDS = [
   'blocker-settled',
   'blocker-unresolved',
   'blocker-declined',
+  'sessions-misshapen',
 ] as const
 
 export type FindingKind = (typeof FINDING_KINDS)[number]
@@ -841,6 +844,39 @@ async function planDisagreement(
   }
 }
 
+/**
+ * Reports a `Sessions:` line that does not parse as name and id pairs, since
+ * the reader takes such a line as naming nobody and a retro would find the
+ * sessions gone. A row whose task file is gone is left to `task-unresolved`.
+ */
+async function checkSessions(
+  rows: readonly BoardRow[],
+  dir: string,
+): Promise<Finding[]> {
+  const found = await Promise.all(
+    rows.map(async (row): Promise<Finding | undefined> => {
+      if (!row.stem) return undefined
+      const file = join(dir, `${row.stem}.md`)
+      if (!existsSync(file)) return undefined
+
+      const text = await readFile(file, 'utf8')
+      const line = text
+        .split('\n')
+        .find((entry) => entry.startsWith(SESSIONS_PREFIX))
+      if (line === undefined || readSessions(text).length > 0) return undefined
+
+      return {
+        kind: 'sessions-misshapen',
+        group: row.group,
+        subject: row.stem,
+        message: `carries "${line}", which does not read as name (sessionId) pairs, so no session it names can be recovered. Rewrite it through canon tasks session.`,
+      }
+    }),
+  )
+
+  return found.filter((finding): finding is Finding => finding !== undefined)
+}
+
 /**
  * Tests the claim a group name makes about a plan. `## Needs a plan` says none
  * is live and `## Up next` says one is written, and neither group has a `Plan`
@@ -1638,6 +1674,7 @@ export async function validateBoard(
     ...checkMapping(rows, backlog, dir),
     ...(await groupRuleFindings(rows, root)),
     ...(await checkPlanAgreement(rows, dir, root)),
+    ...(await checkSessions(rows, dir)),
     ...(await checkStaleTouches(rows, root)),
     ...checkCellWidth(rows),
     ...checkOrdering(rows),

package/docs/target/migrations.md

@@ -1,205 +0,0 @@
----
-title: Target migrations
-description: One-time moves a project scaffolded under an older toolkit runs before its next sync
-category: Agent surface
----
-
-# Target migrations
-
-Each section is a move a project runs once, when it was scaffolded before the change it names. Run `canon upgrade` first, then `canon migrate status --json` to list the moves a project still needs in the order to run them. The recurring sync that follows is in [target sync](sync.md).
-
-`canon:target-update` is the guided path through both. It runs the moves in that order once you approve its preview.
-
-## Move the records first, once
-
-Gitignored session records, being the task board, plans, review reports, and scratch, moved from `.claude/` to `.canon/`. Run these from inside the project, and read the `ok` field of the `--json` record rather than the exit code.
-
-```bash
-canon tooling sync claude . --write
-canon migrate records --json
-canon migrate records --write --json
-```
-
-The first line takes the `.canon/` ignore entry. The second reports and the third applies, repointing files that cite a moved folder and deleting a `.gitignore` line `.canon/` covers, as `dropped`. A line naming an old path keeps it via `canon-keep-record-root` on that line or the nearest non-blank one above.
-
-Then sweep the citations inside the records, which the verb above never reaches.
-
-```bash
-canon migrate record-tree --json
-canon migrate record-tree --write --json
-```
-
-It covers `diagrams`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`. Read the report before `--write`. The record tree is untracked, and a wrong rewrite has no undo.
-
-## Back records up off this machine, once
-
-Run `canon records push` once a private repository exists. It prints the one-time setup command when it finds none, and `canon init` prints the same reminder.
-
-## Move rules off the flat layout, once
-
-Installed rules moved from `.claude/rules/<subdir>/` to `.claude/rules/canon/<subdir>/`. On the flat layout `canon gov sync` exits 0 reporting `No governance surfaces found in target`, and `canon gov install` lands a second copy.
-
-```bash
-canon migrate rule-layout --json
-canon migrate rule-layout --write --json
-```
-
-Run it once, ahead of `canon gov sync` or `canon gov install`.
-
-## Rename the skill citations, once
-
-Plugin skills dropped their `claude-` prefix, so `canon:claude-docs` is now `canon:context-fold`. Five drafters merged into `write-doc`, seven `draft-` skills took verb-first names, and four joined their family. No old name keeps a pointer, and `canon migrate skill-names --write` moves a project. <!-- canon-keep-retired -->
-
-| Old name           | New name                                        |
-| ------------------ | ----------------------------------------------- |
-| `draft-doc`        | `write-doc` <!-- canon-keep-retired -->         |
-| `draft-figure`     | `draw-figure` <!-- canon-keep-retired -->       |
-| `draft-identity`   | `design-identity` <!-- canon-keep-retired -->   |
-| `draft-slides`     | `make-deck` <!-- canon-keep-retired -->         |
-| `draft-and-pick`   | `design-pick` <!-- canon-keep-retired -->       |
-| `draft-ready`      | `plan-ready` <!-- canon-keep-retired -->        |
-| `draft-screencast` | `script-screencast` <!-- canon-keep-retired --> |
-| `pick-by-eye`      | `design-pick` <!-- canon-keep-retired -->       |
-| `ui-record`        | `ui-film` <!-- canon-keep-retired -->           |
-| `ux-audit`         | `ui-audit` <!-- canon-keep-retired -->          |
-| `ux-measure`       | `ui-measure` <!-- canon-keep-retired -->        |
-
-Replace a citation of a skill with no successor by hand, or delete the sentence.
-
-- `canvas` is now `canvas-board`. The sweep rewrites only `canon:canvas` and `skills/canvas`, so replace a bare mention by hand. <!-- canon-keep-retired -->
-- `draft-ready` is rewritten only as `canon:draft-ready` and `skills/draft-ready`, since bare it also describes a pull request, so replace a bare mention by hand. <!-- canon-keep-retired -->
-- `design-extract` and `sketch-design` are replaced by `canon:canvas-board`. <!-- canon-keep-retired -->
-- `review-branch`, `seed-sync`, `restate-plainly`, `bash-cli-script`, `canon-operator`, `canon-rollout`, and `canon-feedback-triage` have no successor <!-- canon-keep-retired -->
-- `create-standard`, `markdown-propose`, `memory-review`, `project-commands`, `repo-metadata`, `ux-walkthrough`, and `plan-ready` have no successor <!-- canon-keep-retired -->
-
-The `memory` record kind left `canon records`, so `canon records validate memory` refuses as an unknown kind and `canon records migrate` is gone.
-
-- `canon repo metadata`, `canon autoship`, and the `120-bash` rule are gone, and `canon gov sync` removes the rule <!-- canon-keep-retired -->
-- `memory-capture`, the `603-memory` rule, and the `memory` standard are gone, so send a lesson to the context entry that owns the fact <!-- canon-keep-retired -->
-
-Two held files run, `.husky/post-merge` and `.claude/hooks/pr-create-log.sh`, and a stale copy calls a missing binary or names a removed skill. Resync what the toolkit owns before sweeping what the project wrote, and run the second line once per stack, naming a held hook with `--replace`.
-
-```bash
-canon gov sync
-canon tooling sync <stack> . --write
-canon migrate skill-names --json
-canon migrate skill-names --write --json
-```
-
-## Rename the pull request template headings, once
-
-The template headings are now `## Key changes` and `## Technical context`, and `canon labels scan` compares case exactly. Rename them in `.github/pull_request_template.md`, or delete it and run `canon tooling sync base . --write`.
-
-## Move the surfaces off `.claude/`, once
-
-`context/`, `wireframes/`, `ARCHITECTURE.md`, `REQUIREMENTS.md`, `DESIGN.md`, and the install stamp folder, now `canon/config/`, moved under `canon/`. `rules/`, `skills/`, `hooks/`, and `settings.json` stay where Claude Code reads them.
-
-```bash
-canon migrate surface-roots --json
-canon migrate surface-roots --write --json
-```
-
-It moves each surface with `git mv` and repoints every tracked citation. No other command notices a surface left at `.claude/`.
-
-## Delete the retired snippets, once
-
-A project scaffolded while snippets installed may hold `.claude/snippets/` or a root `snippets/`.
-
-```bash
-canon sync --check . --json | jq '.reverse'
-```
-
-- `dropped` is the toolkit's copy, unchanged, so delete it
-- `unattributed` is often an edited copy, so read what changed first
-- `project` is the project's own content, so leave it
-
-From the registry the walk reports `historyUnavailable`, so check both paths by hand.
-
-## Stop calling the standards verb, once
-
-`canon standards <name>` is gone, and a call now fails with a too-many-arguments error. Replace each call with the skill that owns the standard, at `references/<name>.md`. <!-- canon-allow-reference: verb retired -->
-
-| Skill             | Standards                                                     |
-| ----------------- | ------------------------------------------------------------- |
-| `task-board`      | `board`, `tasks`, `tasks-decline`                             |
-| `context-fold`    | `context`                                                     |
-| `canvas-board`    | `canvas`, `design` <!-- canon-keep-retired -->                |
-| `docs-sync`       | `docs`, `readme`                                              |
-| `draw-figure`     | `figures`, `mermaid`                                          |
-| `create-rule`     | `rule`                                                        |
-| `create-skill`    | `skill`, `skill-paths`, `skill-practice`, `skill-requirement` |
-| `git-branch`      | `branch`, `slug`                                              |
-| `git-commit`      | `commit`, `versioning`                                        |
-| `git-pr`          | `pr`, `publish`                                               |
-| `markdown-craft`  | `markdown`                                                    |
-| `teach-workspace` | `glossary`, `teach` <!-- canon-keep-retired -->               |
-| `plan-groundwork` | `groundwork`, `groundwork-spikes`                             |
-| `plan-intake`     | `intake`                                                      |
-| `plan-feature`    | `plan`, `plan-lifecycle`                                      |
-| `plan-ready`      | `ready` <!-- canon-keep-retired -->                           |
-| `write-doc`       | `requirements`, `wiki`                                        |
-| `session-map`     | `session`                                                     |
-
-The `standard` name became `skill-reference.md` in `create-skill`.
-
-## Keep or delete the wireframes folder, your call
-
-The wireframes record is retired, and nothing deletes what a project holds.
-
-- `canon/wireframes/` stays yours and unaudited. Keep it as notes or delete it.
-- Delete the `@canon/wireframes/index.md` line in your `CLAUDE.md` with the folder. `canon claude sync` does not rewrite it.
-- `canon gov sync` removes `.claude/rules/canon/standards/wireframes.md`
-
-## Keep or delete the retired product files, your call
-
-The learning workspace, deck renderer, app recorder, canvas, and design install are retired with their verbs, and nothing deletes what a project holds.
-
-- `.canon/teach/` holds HTML that opens as it is <!-- canon-keep-retired -->
-- `.canon/slides/` and a `demos/` folder hold sources nothing renders any more, so delete them once nothing cites them <!-- canon-keep-retired -->
-- Move the `.claude/design/project/` values, `fonts/`, and `fonts.css` to the stylesheet your `canon/DESIGN.md` lead names, then delete `.claude/design/`
-
-A reference to a retired skill takes a hand edit.
-
-- Replace a `canon:teach-workspace` reference with `canon:teach-craft` by hand, since `canon migrate skill-names` does not rewrite it <!-- canon-keep-retired -->
-- Delete a `canon:make-deck`, `canon:script-screencast`, `canon:record-screencast`, `canon:read-frames`, or `canon:video-craft` reference, since none has a successor <!-- canon-keep-retired -->
-- Delete a `canon:canvas-board` reference too. Frameboard, which `canon:design-pick` drives, reads each `.canon/canvas/` folder as a project, so move a kept page under one <!-- canon-keep-retired -->
-
-## Move decisions out of a held architecture record, once
-
-The toolkit no longer seeds `canon/ARCHITECTURE.md`, and a held file and its `CLAUDE.md` import stay. Move a trap a session would hit into that domain's `## Gotchas`, then delete the file and its `@canon/ARCHITECTURE.md` line.
-
-## Deny subagents and merges, and turn auto memory off, once
-
-The seeded `.claude/settings.json` now denies the `Agent` and `Task` tools and both merge commands, and sets `autoMemoryEnabled` to `false`. `canon claude sync` never rewrites a settings file you hold, so it warns while the file holds no default or lacks a merge entry. Removing `Agent` and `Task` later draws no warning.
-
-```bash
-canon migrate session-defaults --json
-canon migrate session-defaults --write --json
-```
-
-The verb only adds a key that is absent. A person who wants auto memory back sets it in their own `.claude/settings.local.json`.
-
-The verb adds `Bash(canon pr merge:*)` and `Bash(gh pr merge:*)` so a session cannot merge. A project migrated before them runs `--write` once more, which also restores `Agent` and `Task` for a person who removed them to allow subagents, so remove them again after.
-
-## Move the capture cases out of the harness, once
-
-A web project's `e2e/screenshot.ts` is a config. It now loads `CASES` from a seeded `e2e/capture/cases.ts` that sync copies once and never overwrites. A harness you edited is held on `--write`, so the new one lands only once you pass `--replace e2e/screenshot.ts`.
-
-- Copy your cases from the old `e2e/screenshot.ts` into `e2e/capture/cases.ts`, then sync with `--replace e2e/screenshot.ts`.
-- Evidence now defaults to `e2e/evidence/`. Set `export const EVIDENCE_ROOT = 'evidence'` in `e2e/capture/cases.ts` to keep a committed baseline at the old path.
-- A run from a folder with no `e2e/capture/cases.ts` exits 1 and names the file.
-
-## Fold the ui rules onto one pointer, once
-
-Eleven ui rules moved unchanged into the `ui-craft` skill, being `a11y`, `keyboard`, `pointer`, `forms`, `motion`, `ux-controls`, `ux-completeness`, `surface-capture`, `copy`, `interface-casing`, and `link-behavior`. Update the plugin, then sync, which folds each one you hold and `design-taste.md` onto one `craft.md` pointer without local edits.
-
-```bash
-canon gov sync .
-```
-
-## Group a long paths section in `CLAUDE.md`, once
-
-The `## Key paths` section of `CLAUDE.md` now keeps to 5 bullets in a row, and every other section stays exempt. `canon claude sync` never rewrites a `CLAUDE.md` you hold, so it warns with the line of each longer run.
-
-- Regroup the section by hand under H3s, each opening on a one-sentence lead.
-- List `CLAUDE.md` in `canon/config/markdown.toml` to gate it from then on.