@erclx/canon 4.119.0 → 4.120.0

package/src/commands/pr.ts

@@ -1,5 +1,5 @@
 import { existsSync } from 'node:fs'
-import { readFile } from 'node:fs/promises'
+import { readdir, readFile, readlink, realpath } from 'node:fs/promises'
 import { basename, join, resolve } from 'node:path'
 import { $ } from 'bun'
 import type { Command } from 'commander'
@@ -28,11 +28,21 @@ import {
 import {
   findEvidenceChecklist,
   findEvidenceCommentId,
+  findEvidenceLocal,
   findEvidencePreview,
   groupEvidence,
   renderEvidenceBody,
 } from '@/pr/evidence'
 import { type HeadRefusal, resolveHead, resolveTip } from '@/pr/head'
+import {
+  findLocalServer,
+  type Listener,
+  type LocalRefusal,
+  type LocalRunner,
+  parseLsofListeners,
+  parseProcNetTcp,
+  stripLocalLine,
+} from '@/pr/local'
 import { KEY_CHANGES } from '@/pr/paths'
 import {
   findDeployWorkflow,
@@ -76,6 +86,28 @@ interface ReadOptions {
 interface EvidenceOptions extends ReadOptions {
   readonly preview?: string
   readonly checklist?: string
+  readonly local?: string
+}
+
+interface LocalOptions extends ReadOptions {
+  readonly remove?: boolean
+  readonly note?: string
+}
+
+/** What replaces the local address line once the pull request closes. */
+const LOCAL_REMOVED_NOTE =
+  '_Local preview removed when the pull request closed._'
+
+/** How long the probe waits on a listener before reading it as not a server. */
+const LOCAL_PROBE_TIMEOUT_MS = 2_000
+
+const LOCAL_REFUSALS: Record<LocalRefusal | 'gh-failed', string> = {
+  'no-server':
+    'Nothing listening inside this worktree served an HTML page. Start the dev server here and re-run to get a link.',
+  'no-listener-reader':
+    'This machine offers neither lsof nor /proc, so no listening socket could be read. Nothing is posted.',
+  'gh-failed':
+    'gh could not read or edit the marked comment on this pull request.',
 }
 
 interface PreviewOptions extends ReadOptions {
@@ -387,6 +419,10 @@ export function register(program: Command): void {
       '--checklist <path>',
       'Close the body with this visual checklist file, from canon:ui-checklist',
     )
+    .option(
+      '--local <url>',
+      "Add this worktree's running server under any preview line, from canon pr local",
+    )
     .addHelpText(
       'after',
       [
@@ -419,6 +455,13 @@ export function register(program: Command): void {
         'image still reports no-evidence, and the caller posts the checklist',
         'on its own.',
         '',
+        '--local adds a **Local preview:** line under the hosted preview line,',
+        'or opens the body with it when there is none, and is carried forward',
+        'the same way. It does not by itself turn no-evidence into ok, so a',
+        'branch with a server running and nothing to show posts no link-only',
+        'comment. Together with --checklist it does, so the checklist and the',
+        'link land in one comment.',
+        '',
         'Exit codes:',
         '  0  read, whether it produced a body or reported no-evidence',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -428,6 +471,7 @@ export function register(program: Command): void {
         '  canon pr evidence 1341 --json',
         '  canon pr evidence 1341 --preview https://feat-x.site.pages.dev --json',
         '  canon pr evidence 1341 --checklist .canon/tmp/handoff/ui-checklist/x.md --json',
+        '  canon pr evidence 1341 --local http://localhost:5173 --json',
         '',
       ].join('\n'),
     )
@@ -484,6 +528,66 @@ export function register(program: Command): void {
     .action(async (number: string | undefined, opts: PreviewOptions) => {
       process.exitCode = await runPreview(number, opts)
     })
+
+  pr.command('local')
+    .description(
+      "Find the server this worktree is running and report its localhost address, or remove it from the pull request's evidence comment",
+    )
+    .argument('[number]', 'Pull request to edit on --remove')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Worktree to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option(
+      '--remove',
+      "Replace the evidence comment's local preview line with a note",
+    )
+    .option(
+      '--note <text>',
+      'What replaces the line on --remove',
+      LOCAL_REMOVED_NOTE,
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Reads every TCP socket in LISTEN, keeps those whose owning process runs',
+        "inside this worktree's toplevel, and requests / on each. The lowest",
+        'port serving an HTML page is reported, which skips a test runner or a',
+        'reload socket answering in the same tree.',
+        '',
+        'A process in a sibling worktree, in the main checkout seen from a',
+        'linked worktree, or in a linked worktree seen from the main checkout',
+        'is never reported, since its server shows another branch. Sockets are',
+        'read through lsof, or through /proc on a Linux machine without it.',
+        '',
+        '--remove reads the pull request comment carrying the pr-evidence',
+        'marker and replaces its **Local preview:** line with --note, editing',
+        'the comment itself so a close workflow with no session can call it.',
+        '',
+        'Read `reason` on the JSON record:',
+        '  ok                  a page answered, with its address in `url`',
+        '  no-server           nothing inside this worktree served a page',
+        '  no-listener-reader  neither lsof nor /proc is available',
+        '  removed             --remove replaced the line',
+        '  no-comment          --remove found no marked comment, a no-op',
+        '  no-line             --remove found no local line, a no-op',
+        '',
+        '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',
+        '',
+        'Examples:',
+        '  canon pr local --json',
+        '  canon pr local 1341 --remove --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (number: string | undefined, opts: LocalOptions) => {
+      process.exitCode =
+        opts.remove === true
+          ? await runLocalRemove(number, opts)
+          : await runLocal(opts)
+    })
 }
 
 interface PullRequestRead {
@@ -1319,7 +1423,15 @@ async function runEvidence(
     baseTree.has(path),
   )
 
-  if (grouped.kind === 'refused' && opts.preview === undefined) {
+  // A local address rides on a checklist or a hosted preview and never opens
+  // a comment alone, so a docs-only branch with a server up posts nothing.
+  const hasChecklistAndLocal =
+    suppliedChecklist !== undefined && opts.local !== undefined
+  if (
+    grouped.kind === 'refused' &&
+    opts.preview === undefined &&
+    !hasChecklistAndLocal
+  ) {
     logStep('Skipped')
     logInfo(
       'No changed path carries an evidence/ segment, so there is nothing to post.',
@@ -1355,6 +1467,7 @@ async function runEvidence(
   let commentId: number | undefined
   let carriedPreview: string | undefined
   let carriedChecklist: string | undefined
+  let carriedLocal: string | undefined
   if (identity.number !== undefined) {
     const commentsRow = await gh(root, [
       'pr',
@@ -1389,9 +1502,11 @@ async function runEvidence(
     commentId = findEvidenceCommentId(comments)
     carriedPreview = findEvidencePreview(comments)
     carriedChecklist = findEvidenceChecklist(comments)
+    carriedLocal = findEvidenceLocal(comments)
   }
 
   const preview = opts.preview ?? carriedPreview
+  const local = opts.local ?? carriedLocal
   const checklist = suppliedChecklist ?? carriedChecklist
   const states = grouped.kind === 'read' ? grouped.states : []
   const body = renderEvidenceBody(
@@ -1401,6 +1516,7 @@ async function runEvidence(
     identity.head,
     preview,
     checklist,
+    local,
   )
 
   const caseCount = states.reduce((n, s) => n + s.items.length, 0)
@@ -1410,6 +1526,7 @@ async function runEvidence(
     `${plural(caseCount, 'case')} across ${plural(states.length, 'state')}`,
   )
   if (preview !== undefined) logInfo(`preview ${preview}`)
+  if (local !== undefined) logInfo(`local preview ${local}`)
   if (checklist !== undefined) {
     logInfo(
       suppliedChecklist === undefined
@@ -1603,6 +1720,211 @@ async function runPreview(
   return 0
 }
 
+async function readText(path: string): Promise<string | undefined> {
+  return readFile(path, 'utf8').catch(() => undefined)
+}
+
+/**
+ * Every listening socket's owning pid, read from `/proc`. Only a process this
+ * user owns exposes its `fd` table, which is also the only process whose
+ * server this user's worktree could have started.
+ */
+async function readProcListeners(): Promise<Listener[] | undefined> {
+  const tables = await Promise.all(
+    ['/proc/net/tcp', '/proc/net/tcp6'].map(readText),
+  )
+  if (tables.every((text) => text === undefined)) return undefined
+  const byInode = new Map(
+    tables.flatMap((text) =>
+      text === undefined
+        ? []
+        : parseProcNetTcp(text).map((s) => [s.inode, s.port] as const),
+    ),
+  )
+
+  const processIds = (await readdir('/proc').catch(() => [])).filter((name) =>
+    /^\d+$/.test(name),
+  )
+  const listeners: Listener[] = []
+  for (const pid of processIds) {
+    const fds = await readdir(`/proc/${pid}/fd`).catch(() => [])
+    for (const fd of fds) {
+      const target = await readlink(`/proc/${pid}/fd/${fd}`).catch(() => '')
+      const inode = /^socket:\[(\d+)\]$/.exec(target)?.[1]
+      const port = inode === undefined ? undefined : byInode.get(inode)
+      if (port !== undefined) listeners.push({ pid: Number(pid), port })
+    }
+  }
+  return listeners
+}
+
+/**
+ * The machine half of a detection: lsof where it is installed, `/proc` on a
+ * Linux machine without it, and no reader anywhere else.
+ */
+function machineLocalRunner(): LocalRunner {
+  const hasLsof = Bun.which('lsof') !== null
+  return {
+    async listListeners() {
+      if (hasLsof) {
+        const result = await $`lsof -nP -iTCP -sTCP:LISTEN -Fpn`
+          .quiet()
+          .nothrow()
+        // lsof exits 1 both when it matched nothing and when it could not
+        // read some process, and the rows it did print are real either way.
+        if (result.exitCode <= 1) return parseLsofListeners(result.text())
+      }
+      if (existsSync('/proc/net/tcp')) return readProcListeners()
+      return undefined
+    },
+    async cwdOf(pid) {
+      if (existsSync(`/proc/${pid}/cwd`)) {
+        return readlink(`/proc/${pid}/cwd`).catch(() => undefined)
+      }
+      if (!hasLsof) return undefined
+      const result = await $`lsof -a -p ${pid} -d cwd -Fn`.quiet().nothrow()
+      const line = result
+        .text()
+        .split('\n')
+        .find((row) => row.startsWith('n'))
+      return line?.slice(1)
+    },
+    // An HTML page rather than any answer, since a test runner's server or a
+    // reload socket in the same tree answers too, and a reviewer opening one
+    // gets a bare 404 instead of the branch.
+    async probe(port) {
+      try {
+        const response = await fetch(`http://localhost:${port}/`, {
+          signal: AbortSignal.timeout(LOCAL_PROBE_TIMEOUT_MS),
+        })
+        await response.body?.cancel()
+        return (response.headers.get('content-type') ?? '').includes(
+          'text/html',
+        )
+      } catch {
+        return false
+      }
+    },
+  }
+}
+
+/** The worktree's toplevel with symlinks resolved, since a process cwd is read back resolved. */
+async function resolveWorktreeRoot(root: string): Promise<string> {
+  const result = await $`git -C ${root} rev-parse --show-toplevel`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
+  const toplevel = result.exitCode === 0 ? result.text().trim() : root
+  return realpath(toplevel).catch(() => toplevel)
+}
+
+async function runLocal(opts: LocalOptions): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  intro('canon pr local')
+
+  const worktree = await resolveWorktreeRoot(root)
+  const result = await findLocalServer(worktree, machineLocalRunner())
+  if (result.kind === 'refused') {
+    return refuseWith(
+      result.reason,
+      LOCAL_REFUSALS[result.reason],
+      emitJson,
+      root,
+    )
+  }
+
+  logStep('Local preview')
+  logInfo(result.url)
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ root, reason: 'ok', url: result.url, port: result.port })}\n`,
+    )
+  }
+  return 0
+}
+
+/**
+ * Replaces the local line on the marked comment. The verb writes here rather
+ * than handing a body back, because its caller is a close workflow with no
+ * session to post one.
+ */
+async function runLocalRemove(
+  number: string | undefined,
+  opts: LocalOptions,
+): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+  const note = opts.note ?? LOCAL_REMOVED_NOTE
+
+  intro('canon pr local --remove')
+
+  if (Bun.which('gh') === null) {
+    return refuseWith('gh-missing', PULL_REFUSALS['gh-missing'], emitJson, root)
+  }
+
+  const args = ['pr', 'view']
+  if (number !== undefined) args.push(number)
+  args.push('--json', 'comments')
+  const row = await gh(root, args)
+  let comments: readonly { url?: string; body: string }[] | undefined
+  try {
+    comments =
+      row === null
+        ? undefined
+        : (
+            JSON.parse(row) as {
+              comments?: readonly { url?: string; body: string }[]
+            }
+          ).comments
+  } catch {
+    comments = undefined
+  }
+  if (comments === undefined) {
+    return refuseWith('gh-failed', LOCAL_REFUSALS['gh-failed'], emitJson, root)
+  }
+
+  const finish = (reason: string, message: string): number => {
+    logStep(reason === 'removed' ? 'Removed' : 'Skipped')
+    logInfo(message)
+    outro()
+    if (emitJson) {
+      process.stdout.write(`${JSON.stringify({ root, reason })}\n`)
+    }
+    return 0
+  }
+
+  const commentId = findEvidenceCommentId(comments)
+  const marked = comments.find((comment) =>
+    comment.url?.endsWith(`#issuecomment-${commentId}`),
+  )
+  if (commentId === undefined || marked === undefined) {
+    return finish('no-comment', 'No comment carries the evidence marker.')
+  }
+
+  const stripped = stripLocalLine(marked.body, note)
+  if (stripped === undefined) {
+    return finish('no-line', 'The evidence comment carries no local line.')
+  }
+
+  const patched = await gh(root, [
+    'api',
+    '-X',
+    'PATCH',
+    `repos/{owner}/{repo}/issues/comments/${commentId}`,
+    '-f',
+    `body=${stripped}`,
+  ])
+  if (patched === null) {
+    return refuseWith('gh-failed', LOCAL_REFUSALS['gh-failed'], emitJson, root)
+  }
+
+  return finish('removed', `comment ${commentId}`)
+}
+
 /**
  * Frames a refusal on stderr in both modes and puts the record on stdout alone,
  * so an operator reading the terminal sees the reason rather than a command

package/src/context/classify/extract.ts

@@ -285,8 +285,8 @@ export function sweepSections(
   // An H3 sitting before the document's first H2, or in a document that
   // carries no H2 at all, has no enclosing section for the main loop below
   // to attribute it to. Sweep it as a section of its own instead of
-  // dropping it, which is the shape `canon/context/development/scratch.md`
-  // takes: an H1 followed directly by eight H3s and no H2 anywhere.
+  // dropping it, which is the shape of an entry whose H1 is followed
+  // directly by H3s with no H2 anywhere.
   const firstH2 = headings.findIndex((h) => h.level === 2)
   const leadingBound = firstH2 === -1 ? headings.length : firstH2
 

package/src/counts/scan.ts

@@ -129,7 +129,7 @@ const QUANTIFIERS = ['all']
  * of the number.
  *
  * Found on this module's own first review, against a live instance the verb
- * gate alone reported clean: `canon/context/development/gates.md` stated
+ * gate alone reported clean: the development gating-stages entry stated
  * `the twelve audits` while the tree held 20, sitting inside the plausibility
  * bound this design already carries, so nothing but the missing shape kept it
  * from reporting.

package/src/design/tokens.ts

@@ -381,7 +381,7 @@ export const TOKENS: DesignTokens = {
   iconography: [
     'No icon library is installed. `assets/brand/mark.svg` is the one authored icon, embedded inline in the hero topbar, and the surfaces otherwise draw literal glyph characters: `│ ├ ✓ ! ✗ + - ◆ ◇ ❯` for the terminal framing.',
     '',
-    'The same mark ships in five independently-maintained copies that carry different colors by design rather than by drift, each fitted to the chrome it renders on: the dark accent for a dark-chrome surface, the light accent for a light-chrome one, and the pair the web favicon takes from `src/design/favicon.ts`, which teach pages also take by rendering the live mark. Unifying them or repairing the one that looks drifted would break the fit each was chosen for. `canon/context/design.md` carries which file holds each copy.',
+    'The same mark ships in five independently-maintained copies that carry different colors by design rather than by drift, each fitted to the chrome it renders on: the dark accent for a dark-chrome surface, the light accent for a light-chrome one, and the pair the web favicon takes from `src/design/favicon.ts`, which teach pages also take by rendering the live mark. Unifying them or repairing the one that looks drifted would break the fit each was chosen for. `canon/context/design/tokens.md` carries which file holds each copy.',
   ].join('\n'),
 }
 

package/src/gate/stages.ts

@@ -83,7 +83,7 @@ export interface Stage {
 
 /**
  * Corpora a `src/` test asserts over from outside `src/`, censused in
- * `canon/context/development/verification.md`. This list and that census are
+ * `canon/context/development/tests.md`. This list and that census are
  * two copies of one set with nothing comparing them, so a corpus joining the
  * census joins this list in the same change. The first four are directory
  * prefixes because their tests walk the tree whole, which is what reaches a
@@ -314,7 +314,7 @@ export const STAGES: readonly Stage[] = [
   {
     // A hook, a workflow, or a husky script reaching one side of the seed or
     // config boundary and not the other is a capability withheld with no
-    // recorded reason, per the criterion in canon/context/tooling.md.
+    // recorded reason, per the criterion in canon/context/tooling/seeds.md.
     id: 'capability-seeding',
     label: 'Capability seeding',
     checks: [

package/src/pr/evidence.ts

@@ -7,6 +7,9 @@ const MARKER_PREFIX = '<!-- pr-evidence:'
 /** How the first line of a body names the branch's preview deployment. */
 const PREVIEW_PREFIX = '**Preview:**'
 
+/** How the opening block names the branch's server on the operator's own machine, under any hosted preview line. */
+export const LOCAL_PREFIX = '**Local preview:**'
+
 /** The heading the checklist sits under, printed outside the delimiters so a carried checklist never doubles it. */
 const CHECKLIST_HEADING = '## What to look at'
 
@@ -128,6 +131,9 @@ export function evidenceMarker(head: string): string {
  *
  * A checklist closes the body, below the comparison it annotates, so one
  * comment carries the preview address, the screenshots, and what to look at.
+ *
+ * A local address sits under the hosted one, never above it, so the hosted
+ * line keeps the first-line position `findEvidencePreview` reads.
  */
 export function renderEvidenceBody(
   states: readonly EvidenceState[],
@@ -136,9 +142,13 @@ export function renderEvidenceBody(
   head: string,
   preview?: string,
   checklist?: string,
+  local?: string,
 ): string {
-  const opening =
-    preview === undefined ? [] : [`${PREVIEW_PREFIX} ${preview}`, '']
+  const addresses = [
+    ...(preview === undefined ? [] : [`${PREVIEW_PREFIX} ${preview}`]),
+    ...(local === undefined ? [] : [`${LOCAL_PREFIX} ${local}`]),
+  ]
+  const opening = addresses.length === 0 ? [] : [...addresses, '']
   const closing =
     checklist === undefined
       ? []
@@ -223,6 +233,36 @@ export function findEvidencePreview(
   return first.slice(PREVIEW_PREFIX.length).trim() || undefined
 }
 
+/**
+ * Where the local address line sits in a body, searched only through the
+ * opening block above the first blank line, so a line quoted further down in
+ * a checklist is never taken for it. -1 when the block carries none.
+ */
+export function findLocalLineIndex(body: string): number {
+  const lines = body.split('\n')
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = (lines[index] ?? '').trim()
+    if (line === '') return -1
+    if (line.startsWith(LOCAL_PREFIX)) return index
+  }
+  return -1
+}
+
+/**
+ * The local address the marked comment already carries, carried forward on a
+ * re-render the way the hosted preview is.
+ */
+export function findEvidenceLocal(
+  comments: readonly EvidenceComment[],
+): string | undefined {
+  const marked = comments.find((comment) => hasEvidenceMarker(comment.body))
+  if (marked === undefined) return undefined
+  const index = findLocalLineIndex(marked.body)
+  if (index === -1) return undefined
+  const line = marked.body.split('\n')[index]?.trim() ?? ''
+  return line.slice(LOCAL_PREFIX.length).trim() || undefined
+}
+
 /**
  * The checklist the marked comment already carries, read back out of its
  * delimiters. The handoff file is deleted once posted, so every later render

package/src/pr/local.ts

@@ -0,0 +1,125 @@
+import { findLocalLineIndex } from '@/pr/evidence'
+
+/**
+ * The folder linked worktrees sit under. A listener there belongs to another
+ * branch even though its cwd sits inside the main checkout's toplevel.
+ */
+const LINKED_WORKTREES = '.claude/worktrees'
+
+/** The state `/proc/net/tcp` writes for a socket in LISTEN. */
+const PROC_LISTEN_STATE = '0A'
+
+export type LocalRefusal = 'no-server' | 'no-listener-reader'
+
+export interface Listener {
+  readonly port: number
+  readonly pid: number
+}
+
+/** The machine reads a detection makes, injected so it can be driven without binding a socket. */
+export interface LocalRunner {
+  /** Every TCP socket in LISTEN with its owning pid, or undefined when this machine offers no way to read them. */
+  listListeners(): Promise<readonly Listener[] | undefined>
+  cwdOf(pid: number): Promise<string | undefined>
+  /** Whether the port serves an HTML page at its root inside the runner's timeout. */
+  probe(port: number): Promise<boolean>
+}
+
+export type LocalResult =
+  | { readonly kind: 'found'; readonly port: number; readonly url: string }
+  | { readonly kind: 'refused'; readonly reason: LocalRefusal }
+
+function isInside(path: string, root: string): boolean {
+  return path === root || path.startsWith(`${root}/`)
+}
+
+/**
+ * Whether a process running in `cwd` serves this worktree. A tool that
+ * changes into a subfolder before listening still counts, while a sibling
+ * worktree nested under the main checkout's `.claude/worktrees/` does not.
+ */
+function belongsTo(cwd: string, worktreeRoot: string): boolean {
+  return (
+    isInside(cwd, worktreeRoot) &&
+    !isInside(cwd, `${worktreeRoot}/${LINKED_WORKTREES}`)
+  )
+}
+
+/**
+ * Finds the server this worktree is running: the lowest port whose listening
+ * process runs inside the worktree and answers an HTTP probe. A port rather
+ * than a process is the unit, since one dev server often holds a second
+ * socket for its reload channel, and the lower one is the page by convention.
+ */
+export async function findLocalServer(
+  worktreeRoot: string,
+  runner: LocalRunner,
+): Promise<LocalResult> {
+  const listeners = await runner.listListeners()
+  if (listeners === undefined) {
+    return { kind: 'refused', reason: 'no-listener-reader' }
+  }
+
+  const cwdByPid = new Map<number, string | undefined>()
+  const ports = new Set<number>()
+  for (const { pid, port } of listeners) {
+    if (!cwdByPid.has(pid)) cwdByPid.set(pid, await runner.cwdOf(pid))
+    const cwd = cwdByPid.get(pid)
+    if (cwd !== undefined && belongsTo(cwd, worktreeRoot)) ports.add(port)
+  }
+
+  for (const port of [...ports].sort((a, b) => a - b)) {
+    if (await runner.probe(port)) {
+      return { kind: 'found', port, url: `http://localhost:${port}` }
+    }
+  }
+  return { kind: 'refused', reason: 'no-server' }
+}
+
+/** Reads `lsof -nP -iTCP -sTCP:LISTEN -Fpn` output, where a `p` line opens a process and each `n` line names one of its sockets. */
+export function parseLsofListeners(text: string): Listener[] {
+  const listeners: Listener[] = []
+  let pid: number | undefined
+  for (const line of text.split('\n')) {
+    if (line.startsWith('p')) pid = Number(line.slice(1))
+    if (!line.startsWith('n') || pid === undefined) continue
+    const port = Number(line.slice(line.lastIndexOf(':') + 1))
+    if (Number.isInteger(port) && port > 0) listeners.push({ pid, port })
+  }
+  return listeners
+}
+
+export interface ProcSocket {
+  readonly port: number
+  readonly inode: string
+}
+
+/** Reads `/proc/net/tcp` or `tcp6`, keeping each listening socket's port and inode for matching against `/proc/<pid>/fd`. */
+export function parseProcNetTcp(text: string): ProcSocket[] {
+  const sockets: ProcSocket[] = []
+  for (const line of text.split('\n').slice(1)) {
+    const fields = line.trim().split(/\s+/)
+    const local = fields[1]
+    const state = fields[3]
+    const inode = fields[9]
+    if (local === undefined || inode === undefined) continue
+    if (state !== PROC_LISTEN_STATE) continue
+    const port = Number.parseInt(local.slice(local.lastIndexOf(':') + 1), 16)
+    if (Number.isInteger(port) && port > 0) sockets.push({ port, inode })
+  }
+  return sockets
+}
+
+/**
+ * Replaces the local address line of a marked body with `note`, leaving
+ * every other byte in place so the trailing marker, the checklist delimiters,
+ * and any ticked box survive. Undefined when the body carries no such line,
+ * which is also what a second strip of the same body returns.
+ */
+export function stripLocalLine(body: string, note: string): string | undefined {
+  const index = findLocalLineIndex(body)
+  if (index === -1) return undefined
+  const lines = body.split('\n')
+  lines[index] = note
+  return lines.join('\n')
+}

package/standards/index.md

@@ -30,6 +30,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Requirements reference](requirements.md): Shape and content rules for canon/REQUIREMENTS.md
 - [Governance rule reference](rule.md): Rule frontmatter, body shape, and voice for .claude/rules files
 - [Session map reference](session.md): Filename and location, the sections a handoff carries, the write and read procedures, and how a role extends it
+- [Skill requirement reference](skill-requirement.md): Shape and content rules for the REQUIREMENT.md beside a skill
 - [Claude skill reference](skill.md): Claude skill structure and authoring rules
 - [Slug reference](slug.md): Transform from a git branch name to a slug, and the three responses to an empty result
 - [Snippet reference](snippets.md): Snippet reference and authoring conventions