@erclx/canon 5.45.0 → 5.46.0

package/src/commands/markdown.ts

@@ -29,7 +29,16 @@ import {
   bodyLines,
   scanBans,
 } from '@/markdown/scan'
-import { densityGates, GATED_PATHS, inDensityScope } from '@/markdown/scope'
+import {
+  appendGatedPrefix,
+  findingsUnder,
+  GATED_CONFIG_REL,
+  type GatedList,
+  prefixShapeError,
+  readGatedConfig,
+  resolveGatedList,
+} from '@/markdown/gated'
+import { densityGates, inDensityScope } from '@/markdown/scope'
 import {
   BASELINE,
   CHECKPOINTS,
@@ -49,6 +58,9 @@ import {
 } from '@/cli/ui'
 import { isOwnCheckout } from '@/roots/project'
 
+/** A config the audit cannot read refuses rather than gating nothing. */
+type AuditRefusal = MarkdownAuditRefusal | 'malformed-config'
+
 const EXIT_REFUSED = 1
 const EXIT_GATE = 2
 
@@ -119,9 +131,12 @@ export function register(program: Command): void {
         'a row, a 200-character bullet, 5 plain bullets in a row, no H4, and a',
         'paragraph or table opening every H3. Only context, docs, skills, tooling',
         'seeds and references, the wiki, README.md, and CONTRIBUTING.md take a',
-        'finding. One gates under a prefix in GATED_PATHS in src/markdown/scope.ts,',
-        'and a bullet run gates in context, docs, and skills from the start.',
-        'Outside a canon checkout every density finding reports and none gates.',
+        'finding. In a canon checkout one gates under a prefix in GATED_PATHS in',
+        'src/markdown/scope.ts, and a bullet run gates in context, docs, and',
+        'skills from the start. Elsewhere one gates only under a prefix',
+        'canon/config/markdown.toml lists, which canon markdown gated add writes,',
+        'and with no such file every density finding reports and none gates.',
+        'A config that does not parse refuses with its path named.',
         '',
         'A page whose frontmatter carries kind: reference takes the reference',
         'shape: no H2 beyond Output, Refusals, and See also, each at most once',
@@ -165,6 +180,131 @@ export function register(program: Command): void {
     .action(async (paths: string[], opts: AuditCommandOptions) => {
       process.exitCode = await runAudit(paths, opts)
     })
+
+  const gated = markdown
+    .command('gated')
+    .description("Read and extend a project's gated density prefixes")
+    .helpOption('-h, --help', 'Show this help message')
+
+  gated
+    .command('add')
+    .description(
+      'Gate a folder or file once it carries no density or reference shape finding',
+    )
+    .argument(
+      '<prefix>',
+      'A folder ending in a slash, or the path of one existing file',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the prefix is listed, appended now or already present',
+        '  1  refused, with the reason on stderr, and the config left untouched',
+        '',
+        'Appends the prefix to canon/config/markdown.toml only when every file',
+        'under it carries zero findings that would gate once it is listed, so a',
+        'gated folder never fails a push the moment it is added. A folder holding',
+        'no markdown file passes. A prefix without a trailing slash would also',
+        'match a sibling such as docs-old/, so one must name an existing file.',
+        "A skill's REQUIREMENT.md gates only on its own path, never a folder.",
+        '',
+        "Canon's own checkout lists its prefixes in GATED_PATHS in",
+        'src/markdown/scope.ts, so the verb refuses there.',
+        '',
+        'Examples:',
+        '  canon markdown gated add docs/',
+        '  canon markdown gated add .claude/skills/my-skill/REQUIREMENT.md --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (prefix: string, opts: AuditCommandOptions) => {
+      process.exitCode = await runGatedAdd(prefix, opts)
+    })
+}
+
+type GatedAddRefusal =
+  | 'canon-checkout'
+  | 'malformed-config'
+  | 'bad-prefix'
+  | 'no-git'
+  | 'findings'
+
+async function runGatedAdd(
+  prefix: string,
+  opts: AuditCommandOptions,
+): Promise<number> {
+  const root = process.cwd()
+  const json = opts.json ?? false
+  const refuseAdd = (
+    reason: GatedAddRefusal,
+    message: string,
+    extra: Record<string, unknown> = {},
+  ): number => {
+    intro('canon markdown gated add')
+    logStep('Refused')
+    logWarn(message)
+    outro()
+    if (json) {
+      process.stdout.write(
+        `${JSON.stringify({ root, prefix, reason, message, ...extra })}\n`,
+      )
+    }
+    return EXIT_REFUSED
+  }
+
+  if (isOwnCheckout(root)) {
+    return refuseAdd(
+      'canon-checkout',
+      'This is a canon checkout, which gates through GATED_PATHS in src/markdown/scope.ts. Add the prefix there.',
+    )
+  }
+
+  const config = readGatedConfig(root)
+  if (config.kind === 'malformed') {
+    return refuseAdd('malformed-config', config.message)
+  }
+
+  const shape = prefixShapeError(root, prefix)
+  if (shape !== undefined) return refuseAdd('bad-prefix', shape)
+
+  const findings = await findingsUnder(root, prefix)
+  if (!findings) {
+    return refuseAdd(
+      'no-git',
+      'git could not list the tree, so nothing under the prefix was measured. Run inside a git repository.',
+    )
+  }
+  if (findings.length > 0) {
+    return refuseAdd(
+      'findings',
+      `${plural(findings.length, 'finding')} under ${prefix} would gate once it is listed. Run 'canon markdown audit ${prefix}' and bring it to zero first.`,
+      { findings },
+    )
+  }
+
+  const current = config.kind === 'listed' ? config.prefixes : []
+  const action = appendGatedPrefix(root, current, prefix)
+
+  intro('canon markdown gated add')
+  logStep(action === 'appended' ? 'Appended' : 'Already listed')
+  logInfo(
+    action === 'appended'
+      ? `${prefix} now gates in ${GATED_CONFIG_REL}.`
+      : `${prefix} was already listed in ${GATED_CONFIG_REL}, so nothing was written.`,
+  )
+  outro()
+
+  if (json) {
+    process.stdout.write(
+      `${JSON.stringify({ root, prefix, action, config: GATED_CONFIG_REL })}\n`,
+    )
+  }
+
+  return 0
 }
 
 async function runAudit(
@@ -194,12 +334,20 @@ async function runAudit(
     )
   }
 
+  const resolution = resolveGatedList(root)
+  if (resolution.kind === 'malformed') {
+    return refuse(
+      'malformed-config',
+      resolution.message,
+      root,
+      opts.json ?? false,
+    )
+  }
+  const gated = resolution.list
+
   const bans = BAN_SETS
   const empty = emptyBanSets(bans)
   const checkpoints = CHECKPOINTS
-  // `GATED_PATHS` describes this repository's rewrite progress, so a target
-  // reads every density finding as a report until its own corpus is gated.
-  const gates = isOwnCheckout(root)
 
   const reports: FileReport[] = await Promise.all(
     scope.files.map(async (rel) => {
@@ -216,12 +364,17 @@ async function runAudit(
         density: inDensityScope(rel)
           ? densityFindings(lines).map((finding) => ({
               ...finding,
-              gating: gates && densityGates(rel, finding.kind),
+              gating: densityGates(
+                rel,
+                finding.kind,
+                gated.prefixes,
+                gated.alwaysGated,
+              ),
             }))
           : [],
         referenceShape: referenceShapeFindings(source).map((finding) => ({
           ...finding,
-          gating: gates && referenceShapeGates(rel),
+          gating: referenceShapeGates(rel, gated.prefixes),
         })),
         links: findBrokenLinks(lines, (path) =>
           existsSync(resolve(dirname(abs), path)),
@@ -239,8 +392,8 @@ async function runAudit(
   reportLinks(reports, root)
   reportColons(reports)
   reportHeadingCase(reports)
-  reportDensity(reports, gates)
-  reportReferenceShape(reports, gates)
+  reportDensity(reports, gated, resolution.source)
+  reportReferenceShape(reports, gated)
   reportBullets(reports, checkpoints)
   reportParagraphs(reports, checkpoints)
   reportCadence(reports, checkpoints)
@@ -308,7 +461,7 @@ async function runAudit(
 }
 
 function refuse(
-  reason: MarkdownAuditRefusal,
+  reason: AuditRefusal,
   message: string,
   root: string,
   emitJson: boolean,
@@ -480,7 +633,11 @@ function describeDensity(finding: GatedDensityFinding): string {
  * under no gated prefix reports the same finding a gated one fails on and a
  * reader has to tell the two apart in one frame.
  */
-function reportDensity(reports: readonly FileReport[], gates: boolean): void {
+function reportDensity(
+  reports: readonly FileReport[],
+  gated: GatedList,
+  source: 'canon' | 'config' | 'absent',
+): void {
   logStep('Density')
   logInfo(
     `Paragraphs past ${CHECKPOINTS.paragraph} characters, more than 2 paragraphs in a row, bullets past ${CHECKPOINTS.bullet} characters, more than 5 plain bullets in a row, a heading past H3, and an H3 opening with neither a paragraph nor a table.`,
@@ -488,11 +645,7 @@ function reportDensity(reports: readonly FileReport[], gates: boolean): void {
   logInfo(
     'Measured on context entries, docs, skill bodies, references, and requirements, tooling seeds and stack references, the wiki, README.md, and CONTRIBUTING.md. Every other path takes no density finding.',
   )
-  logInfo(
-    gates
-      ? `A finding gates under a gated prefix (${GATED_PATHS.length === 0 ? 'none yet' : GATED_PATHS.join(', ')}), and a bullet run gates in context, docs, and skills already. Every other finding reports.`
-      : 'This tree is not a canon checkout, so every density finding reports and none gates.',
-  )
+  logInfo(densityGatingLine(gated, source))
 
   const carrying = reports
     .filter((report) => report.density.length > 0)
@@ -528,6 +681,20 @@ function reportDensity(reports: readonly FileReport[], gates: boolean): void {
   )
 }
 
+function densityGatingLine(
+  gated: GatedList,
+  source: 'canon' | 'config' | 'absent',
+): string {
+  if (source === 'absent') {
+    return `No ${GATED_CONFIG_REL} lists a gated prefix, so every density finding reports and none gates. Run 'canon markdown gated add <prefix>' once a folder reaches zero.`
+  }
+  const listed =
+    gated.prefixes.length === 0 ? 'none yet' : gated.prefixes.join(', ')
+  return source === 'canon'
+    ? `A finding gates under a gated prefix (${listed}), and a bullet run gates in context, docs, and skills already. Every other finding reports.`
+    : `A finding gates under a prefix ${GATED_CONFIG_REL} lists (${listed}). Every other finding reports.`
+}
+
 const REFERENCE_SHAPE_LABELS: Record<ReferenceShapeKind, string> = {
   'extra-section': 'section outside the shape',
   'section-order': 'section out of order or repeated',
@@ -546,16 +713,16 @@ function describeReferenceShape(finding: GatedReferenceShapeFinding): string {
  */
 function reportReferenceShape(
   reports: readonly FileReport[],
-  gates: boolean,
+  gated: GatedList,
 ): void {
   logStep('Reference shape')
   logInfo(
     `A page whose frontmatter carries kind: reference holds its opening, then ${REFERENCE_SECTIONS.join(', ')}, each at most once and in that order, with no H3 and no table of flags. An unmarked page is never measured.`,
   )
   logInfo(
-    gates
+    gated.prefixes.length > 0
       ? 'A finding gates under the prefixes the density step names. Every other finding reports.'
-      : 'This tree is not a canon checkout, so every reference shape finding reports and none gates.',
+      : 'No prefix is gated, so every reference shape finding reports and none gates.',
   )
 
   const carrying = reports.filter((report) => report.referenceShape.length > 0)

package/src/commands/sessions.ts

@@ -138,6 +138,14 @@ export function register(program: Command): void {
         'cannot rule out a pid handed to an unrelated process, so a roster',
         'reported that way is a candidate list rather than an identity.',
         '',
+        'A reader in another pid namespace, such as a sandboxed shell, cannot',
+        'see the pid of a record stamped elsewhere. That row is judged on its',
+        'messaging socket instead: it stays on the roster as "unverified" with',
+        '"via": "socket", since a crashed session leaves its socket behind. A',
+        'foreign record whose socket is gone is left off the roster and',
+        'counted in "foreignDead", so an empty roster beside a count above zero',
+        'is one this reader could not check, not one whose sessions ended.',
+        '',
         'The JSON record also carries "statusUpdatedAt" (the stamp the client',
         'wrote beside "status", or null where its record carries none) and',
         '"statusDwellMs" (the elapsed milliseconds since that stamp, falling',
@@ -464,7 +472,13 @@ async function runList(opts: ListCommandOptions): Promise<number> {
 
   intro('canon sessions list')
   reportConfidence(report)
-  reportSessions(shown, opts.branch, repository, own !== null)
+  reportSessions(
+    shown,
+    opts.branch,
+    repository,
+    own !== null,
+    report.foreignDead,
+  )
   if (claim) reportClaim(claim)
   outro()
 
@@ -473,6 +487,7 @@ async function runList(opts: ListCommandOptions): Promise<number> {
       `${JSON.stringify({
         dir: report.dir,
         confidence: report.confidence,
+        foreignDead: report.foreignDead,
         branch: opts.branch ?? null,
         repository,
         worktree: claim?.worktree ?? null,
@@ -522,7 +537,9 @@ function reportConfidence(
   // per session ever run, which is what makes the empty result worth stating.
   if (report.sessions.length === 0) {
     logInfo(
-      'No row to decide. Every record belongs to a session that has ended.',
+      report.foreignDead > 0
+        ? 'No row to decide.'
+        : 'No row to decide. Every record belongs to a session that has ended.',
     )
     return
   }
@@ -534,6 +551,13 @@ function reportConfidence(
     return
   }
 
+  if (report.sessions.some((session) => session.via === 'socket')) {
+    logWarn(
+      'This reader sits in another pid namespace than some records, so those rows rest on a messaging socket existing alone. A crashed session leaves its socket behind, so treat the mapping as inferred and open by asking to be corrected.',
+    )
+    return
+  }
+
   logWarn(
     'Start times could not be read, so rows rest on a pid answering alone. Treat the mapping as inferred and open by asking to be corrected.',
   )
@@ -544,6 +568,7 @@ function reportSessions(
   branch: string | undefined,
   repository: string | null,
   scoped: boolean,
+  foreignDead: number,
 ): void {
   logStep('Sessions')
 
@@ -567,7 +592,9 @@ function reportSessions(
     }
 
     logInfo(
-      'No live session. Every record in the registry belongs to a session that has ended.',
+      foreignDead > 0
+        ? `No live session could be confirmed. ${foreignDead} of the records come from another pid namespace and no socket answers for them, so this reader could not check whether they ended.`
+        : 'No live session. Every record in the registry belongs to a session that has ended.',
     )
     return
   }
@@ -630,6 +657,12 @@ function reportClaim(claim: ClaimReport): void {
     )
   }
 
+  if (claim.foreignDead > 0) {
+    logWarn(
+      `${claim.foreignDead} records from another pid namespace have no answering socket, so a session holding this branch may be missing. Treat it as unverified rather than clear.`,
+    )
+  }
+
   if (!claim.refsReadable) {
     logWarn(
       'The ref read failed, so this cannot say whether the branch already exists. Treat it as unverified rather than clear.',

package/src/commands/tasks.ts

@@ -33,6 +33,7 @@ import {
   claimLabel,
   nextLabel,
 } from '@/tasks/label'
+import { type ClosureOutcome, readClosure } from '@/tasks/closes'
 import { listTasks } from '@/tasks/list'
 import {
   type Claim,
@@ -142,6 +143,13 @@ interface OutcomeCommandOptions {
   readonly root?: string
 }
 
+interface ClosesCommandOptions {
+  readonly branch?: string
+  readonly json?: boolean
+  readonly plan?: string
+  readonly root?: string
+}
+
 interface ListCommandOptions {
   readonly json?: boolean
   readonly root?: string
@@ -635,6 +643,57 @@ export function register(program: Command): void {
       process.exitCode = await runOutcome(task, opts)
     })
 
+  tasks
+    .command('closes')
+    .description('Name the issues the branch pull request closes')
+    .argument('[task]', 'Task filename stem, as in v28.1-trigger-escalation')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--plan <slug>', 'Select the task whose Plan line names this plan')
+    .option(
+      '--branch <name>',
+      'Branch to treat as this pull request, defaulting to the checked-out one',
+    )
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Board root, defaulting to the main worktree')
+    .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 task and a plan both named, or neither',
+        '',
+        'Exit codes:',
+        '  0  the task is read, whether or not it closes',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Reads the `Issue:` lines, each `#NNN` or a comma list, and reports',
+        '`issues` and `closing`. The pull request closes them only when it is',
+        "the task's last slice, the condition the merge-time archive applies:",
+        'no open outcome and no other branch on `Pending branch:`. The branch',
+        'and the names it carried before a rename count as this one. Read off',
+        '`reason` when `closing` is false:',
+        '  no-issues       the task carries no `Issue:` number',
+        '  earlier-slice   this branch has a pull request on the task that is not',
+        '                  the last listed, so a later number closes the issue',
+        '  lookup-failed   the pull request lookup failed while the task already',
+        '                  lists a pull request, so an earlier slice cannot be ruled out',
+        '  open-outcomes   an outcome is still open, so a later slice closes it',
+        '  pending-branch  another branch is on `Pending branch:`',
+        '  no-outcomes     the task carries no outcomes',
+        '',
+        'Examples:',
+        '  canon tasks closes --plan closing-issue-references --json',
+        '  canon tasks closes v28.1-trigger-escalation --branch feat/x',
+        '',
+      ].join('\n'),
+    )
+    .action(async (task: string | undefined, opts: ClosesCommandOptions) => {
+      process.exitCode = await runCloses(task, opts)
+    })
+
   tasks
     .command('next-label')
     .description(
@@ -1196,6 +1255,67 @@ async function branchPullNumbers(
   }
 }
 
+/**
+ * The pull request numbers whose head is `branch`, read over REST because a
+ * cloud session's GitHub proxy refuses the GraphQL `gh pr list` runs on.
+ * Unlike `branchPullNumbers`, a failed or unreadable answer is null rather
+ * than an empty list, since the closing decision must not read a failure as
+ * a branch with no pull request.
+ */
+async function branchPullNumbersRest(
+  branch: string | undefined,
+): Promise<readonly number[] | null> {
+  if (branch === undefined) return []
+
+  const owner = await execa(
+    'gh',
+    ['api', 'repos/{owner}/{repo}', '--jq', '.owner.login'],
+    {
+      cwd: process.cwd(),
+      reject: false,
+      timeout: GH_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+    },
+  )
+  if (owner.exitCode !== 0 || owner.stdout.trim() === '') return null
+
+  const result = await execa(
+    'gh',
+    [
+      'api',
+      '-X',
+      'GET',
+      'repos/{owner}/{repo}/pulls',
+      '-f',
+      `head=${owner.stdout.trim()}:${branch}`,
+      '-f',
+      'state=all',
+      '--jq',
+      '[.[].number]',
+    ],
+    {
+      cwd: process.cwd(),
+      reject: false,
+      timeout: GH_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+    },
+  )
+  if (result.exitCode !== 0) return null
+
+  try {
+    const numbers: unknown = JSON.parse(result.stdout)
+    if (!Array.isArray(numbers)) return null
+
+    return numbers.every((number) => Number.isInteger(number))
+      ? (numbers as number[])
+      : null
+  } catch {
+    return null
+  }
+}
+
 async function runPlanLink(
   task: string,
   plan: string,
@@ -1381,6 +1501,66 @@ function reportPlanLink(
   return 0
 }
 
+async function runCloses(
+  task: string | undefined,
+  opts: ClosesCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  const selector = selectorFor(task, opts.plan)
+
+  if ('ok' in selector) {
+    return reportRecord('canon tasks closes', selector, emitJson, process.cwd())
+  }
+
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const branch = opts.branch ?? (await workingBranch())
+  const branches = branch ? [branch, ...(await formerNames(branch))] : []
+  const outcome = await readClosure(
+    root,
+    selector,
+    branches,
+    await branchPullNumbersRest(branch),
+  )
+
+  return reportCloses(outcome, emitJson, root)
+}
+
+function reportCloses(
+  outcome: ClosureOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    return reportRecord('canon tasks closes', outcome, emitJson, root)
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        task: outcome.stem,
+        path: relative(root, outcome.path),
+        issues: outcome.issues,
+        closing: outcome.closing,
+        reason: outcome.reason,
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro('canon tasks closes')
+  logStep(outcome.closing ? 'Closes' : 'Closes nothing')
+  logInfo(
+    outcome.issues.length > 0
+      ? `${outcome.stem} names ${outcome.issues.map((n) => `#${n}`).join(', ')}, ${outcome.reason}`
+      : `${outcome.stem} names no issue`,
+  )
+  outro()
+
+  return 0
+}
+
 function reportOutcome(
   outcome: CloseOutcome,
   emitJson: boolean,

package/src/commands/worktrees.ts

@@ -109,6 +109,8 @@ const UNREADABLE: Record<Unreadable, string> = {
     'The pull request read failed, so every worktree would report as unmerged whatever its real state. Authenticate gh and run this again.',
   'sessions-unreadable':
     'The session roster could not be read, so nothing was read about which worktrees are still held.',
+  'sessions-unchecked':
+    'Some session records come from another pid namespace and no socket answers for them, so a live holder may be missing from the roster. Run this from the namespace the sessions run in.',
 }
 
 const CONDITIONS = [