@erclx/canon 5.39.0 → 5.40.0

package/src/commands/pr.ts

@@ -69,7 +69,9 @@ import {
   type LiftRefusal,
   type PullState,
   readBaseStanding,
+  readChangedPaths,
 } from '@/pr/lift'
+import { loadPaintedPatterns } from '@/pr/painted'
 import {
   dropAddressLine,
   findLocalServer,
@@ -421,6 +423,24 @@ export function register(program: Command): void {
         'points the change at a locative the path does not name. Read the bullet on',
         "the record's preview before filing an unmet path as a stale claim.",
         '',
+        'Refusals, read off `reason`:',
+        '  no-section          the body carries no `## Key changes` heading, so it',
+        '                      claims nothing',
+        '  no-claims           the heading is there and no span resolved, which is',
+        '                      the extractor failing over prose and raises nothing',
+        '  no-changes          the pull request changed no files, so no claim has',
+        '                      anything to answer',
+        '  unreadable-body     the pull request body could not be read',
+        '  unreadable-tree     the file tree of the head could not be read',
+        '  no-base             GitHub reported no merge base for the pull request',
+        '  bad-base            `--base` names a ref sharing no history with HEAD',
+        '  unreadable-changes  the changed files could not be listed',
+        '  ambiguous-pull      two open pull requests share the branch against',
+        '                      different bases, so name a number',
+        '  gh-missing          `gh` is not on the path, so no pull request could be',
+        '                      resolved',
+        '  gh-failed           `gh` could not answer for this repository or branch',
+        '',
         'Exit codes:',
         '  0  every claimed path is in the diff',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -455,6 +475,17 @@ export function register(program: Command): void {
         'tip from the remote with `git ls-remote` and reports which commit each',
         'source names.',
         '',
+        'Refusals, read off `reason`:',
+        '  ambiguous-pull    two open pull requests share the branch against',
+        '                    different bases, so name a number',
+        '  no-branch         the pull request carries no head branch name',
+        '  unresolvable-ref  the remote read failed, which is not an absent branch',
+        '  no-remote-branch  the remote carries no branch by that name, so there',
+        '                    is no tip to compare against',
+        '  gh-missing        `gh` is not on the path, so no pull request resolved',
+        '  gh-failed         `gh` could not answer for this branch, so name a number',
+        '  no-object-head    the pull request object reported no head commit',
+        '',
         'Read the verdict off the record rather than off the exit. A stale head',
         'exits 0, because an operator shell profile can wrap this binary in a',
         'function whose status comes from a trailing command.',
@@ -492,6 +523,19 @@ export function register(program: Command): void {
         'an empty row list, and reading that as passing is the false green the',
         'sha key alone does not close.',
         '',
+        'Refusals, read off `reason`:',
+        '  ambiguous-pull    two open pull requests share the branch against',
+        '                    different bases, so name a number',
+        '  no-branch         the pull request carries no head branch name',
+        '  unresolvable-ref  the remote read failed, which is not an absent branch',
+        '  no-remote-branch  the remote carries no branch by that name, so there',
+        '                    is no tip to compare against',
+        '  runs-unreadable   the check runs for the tip could not be read, which is',
+        '                    unread rather than none',
+        '  gh-missing        `gh` is not on the path, so no pull request resolved',
+        '  gh-failed         `gh` could not answer for this branch, so name a number',
+        '  no-object-head    the pull request object reported no head commit',
+        '',
         'A branch conflicting with its base gets no merge ref, so no run ever',
         'starts for it and the state stays pending. The record carries',
         '`conflicted: true` beside it when `mergeStateStatus` reads DIRTY and no',
@@ -538,6 +582,19 @@ export function register(program: Command): void {
         '  fallback  a pass posted before the marker shipped, off GitHub stamps',
         '  none      the thread carries no pass, so the next one is a first pass',
         '',
+        'Refusals, read off `reason`:',
+        '  ambiguous-pull    two open pull requests share the branch against',
+        '                    different bases, so name a number',
+        '  no-branch         the pull request carries no head branch name',
+        '  unresolvable-ref  the remote read failed, which is not an absent branch',
+        '  no-remote-branch  the remote carries no branch by that name, so there',
+        '                    is no tip to compare against',
+        '  reviews-unreadable  the reviews could not be parsed, which is unread',
+        '                      rather than none',
+        '  gh-missing        `gh` is not on the path, so no pull request resolved',
+        '  gh-failed         `gh` could not answer for this branch, so name a number',
+        '  no-object-head    the pull request object reported no head commit',
+        '',
         'Exit codes:',
         '  0  the thread was read, whether it carries a pass or not',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -656,6 +713,17 @@ export function register(program: Command): void {
         'The record carries `owed` and the same marked fields. --check refuses',
         'with --preview, --local, or --checklist as check-writes.',
         '',
+        'Refusals, read off `reason`:',
+        '  unreadable-checklist  --checklist named a path that could not be read,',
+        '                        or one holding nothing',
+        '  no-branch             the pull request carries no head branch name',
+        '  no-base               GitHub reported no merge base for the pull request',
+        '  unreadable-changes    GitHub could not list what the pull request changed',
+        '  gh-missing            `gh` is not on the path',
+        '  gh-failed             `gh` could not read or edit the pull request or its',
+        '                        comments',
+        '  no-object-head        the pull request object reported no head commit',
+        '',
         'Exit codes:',
         '  0  read, whether it produced a body, reported no-evidence, or checked',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -696,7 +764,11 @@ export function register(program: Command): void {
         'they are read:',
         '  review    the newest `## Review` is closed at the head, off its marker',
         '  ui        the newest `## UI review` is closed at the head, bound only',
-        '            where `canon pr evidence --check` carries a checklist',
+        '            where `canon pr evidence --check` carries a checklist. A close',
+        '            on an earlier commit still holds when it is an ancestor of the',
+        '            head and no painted path changed since, and the record names',
+        '            it as `carriedFrom`. A painted change refuses `ui-behind` and',
+        '            lists the paths as `paintedPaths`',
         '  evidence  the evidence check reads settled',
         '  standing  the head is fresh against the base, not stale or conflicted',
         '  ci        every check run on the tip passed, waited on up to --wait',
@@ -705,8 +777,21 @@ export function register(program: Command): void {
         'wait, so a reviewer whose partner is still driving refuses at once. The',
         'head and the reviews are read again before the mutation.',
         '',
+        'Painted paths are what a browser renders (`.tsx`, `.jsx`, `.vue`,',
+        '`.svelte`, `.astro`, `.html`, `.css`, `.scss`, `.svg`, images, fonts)',
+        'minus test, spec, and story files. A project adds to or trims the list',
+        'in `canon/config/painted.json` as `{ "painted": [glob], "unpainted":',
+        '[glob] }`.',
+        '',
+        'A pull request that is already ready has the review, ui, and evidence',
+        'gates read too. One that reads not clear returns to draft with reason',
+        '`redrafted` and the failing reason as `failed`, exit 1. Standing and CI',
+        'are reported and never cause a re-draft. A ready pull request that',
+        'clears reports `already-ready`, exit 0. Under --check nothing is',
+        'written and the first failing reason is reported.',
+        '',
         'Reasons:',
-        '  lifted, already-ready, clear (--check)',
+        '  lifted, already-ready, redrafted, clear (--check)',
         '  pull-closed, review-missing, review-open, review-unmarked,',
         '  review-behind, ui-missing, ui-open, ui-unmarked, ui-behind,',
         '  evidence-owed, standing-stale, standing-conflict, standing-unknown,',
@@ -784,6 +869,15 @@ export function register(program: Command): void {
         '  building    a deploy of the tip is still running, so wait',
         '  no-build    no deploy of this branch has succeeded',
         '',
+        'Refusals before either read, read off `reason`:',
+        '  bad-timeout         --timeout was not a positive number',
+        '  check-timeout       --check was combined with --timeout',
+        '  no-branch           the pull request carries no head branch name',
+        '  unreadable-changes  the changed paths of the pull request could not be read',
+        '  gh-missing          `gh` is not on the path',
+        '  gh-failed           `gh` could not read the pull request, or list or',
+        '                      dispatch the workflow',
+        '',
         'Exit codes:',
         '  0  a preview was published, or --check read fresh',
         '  1  refused, or --check read anything but fresh',
@@ -838,6 +932,10 @@ export function register(program: Command): void {
         '  no-comment          --remove found no marked comment, a no-op',
         '  no-line             --remove found no address line, a no-op',
         '',
+        'Refusals, read off `reason`:',
+        '  gh-missing  `--remove` needs `gh` and it is not on the path',
+        '  gh-failed   `--remove` could not read or edit the comment',
+        '',
         'Exit codes:',
         '  0  a server was found, or --remove finished, including a no-op',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -3169,6 +3267,43 @@ const LIFT_REFUSALS: Record<LiftRefusal | 'bad-wait' | 'gh-missing', string> = {
 const READY_MUTATION =
   'mutation($id: ID!) { markPullRequestReadyForReview(input: {pullRequestId: $id}) { pullRequest { isDraft } } }'
 
+const CONVERT_DRAFT_MUTATION =
+  'mutation($id: ID!) { convertPullRequestToDraft(input: {pullRequestId: $id}) { pullRequest { isDraft } } }'
+
+/**
+ * Runs one pull request mutation and answers whether the draft flag now reads
+ * `isDraft`. The flag is read back rather than the exit trusted, since the
+ * mutation can answer 200 with an errors array and no change.
+ */
+async function flipDraft(
+  root: string,
+  mutation: string,
+  field: 'markPullRequestReadyForReview' | 'convertPullRequestToDraft',
+  nodeId: string,
+  isDraft: boolean,
+): Promise<boolean> {
+  const result = await execa(
+    'gh',
+    ['api', 'graphql', '-f', `query=${mutation}`, '-f', `id=${nodeId}`],
+    {
+      cwd: root,
+      reject: false,
+      timeout: GH_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+    },
+  )
+  if (result.exitCode !== 0) return false
+  try {
+    const body = JSON.parse(String(result.stdout)) as {
+      data?: Record<string, { pullRequest?: { isDraft?: boolean } } | undefined>
+    }
+    return body.data?.[field]?.pullRequest?.isDraft === isDraft
+  } catch {
+    return false
+  }
+}
+
 function gitRunner(root: string): GitRunner {
   return async (args) => {
     const result = await execa('git', ['-C', root, ...args], {
@@ -3292,44 +3427,23 @@ function liftApi(root: string, number: string, baseRef: string): LiftApi {
         return undefined
       }
     },
-    markReady: async (nodeId) => {
-      const result = await execa(
-        'gh',
-        [
-          'api',
-          'graphql',
-          '-f',
-          `query=${READY_MUTATION}`,
-          '-f',
-          `id=${nodeId}`,
-        ],
-        {
-          cwd: root,
-          reject: false,
-          timeout: GH_TIMEOUT_MS,
-          env: gitEnv(),
-          extendEnv: false,
-        },
-      )
-      if (result.exitCode !== 0) return false
-      // The flag is read back rather than the exit trusted, since the
-      // mutation can answer 200 with an errors array and no change.
-      try {
-        const body = JSON.parse(String(result.stdout)) as {
-          data?: {
-            markPullRequestReadyForReview?: {
-              pullRequest?: { isDraft?: boolean }
-            }
-          }
-        }
-        return (
-          body.data?.markPullRequestReadyForReview?.pullRequest?.isDraft ===
-          false
-        )
-      } catch {
-        return false
-      }
-    },
+    markReady: (nodeId) =>
+      flipDraft(
+        root,
+        READY_MUTATION,
+        'markPullRequestReadyForReview',
+        nodeId,
+        false,
+      ),
+    markDraft: (nodeId) =>
+      flipDraft(
+        root,
+        CONVERT_DRAFT_MUTATION,
+        'convertPullRequestToDraft',
+        nodeId,
+        true,
+      ),
+    readChanged: (from, to) => readChangedPaths(git, from, to),
     sleep: (ms) => new Promise((done) => setTimeout(done, ms)),
     now: () => Date.now(),
   }
@@ -3385,6 +3499,7 @@ async function runLift(
   const record = await lift(liftApi(root, resolved.number, `origin/${base}`), {
     isCheck: opts.check ?? false,
     waitSeconds,
+    painted: loadPaintedPatterns(root),
   })
 
   logStep(record.reason)
@@ -3393,9 +3508,11 @@ async function runLift(
       ? `#${resolved.number} is ready for review at ${record.head?.slice(0, 8)}`
       : record.reason === 'already-ready'
         ? `#${resolved.number} is already ready for review`
-        : record.reason === 'clear'
-          ? `every gate reads clear for #${resolved.number}`
-          : LIFT_REFUSALS[record.reason],
+        : record.reason === 'redrafted'
+          ? `#${resolved.number} is back to draft, since ${record.failed === undefined ? 'a gate' : LIFT_REFUSALS[record.failed]}`
+          : record.reason === 'clear'
+            ? `every gate reads clear for #${resolved.number}`
+            : LIFT_REFUSALS[record.reason],
   )
   for (const gate of record.gates) {
     if (!gate.isOk) logWarn(`${gate.gate}: ${gate.reason ?? 'not clear'}`)

package/src/commands/records.ts

@@ -100,6 +100,10 @@ export function register(program: Command): void {
         '  groundwork  README and current-state files, numbering, dating, and a half-closed track',
         '  intake      overview file, numbering, dating, and the four bullets every item carries',
         '',
+        'Refusals, read off `reason`:',
+        "  no-folder     none of the kind's directories exist at either record root",
+        '  unknown-kind  the argument names no published kind',
+        '',
         'Exit codes:',
         '  0  every check passed',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -216,6 +220,10 @@ export function register(program: Command): void {
         'and the release tags merged into HEAD after that day, or never when it',
         'carries no date.',
         '',
+        'Refusals, read off `reason`:',
+        '  unknown-kind     any kind but `canonical`',
+        '  unreadable-tags  the release tags could not be read',
+        '',
         'Exit codes:',
         '  0  the reading completed, whatever it found',
         '  1  refused, with the reason on stderr or in the JSON record',

package/src/commands/secrets.ts

@@ -60,6 +60,12 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr',
         '  2  at least one value was found',
         '',
+        'Reasons:',
+        '  no-manifest, no-publish, no-shipped-files',
+        '    nothing is published from this tree, so the corpus is absent',
+        '  no-files-field  a publish would pack the whole tree and none of it was read',
+        '  no-git          git could not list the tree, so the corpus is unknown',
+        '',
         'Examples:',
         '  canon secrets scan',
         '  canon secrets scan --json',

package/src/commands/sessions.ts

@@ -69,6 +69,14 @@ export function register(program: Command): void {
     .addHelpText(
       'after',
       [
+        '',
+        'Refusals, read off `reason`:',
+        '  no-registry       no session registry exists, so nothing was read and',
+        '                    the roster is not empty',
+        '  no-repository     `--branch` resolved no repository. Run inside one or',
+        '                    pass `--repository`',
+        '  no-self-identity  `--self` found nothing to name this session with',
+        '  no-self-row       `--self` found no roster row for this session',
         '',
         'Exit codes:',
         '  0  the roster was read',

package/src/commands/tasks.ts

@@ -176,6 +176,18 @@ export function register(program: Command): void {
         'listed, and pending-branch while a Pending branch: line names a branch',
         'whose own pull request is not recorded yet. A stem skips both.',
         '',
+        'Refusals, read off `reason`:',
+        '  no-board        the repository holds no `.canon/tasks/` board',
+        '  no-match        no task matches the selector',
+        '  ambiguous       more than one task matches the selector',
+        '  no-outcomes     the task carries no outcomes to check',
+        '  open-outcomes   an outcome is still unchecked',
+        '  earlier-slice   `--pull-request` names a number that is not the last on',
+        '                  the task',
+        '  pending-branch  a `Pending branch:` line names a branch whose pull',
+        '                  request is not recorded yet',
+        '  bad-input       a malformed selector',
+        '',
         'Exit codes:',
         '  0  the task was archived',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -209,6 +221,12 @@ export function register(program: Command): void {
         'decided against at any outcome state, and the two never share a',
         'refusal set since they answer different questions.',
         '',
+        'Refusals, read off `reason`:',
+        '  no-board   the repository holds no `.canon/tasks/` board',
+        '  no-match   no task matches the selector',
+        '  ambiguous  more than one task matches the selector',
+        '  bad-input  a missing `--reason`, or a `--by` that resolves to nobody',
+        '',
         'Exit codes:',
         '  0  the task was declined',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -243,6 +261,12 @@ export function register(program: Command): void {
         '  every Run now row names the files it touches',
         '  a file two Run now rows share is listed, never failed',
         '',
+        'Refusals, read off `reason`:',
+        '  no-board     the repository holds no `.canon/tasks/` board',
+        '  no-ordering  the board has no ordering file',
+        '  no-groups    the board groups rows under headings of its own, with no',
+        '               declared columns',
+        '',
         'Exit codes:',
         '  0  every check passed',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -422,6 +446,12 @@ export function register(program: Command): void {
     .addHelpText(
       'after',
       [
+        '',
+        'Refusals, read off `reason`:',
+        '  no-board   the repository holds no `.canon/tasks/` board',
+        '  no-match   no task matches the selector',
+        '  ambiguous  more than one task matches the selector',
+        '  bad-input  a number that is not a pull request number',
         '',
         'Exit codes:',
         '  0  the line was added, appended to, corrected, or already correct',
@@ -468,6 +498,13 @@ export function register(program: Command): void {
     .addHelpText(
       'after',
       [
+        '',
+        'Refusals, read off `reason`:',
+        '  no-board       the repository holds no `.canon/tasks/` board',
+        '  no-match       no task matches the selector',
+        '  no-plan        the plan named does not exist',
+        '  several-plans  the task line links more than one plan',
+        '  bad-input      a malformed argument',
         '',
         'Exit codes:',
         '  0  the line was added, appended to, corrected, or already correct',
@@ -514,6 +551,14 @@ export function register(program: Command): void {
     .addHelpText(
       'after',
       [
+        '',
+        'Refusals, read off `reason`:',
+        '  no-board      the repository holds no `.canon/tasks/` board',
+        '  no-match      no task matches the selector',
+        '  ambiguous     more than one task matches the selector',
+        '  no-outcomes   the task carries no outcomes',
+        '  out-of-range  a `--close` position past the end of the outcome list',
+        '  bad-input     a malformed position',
         '',
         'Exit codes:',
         '  0  every named outcome is closed',
@@ -557,6 +602,10 @@ export function register(program: Command): void {
         'archive holds labels the live board no longer shows and a scan',
         'confined to the board hands out one already spent.',
         '',
+        'Refusals, read off `reason`:',
+        '  no-board         the repository holds no `.canon/tasks/` board',
+        '  label-contended  `--claim` lost five reservations, and the verb exits 2',
+        '',
         'Exit codes:',
         '  0  the label is derived',
         '  1  refused with no-board',
@@ -593,6 +642,9 @@ export function register(program: Command): void {
         'or both, read from priority.md and backlog.md through the parsers',
         'validate uses. It lists the live root only, never archive/ or declined/.',
         '',
+        'Refusals, read off `reason`:',
+        '  no-board  the repository holds no `.canon/tasks/` board',
+        '',
         'Exit codes:',
         '  0  the list is derived',
         '  1  refused with no-board',

package/src/commands/teach.ts

@@ -120,6 +120,19 @@ export function register(program: Command): void {
         'rewriting anything, canon teach list <topic> prints the canon serve',
         'line, with the teach folder written from where you stand.',
         '',
+        'Reasons, on stderr or in the JSON record:',
+        '  no-teach      the root carries no .canon/teach/ folder',
+        '  no-workspace  no workspace matches the topic',
+        '  ambiguous     two workspaces claim one topic',
+        '  exists        a workspace already covers the topic an open names',
+        '  no-file       the workspace carries no file the verb writes into',
+        '  no-section    RESOURCES.md carries no heading the entries belong under',
+        '  listed        a URL is already read, or a lead is offered as listed',
+        '  defined       a term already carries a glossary entry',
+        '  bad-input     the command line is malformed',
+        '  no-port       up found every port in reach taken',
+        '  bind-failed   up could not bind, such as a privileged port',
+        '',
       ].join('\n'),
     )
 

package/src/commands/upstream.ts

@@ -103,6 +103,14 @@ export function register(program: Command): void {
         'Writes nothing. The cursor moves only through `upstream advance`, so a',
         'run that dies midway reads the same range next time.',
         '',
+        'Reasons:',
+        '  no-cursor         no cursor is stored and no --since was given',
+        '  bad-since         --since is not a dotted version',
+        '  cursor-missing    every release the feed returned is newer than the cursor',
+        '  rate-limited      GitHub refused the request, so set GH_TOKEN or GITHUB_TOKEN',
+        '  network           the feed could not be reached',
+        '  http              GitHub answered with an error status',
+        '',
         'Exit codes:',
         '  0  the range was read, possibly empty',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -154,7 +162,19 @@ export function register(program: Command): void {
         'Due when the cursor is a week old and the installed version is ahead of',
         'it, or sooner when an Added line in the gap names a canon surface. The',
         'gap is read from GitHub at most once a day and cached under the scratch',
-        'folder, and a failed read is held for the day as well.',
+        'folder, and a failed read is held for the day as well. The record',
+        'carries due, reason, releases, installed, and cursor, and releases is',
+        'null when the feed was not read.',
+        '',
+        'Reasons:',
+        '  Due, by reason:',
+        '    no-cursor       no digest has been run',
+        '    week            the cursor is seven or more days old and the install is ahead',
+        '    vocabulary      an Added line in the gap names a plugin, skill, hook, or worktree',
+        '  Not due, by reason:',
+        '    current         the install is at or below the cursor, as after a downgrade',
+        '    recent          the cursor is under a week old and no line in the gap matches',
+        '    unknown-version claude --version could not be read',
         '',
         'Exit codes:',
         '  0  answered, whether or not a digest is due',
@@ -185,6 +205,10 @@ export function register(program: Command): void {
         'folder through a temp file and a rename. It refuses a version older than',
         'the stored cursor.',
         '',
+        'Reasons:',
+        '  invalid-version    the version is not a dotted number',
+        '  older-than-cursor  the version is older than the stored cursor',
+        '',
         'Exit codes:',
         '  0  the cursor moved',
         '  1  refused, with the reason on stderr or in the JSON record',

package/src/commands/worktrees.ts

@@ -119,6 +119,11 @@ const CONDITIONS = [
   'command is running in, since git removes the directory a caller stands',
   'in and every later call scoped to it then fails.',
   '',
+  'A "refusals" entry is one of these reasons:',
+  ...Object.entries(REFUSALS).map(
+    ([reason, meaning]) => `  ${reason.padEnd(24)}${meaning}`,
+  ),
+  '',
   'An unreadable input refuses the whole reading rather than reporting',
   'every worktree as not reclaimable, since an absent merge state and a',
   'branch with no merged pull request produce the same empty answer.',

package/src/context/audit.ts

@@ -104,6 +104,19 @@ export const LAYOUT_PARAGRAPH_CAP = 1
 /** The one Layout H3 not titled with a path, holding the trivial folders. */
 export const OTHER_FOLDERS = 'Other folders'
 
+/** The run-command table H3 only the development entry carries under `Layout`. */
+export const SCRIPTS_HEADING = 'Scripts'
+
+/**
+ * Whether an entry path is the development entry, being the flat entry, the
+ * overview of a split one a target may still carry, or this repository's
+ * `local-loop` entry. The standard exempts the
+ * `Scripts` H3 for that entry alone, so the path is what tells.
+ */
+function isDevelopmentEntry(rel: string): boolean {
+  return /(?:^|\/)development(?:\/(?:overview|local-loop))?\.md$/.test(rel)
+}
+
 /**
  * The context standard's list, kept as its own export because the audit record
  * has published it flat under `checkpoints.requiredSections` since before any
@@ -584,13 +597,18 @@ interface FolderHeading {
  * A cap reports once per section or folder heading however far past it the
  * count runs, since the fix is one cut either way. `Other folders` is exempt
  * from both folder caps, its one-line bullets being held by the bullet run
- * limit `canon markdown audit` already gates.
+ * limit `canon markdown audit` already gates. The development entry's `Scripts`
+ * H3 is exempt from the heading rule and both caps the same way, its table
+ * being a run-command surface rather than a folder.
  */
 function shapeIssues(
+  rel: string,
   lines: readonly BodyLine[],
   retired: readonly string[],
 ): ShapeIssue[] {
   const issues: ShapeIssue[] = []
+  const exempt = new Set([OTHER_FOLDERS])
+  if (isDevelopmentEntry(rel)) exempt.add(SCRIPTS_HEADING)
   let section: string | undefined
   let gotchas: { line: number; bullets: number } | undefined
   let folder: FolderHeading | undefined
@@ -599,7 +617,7 @@ function shapeIssues(
   let afterBlank = false
 
   const closeFolder = (): void => {
-    if (folder && folder.text !== OTHER_FOLDERS) {
+    if (folder && !exempt.has(folder.text)) {
       if (folder.paragraphs > LAYOUT_PARAGRAPH_CAP) {
         issues.push({
           line: folder.line,
@@ -659,7 +677,7 @@ function shapeIssues(
       } else if (section === 'Layout' && level === 3) {
         closeFolder()
         folder = { line: line.number, text, bullets: 0, paragraphs: 0 }
-        if (!FOLDER_TITLE.test(text) && text !== OTHER_FOLDERS) {
+        if (!FOLDER_TITLE.test(text) && !exempt.has(text)) {
           issues.push({ line: line.number, kind: 'layout-heading', text })
         }
       } else if (section === 'Layout') {
@@ -780,7 +798,7 @@ export function measureEntry(
     bareReferences: bareReferences(lines, siblings),
     sections: declaredSections(lines, required),
     otherSections: otherSections(lines, allowed, retired),
-    shape: governsContent ? shapeIssues(lines, retired) : [],
+    shape: governsContent ? shapeIssues(rel, lines, retired) : [],
     stub: isStubSeed(source),
     governed: governsContent,
   }

package/src/context/folders.ts

@@ -56,7 +56,7 @@ export interface AuditedFolder {
    * The requested folder name this was resolved under, which is what says
    * which standard governs the entries. A nested split folder carries the name
    * of the folder it sits beneath rather than its own, so
-   * `canon/context/claude-plugin` is governed as `context`.
+   * `canon/context/<domain>` is governed as `context`.
    */
   readonly name: string
   /**

package/src/context/shape-gated.ts

@@ -15,8 +15,10 @@
  */
 export const SHAPE_GATED_FOLDERS: readonly string[] = [
   'canon/context/context-model.md',
-  'canon/context/design.md',
-  'canon/context/web.md',
+  'canon/context/development/',
+  'canon/context/features/',
+  'canon/context/surfaces/',
+  'canon/context/workflow/',
 ]
 
 /** Whether a repository-relative entry path sits under a gated prefix. */

package/src/counts/scan.ts

@@ -80,7 +80,7 @@ function sentencesOf(line: string): string[] {
  * the 290 showed removing all of them while keeping that one.
  *
  * `authors` joined the list on a corpus measurement rather than on the shape
- * argument above. `canon/context/development/regeneration.md` states `the
+ * argument above. A context entry asserting `the
  * toolkit authors 69 rules under governance/rules/`, which is the assertion
  * shape this list was built for with a verb the list did not carry, and the
  * word costs one further sentence across the whole corpus and no finding.

package/src/design/components.ts

@@ -250,7 +250,7 @@ const TEACH_CHROME: Component = {
     'navigation shared by every teach page. Recovered from two gitignored',
     'course.css files that predate a regression that dropped this layer from the',
     "generator, and rewritten onto this module's tokens rather than the",
-    'incompatible palette they carried. See canon/context/features/teach/chrome.md',
+    'incompatible palette they carried. See canon/context/features/teach.md',
     'for the shape.',
   ].join('\n   '),
   reads: [