@descent-vtt/spec-harness 0.6.0 → 0.7.0

package/dist/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What an agent needs to start a round, and nothing it does not.\n *\n * The brief in full - it is the contract, and a summary of a contract is a\n * different contract. Then what the brief implies but does not say: the scope\n * as the guard will read it, the rulings already signed, the briefs it waits\n * on, the rules spec-guard holds the scope's code to, and the documents the\n * brief cites. The cited documents are the one part that can be large, so\n * they fill what the budget leaves, in the order the brief cites them, and\n * the rest are named rather than dropped silently. So is a document whose\n * front matter is never closed, whose status cannot be read, rather than\n * shown as one without a status, and a pattern in the scope, a protection or\n * a ruling's path the guard cannot read, with spec-core's reason and what the\n * guard does without it, rather than listed as one it can.\n */\n\nimport { sameId } from './branch.js';\nimport { whyUnreadable } from './guard.js';\nimport type { BriefRow } from './types.js';\n\nexport interface CitedDocument {\n  readonly path: string;\n  readonly title: string | null;\n  readonly status: string | null;\n  /** `null` when the link does not resolve to a readable file. */\n  readonly text: string | null;\n  /** YAML front matter opened on line 1 and never closed, so no status was read from it. */\n  readonly unclosedFrontMatter?: boolean | undefined;\n}\n\nexport interface RuleInForce {\n  readonly document: string;\n  readonly line: number;\n  readonly kind: string;\n  readonly description: string;\n  readonly reason: string | null;\n}\n\n/**\n * The rules in force for the scope; `none` when spec-guard reads no\n * specification here, so none can be in force; `unavailable` when the rules\n * could not be read.\n */\nexport type Rules = readonly RuleInForce[] | { readonly none: string } | { readonly unavailable: string };\n\ninterface QueryDocument {\n  readonly specFiles?: unknown;\n  readonly results?: readonly { readonly rules?: readonly (RuleInForce & { readonly reason?: string | null; readonly inForce?: boolean })[] }[];\n}\n\n/**\n * spec-guard's answer to `query --json`, read. It exits 2 both when no spec\n * file matched its patterns - a repository that keeps none, or keeps them\n * where it does not look - and when it could not read the specs it has; only\n * the first prints a document, one with no spec file in it, so that is how\n * the two are told apart. What it said on stderr is the reason for the second.\n */\nexport function readRules(answer: { readonly code: number; readonly document: unknown; readonly stderr: string }): Rules {\n  const document = (answer.document ?? {}) as QueryDocument;\n  if (answer.code !== 0) {\n    if (Array.isArray(document.specFiles) && document.specFiles.length === 0) {\n      return { none: 'no spec file matched its patterns (\"specs\" in its configuration, docs/**/*.md by default)' };\n    }\n    const said = (answer.stderr.trim().split('\\n')[0] ?? '').replace(/^spec-guard:\\s*/, '');\n    return { unavailable: said === '' ? `spec-guard exited ${answer.code}` : `spec-guard exited ${answer.code}: ${said}` };\n  }\n  const seen = new Set<string>();\n  const out: RuleInForce[] = [];\n  for (const result of document.results ?? []) {\n    for (const rule of result.rules ?? []) {\n      const key = `${rule.document}:${rule.line}`;\n      if (rule.inForce === false || seen.has(key)) continue;\n      seen.add(key);\n      out.push({ document: rule.document, line: rule.line, kind: rule.kind, description: rule.description, reason: rule.reason ?? null });\n    }\n  }\n  return out;\n}\n\nexport interface RulingInForce {\n  readonly id: string;\n  readonly paths: readonly string[];\n  readonly signer: string;\n}\n\nexport interface ContextInput {\n  readonly brief: BriefRow;\n  readonly briefText: string;\n  readonly dependencies: readonly BriefRow[];\n  readonly cited: readonly CitedDocument[];\n  /** The rules in force for the scope, none because spec-guard reads no specification, or why they could not be read. */\n  readonly rules: Rules;\n  readonly rulings: readonly RulingInForce[];\n  readonly branch: string | null;\n  readonly base: string | null;\n  readonly budget: number;\n}\n\n/** A pattern in the brief's scope or protections that the guard cannot read, with spec-core's reason. */\nexport interface UnreadablePattern {\n  readonly pattern: string;\n  readonly reason: string;\n}\n\n/** A path of a ruling in force that the guard cannot read, with the ruling's id and spec-core's reason. */\nexport interface UnreadableRulingPath extends UnreadablePattern {\n  readonly ruling: string;\n}\n\nexport interface ContextPacket {\n  readonly markdown: string;\n  /** Cited documents included whole. */\n  readonly included: readonly string[];\n  /** Cited documents named but left out for the budget. */\n  readonly omitted: readonly string[];\n  /** Links in the brief that resolve to nothing. */\n  readonly unresolved: readonly string[];\n  /** Cited documents whose front matter opens on line 1 and is never closed, so no status was read from them. */\n  readonly unclosedFrontMatter: readonly string[];\n  /** Patterns in `affectedFiles` the guard cannot read, in the brief's order: each puts no path in the scope. */\n  readonly unreadableScope: readonly UnreadablePattern[];\n  /** Patterns in `protectedFiles` the guard cannot read, in the brief's order: while one stands, the guard refuses every write but to the brief. */\n  readonly unreadableProtections: readonly UnreadablePattern[];\n  /** Paths of the rulings in force the guard cannot read, in the order the rulings are listed: each allows nothing. */\n  readonly unreadableRulingPaths: readonly UnreadableRulingPath[];\n}\n\nfunction list(items: readonly string[]): string {\n  return items.map((item) => `- \\`${item}\\``).join('\\n');\n}\n\n/**\n * Each pattern a line, as the guard reads it: as written, or with spec-core's\n * reason the guard cannot read it and what the guard does without it. The\n * guard's own compile decides, so the packet and the guard cannot disagree.\n */\nfunction patternLines(patterns: readonly string[], consequence: string): { lines: string[]; unreadable: UnreadablePattern[] } {\n  const unreadable: UnreadablePattern[] = [];\n  const lines = patterns.map((pattern) => {\n    const reason = whyUnreadable(pattern);\n    if (reason === null) return `- \\`${pattern}\\``;\n    unreadable.push({ pattern, reason });\n    return `- \\`${pattern}\\`, which the guard cannot read: ${reason}; ${consequence}`;\n  });\n  return { lines, unreadable };\n}\n\nfunction rulesSection(rules: Rules, scopeUnread: boolean): string {\n  if ('none' in rules) return `spec-guard holds no rule over this scope: ${rules.none}.`;\n  if ('unavailable' in rules) {\n    return `The rules spec-guard holds this code to could not be read: ${rules.unavailable}. Treat every ADR as binding until they can.`;\n  }\n  if (rules.length === 0) {\n    // With no pattern of the scope readable, spec-guard was asked about no\n    // path, so an empty answer is no answer: \"no rule\" would tell the agent\n    // the code it writes is unconstrained.\n    return scopeUnread\n      ? 'The scope could not be read: no pattern in `affectedFiles` can be read, so spec-guard was not asked for the rules over it. Treat every ADR as binding until the scope is fixed.'\n      : 'spec-guard holds no rule over this scope.';\n  }\n  const byDocument = new Map<string, RuleInForce[]>();\n  for (const rule of rules) byDocument.set(rule.document, [...(byDocument.get(rule.document) ?? []), rule]);\n  const parts: string[] = [];\n  for (const [document, found] of byDocument) {\n    parts.push(`### ${document}`, '');\n    for (const rule of found) parts.push(`- line ${rule.line}: ${rule.description}${rule.reason === null ? '' : ` - ${rule.reason}`}`);\n    parts.push('');\n  }\n  return parts.join('\\n').trimEnd();\n}\n\n/**\n * A brief's title without the id it repeats: `012 - Rotate tokens` read as\n * `Rotate tokens`, and the same with an en or an em dash, which `spec-brief\n * new` writes, or with a colon after the id. Only the brief's own id is taken\n * off: `Fix - the login bug` is a title, not an id and a title.\n */\nexport function titleOf(brief: Pick<BriefRow, 'id' | 'title'>): string | null {\n  if (brief.title === null) return null;\n  return brief.title.replace(/^\\s*([^\\s:]+)(?:\\s+[-\\u2013\\u2014]|:)\\s+/, (whole, first: string) => (sameId(first, brief.id) ? '' : whole));\n}\n\n/** Renders the packet, filling the budget with cited documents in the order the brief cites them. */\nexport function renderContext(input: ContextInput): ContextPacket {\n  const { brief } = input;\n  const title = titleOf(brief);\n  const header = [\n    `# Round ${brief.id}${title === null ? '' : `: ${title}`}`,\n    '',\n    [\n      `Status ${brief.status ?? 'unknown'}`,\n      brief.wave === null ? null : `wave ${brief.wave}`,\n      input.branch === null ? null : `branch \\`${input.branch}\\``,\n      input.base === null ? null : `measured from \\`${input.base}\\``,\n    ]\n      .filter((part) => part !== null)\n      .join(' · '),\n    '',\n  ].join('\\n');\n\n  const contract = ['## The contract', '', `\\`${brief.file}\\`, in full:`, '', '````markdown', input.briefText.trimEnd(), '````', ''].join('\\n');\n\n  // The guard passes over a ruling's path it cannot read, so the path allows\n  // nothing. The paths share a line, so the note is in parentheses, closed\n  // before the next path.\n  const unreadableRulingPaths: UnreadableRulingPath[] = [];\n  const rulings =\n    input.rulings.length === 0\n      ? '- none'\n      : input.rulings\n          .map((ruling) => {\n            const paths = ruling.paths.map((pattern) => {\n              const reason = whyUnreadable(pattern);\n              if (reason === null) return `\\`${pattern}\\``;\n              unreadableRulingPaths.push({ ruling: ruling.id, pattern, reason });\n              return `\\`${pattern}\\` (which the guard cannot read: ${reason}; it allows nothing)`;\n            });\n            return `- ${ruling.id}, signed by ${ruling.signer}: ${paths.join(', ')}`;\n          })\n          .join('\\n');\n  const mayWrite = patternLines(brief.affectedFiles, 'it puts no path in the scope');\n  const unreadableScope = mayWrite.unreadable;\n  // While a protection the guard cannot read stands, the guard refuses every\n  // write, and no ruling waives it; a write to the brief is let through,\n  // since that is where it is fixed.\n  const mustNot = patternLines(brief.protectedFiles, 'until it is fixed, the guard refuses every write but to the brief');\n  const unreadableProtections = mustNot.unreadable;\n  const scope = [\n    '## Scope, as the guard reads it',\n    '',\n    'May write:',\n    mayWrite.lines.length === 0 ? '- nothing declared: every write is outside the scope' : mayWrite.lines.join('\\n'),\n    '',\n    'Must not change without a ruling:',\n    mustNot.lines.length === 0 ? '- nothing declared' : mustNot.lines.join('\\n'),\n    '',\n    'Rulings in force:',\n    rulings,\n    '',\n  ].join('\\n');\n\n  const waiting = input.dependencies.map((dependency) => {\n    const state = dependency.phase === 'archived' ? 'archived, done' : `still ${dependency.status ?? 'live'}`;\n    const named = titleOf(dependency);\n    return `- ${dependency.id}${named === null ? '' : ` ${named}`}: ${state}`;\n  });\n  const dependencies = ['## Depends on', '', waiting.length === 0 ? '- nothing' : waiting.join('\\n'), ''].join('\\n');\n\n  const scopeUnread = mayWrite.lines.length > 0 && unreadableScope.length === mayWrite.lines.length;\n  const rules = ['## Rules in force for this scope', '', rulesSection(input.rules, scopeUnread), ''].join('\\n');\n\n  const howTo = [\n    '## How this round works',\n    '',\n    '- Before writing a file, ask whether the round may: `spec-harness guard <path>`, or the `check_path` tool.',\n    '- A protected file is changed only under a ruling a person signs. If the round cannot be done without one, stop and ask: `spec-harness escalate --path <file> --reason <why>`, or the `request_escalation` tool. Do not work around it.',\n    '- Every box in the brief ends ticked, or with a note under it that starts with a disposition (`**Delegated`, `**Accepted debt`, `**Rejected`, or what the repository configures).',\n    '- When the work is done, run `spec-harness audit` and fix what it reports. The archive is a person\\'s decision, not the round\\'s.',\n    '',\n  ].join('\\n');\n\n  const fixed = [header, contract, scope, dependencies, rules, howTo].join('\\n');\n  const included: string[] = [];\n  const omitted: string[] = [];\n  const unresolved: string[] = [];\n  const unclosed: string[] = [];\n  const documents: string[] = [];\n  let used = fixed.length;\n  for (const cited of input.cited) {\n    if (cited.text === null) {\n      unresolved.push(cited.path);\n      continue;\n    }\n    // Named whether or not the budget leaves room for it: the status is\n    // unread either way, and the fix is the same.\n    if (cited.unclosedFrontMatter === true) unclosed.push(cited.path);\n    const heading = `### \\`${cited.path}\\`${cited.title === null ? '' : ` - ${cited.title}`}${cited.status === null ? '' : ` (${cited.status})`}`;\n    const block = [heading, '', '````markdown', cited.text.trimEnd(), '````', ''].join('\\n');\n    if (used + block.length > input.budget) {\n      omitted.push(cited.path);\n      continue;\n    }\n    used += block.length;\n    included.push(cited.path);\n    documents.push(block);\n  }\n  const citedSection = ['## Documents the brief cites', ''];\n  if (documents.length === 0 && omitted.length === 0 && unresolved.length === 0) citedSection.push('None.', '');\n  citedSection.push(...documents);\n  if (omitted.length > 0) {\n    citedSection.push(`Left out to stay within ${input.budget} characters; read them when the work reaches them:`, list(omitted), '');\n  }\n  if (unresolved.length > 0) citedSection.push('Cited but not found in the repository:', list(unresolved), '');\n  if (unclosed.length > 0) {\n    citedSection.push('Front matter opened on line 1 and never closed, so the status was not read; close the block with `---` on a line of its own:', list(unclosed), '');\n  }\n\n  return {\n    markdown: `${fixed}\\n${citedSection.join('\\n').trimEnd()}\\n`,\n    included,\n    omitted,\n    unresolved,\n    unclosedFrontMatter: unclosed,\n    unreadableScope,\n    unreadableProtections,\n    unreadableRulingPaths,\n  };\n}\n"]}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What an agent needs to start a round, and nothing it does not.\n *\n * The brief in full - it is the contract, and a summary of a contract is a\n * different contract. Then what the brief implies but does not say: the scope\n * as the guard will read it, the rulings already signed, the briefs it waits\n * on, the rules spec-guard holds the scope's code to, and the documents the\n * brief cites. The cited documents are the one part that can be large, so\n * they fill what the budget leaves, in the order the brief cites them, and\n * the rest are named rather than dropped silently. So is a document whose\n * front matter is never closed, whose status cannot be read, rather than\n * shown as one without a status, and a pattern in the scope, a protection or\n * a ruling's path the guard cannot read, with spec-core's reason and what the\n * guard does without it, rather than listed as one it can; and one a leading\n * `/` roots, which names no path the guard decides.\n */\n\nimport { sameId } from './branch.js';\nimport { rooted, whyUnreadable } from './guard.js';\nimport type { BriefRow } from './types.js';\n\nexport interface CitedDocument {\n  readonly path: string;\n  readonly title: string | null;\n  readonly status: string | null;\n  /** `null` when the link does not resolve to a readable file. */\n  readonly text: string | null;\n  /** YAML front matter opened on line 1 and never closed, so no status was read from it. */\n  readonly unclosedFrontMatter?: boolean | undefined;\n}\n\nexport interface RuleInForce {\n  readonly document: string;\n  readonly line: number;\n  readonly kind: string;\n  readonly description: string;\n  readonly reason: string | null;\n}\n\n/**\n * The rules in force for the scope; `none` when spec-guard reads no\n * specification here, so none can be in force; `unavailable` when the rules\n * could not be read.\n */\nexport type Rules = readonly RuleInForce[] | { readonly none: string } | { readonly unavailable: string };\n\ninterface QueryDocument {\n  readonly specFiles?: unknown;\n  readonly results?: readonly { readonly rules?: readonly (RuleInForce & { readonly reason?: string | null; readonly inForce?: boolean })[] }[];\n}\n\n/**\n * spec-guard's answer to `query --json`, read. It exits 2 both when no spec\n * file matched its patterns - a repository that keeps none, or keeps them\n * where it does not look - and when it could not read the specs it has; only\n * the first prints a document, one with no spec file in it, so that is how\n * the two are told apart. What it said on stderr is the reason for the second.\n */\nexport function readRules(answer: { readonly code: number; readonly document: unknown; readonly stderr: string }): Rules {\n  const document = (answer.document ?? {}) as QueryDocument;\n  if (answer.code !== 0) {\n    if (Array.isArray(document.specFiles) && document.specFiles.length === 0) {\n      return { none: 'no spec file matched its patterns (\"specs\" in its configuration, docs/**/*.md by default)' };\n    }\n    const said = (answer.stderr.trim().split('\\n')[0] ?? '').replace(/^spec-guard:\\s*/, '');\n    return { unavailable: said === '' ? `spec-guard exited ${answer.code}` : `spec-guard exited ${answer.code}: ${said}` };\n  }\n  const seen = new Set<string>();\n  const out: RuleInForce[] = [];\n  for (const result of document.results ?? []) {\n    for (const rule of result.rules ?? []) {\n      const key = `${rule.document}:${rule.line}`;\n      if (rule.inForce === false || seen.has(key)) continue;\n      seen.add(key);\n      out.push({ document: rule.document, line: rule.line, kind: rule.kind, description: rule.description, reason: rule.reason ?? null });\n    }\n  }\n  return out;\n}\n\nexport interface RulingInForce {\n  readonly id: string;\n  readonly paths: readonly string[];\n  readonly signer: string;\n}\n\nexport interface ContextInput {\n  readonly brief: BriefRow;\n  readonly briefText: string;\n  readonly dependencies: readonly BriefRow[];\n  readonly cited: readonly CitedDocument[];\n  /** The rules in force for the scope, none because spec-guard reads no specification, or why they could not be read. */\n  readonly rules: Rules;\n  readonly rulings: readonly RulingInForce[];\n  readonly branch: string | null;\n  readonly base: string | null;\n  readonly budget: number;\n}\n\n/** A pattern in the brief's scope or protections that the guard cannot read, with spec-core's reason. */\nexport interface UnreadablePattern {\n  readonly pattern: string;\n  readonly reason: string;\n}\n\n/** A path of a ruling in force that the guard cannot read, with the ruling's id and spec-core's reason. */\nexport interface UnreadableRulingPath extends UnreadablePattern {\n  readonly ruling: string;\n}\n\nexport interface ContextPacket {\n  readonly markdown: string;\n  /** Cited documents included whole. */\n  readonly included: readonly string[];\n  /** Cited documents named but left out for the budget. */\n  readonly omitted: readonly string[];\n  /** Links in the brief that resolve to nothing. */\n  readonly unresolved: readonly string[];\n  /** Cited documents whose front matter opens on line 1 and is never closed, so no status was read from them. */\n  readonly unclosedFrontMatter: readonly string[];\n  /** Patterns in `affectedFiles` the guard cannot read, in the brief's order: each puts no path in the scope. */\n  readonly unreadableScope: readonly UnreadablePattern[];\n  /** Patterns in `protectedFiles` the guard cannot read, in the brief's order: while one stands, the guard refuses every write but to the brief. */\n  readonly unreadableProtections: readonly UnreadablePattern[];\n  /** Paths of the rulings in force the guard cannot read, in the order the rulings are listed: each allows nothing. */\n  readonly unreadableRulingPaths: readonly UnreadableRulingPath[];\n}\n\nfunction list(items: readonly string[]): string {\n  return items.map((item) => `- \\`${item}\\``).join('\\n');\n}\n\n/**\n * Each pattern a line, as the guard reads it: as written, or with spec-core's\n * reason the guard cannot read it and what the guard does without it. The\n * guard's own compile decides, so the packet and the guard cannot disagree.\n * With `rootedNote`, a pattern a leading `/` roots, or one of whose\n * alternatives it roots, is marked too, and counted when every alternative\n * is rooted.\n */\nfunction patternLines(\n  patterns: readonly string[],\n  consequence: string,\n  rootedNote?: { readonly whole: string; readonly part: string },\n): { lines: string[]; unreadable: UnreadablePattern[]; rootedWhole: number } {\n  const unreadable: UnreadablePattern[] = [];\n  let rootedWhole = 0;\n  const lines = patterns.map((pattern) => {\n    const reason = whyUnreadable(pattern);\n    if (reason === null) {\n      const root = rootedNote === undefined ? null : rooted(pattern);\n      if (root === null) return `- \\`${pattern}\\``;\n      if (root === 'whole') rootedWhole += 1;\n      return `- \\`${pattern}\\`, ${(rootedNote as { whole: string; part: string })[root]}`;\n    }\n    unreadable.push({ pattern, reason });\n    return `- \\`${pattern}\\`, which the guard cannot read: ${reason}; ${consequence}`;\n  });\n  return { lines, unreadable, rootedWhole };\n}\n\nfunction rulesSection(rules: Rules, scopeUnread: boolean, scopeRooted: boolean): string {\n  if ('none' in rules) return `spec-guard holds no rule over this scope: ${rules.none}.`;\n  if ('unavailable' in rules) {\n    return `The rules spec-guard holds this code to could not be read: ${rules.unavailable}. Treat every ADR as binding until they can.`;\n  }\n  if (rules.length === 0) {\n    // With no pattern of the scope readable, spec-guard was asked about no\n    // path, so an empty answer is no answer: \"no rule\" would tell the agent\n    // the code it writes is unconstrained.\n    if (scopeUnread) {\n      return 'The scope could not be read: no pattern in `affectedFiles` can be read, so spec-guard was not asked for the rules over it. Treat every ADR as binding until the scope is fixed.';\n    }\n    return scopeRooted\n      ? \"No pattern in `affectedFiles` puts a path in the scope: each is rooted at the filesystem's root or cannot be read, so spec-guard was not asked for the rules over it. Treat every ADR as binding until the scope is fixed.\"\n      : 'spec-guard holds no rule over this scope.';\n  }\n  const byDocument = new Map<string, RuleInForce[]>();\n  for (const rule of rules) byDocument.set(rule.document, [...(byDocument.get(rule.document) ?? []), rule]);\n  const parts: string[] = [];\n  for (const [document, found] of byDocument) {\n    parts.push(`### ${document}`, '');\n    for (const rule of found) parts.push(`- line ${rule.line}: ${rule.description}${rule.reason === null ? '' : ` - ${rule.reason}`}`);\n    parts.push('');\n  }\n  return parts.join('\\n').trimEnd();\n}\n\n/**\n * A brief's title without the id it repeats, by the rules spec-brief reads\n * it with: the brief's own id, then an em dash, which `spec-brief new`\n * writes, an en dash, a full-width colon or a colon, spaced or not, or a\n * hyphen with a space on each side; `012 - Rotate tokens`, `012\\u2014Rotate\n * tokens` and `012\\uFF1ARotate tokens` read as `Rotate tokens`. A bare hyphen\n * is part of a word or a number, as in `001-2 migration`, and only the\n * brief's own id is taken off: `Fix - the login bug` is a title, and so is\n * `0010 \\u2014 x` on brief 001.\n */\nexport function titleOf(brief: Pick<BriefRow, 'id' | 'title'>): string | null {\n  if (brief.title === null) return null;\n  return brief.title.replace(/^\\s*([^\\s:\\uFF1A\\u2013\\u2014]+)(?:\\s*[:\\uFF1A\\u2013\\u2014]\\s*|\\s+-\\s+)(?=\\S)/, (whole, first: string) =>\n    sameId(first, brief.id) ? '' : whole,\n  );\n}\n\n/** Renders the packet, filling the budget with cited documents in the order the brief cites them. */\nexport function renderContext(input: ContextInput): ContextPacket {\n  const { brief } = input;\n  const title = titleOf(brief);\n  const header = [\n    `# Round ${brief.id}${title === null ? '' : `: ${title}`}`,\n    '',\n    [\n      `Status ${brief.status ?? 'unknown'}`,\n      brief.wave === null ? null : `wave ${brief.wave}`,\n      input.branch === null ? null : `branch \\`${input.branch}\\``,\n      input.base === null ? null : `measured from \\`${input.base}\\``,\n    ]\n      .filter((part) => part !== null)\n      .join(' · '),\n    '',\n  ].join('\\n');\n\n  const contract = ['## The contract', '', `\\`${brief.file}\\`, in full:`, '', '````markdown', input.briefText.trimEnd(), '````', ''].join('\\n');\n\n  // The guard passes over a ruling's path it cannot read, so the path allows\n  // nothing. The paths share a line, so the note is in parentheses, closed\n  // before the next path.\n  const unreadableRulingPaths: UnreadableRulingPath[] = [];\n  const rulings =\n    input.rulings.length === 0\n      ? '- none'\n      : input.rulings\n          .map((ruling) => {\n            const paths = ruling.paths.map((pattern) => {\n              const reason = whyUnreadable(pattern);\n              if (reason === null) {\n                // A rooted path can be read, and names no path the guard decides.\n                const root = rooted(pattern);\n                if (root === 'whole') return `\\`${pattern}\\` (which a leading \\`/\\` roots at the filesystem's root; it allows nothing)`;\n                if (root === 'part') return `\\`${pattern}\\` (an alternative of which a leading \\`/\\` roots at the filesystem's root; that alternative allows nothing)`;\n                return `\\`${pattern}\\``;\n              }\n              unreadableRulingPaths.push({ ruling: ruling.id, pattern, reason });\n              return `\\`${pattern}\\` (which the guard cannot read: ${reason}; it allows nothing)`;\n            });\n            return `- ${ruling.id}, signed by ${ruling.signer}: ${paths.join(', ')}`;\n          })\n          .join('\\n');\n  // A rooted pattern can be read and puts no path in the scope: every path\n  // the guard decides is repository-relative. spec-guard is not asked about it.\n  const mayWrite = patternLines(brief.affectedFiles, 'it puts no path in the scope', {\n    whole: \"which a leading `/` roots at the filesystem's root: it puts no path in the scope, and spec-guard is not asked about it\",\n    part: \"an alternative of which a leading `/` roots at the filesystem's root: that alternative puts no path in the scope, and spec-guard is not asked about it\",\n  });\n  const unreadableScope = mayWrite.unreadable;\n  // While a protection the guard cannot read stands, the guard refuses every\n  // write, and no ruling waives it; a write to the brief is let through,\n  // since that is where it is fixed. A rooted protection can be read, and\n  // protects nothing: the file it was meant to protect is the round's to write.\n  const mustNot = patternLines(brief.protectedFiles, 'until it is fixed, the guard refuses every write but to the brief', {\n    whole: \"which a leading `/` roots at the filesystem's root: it protects no path\",\n    part: \"an alternative of which a leading `/` roots at the filesystem's root: that alternative protects no path\",\n  });\n  const unreadableProtections = mustNot.unreadable;\n  const scope = [\n    '## Scope, as the guard reads it',\n    '',\n    'May write:',\n    mayWrite.lines.length === 0 ? '- nothing declared: every write is outside the scope' : mayWrite.lines.join('\\n'),\n    '',\n    'Must not change without a ruling:',\n    mustNot.lines.length === 0 ? '- nothing declared' : mustNot.lines.join('\\n'),\n    '',\n    'Rulings in force:',\n    rulings,\n    '',\n  ].join('\\n');\n\n  const waiting = input.dependencies.map((dependency) => {\n    const state = dependency.phase === 'archived' ? 'archived, done' : `still ${dependency.status ?? 'live'}`;\n    const named = titleOf(dependency);\n    return `- ${dependency.id}${named === null ? '' : ` ${named}`}: ${state}`;\n  });\n  const dependencies = ['## Depends on', '', waiting.length === 0 ? '- nothing' : waiting.join('\\n'), ''].join('\\n');\n\n  const scopeUnread = mayWrite.lines.length > 0 && unreadableScope.length === mayWrite.lines.length;\n  const scopeRooted = mayWrite.rootedWhole > 0 && unreadableScope.length + mayWrite.rootedWhole === mayWrite.lines.length;\n  const rules = ['## Rules in force for this scope', '', rulesSection(input.rules, scopeUnread, scopeRooted), ''].join('\\n');\n\n  const howTo = [\n    '## How this round works',\n    '',\n    '- Before writing a file, ask whether the round may: `spec-harness guard <path>`, or the `check_path` tool.',\n    '- A protected file is changed only under a ruling a person signs. If the round cannot be done without one, stop and ask: `spec-harness escalate --path <file> --reason <why>`, or the `request_escalation` tool. Do not work around it.',\n    '- Every box in the brief ends ticked, or with a note under it that starts with a disposition (`**Delegated`, `**Accepted debt`, `**Rejected`, or what the repository configures).',\n    '- When the work is done, run `spec-harness audit` and fix what it reports. The archive is a person\\'s decision, not the round\\'s.',\n    '',\n  ].join('\\n');\n\n  const fixed = [header, contract, scope, dependencies, rules, howTo].join('\\n');\n  const included: string[] = [];\n  const omitted: string[] = [];\n  const unresolved: string[] = [];\n  const unclosed: string[] = [];\n  const documents: string[] = [];\n  let used = fixed.length;\n  for (const cited of input.cited) {\n    if (cited.text === null) {\n      unresolved.push(cited.path);\n      continue;\n    }\n    // Named whether or not the budget leaves room for it: the status is\n    // unread either way, and the fix is the same.\n    if (cited.unclosedFrontMatter === true) unclosed.push(cited.path);\n    const heading = `### \\`${cited.path}\\`${cited.title === null ? '' : ` - ${cited.title}`}${cited.status === null ? '' : ` (${cited.status})`}`;\n    const block = [heading, '', '````markdown', cited.text.trimEnd(), '````', ''].join('\\n');\n    if (used + block.length > input.budget) {\n      omitted.push(cited.path);\n      continue;\n    }\n    used += block.length;\n    included.push(cited.path);\n    documents.push(block);\n  }\n  const citedSection = ['## Documents the brief cites', ''];\n  if (documents.length === 0 && omitted.length === 0 && unresolved.length === 0) citedSection.push('None.', '');\n  citedSection.push(...documents);\n  if (omitted.length > 0) {\n    citedSection.push(`Left out to stay within ${input.budget} characters; read them when the work reaches them:`, list(omitted), '');\n  }\n  if (unresolved.length > 0) citedSection.push('Cited but not found in the repository:', list(unresolved), '');\n  if (unclosed.length > 0) {\n    citedSection.push('Front matter opened on line 1 and never closed, so the status was not read; close the block with `---` on a line of its own:', list(unclosed), '');\n  }\n\n  return {\n    markdown: `${fixed}\\n${citedSection.join('\\n').trimEnd()}\\n`,\n    included,\n    omitted,\n    unresolved,\n    unclosedFrontMatter: unclosed,\n    unreadableScope,\n    unreadableProtections,\n    unreadableRulingPaths,\n  };\n}\n"]}

package/dist/document.d.ts

@@ -27,7 +27,8 @@ export interface DocumentReader {
     sectionTables(text: string, section: string): SectionTables;
     citations(text: string): Citation[];
     /**
-     * The first level-one heading, and the front matter's status. YAML front
+     * The first level-one heading, and the front matter's status, under
+     * `status`, `狀態` or `状态`, the first the document holds. YAML front
      * matter opened on line 1 and never closed is `unclosedFrontMatter`: none
      * of it is read, so a status its author wrote there reads as none.
      */

package/dist/document.js.map

@@ -1 +1 @@
-{"version":3,"file":"document.js","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG","sourcesContent":["/**\n * What the harness reads out of a brief or a cited document, through\n * spec-core's Markdown scanner so that code and comments are never mistaken\n * for structure: fenced blocks with their info strings, the section a line\n * sits in, a section's tables, the relative links a document cites, and a\n * document's title and status.\n */\n\nimport type { CodeBlock } from './probe.js';\nimport type { TableView } from './rulings.js';\n\nexport interface Citation {\n  readonly target: string;\n  /** 1-based. */\n  readonly line: number;\n}\n\nexport interface SectionTables {\n  readonly tables: readonly TableView[];\n  /** 1-based line of the section's heading, or `null` when there is no such section. */\n  readonly headingLine: number | null;\n  /** 0-based index of the line after the section's last table row, or `null` when it has no table. */\n  readonly tableEndLine: number | null;\n}\n\nexport interface DocumentReader {\n  codeBlocks(text: string): CodeBlock[];\n  sectionAt(text: string, line: number): string | null;\n  /** Every section a line sits in, outermost first: a `###` under a `##` is in both. */\n  sectionsAt(text: string, line: number): string[];\n  sectionTables(text: string, section: string): SectionTables;\n  citations(text: string): Citation[];\n  /**\n   * The first level-one heading, and the front matter's status. YAML front\n   * matter opened on line 1 and never closed is `unclosedFrontMatter`: none\n   * of it is read, so a status its author wrote there reads as none.\n   */\n  titleAndStatus(text: string): { readonly title: string | null; readonly status: string | null; readonly unclosedFrontMatter: boolean };\n}\n"]}
+{"version":3,"file":"document.js","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG","sourcesContent":["/**\n * What the harness reads out of a brief or a cited document, through\n * spec-core's Markdown scanner so that code and comments are never mistaken\n * for structure: fenced blocks with their info strings, the section a line\n * sits in, a section's tables, the relative links a document cites, and a\n * document's title and status.\n */\n\nimport type { CodeBlock } from './probe.js';\nimport type { TableView } from './rulings.js';\n\nexport interface Citation {\n  readonly target: string;\n  /** 1-based. */\n  readonly line: number;\n}\n\nexport interface SectionTables {\n  readonly tables: readonly TableView[];\n  /** 1-based line of the section's heading, or `null` when there is no such section. */\n  readonly headingLine: number | null;\n  /** 0-based index of the line after the section's last table row, or `null` when it has no table. */\n  readonly tableEndLine: number | null;\n}\n\nexport interface DocumentReader {\n  codeBlocks(text: string): CodeBlock[];\n  sectionAt(text: string, line: number): string | null;\n  /** Every section a line sits in, outermost first: a `###` under a `##` is in both. */\n  sectionsAt(text: string, line: number): string[];\n  sectionTables(text: string, section: string): SectionTables;\n  citations(text: string): Citation[];\n  /**\n   * The first level-one heading, and the front matter's status, under\n   * `status`, `狀態` or `状态`, the first the document holds. YAML front\n   * matter opened on line 1 and never closed is `unclosedFrontMatter`: none\n   * of it is read, so a status its author wrote there reads as none.\n   */\n  titleAndStatus(text: string): { readonly title: string | null; readonly status: string | null; readonly unclosedFrontMatter: boolean };\n}\n"]}

package/dist/formats.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Findings in the formats a forge reads beside a change: GitLab Code Quality,
+ * SARIF 2.1.0 and GitHub workflow commands (spec-core ADR-0005).
+ *
+ * The shapes are the siblings': spec-brief's severities and its hint in the
+ * text, spec-guard's fingerprint of a finding's identity. Pure: the command
+ * prints what these return.
+ */
+import type { Finding } from './types.js';
+/** The formats that place findings, which `audit` and `premises` print. */
+export type FindingFormat = 'gitlab' | 'sarif' | 'github';
+export declare const FINDING_FORMATS: readonly FindingFormat[];
+export interface FormatOptions {
+    /** Where a finding with no file of its own is placed: the brief the command is about. */
+    readonly file: string;
+    /** This tool's version, which SARIF names. */
+    readonly version: string;
+    /** What the run measured, which SARIF carries as a note beside its results. */
+    readonly summary?: string | undefined;
+}
+/** GitLab Code Quality: a JSON array of issues, which a merge request shows beside the lines they are on. */
+export declare function formatGitlab(findings: readonly Finding[], options: FormatOptions): string;
+/**
+ * SARIF 2.1.0, for code scanning. What the run measured is a note in the
+ * invocation, SARIF's place for what happened in a run that is not a finding,
+ * so a page with no result still says what was checked.
+ */
+export declare function formatSarif(findings: readonly Finding[], options: FormatOptions): string;
+/** GitHub Actions workflow commands, one line each, which a job's log turns into annotations on the diff. */
+export declare function formatGithub(findings: readonly Finding[], options: FormatOptions): string;
+export declare function formatFindings(format: FindingFormat, findings: readonly Finding[], options: FormatOptions): string;

package/dist/formats.js

@@ -0,0 +1,127 @@
+/**
+ * Findings in the formats a forge reads beside a change: GitLab Code Quality,
+ * SARIF 2.1.0 and GitHub workflow commands (spec-core ADR-0005).
+ *
+ * The shapes are the siblings': spec-brief's severities and its hint in the
+ * text, spec-guard's fingerprint of a finding's identity. Pure: the command
+ * prints what these return.
+ */
+import { createHash } from 'node:crypto';
+import { RULES } from './audit.js';
+export const FINDING_FORMATS = ['gitlab', 'sarif', 'github'];
+/**
+ * GitLab's severities. An error fails the run, but it is not the crash or the
+ * security hole `critical` and `blocker` say in GitLab's own reports, so the
+ * scale tops out at `major`, as spec-brief's does.
+ */
+const GITLAB_SEVERITY = { error: 'major', warning: 'minor', note: 'info' };
+const SARIF_LEVEL = { error: 'error', warning: 'warning', note: 'note' };
+const GITHUB_COMMAND = { error: 'error', warning: 'warning', note: 'notice' };
+/**
+ * Each finding with its place and its fingerprint. A finding about a whole
+ * brief is placed on the brief's first line. The fingerprint is the SHA-256
+ * of the finding's identity - its rule, its file and its subject - and never
+ * of its message, hint or line: GitLab tells a new finding from one it has
+ * seen by it, so a reworded message or a line added above must not read as
+ * one problem fixed and another found. Two findings with one identity are
+ * told apart by the order they come in.
+ */
+function place(findings, fallback) {
+    const seen = new Map();
+    return findings.map((finding) => {
+        const file = finding.file ?? fallback;
+        const identity = [finding.rule, file, finding.subject ?? ''].join('\u0000');
+        const repeat = seen.get(identity) ?? 0;
+        seen.set(identity, repeat + 1);
+        const fingerprint = createHash('sha256').update(repeat === 0 ? identity : `${identity}\u0000${repeat}`).digest('hex');
+        return { finding, file, line: Math.max(finding.line ?? 1, 1), fingerprint };
+    });
+}
+/**
+ * The message and the next action, which every format carries (spec-core
+ * ADR-0005). A message a sibling ended with a full stop keeps one.
+ */
+function text(finding) {
+    return `${finding.message.replace(/\.$/, '')}. ${finding.hint}`;
+}
+/** GitLab Code Quality: a JSON array of issues, which a merge request shows beside the lines they are on. */
+export function formatGitlab(findings, options) {
+    const issues = place(findings, options.file).map(({ finding, file, line, fingerprint }) => ({
+        description: text(finding),
+        check_name: finding.rule,
+        fingerprint,
+        severity: GITLAB_SEVERITY[finding.severity],
+        location: { path: file, lines: { begin: line } },
+    }));
+    return `${JSON.stringify(issues, null, 2)}\n`;
+}
+/** How SARIF describes a rule: the audit's own words, or the archive rule spec-brief gave. */
+function describeRule(id) {
+    if (id.startsWith('archive/'))
+        return `A reason spec-brief's archive gives: ${id.slice('archive/'.length)}.`;
+    return RULES[id] ?? id;
+}
+/**
+ * SARIF 2.1.0, for code scanning. What the run measured is a note in the
+ * invocation, SARIF's place for what happened in a run that is not a finding,
+ * so a page with no result still says what was checked.
+ */
+export function formatSarif(findings, options) {
+    const placed = place(findings, options.file);
+    const ids = [...new Set(findings.map((finding) => finding.rule))].sort();
+    const document = {
+        $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+        version: '2.1.0',
+        runs: [
+            {
+                ...(options.summary === undefined
+                    ? {}
+                    : { invocations: [{ executionSuccessful: true, toolExecutionNotifications: [{ level: 'note', message: { text: options.summary } }] }] }),
+                tool: {
+                    driver: {
+                        name: 'spec-harness',
+                        version: options.version,
+                        informationUri: 'https://github.com/DescentVTT/spec-harness',
+                        rules: ids.map((id) => ({ id, shortDescription: { text: describeRule(id) } })),
+                    },
+                },
+                results: placed.map(({ finding, file, line, fingerprint }) => ({
+                    ruleId: finding.rule,
+                    level: SARIF_LEVEL[finding.severity],
+                    message: { text: text(finding) },
+                    locations: [{ physicalLocation: { artifactLocation: { uri: file, uriBaseId: '%SRCROOT%' }, region: { startLine: line } } }],
+                    partialFingerprints: { specHarnessFinding: fingerprint },
+                })),
+            },
+        ],
+    };
+    return `${JSON.stringify(document, null, 2)}\n`;
+}
+/** A workflow command's message: `%`, and the line breaks that would end the command. */
+function escapeData(value) {
+    return value.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
+}
+/** A workflow command's property: as a message, and the `:` and `,` that would end the property. */
+function escapeProperty(value) {
+    return escapeData(value).replace(/:/g, '%3A').replace(/,/g, '%2C');
+}
+/** GitHub Actions workflow commands, one line each, which a job's log turns into annotations on the diff. */
+export function formatGithub(findings, options) {
+    return place(findings, options.file)
+        .map(({ finding, file, line }) => {
+        const properties = `file=${escapeProperty(file)},line=${line},title=${escapeProperty(`spec-harness ${finding.rule}`)}`;
+        return `::${GITHUB_COMMAND[finding.severity]} ${properties}::${escapeData(text(finding))}\n`;
+    })
+        .join('');
+}
+export function formatFindings(format, findings, options) {
+    switch (format) {
+        case 'gitlab':
+            return formatGitlab(findings, options);
+        case 'sarif':
+            return formatSarif(findings, options);
+        case 'github':
+            return formatGithub(findings, options);
+    }
+}
+//# sourceMappingURL=formats.js.map

package/dist/formats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formats.js","sourceRoot":"","sources":["../src/formats.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Findings in the formats a forge reads beside a change: GitLab Code Quality,\n * SARIF 2.1.0 and GitHub workflow commands (spec-core ADR-0005).\n *\n * The shapes are the siblings': spec-brief's severities and its hint in the\n * text, spec-guard's fingerprint of a finding's identity. Pure: the command\n * prints what these return.\n */\n\nimport { createHash } from 'node:crypto';\n\nimport { RULES } from './audit.js';\nimport type { Finding, Severity } from './types.js';\n\n/** The formats that place findings, which `audit` and `premises` print. */\nexport type FindingFormat = 'gitlab' | 'sarif' | 'github';\n\nexport const FINDING_FORMATS: readonly FindingFormat[] = ['gitlab', 'sarif', 'github'];\n\nexport interface FormatOptions {\n  /** Where a finding with no file of its own is placed: the brief the command is about. */\n  readonly file: string;\n  /** This tool's version, which SARIF names. */\n  readonly version: string;\n  /** What the run measured, which SARIF carries as a note beside its results. */\n  readonly summary?: string | undefined;\n}\n\n/**\n * GitLab's severities. An error fails the run, but it is not the crash or the\n * security hole `critical` and `blocker` say in GitLab's own reports, so the\n * scale tops out at `major`, as spec-brief's does.\n */\nconst GITLAB_SEVERITY: Readonly<Record<Severity, string>> = { error: 'major', warning: 'minor', note: 'info' };\nconst SARIF_LEVEL: Readonly<Record<Severity, string>> = { error: 'error', warning: 'warning', note: 'note' };\nconst GITHUB_COMMAND: Readonly<Record<Severity, string>> = { error: 'error', warning: 'warning', note: 'notice' };\n\ninterface Placed {\n  readonly finding: Finding;\n  readonly file: string;\n  readonly line: number;\n  readonly fingerprint: string;\n}\n\n/**\n * Each finding with its place and its fingerprint. A finding about a whole\n * brief is placed on the brief's first line. The fingerprint is the SHA-256\n * of the finding's identity - its rule, its file and its subject - and never\n * of its message, hint or line: GitLab tells a new finding from one it has\n * seen by it, so a reworded message or a line added above must not read as\n * one problem fixed and another found. Two findings with one identity are\n * told apart by the order they come in.\n */\nfunction place(findings: readonly Finding[], fallback: string): Placed[] {\n  const seen = new Map<string, number>();\n  return findings.map((finding) => {\n    const file = finding.file ?? fallback;\n    const identity = [finding.rule, file, finding.subject ?? ''].join('\\u0000');\n    const repeat = seen.get(identity) ?? 0;\n    seen.set(identity, repeat + 1);\n    const fingerprint = createHash('sha256').update(repeat === 0 ? identity : `${identity}\\u0000${repeat}`).digest('hex');\n    return { finding, file, line: Math.max(finding.line ?? 1, 1), fingerprint };\n  });\n}\n\n/**\n * The message and the next action, which every format carries (spec-core\n * ADR-0005). A message a sibling ended with a full stop keeps one.\n */\nfunction text(finding: Finding): string {\n  return `${finding.message.replace(/\\.$/, '')}. ${finding.hint}`;\n}\n\n/** GitLab Code Quality: a JSON array of issues, which a merge request shows beside the lines they are on. */\nexport function formatGitlab(findings: readonly Finding[], options: FormatOptions): string {\n  const issues = place(findings, options.file).map(({ finding, file, line, fingerprint }) => ({\n    description: text(finding),\n    check_name: finding.rule,\n    fingerprint,\n    severity: GITLAB_SEVERITY[finding.severity],\n    location: { path: file, lines: { begin: line } },\n  }));\n  return `${JSON.stringify(issues, null, 2)}\\n`;\n}\n\n/** How SARIF describes a rule: the audit's own words, or the archive rule spec-brief gave. */\nfunction describeRule(id: string): string {\n  if (id.startsWith('archive/')) return `A reason spec-brief's archive gives: ${id.slice('archive/'.length)}.`;\n  return RULES[id] ?? id;\n}\n\n/**\n * SARIF 2.1.0, for code scanning. What the run measured is a note in the\n * invocation, SARIF's place for what happened in a run that is not a finding,\n * so a page with no result still says what was checked.\n */\nexport function formatSarif(findings: readonly Finding[], options: FormatOptions): string {\n  const placed = place(findings, options.file);\n  const ids = [...new Set(findings.map((finding) => finding.rule))].sort();\n  const document = {\n    $schema: 'https://json.schemastore.org/sarif-2.1.0.json',\n    version: '2.1.0',\n    runs: [\n      {\n        ...(options.summary === undefined\n          ? {}\n          : { invocations: [{ executionSuccessful: true, toolExecutionNotifications: [{ level: 'note', message: { text: options.summary } }] }] }),\n        tool: {\n          driver: {\n            name: 'spec-harness',\n            version: options.version,\n            informationUri: 'https://github.com/DescentVTT/spec-harness',\n            rules: ids.map((id) => ({ id, shortDescription: { text: describeRule(id) } })),\n          },\n        },\n        results: placed.map(({ finding, file, line, fingerprint }) => ({\n          ruleId: finding.rule,\n          level: SARIF_LEVEL[finding.severity],\n          message: { text: text(finding) },\n          locations: [{ physicalLocation: { artifactLocation: { uri: file, uriBaseId: '%SRCROOT%' }, region: { startLine: line } } }],\n          partialFingerprints: { specHarnessFinding: fingerprint },\n        })),\n      },\n    ],\n  };\n  return `${JSON.stringify(document, null, 2)}\\n`;\n}\n\n/** A workflow command's message: `%`, and the line breaks that would end the command. */\nfunction escapeData(value: string): string {\n  return value.replace(/%/g, '%25').replace(/\\r/g, '%0D').replace(/\\n/g, '%0A');\n}\n\n/** A workflow command's property: as a message, and the `:` and `,` that would end the property. */\nfunction escapeProperty(value: string): string {\n  return escapeData(value).replace(/:/g, '%3A').replace(/,/g, '%2C');\n}\n\n/** GitHub Actions workflow commands, one line each, which a job's log turns into annotations on the diff. */\nexport function formatGithub(findings: readonly Finding[], options: FormatOptions): string {\n  return place(findings, options.file)\n    .map(({ finding, file, line }) => {\n      const properties = `file=${escapeProperty(file)},line=${line},title=${escapeProperty(`spec-harness ${finding.rule}`)}`;\n      return `::${GITHUB_COMMAND[finding.severity]} ${properties}::${escapeData(text(finding))}\\n`;\n    })\n    .join('');\n}\n\nexport function formatFindings(format: FindingFormat, findings: readonly Finding[], options: FormatOptions): string {\n  switch (format) {\n    case 'gitlab':\n      return formatGitlab(findings, options);\n    case 'sarif':\n      return formatSarif(findings, options);\n    case 'github':\n      return formatGithub(findings, options);\n  }\n}\n"]}

package/dist/git.d.ts

@@ -21,6 +21,12 @@ export declare class GitError extends Error {
 export declare function workTreeRoot(cwd: string): Promise<string | null>;
 /** The git directory every worktree of this repository shares. */
 export declare function commonDirectory(cwd: string): Promise<string | null>;
+/**
+ * Where git runs the hook `name` from, absolute: `core.hooksPath` read as git
+ * reads it - relative to the work tree, absolute, or under `~` - and a linked
+ * worktree's shared hooks. `null` when git cannot say, before 2.31.
+ */
+export declare function hookPath(name: string, cwd: string): Promise<string | null>;
 /** The checked-out branch's short name, or `null` on a detached head. */
 export declare function currentBranch(cwd: string): Promise<string | null>;
 /** The remote's default branch as a local ref, such as `origin/main`, or `null`. */

package/dist/git.js

@@ -36,6 +36,14 @@ export async function workTreeRoot(cwd) {
 export async function commonDirectory(cwd) {
     return value(['rev-parse', '--path-format=absolute', '--git-common-dir'], cwd);
 }
+/**
+ * Where git runs the hook `name` from, absolute: `core.hooksPath` read as git
+ * reads it - relative to the work tree, absolute, or under `~` - and a linked
+ * worktree's shared hooks. `null` when git cannot say, before 2.31.
+ */
+export async function hookPath(name, cwd) {
+    return value(['rev-parse', '--path-format=absolute', '--git-path', `hooks/${name}`], cwd);
+}
 /** The checked-out branch's short name, or `null` on a detached head. */
 export async function currentBranch(cwd) {
     return value(['symbolic-ref', '--quiet', '--short', 'HEAD'], cwd);

package/dist/git.js.map

@@ -1 +1 @@
-{"version":3,"file":"git.js","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The edge where the harness meets git.\n *\n * Reads, except for two things ADR-0003 allows and bounds: a temporary\n * worktree, added and always removed by the sandbox, and nothing else. Every\n * call is an argument vector, never a shell string, so a path or a ref cannot\n * become a command.\n */\n\nimport { execFile } from 'node:child_process';\n\nimport type { FileChange } from './types.js';\n\nexport interface Run {\n  readonly code: number;\n  readonly stdout: string;\n  readonly stderr: string;\n}\n\n/** Runs git and answers whatever it answered; a missing git is a code of -1. */\nexport function git(args: readonly string[], cwd: string, input?: string): Promise<Run> {\n  return new Promise((resolve) => {\n    const child = execFile(\n      'git',\n      [...args],\n      { cwd, maxBuffer: 256 * 1024 * 1024, encoding: 'utf8', windowsHide: true },\n      (error, stdout, stderr) => {\n        const code = error === null ? 0 : typeof (error as { code?: unknown }).code === 'number' ? ((error as { code: number }).code) : -1;\n        resolve({ code, stdout, stderr });\n      },\n    );\n    if (input !== undefined) child.stdin?.end(input);\n  });\n}\n\nasync function value(args: readonly string[], cwd: string): Promise<string | null> {\n  const run = await git(args, cwd);\n  return run.code === 0 ? run.stdout.trim() : null;\n}\n\nexport class GitError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'GitError';\n  }\n}\n\n/** The top of the work tree holding `cwd`, POSIX-separated, or `null` outside one. */\nexport async function workTreeRoot(cwd: string): Promise<string | null> {\n  return value(['rev-parse', '--show-toplevel'], cwd);\n}\n\n/** The git directory every worktree of this repository shares. */\nexport async function commonDirectory(cwd: string): Promise<string | null> {\n  return value(['rev-parse', '--path-format=absolute', '--git-common-dir'], cwd);\n}\n\n/** The checked-out branch's short name, or `null` on a detached head. */\nexport async function currentBranch(cwd: string): Promise<string | null> {\n  return value(['symbolic-ref', '--quiet', '--short', 'HEAD'], cwd);\n}\n\n/** The remote's default branch as a local ref, such as `origin/main`, or `null`. */\nexport async function remoteDefault(cwd: string): Promise<string | null> {\n  return value(['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], cwd);\n}\n\n/** Every local branch, by its short name. */\nexport async function localBranches(cwd: string): Promise<string[]> {\n  const listed = await value(['for-each-ref', '--format=%(refname:short)', 'refs/heads/'], cwd);\n  return listed === null || listed === '' ? [] : listed.split('\\n').map((name) => name.trim());\n}\n\nexport async function revision(ref: string, cwd: string): Promise<string | null> {\n  return value(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], cwd);\n}\n\nexport async function mergeBase(a: string, b: string, cwd: string): Promise<string | null> {\n  return value(['merge-base', a, b], cwd);\n}\n\n/** Parses `git diff --name-status -z` output. */\nexport function parseNameStatus(output: string): FileChange[] {\n  const fields = output.split('\\0');\n  const out: FileChange[] = [];\n  for (let i = 0; i < fields.length; ) {\n    const code = fields[i] ?? '';\n    if (code === '') {\n      i += 1;\n      continue;\n    }\n    const status = code.charAt(0) as FileChange['status'];\n    if (status === 'R' || status === 'C') {\n      out.push({ status, from: fields[i + 1] ?? '', path: fields[i + 2] ?? '' });\n      i += 3;\n    } else {\n      out.push({ status, path: fields[i + 1] ?? '' });\n      i += 2;\n    }\n  }\n  return out;\n}\n\n/** The files changed from one revision to another, renames found. */\nexport async function changes(from: string, to: string, cwd: string): Promise<FileChange[]> {\n  const run = await git(['diff', '--name-status', '-z', '--find-renames', '--no-color', from, to, '--'], cwd);\n  if (run.code !== 0) throw new GitError(`git diff ${from} ${to} failed: ${run.stderr.trim()}`);\n  return parseNameStatus(run.stdout);\n}\n\n/** The files a commit would change: what is staged. */\nexport async function stagedChanges(cwd: string): Promise<FileChange[]> {\n  const run = await git(['diff', '--cached', '--name-status', '-z', '--find-renames', '--no-color', '--'], cwd);\n  if (run.code !== 0) throw new GitError(`git diff --cached failed: ${run.stderr.trim()}`);\n  return parseNameStatus(run.stdout);\n}\n\n/** A file's content at a revision, or `null` when it does not exist there. */\nexport async function show(ref: string, path: string, cwd: string): Promise<string | null> {\n  const run = await git(['show', `${ref}:${path}`], cwd);\n  return run.code === 0 ? run.stdout : null;\n}\n\n/**\n * The commit that last changed one line of a file, as of a revision, or of\n * the working tree when `ref` is `null` - where a line nobody committed yet\n * belongs to the all-zero commit.\n */\nexport async function blameLine(ref: string | null, path: string, line: number, cwd: string): Promise<string | null> {\n  const run = await git(['blame', '--porcelain', '-L', `${line},${line}`, ...(ref === null ? [] : [ref]), '--', path], cwd);\n  if (run.code !== 0) return null;\n  const sha = /^([0-9a-f]{40,64}) /.exec(run.stdout)?.[1];\n  return sha ?? null;\n}\n\nexport interface Signature {\n  readonly good: boolean;\n  /** The allowed signer's principal, for a good signature. */\n  readonly principal: string | null;\n  readonly detail: string;\n}\n\n/**\n * Whether a commit carries a good SSH signature by a principal in the given\n * allowed-signers file. The file is passed in, never read from the commit's\n * own tree: a round cannot vouch for itself (ADR-0006).\n */\nexport async function verifyCommit(sha: string, allowedSignersFile: string, cwd: string): Promise<Signature> {\n  const run = await git(\n    ['-c', `gpg.ssh.allowedSignersFile=${allowedSignersFile}`, '-c', 'gpg.format=ssh', 'verify-commit', '--raw', sha],\n    cwd,\n  );\n  const text = `${run.stderr}\\n${run.stdout}`;\n  const principal = /Good \"git\" signature for (\\S+)/.exec(text)?.[1] ?? null;\n  return { good: run.code === 0 && principal !== null, principal, detail: text.trim().split('\\n')[0] ?? '' };\n}\n\nexport async function addWorktree(path: string, rev: string, cwd: string): Promise<void> {\n  const run = await git(['worktree', 'add', '--detach', '--force', path, rev], cwd);\n  if (run.code !== 0) throw new GitError(`git worktree add failed: ${run.stderr.trim()}`);\n}\n\n/**\n * Forgets the worktree at `path`, and no other, once its directory is\n * deleted. Git refuses to remove a worktree whose directory has lost its\n * `.git` file, and removes its record of one whose directory is gone, found by\n * the path it was added at: `git worktree prune` would also forget every other\n * worktree git has lost track of, the person's among them.\n */\nexport async function removeWorktree(path: string, cwd: string): Promise<void> {\n  await git(['worktree', 'remove', '--force', path], cwd);\n}\n"]}
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The edge where the harness meets git.\n *\n * Reads, except for two things ADR-0003 allows and bounds: a temporary\n * worktree, added and always removed by the sandbox, and nothing else. Every\n * call is an argument vector, never a shell string, so a path or a ref cannot\n * become a command.\n */\n\nimport { execFile } from 'node:child_process';\n\nimport type { FileChange } from './types.js';\n\nexport interface Run {\n  readonly code: number;\n  readonly stdout: string;\n  readonly stderr: string;\n}\n\n/** Runs git and answers whatever it answered; a missing git is a code of -1. */\nexport function git(args: readonly string[], cwd: string, input?: string): Promise<Run> {\n  return new Promise((resolve) => {\n    const child = execFile(\n      'git',\n      [...args],\n      { cwd, maxBuffer: 256 * 1024 * 1024, encoding: 'utf8', windowsHide: true },\n      (error, stdout, stderr) => {\n        const code = error === null ? 0 : typeof (error as { code?: unknown }).code === 'number' ? ((error as { code: number }).code) : -1;\n        resolve({ code, stdout, stderr });\n      },\n    );\n    if (input !== undefined) child.stdin?.end(input);\n  });\n}\n\nasync function value(args: readonly string[], cwd: string): Promise<string | null> {\n  const run = await git(args, cwd);\n  return run.code === 0 ? run.stdout.trim() : null;\n}\n\nexport class GitError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'GitError';\n  }\n}\n\n/** The top of the work tree holding `cwd`, POSIX-separated, or `null` outside one. */\nexport async function workTreeRoot(cwd: string): Promise<string | null> {\n  return value(['rev-parse', '--show-toplevel'], cwd);\n}\n\n/** The git directory every worktree of this repository shares. */\nexport async function commonDirectory(cwd: string): Promise<string | null> {\n  return value(['rev-parse', '--path-format=absolute', '--git-common-dir'], cwd);\n}\n\n/**\n * Where git runs the hook `name` from, absolute: `core.hooksPath` read as git\n * reads it - relative to the work tree, absolute, or under `~` - and a linked\n * worktree's shared hooks. `null` when git cannot say, before 2.31.\n */\nexport async function hookPath(name: string, cwd: string): Promise<string | null> {\n  return value(['rev-parse', '--path-format=absolute', '--git-path', `hooks/${name}`], cwd);\n}\n\n/** The checked-out branch's short name, or `null` on a detached head. */\nexport async function currentBranch(cwd: string): Promise<string | null> {\n  return value(['symbolic-ref', '--quiet', '--short', 'HEAD'], cwd);\n}\n\n/** The remote's default branch as a local ref, such as `origin/main`, or `null`. */\nexport async function remoteDefault(cwd: string): Promise<string | null> {\n  return value(['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], cwd);\n}\n\n/** Every local branch, by its short name. */\nexport async function localBranches(cwd: string): Promise<string[]> {\n  const listed = await value(['for-each-ref', '--format=%(refname:short)', 'refs/heads/'], cwd);\n  return listed === null || listed === '' ? [] : listed.split('\\n').map((name) => name.trim());\n}\n\nexport async function revision(ref: string, cwd: string): Promise<string | null> {\n  return value(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], cwd);\n}\n\nexport async function mergeBase(a: string, b: string, cwd: string): Promise<string | null> {\n  return value(['merge-base', a, b], cwd);\n}\n\n/** Parses `git diff --name-status -z` output. */\nexport function parseNameStatus(output: string): FileChange[] {\n  const fields = output.split('\\0');\n  const out: FileChange[] = [];\n  for (let i = 0; i < fields.length; ) {\n    const code = fields[i] ?? '';\n    if (code === '') {\n      i += 1;\n      continue;\n    }\n    const status = code.charAt(0) as FileChange['status'];\n    if (status === 'R' || status === 'C') {\n      out.push({ status, from: fields[i + 1] ?? '', path: fields[i + 2] ?? '' });\n      i += 3;\n    } else {\n      out.push({ status, path: fields[i + 1] ?? '' });\n      i += 2;\n    }\n  }\n  return out;\n}\n\n/** The files changed from one revision to another, renames found. */\nexport async function changes(from: string, to: string, cwd: string): Promise<FileChange[]> {\n  const run = await git(['diff', '--name-status', '-z', '--find-renames', '--no-color', from, to, '--'], cwd);\n  if (run.code !== 0) throw new GitError(`git diff ${from} ${to} failed: ${run.stderr.trim()}`);\n  return parseNameStatus(run.stdout);\n}\n\n/** The files a commit would change: what is staged. */\nexport async function stagedChanges(cwd: string): Promise<FileChange[]> {\n  const run = await git(['diff', '--cached', '--name-status', '-z', '--find-renames', '--no-color', '--'], cwd);\n  if (run.code !== 0) throw new GitError(`git diff --cached failed: ${run.stderr.trim()}`);\n  return parseNameStatus(run.stdout);\n}\n\n/** A file's content at a revision, or `null` when it does not exist there. */\nexport async function show(ref: string, path: string, cwd: string): Promise<string | null> {\n  const run = await git(['show', `${ref}:${path}`], cwd);\n  return run.code === 0 ? run.stdout : null;\n}\n\n/**\n * The commit that last changed one line of a file, as of a revision, or of\n * the working tree when `ref` is `null` - where a line nobody committed yet\n * belongs to the all-zero commit.\n */\nexport async function blameLine(ref: string | null, path: string, line: number, cwd: string): Promise<string | null> {\n  const run = await git(['blame', '--porcelain', '-L', `${line},${line}`, ...(ref === null ? [] : [ref]), '--', path], cwd);\n  if (run.code !== 0) return null;\n  const sha = /^([0-9a-f]{40,64}) /.exec(run.stdout)?.[1];\n  return sha ?? null;\n}\n\nexport interface Signature {\n  readonly good: boolean;\n  /** The allowed signer's principal, for a good signature. */\n  readonly principal: string | null;\n  readonly detail: string;\n}\n\n/**\n * Whether a commit carries a good SSH signature by a principal in the given\n * allowed-signers file. The file is passed in, never read from the commit's\n * own tree: a round cannot vouch for itself (ADR-0006).\n */\nexport async function verifyCommit(sha: string, allowedSignersFile: string, cwd: string): Promise<Signature> {\n  const run = await git(\n    ['-c', `gpg.ssh.allowedSignersFile=${allowedSignersFile}`, '-c', 'gpg.format=ssh', 'verify-commit', '--raw', sha],\n    cwd,\n  );\n  const text = `${run.stderr}\\n${run.stdout}`;\n  const principal = /Good \"git\" signature for (\\S+)/.exec(text)?.[1] ?? null;\n  return { good: run.code === 0 && principal !== null, principal, detail: text.trim().split('\\n')[0] ?? '' };\n}\n\nexport async function addWorktree(path: string, rev: string, cwd: string): Promise<void> {\n  const run = await git(['worktree', 'add', '--detach', '--force', path, rev], cwd);\n  if (run.code !== 0) throw new GitError(`git worktree add failed: ${run.stderr.trim()}`);\n}\n\n/**\n * Forgets the worktree at `path`, and no other, once its directory is\n * deleted. Git refuses to remove a worktree whose directory has lost its\n * `.git` file, and removes its record of one whose directory is gone, found by\n * the path it was added at: `git worktree prune` would also forget every other\n * worktree git has lost track of, the person's among them.\n */\nexport async function removeWorktree(path: string, cwd: string): Promise<void> {\n  await git(['worktree', 'remove', '--force', path], cwd);\n}\n"]}

package/dist/guard.d.ts

@@ -44,6 +44,14 @@ export interface GuardInput {
  * can. The guard matches no path by a pattern it cannot read.
  */
 export declare function whyUnreadable(pattern: string): string | null;
+/**
+ * Whether a leading `/` roots a pattern the guard can read at the
+ * filesystem's root: `whole` when every alternative is rooted, `part` when
+ * some brace alternative is, `null` when none is or the pattern cannot be
+ * read. The guard decides repository-relative paths, so a rooted
+ * alternative matches none of them.
+ */
+export declare function rooted(pattern: string): 'whole' | 'part' | null;
 /** The first verified ruling whose paths cover `path`, read as the guard reads a scope. */
 export declare function rulingFor(rulings: readonly VerifiedRuling[], path: string): VerifiedRuling | undefined;
 /** Decides one path. Pure: the caller resolved the path, the brief and the rulings. */

package/dist/guard.js

@@ -8,7 +8,7 @@
  * through a shell passes it - so the audit and spec-brief's archive are the
  * gates, and this is what keeps an honest agent from needing them (ADR-0005).
  */
-import { parseGlob } from './vendor/spec-core/pattern/index.js';
+import { globAlternatives, parseGlob } from './vendor/spec-core/pattern/index.js';
 function compile(pattern) {
     const parsed = parseGlob(pattern, { dialect: 'path', caseSensitive: true, literal: 'either' });
     return parsed.ok ? parsed.glob : parsed.error;
@@ -21,6 +21,24 @@ export function whyUnreadable(pattern) {
     const glob = compile(pattern);
     return typeof glob === 'string' ? glob : null;
 }
+/**
+ * Whether a leading `/` roots a pattern the guard can read at the
+ * filesystem's root: `whole` when every alternative is rooted, `part` when
+ * some brace alternative is, `null` when none is or the pattern cannot be
+ * read. The guard decides repository-relative paths, so a rooted
+ * alternative matches none of them.
+ */
+export function rooted(pattern) {
+    if (typeof compile(pattern) === 'string')
+        return null;
+    // spec-core refuses here only what its compile refuses, so a pattern the
+    // guard reads always has its alternatives read.
+    const { alternatives } = globAlternatives(pattern);
+    const roots = alternatives.filter((alternative) => alternative.rooted).length;
+    if (roots === 0)
+        return null;
+    return roots === alternatives.length ? 'whole' : 'part';
+}
 function matching(patterns, path) {
     const matched = [];
     const unreadable = [];

package/dist/guard.js.map

@@ -1 +1 @@
-{"version":3,"file":"guard.js","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * May this round write this file?\n *\n * The answer is read from the brief the round runs under: `protectedFiles`\n * are refused unless a person has ruled otherwise, `affectedFiles` are the\n * round's to write, and anything else is outside the scope the person\n * approved. A guard is a guardrail, not a boundary - an agent that writes\n * through a shell passes it - so the audit and spec-brief's archive are the\n * gates, and this is what keeps an honest agent from needing them (ADR-0005).\n */\n\nimport { parseGlob, type Glob } from './vendor/spec-core/pattern/index.js';\nimport type { OutOfScope } from './config.js';\nimport type { BriefRow } from './types.js';\n\nexport type Verdict = 'allow' | 'warn' | 'ask' | 'deny';\n\nexport type Reason =\n  | 'outside-repository'\n  | 'no-brief'\n  | 'brief-file'\n  | 'protected'\n  | 'ruled'\n  | 'unreadable-protection'\n  | 'in-scope'\n  | 'out-of-scope';\n\nexport interface Decision {\n  /** Repository-relative, or the path as given when it lies outside. */\n  readonly path: string;\n  readonly verdict: Verdict;\n  readonly reason: Reason;\n  /** The patterns or ruling that decided it. */\n  readonly because: readonly string[];\n  readonly message: string;\n  readonly hint: string;\n}\n\n/** A ruling whose signature has been verified: a person allowed these paths. */\nexport interface VerifiedRuling {\n  readonly id: string;\n  readonly paths: readonly string[];\n  readonly signer: string;\n}\n\nexport interface GuardInput {\n  /** Repository-relative POSIX path, or `null` for a path outside the repository. */\n  readonly path: string | null;\n  /** The path as the caller gave it, for messages. */\n  readonly given: string;\n  readonly brief: BriefRow | null;\n  /** Why there is no brief, when there is none. */\n  readonly noBrief?: string | undefined;\n  readonly rulings: readonly VerifiedRuling[];\n  readonly outOfScope: OutOfScope;\n}\n\nfunction compile(pattern: string): Glob | string {\n  const parsed = parseGlob(pattern, { dialect: 'path', caseSensitive: true, literal: 'either' });\n  return parsed.ok ? parsed.glob : parsed.error;\n}\n\n/**\n * Why the guard cannot read a pattern, in spec-core's words; `null` when it\n * can. The guard matches no path by a pattern it cannot read.\n */\nexport function whyUnreadable(pattern: string): string | null {\n  const glob = compile(pattern);\n  return typeof glob === 'string' ? glob : null;\n}\n\nfunction matching(patterns: readonly string[], path: string): { matched: string[]; unreadable: string[] } {\n  const matched: string[] = [];\n  const unreadable: string[] = [];\n  for (const pattern of patterns) {\n    const glob = compile(pattern);\n    if (typeof glob === 'string') unreadable.push(`${pattern} (${glob})`);\n    else if (glob.match(path)) matched.push(pattern);\n  }\n  return { matched, unreadable };\n}\n\n/** The first verified ruling whose paths cover `path`, read as the guard reads a scope. */\nexport function rulingFor(rulings: readonly VerifiedRuling[], path: string): VerifiedRuling | undefined {\n  return rulings.find((candidate) => matching(candidate.paths, path).matched.length > 0);\n}\n\nconst ESCALATE =\n  'if the round cannot be done without it, stop and ask for a ruling: spec-harness escalate --path <file> --reason <why>, or the request_escalation tool';\n\n/** Decides one path. Pure: the caller resolved the path, the brief and the rulings. */\nexport function decide(input: GuardInput): Decision {\n  const { path, given, brief } = input;\n  if (path === null) {\n    return {\n      path: given,\n      verdict: 'allow',\n      reason: 'outside-repository',\n      because: [],\n      message: `${given} is outside the repository; no brief governs it`,\n      hint: 'nothing to do',\n    };\n  }\n  if (brief === null) {\n    return {\n      path,\n      verdict: 'allow',\n      reason: 'no-brief',\n      because: [],\n      message: `no brief governs ${path}: ${input.noBrief ?? 'no active brief'}`,\n      hint: 'name the brief this work belongs to, so its scope can be checked',\n    };\n  }\n  if (path === brief.file) {\n    return {\n      path,\n      verdict: 'allow',\n      reason: 'brief-file',\n      because: [],\n      message: `${path} is brief ${brief.id} itself`,\n      hint: 'tick or disposition its boxes as the work lands',\n    };\n  }\n\n  const protectedHits = matching(brief.protectedFiles, path);\n  if (protectedHits.unreadable.length > 0) {\n    // A protection that cannot be read cannot be honoured, and cannot be\n    // assumed not to apply: refuse until the brief is fixed.\n    return {\n      path,\n      verdict: 'deny',\n      reason: 'unreadable-protection',\n      because: protectedHits.unreadable,\n      message: `brief ${brief.id} protects files with a pattern that cannot be read: ${protectedHits.unreadable.join('; ')}`,\n      hint: `fix protectedFiles in ${brief.file} (spec-brief lint names the problem)`,\n    };\n  }\n  if (protectedHits.matched.length > 0) {\n    const ruling = rulingFor(input.rulings, path);\n    if (ruling !== undefined) {\n      return {\n        path,\n        verdict: 'allow',\n        reason: 'ruled',\n        because: [ruling.id],\n        message: `${path} is protected by brief ${brief.id}, and ruling ${ruling.id}, signed by ${ruling.signer}, allows it`,\n        hint: 'keep the change to what the ruling allows',\n      };\n    }\n    return {\n      path,\n      verdict: 'deny',\n      reason: 'protected',\n      because: protectedHits.matched,\n      message: `brief ${brief.id} does not empower this round to change ${path} (protectedFiles: ${protectedHits.matched.join(', ')})`,\n      hint: ESCALATE,\n    };\n  }\n\n  const affectedHits = matching(brief.affectedFiles, path);\n  if (affectedHits.matched.length > 0) {\n    return {\n      path,\n      verdict: 'allow',\n      reason: 'in-scope',\n      because: affectedHits.matched,\n      message: `${path} is in brief ${brief.id}'s scope (${affectedHits.matched.join(', ')})`,\n      hint: 'nothing to do',\n    };\n  }\n\n  const verdict: Verdict = input.outOfScope;\n  const scope = brief.affectedFiles.length === 0 ? 'declares no affectedFiles' : `covers ${brief.affectedFiles.join(', ')}`;\n  return {\n    path,\n    verdict,\n    reason: 'out-of-scope',\n    because: affectedHits.unreadable,\n    message: `${path} is outside brief ${brief.id}'s scope, which ${scope}`,\n    hint:\n      verdict === 'deny'\n        ? `add it to affectedFiles in ${brief.file} if the round needs it, which is a change the person who approved the brief must see; or ${ESCALATE}`\n        : `if the round needs it, say so in ${brief.file} and add it to affectedFiles; the archive reports every file outside the scope`,\n  };\n}\n"]}
+{"version":3,"file":"guard.js","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * May this round write this file?\n *\n * The answer is read from the brief the round runs under: `protectedFiles`\n * are refused unless a person has ruled otherwise, `affectedFiles` are the\n * round's to write, and anything else is outside the scope the person\n * approved. A guard is a guardrail, not a boundary - an agent that writes\n * through a shell passes it - so the audit and spec-brief's archive are the\n * gates, and this is what keeps an honest agent from needing them (ADR-0005).\n */\n\nimport { globAlternatives, parseGlob, type Glob, type GlobAlternative } from './vendor/spec-core/pattern/index.js';\nimport type { OutOfScope } from './config.js';\nimport type { BriefRow } from './types.js';\n\nexport type Verdict = 'allow' | 'warn' | 'ask' | 'deny';\n\nexport type Reason =\n  | 'outside-repository'\n  | 'no-brief'\n  | 'brief-file'\n  | 'protected'\n  | 'ruled'\n  | 'unreadable-protection'\n  | 'in-scope'\n  | 'out-of-scope';\n\nexport interface Decision {\n  /** Repository-relative, or the path as given when it lies outside. */\n  readonly path: string;\n  readonly verdict: Verdict;\n  readonly reason: Reason;\n  /** The patterns or ruling that decided it. */\n  readonly because: readonly string[];\n  readonly message: string;\n  readonly hint: string;\n}\n\n/** A ruling whose signature has been verified: a person allowed these paths. */\nexport interface VerifiedRuling {\n  readonly id: string;\n  readonly paths: readonly string[];\n  readonly signer: string;\n}\n\nexport interface GuardInput {\n  /** Repository-relative POSIX path, or `null` for a path outside the repository. */\n  readonly path: string | null;\n  /** The path as the caller gave it, for messages. */\n  readonly given: string;\n  readonly brief: BriefRow | null;\n  /** Why there is no brief, when there is none. */\n  readonly noBrief?: string | undefined;\n  readonly rulings: readonly VerifiedRuling[];\n  readonly outOfScope: OutOfScope;\n}\n\nfunction compile(pattern: string): Glob | string {\n  const parsed = parseGlob(pattern, { dialect: 'path', caseSensitive: true, literal: 'either' });\n  return parsed.ok ? parsed.glob : parsed.error;\n}\n\n/**\n * Why the guard cannot read a pattern, in spec-core's words; `null` when it\n * can. The guard matches no path by a pattern it cannot read.\n */\nexport function whyUnreadable(pattern: string): string | null {\n  const glob = compile(pattern);\n  return typeof glob === 'string' ? glob : null;\n}\n\n/**\n * Whether a leading `/` roots a pattern the guard can read at the\n * filesystem's root: `whole` when every alternative is rooted, `part` when\n * some brace alternative is, `null` when none is or the pattern cannot be\n * read. The guard decides repository-relative paths, so a rooted\n * alternative matches none of them.\n */\nexport function rooted(pattern: string): 'whole' | 'part' | null {\n  if (typeof compile(pattern) === 'string') return null;\n  // spec-core refuses here only what its compile refuses, so a pattern the\n  // guard reads always has its alternatives read.\n  const { alternatives } = globAlternatives(pattern) as { readonly alternatives: readonly GlobAlternative[] };\n  const roots = alternatives.filter((alternative) => alternative.rooted).length;\n  if (roots === 0) return null;\n  return roots === alternatives.length ? 'whole' : 'part';\n}\n\nfunction matching(patterns: readonly string[], path: string): { matched: string[]; unreadable: string[] } {\n  const matched: string[] = [];\n  const unreadable: string[] = [];\n  for (const pattern of patterns) {\n    const glob = compile(pattern);\n    if (typeof glob === 'string') unreadable.push(`${pattern} (${glob})`);\n    else if (glob.match(path)) matched.push(pattern);\n  }\n  return { matched, unreadable };\n}\n\n/** The first verified ruling whose paths cover `path`, read as the guard reads a scope. */\nexport function rulingFor(rulings: readonly VerifiedRuling[], path: string): VerifiedRuling | undefined {\n  return rulings.find((candidate) => matching(candidate.paths, path).matched.length > 0);\n}\n\nconst ESCALATE =\n  'if the round cannot be done without it, stop and ask for a ruling: spec-harness escalate --path <file> --reason <why>, or the request_escalation tool';\n\n/** Decides one path. Pure: the caller resolved the path, the brief and the rulings. */\nexport function decide(input: GuardInput): Decision {\n  const { path, given, brief } = input;\n  if (path === null) {\n    return {\n      path: given,\n      verdict: 'allow',\n      reason: 'outside-repository',\n      because: [],\n      message: `${given} is outside the repository; no brief governs it`,\n      hint: 'nothing to do',\n    };\n  }\n  if (brief === null) {\n    return {\n      path,\n      verdict: 'allow',\n      reason: 'no-brief',\n      because: [],\n      message: `no brief governs ${path}: ${input.noBrief ?? 'no active brief'}`,\n      hint: 'name the brief this work belongs to, so its scope can be checked',\n    };\n  }\n  if (path === brief.file) {\n    return {\n      path,\n      verdict: 'allow',\n      reason: 'brief-file',\n      because: [],\n      message: `${path} is brief ${brief.id} itself`,\n      hint: 'tick or disposition its boxes as the work lands',\n    };\n  }\n\n  const protectedHits = matching(brief.protectedFiles, path);\n  if (protectedHits.unreadable.length > 0) {\n    // A protection that cannot be read cannot be honoured, and cannot be\n    // assumed not to apply: refuse until the brief is fixed.\n    return {\n      path,\n      verdict: 'deny',\n      reason: 'unreadable-protection',\n      because: protectedHits.unreadable,\n      message: `brief ${brief.id} protects files with a pattern that cannot be read: ${protectedHits.unreadable.join('; ')}`,\n      hint: `fix protectedFiles in ${brief.file} (spec-brief lint names the problem)`,\n    };\n  }\n  if (protectedHits.matched.length > 0) {\n    const ruling = rulingFor(input.rulings, path);\n    if (ruling !== undefined) {\n      return {\n        path,\n        verdict: 'allow',\n        reason: 'ruled',\n        because: [ruling.id],\n        message: `${path} is protected by brief ${brief.id}, and ruling ${ruling.id}, signed by ${ruling.signer}, allows it`,\n        hint: 'keep the change to what the ruling allows',\n      };\n    }\n    return {\n      path,\n      verdict: 'deny',\n      reason: 'protected',\n      because: protectedHits.matched,\n      message: `brief ${brief.id} does not empower this round to change ${path} (protectedFiles: ${protectedHits.matched.join(', ')})`,\n      hint: ESCALATE,\n    };\n  }\n\n  const affectedHits = matching(brief.affectedFiles, path);\n  if (affectedHits.matched.length > 0) {\n    return {\n      path,\n      verdict: 'allow',\n      reason: 'in-scope',\n      because: affectedHits.matched,\n      message: `${path} is in brief ${brief.id}'s scope (${affectedHits.matched.join(', ')})`,\n      hint: 'nothing to do',\n    };\n  }\n\n  const verdict: Verdict = input.outOfScope;\n  const scope = brief.affectedFiles.length === 0 ? 'declares no affectedFiles' : `covers ${brief.affectedFiles.join(', ')}`;\n  return {\n    path,\n    verdict,\n    reason: 'out-of-scope',\n    because: affectedHits.unreadable,\n    message: `${path} is outside brief ${brief.id}'s scope, which ${scope}`,\n    hint:\n      verdict === 'deny'\n        ? `add it to affectedFiles in ${brief.file} if the round needs it, which is a change the person who approved the brief must see; or ${ESCALATE}`\n        : `if the round needs it, say so in ${brief.file} and add it to affectedFiles; the archive reports every file outside the scope`,\n  };\n}\n"]}

package/dist/host.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The edge where the harness meets a program that is neither git nor a
+ * sibling: Claude Code, asked which release it is.
+ *
+ * Found on `PATH` and started without a shell, as every program the harness
+ * runs is (ADR-0002). On Windows a program is an `.exe` or a `.com`; a
+ * `claude.cmd` shim, as npm installs one, can be started only by a shell, so
+ * it is named rather than run, and its release cannot be told.
+ */
+import type { ClaudeCodeAnswer } from './versions.js';
+/** The file `name` names on `PATH` as the environment gives it, or `null`. */
+export declare function onPath(name: string, env: Readonly<Record<string, string | undefined>>, platform?: NodeJS.Platform): string | null;
+/** `claude --version`, as the Claude Code on `PATH` answers it, or why it cannot. */
+export declare function claudeVersion(env: Readonly<Record<string, string | undefined>>, platform?: NodeJS.Platform): Promise<ClaudeCodeAnswer>;

package/dist/host.js

@@ -0,0 +1,50 @@
+/**
+ * The edge where the harness meets a program that is neither git nor a
+ * sibling: Claude Code, asked which release it is.
+ *
+ * Found on `PATH` and started without a shell, as every program the harness
+ * runs is (ADR-0002). On Windows a program is an `.exe` or a `.com`; a
+ * `claude.cmd` shim, as npm installs one, can be started only by a shell, so
+ * it is named rather than run, and its release cannot be told.
+ */
+import { execFile } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+/** What Windows runs for a name with no extension, in order; the first two alone without a shell. */
+const WINDOWS_EXTENSIONS = ['.COM', '.EXE', '.BAT', '.CMD'];
+/** The file `name` names on `PATH` as the environment gives it, or `null`. */
+export function onPath(name, env, platform = process.platform) {
+    const path = env['PATH'] ?? env['Path'] ?? '';
+    const windows = platform === 'win32';
+    const extensions = windows
+        ? (env['PATHEXT'] ?? WINDOWS_EXTENSIONS.join(';')).split(';').filter((extension) => extension !== '')
+        : [''];
+    for (const directory of path.split(windows ? ';' : delimiter)) {
+        if (directory === '')
+            continue;
+        for (const extension of extensions) {
+            const file = join(directory, `${name}${extension.toLowerCase()}`);
+            if (existsSync(file) && statSync(file).isFile())
+                return file;
+        }
+    }
+    return null;
+}
+/** `claude --version`, as the Claude Code on `PATH` answers it, or why it cannot. */
+export async function claudeVersion(env, platform = process.platform) {
+    const file = onPath('claude', env, platform);
+    if (file === null)
+        return { missing: 'no claude is on PATH' };
+    if (platform === 'win32' && !/\.(?:exe|com)$/i.test(file)) {
+        return { missing: `claude on PATH is ${file}, a script that cannot be started without a shell, which spec-harness does not use` };
+    }
+    return new Promise((resolve) => {
+        execFile(file, ['--version'], { encoding: 'utf8', windowsHide: true, timeout: 15_000, shell: false }, (error, stdout) => {
+            if (error !== null)
+                resolve({ missing: `${file} --version failed: ${error.message.split('\n')[0] ?? ''}` });
+            else
+                resolve({ output: stdout });
+        });
+    });
+}
+//# sourceMappingURL=host.js.map