@mnstry/atelier 0.2.0-alpha.12 → 0.2.0-alpha.14

package/src/boundary/policy.mjs

@@ -7,6 +7,9 @@ import { matchesPathPattern } from '../project/path-match.mjs'
 import { sanitizedGitEnvironment } from '../runtime/git-adapter.mjs'
 import {
   CHECK_AGGREGATE_MAX_BYTES,
+  canonicalDiffArgs,
+  gitOutputResult,
+  parseDiffSections,
   parsePushRefInput,
   resolveContentRules,
   scanPushUpdate,
@@ -15,6 +18,7 @@ import {
   validateContentRuleExceptions,
   validateContentRules,
 } from './content-rules.mjs'
+import { delegationsPathFor, loadDelegationsFile, ownerKeysForCommand, resolveDelegation, validateDelegationsDocument } from './delegation.mjs'
 
 export const BOUNDARY_POLICY_SCHEMA = 'mnstry.atelier-boundary-policy@v1'
 export const PROMOTE_EVENT_SCHEMA = 'git-promote-event@v1'
@@ -115,6 +119,12 @@ function unknownKeys(value, label, allowed) {
     .map((key) => `${label} must not include additional property ${key}`)
 }
 
+// The schema declares `ext` as a reserved extension container that consumers
+// must ignore. It is accepted, never read, and never carries authority.
+function extErrors(value, label) {
+  return value?.ext != null && !isObject(value.ext) ? [`${label}.ext must be an object`] : []
+}
+
 function validAudienceList(value, label, required = false) {
   if (value == null && !required) return []
   if (!Array.isArray(value)) return [`${label} must be a list`]
@@ -128,8 +138,12 @@ function validAudienceList(value, label, required = false) {
 export function validateBoundaryPolicy(policy, project = null) {
   const errors = []
   if (!isObject(policy)) return ['boundary policy must be a JSON object']
-  errors.push(...unknownKeys(policy, '/', new Set(['schema', 'mode', 'actors', 'repos', 'promotion', 'forbiddenPaths', 'contentRules', 'contentRuleExceptions', 'governanceLedgerPath'])))
+  errors.push(...unknownKeys(policy, '/', new Set(['schema', 'contractVersion', 'mode', 'actors', 'repos', 'promotion', 'forbiddenPaths', 'contentRules', 'contentRuleExceptions', 'governanceLedgerPath', 'ext'])))
   if (policy.schema !== BOUNDARY_POLICY_SCHEMA) errors.push(`schema must be ${BOUNDARY_POLICY_SCHEMA}`)
+  if (policy.contractVersion != null && !(typeof policy.contractVersion === 'string' && /^1\.[0-9]+\.[0-9]+$/.test(policy.contractVersion))) {
+    errors.push('contractVersion must be a 1.x.y version')
+  }
+  errors.push(...extErrors(policy, '/'))
   if (!VALID_BOUNDARY_MODES.has(policy.mode)) errors.push('mode must be strict or legacy-warning')
 
   const actors = policy.actors
@@ -138,7 +152,8 @@ export function validateBoundaryPolicy(policy, project = null) {
   if (!isObject(actors)) errors.push('actors must be an object')
   if (!isObject(repos)) errors.push('repos must be an object')
   if (policy.promotion != null && !isObject(policy.promotion)) errors.push('promotion must be an object')
-  errors.push(...unknownKeys(promotion, 'promotion', new Set(['requiresGitPromote', 'recordsPath'])))
+  errors.push(...unknownKeys(promotion, 'promotion', new Set(['requiresGitPromote', 'recordsPath', 'ext'])))
+  errors.push(...extErrors(promotion, 'promotion'))
   if (policy.forbiddenPaths != null && !Array.isArray(policy.forbiddenPaths)) errors.push('forbiddenPaths must be a list')
   if (policy.contentRules != null) errors.push(...validateContentRules(policy.contentRules))
   if (policy.contentRuleExceptions != null) {
@@ -153,11 +168,15 @@ export function validateBoundaryPolicy(policy, project = null) {
   }
 
   for (const [actorId, actor] of Object.entries(isObject(actors) ? actors : {})) {
-    errors.push(...unknownKeys(actor, `actors.${actorId}`, new Set(['githubLogin', 'gitEmails', 'privateDomainRepo'])))
+    errors.push(...unknownKeys(actor, `actors.${actorId}`, new Set(['githubLogin', 'gitEmails', 'privateDomainRepo', 'ext'])))
+    errors.push(...extErrors(actor, `actors.${actorId}`))
     if (!isObject(actor)) {
       errors.push(`actors.${actorId} must be an object`)
       continue
     }
+    // The schema types these fields; a non-string login would still match through String().
+    if (actor.githubLogin != null && typeof actor.githubLogin !== 'string') errors.push(`actors.${actorId}.githubLogin must be a string`)
+    if (actor.gitEmails != null && !Array.isArray(actor.gitEmails)) errors.push(`actors.${actorId}.gitEmails must be a list`)
     if (!firstString(actor.githubLogin) && !asArray(actor.gitEmails).length) {
       errors.push(`actors.${actorId} must declare githubLogin or gitEmails`)
     }
@@ -176,7 +195,8 @@ export function validateBoundaryPolicy(policy, project = null) {
   }
 
   for (const [repoName, repo] of Object.entries(isObject(repos) ? repos : {})) {
-    errors.push(...unknownKeys(repo, `repos.${repoName}`, new Set(['kind', 'ownerActor', 'readBoundary', 'allowedAudiences', 'forbiddenAudiences', 'autoCommit'])))
+    errors.push(...unknownKeys(repo, `repos.${repoName}`, new Set(['kind', 'ownerActor', 'readBoundary', 'allowedAudiences', 'forbiddenAudiences', 'autoCommit', 'ext'])))
+    errors.push(...extErrors(repo, `repos.${repoName}`))
     if (!isObject(repo)) {
       errors.push(`repos.${repoName} must be an object`)
       continue
@@ -306,7 +326,7 @@ function nodePlacementFindings({ node, policy }) {
   return findings
 }
 
-function actorFindings({ policy, project, actor, gitExecutable, allowNetworkActorResolution, allowHistoryActorResolution, forceActorErrors }) {
+function actorFindings({ policy, project, actor, gitExecutable, allowNetworkActorResolution, allowHistoryActorResolution, forceActorErrors, operation, delegations, ownerKeys, now }) {
   const findings = []
   const operatedRepos = new Set(managedRepos(project).map((repo) => repo.name))
   const ownedRepos = Object.entries(policy.repos ?? {}).filter(([name, repo]) =>
@@ -322,23 +342,102 @@ function actorFindings({ policy, project, actor, gitExecutable, allowNetworkActo
       findings.push(finding({ severity, code: 'private-domain-actor-unverified', repo: repoName,
         message: `${repoName}: could not verify local actor for private domain repo owned by ${repo.ownerActor}${current.reason ? ` (${current.reason})` : ''}` }))
     } else if (current.actorId !== repo.ownerActor) {
-      findings.push(finding({ severity, code: 'private-domain-actor-mismatch', repo: repoName, message: `${repoName}: private domain repo is owned by ${repo.ownerActor}, but current actor is ${current.actorId}` }))
+      // Only an owner-signed delegation, verified against a host-supplied key,
+      // changes this outcome, and only for its operator, repos and operation.
+      const delegated = resolveDelegation({ policy, project, delegations, repoName, repo, actorId: current.actorId, operation, ownerKeys, now })
+      if (delegated.applies) {
+        const { id, owner, expiresAt } = delegated.delegation
+        findings.push(finding({ severity: 'info', code: 'private-domain-delegated-operator', repo: repoName,
+          message: `${repoName}: ${current.actorId} operates under delegation ${id} from owner ${owner} until ${expiresAt}`,
+          details: { actorId: current.actorId, owner, delegationId: id, expiresAt, operation } }))
+      } else {
+        const note = delegated.reason === 'delegation-missing' ? '' : ` (${delegated.reason})`
+        findings.push(finding({ severity, code: 'private-domain-actor-mismatch', repo: repoName,
+          message: `${repoName}: private domain repo is owned by ${repo.ownerActor}, but current actor is ${current.actorId}${note}`,
+          details: { delegationReason: delegated.reason } }))
+      }
     }
   }
   return findings
 }
 
-export function stagedPathsForProject(project, { gitExecutable = 'git' } = {}) {
+/**
+ * The index a pre-commit hook is judging. Git names it in GIT_INDEX_FILE (a
+ * temporary index under `git commit -a` or `git commit <paths>`, a linked
+ * worktree's own index, or `.git/index` relative to the work tree's top) and
+ * runs the hook at that top, though a chained hook may have moved. The work
+ * tree is found by Git's own discovery from where the hook runs; the hook's
+ * GIT_DIR is not used, because in a linked worktree Git exports it without a
+ * work tree, which would make any subdirectory look like the top. A work tree
+ * discovery cannot find is unresolved, and blocks. Returns null when no index
+ * is named.
+ */
+export function hookIndexFromEnvironment({ env = process.env, cwd = process.cwd(), gitExecutable = 'git' } = {}) {
+  const named = typeof env.GIT_INDEX_FILE === 'string' ? env.GIT_INDEX_FILE : ''
+  if (!named) return null
+  const workTree = gitPathOutput(cwd, ['rev-parse', '--show-toplevel'], sanitizedGitEnvironment(), gitExecutable)
+  const commonDir = gitPathOutput(cwd, ['rev-parse', '--git-common-dir'], sanitizedGitEnvironment(), gitExecutable)
+  return { workTree, indexFile: path.resolve(workTree ?? cwd, named), commonDir }
+}
+
+function gitPathOutput(cwd, args, env, gitExecutable = 'git') {
+  const result = spawnSync(gitExecutable, ['-C', cwd, ...args], { encoding: 'utf8', env })
+  const output = result.status === 0 ? String(result.stdout ?? '').replace(/\r?\n$/, '') : ''
+  return output ? nativeRealPath(path.resolve(cwd, output)) : null
+}
+
+// The file system's own spelling of a path, so a configured path that differs
+// only in case (macOS, Windows) still names the same repo.
+function nativeRealPath(value) {
+  try {
+    return fs.realpathSync.native(path.resolve(value))
+  } catch {
+    return path.resolve(value)
+  }
+}
+
+/**
+ * Where each managed repo's staged state is read. The repo the hook is
+ * committing is read from the hook's work tree and index: the managed repo
+ * configured at that work tree, or the one managed repo sharing its Git
+ * directory (a linked worktree of it). Every other repo is read as configured.
+ * When an index is named but no single managed repo is being committed, the
+ * guard cannot tell what it is judging, and says so.
+ */
+function stagedTargets(project, hookIndex, gitExecutable = 'git') {
+  const repos = managedRepos(project)
+  const targets = new Map(repos.map((repo) => [repo, { root: repo.path, indexFile: null }]))
+  if (!hookIndex) return { targets, unresolved: null }
+  let committing = hookIndex.workTree ? repos.filter((repo) => repo.path && nativeRealPath(repo.path) === hookIndex.workTree) : []
+  if (committing.length === 0 && hookIndex.commonDir) {
+    committing = repos.filter((repo) => repo.path && fs.existsSync(repo.path)
+      && gitPathOutput(repo.path, ['rev-parse', '--git-common-dir'], sanitizedGitEnvironment(), gitExecutable) === hookIndex.commonDir)
+  }
+  if (committing.length !== 1) return { targets, unresolved: hookIndex.workTree ?? '(an unresolved work tree)' }
+  targets.set(committing[0], { root: hookIndex.workTree, indexFile: hookIndex.indexFile })
+  return { targets, unresolved: null }
+}
+
+function stagedPathsResult(targets, { gitExecutable = 'git' } = {}) {
   const paths = []
-  for (const repo of managedRepos(project)) {
-    if (!repo.path || !fs.existsSync(path.join(repo.path, '.git'))) continue
-    const result = spawnSync(gitExecutable, ['-C', repo.path, 'diff', '--cached', '--name-only', '--diff-filter=ACMR'], { encoding: 'utf8', env: sanitizedGitEnvironment() })
-    if (result.status !== 0) continue
-    for (const rel of result.stdout.split('\n').map((line) => line.trim()).filter(Boolean)) {
-      paths.push({ repo: repo.name, repoRoot: repo.path, path: normalize(rel) })
+  const failures = []
+  for (const [repo, target] of targets) {
+    if (!target.root || !fs.existsSync(path.join(target.root, '.git'))) continue
+    // NUL-separated names are exact: a quoted name could never match a forbidden-path glob.
+    const result = gitOutputResult(target.root, ['diff', '--cached', '--name-only', '-z', '--no-relative', '--diff-filter=ACMR'], { gitExecutable, indexFile: target.indexFile })
+    if (!result.ok) {
+      failures.push({ repo, reason: result.code })
+      continue
+    }
+    for (const rel of result.stdout.split('\0').filter(Boolean)) {
+      paths.push({ repo: repo.name, repoRoot: target.root, path: normalize(rel) })
     }
   }
-  return paths
+  return { paths, failures }
+}
+
+export function stagedPathsForProject(project, { gitExecutable = 'git', hookIndex = null } = {}) {
+  return stagedPathsResult(stagedTargets(project, hookIndex, gitExecutable).targets, { gitExecutable }).paths
 }
 
 function forbiddenPathFindings({ policy, stagedPaths }) {
@@ -380,30 +479,14 @@ function isInitializationDefault(field, value) {
   return Array.isArray(defaults) && defaults.includes(value)
 }
 
+/** Diff sections with their hunks, read by the same parser as the content scan. */
 export function diffFileSections(diff) {
-  const files = []
-  let current = null
-  let hunk = null
-  for (const line of String(diff ?? '').split('\n')) {
-    if (line.startsWith('diff --git ')) {
-      const header = line.match(/^diff --git a\/(.*) b\/(.*)$/)
-      current = { path: header ? normalize(header[2]) : null, hunks: [], lines: [] }
-      files.push(current)
-      hunk = null
-      continue
-    }
-    if (!current) continue
-    current.lines.push(line)
-    if (line.startsWith('@@')) {
-      hunk = { added: [], removed: [] }
-      current.hunks.push(hunk)
-      continue
-    }
-    if (!hunk) continue
-    if (/^\+(?!\+)/.test(line)) hunk.added.push(line.slice(1))
-    else if (/^-(?!-)/.test(line)) hunk.removed.push(line.slice(1))
-  }
-  return files
+  return parseDiffSections(diff, { detail: true }).map((section) => ({
+    path: section.path,
+    hunks: section.hunks,
+    lines: section.lines,
+    incomplete: section.incomplete,
+  }))
 }
 
 export function semanticChangesInFile(file) {
@@ -426,26 +509,38 @@ export function semanticChangesInFile(file) {
   return changes
 }
 
-function semanticDiffFindings({ policy, project, gitExecutable = 'git' }) {
+function semanticDiffFindings({ targets, gitExecutable = 'git' }) {
   const findings = []
   const severity = 'error'
-  for (const repo of managedRepos(project)) {
-    if (!repo.path || !fs.existsSync(path.join(repo.path, '.git'))) {
+  for (const [repo, target] of targets) {
+    if (!target.root || !fs.existsSync(path.join(target.root, '.git'))) {
       findings.push(unscannableRepoFinding(repo, 'configured path is absent or is not a Git checkout'))
       continue
     }
-    const result = spawnSync(gitExecutable, ['-C', repo.path, 'diff', '--cached', '--unified=0', '--', '*.md', '*.kg.json'], { encoding: 'utf8', env: sanitizedGitEnvironment() })
-    if (result.status !== 0) {
+    // --text: a document declared binary, or holding a NUL byte, still has its fields read.
+    const result = gitOutputResult(target.root, [...canonicalDiffArgs(['--cached'], ['--text']), '--', '*.md', '*.kg.json'], { gitExecutable, indexFile: target.indexFile })
+    if (!result.ok) {
       findings.push(unscannableRepoFinding(repo, 'git diff --cached failed'))
       continue
     }
     if (!result.stdout.trim()) continue
     for (const file of diffFileSections(result.stdout)) {
+      if (file.incomplete) {
+        findings.push(finding({
+          severity,
+          code: 'semantic-field-scan-incomplete',
+          repo: repo.name,
+          path: file.path,
+          message: `${repo.name}/${file.path ?? '(unknown path)'}: the staged diff could not be read, so its semantic fields were not checked`,
+          details: { reason: file.incomplete },
+        }))
+        continue
+      }
       const changes = semanticChangesInFile(file)
       if (!changes.length) continue
-      // The marker has to travel in the same file's diff as the change it approves —
-      // a marker elsewhere in the commit approves nothing.
-      if (REVIEW_MARKER_RE.test(file.lines.join('\n'))) continue
+      // The marker has to be added in the same file's diff as the change it approves:
+      // a marker elsewhere in the commit, a removed one, or one in a file name approves nothing.
+      if (file.hunks.some((hunk) => hunk.added.some((line) => REVIEW_MARKER_RE.test(line)))) continue
       const label = `${repo.name}/${file.path ?? '(unknown path)'}`
       findings.push(
         finding({
@@ -462,17 +557,17 @@ function semanticDiffFindings({ policy, project, gitExecutable = 'git' }) {
   return findings
 }
 
-function stagedContentFindings({ policy, project, gitExecutable = 'git' }) {
+function stagedContentFindings({ policy, targets, gitExecutable = 'git' }) {
   const rules = resolveContentRules(policy)
   const exceptions = asArray(policy?.contentRuleExceptions)
   const findings = []
   let totalBytes = 0
-  for (const repo of managedRepos(project)) {
-    if (!repo.path || !fs.existsSync(path.join(repo.path, '.git'))) {
+  for (const [repo, target] of targets) {
+    if (!target.root || !fs.existsSync(path.join(target.root, '.git'))) {
       findings.push(unscannableRepoFinding(repo, 'configured path is absent or is not a Git checkout'))
       continue
     }
-    const result = scanStagedRepository({ repoRoot: repo.path, rules, exceptions, repo: repo.name, gitExecutable })
+    const result = scanStagedRepository({ repoRoot: target.root, rules, exceptions, repo: repo.name, gitExecutable, indexFile: target.indexFile })
     findings.push(...result.findings, ...result.diagnostics)
     totalBytes += result.bytes
     if (totalBytes > CHECK_AGGREGATE_MAX_BYTES) {
@@ -515,7 +610,7 @@ function repoForCwd(project, cwd) {
  * which reports without blocking, so an accepted usage elsewhere in the repo can
  * never strand unrelated work on the machine.
  */
-export function checkPushContent({ project, policy, repo, updates, cwd = process.cwd(), gitRunner = spawnSync } = {}) {
+export function checkPushContent({ project, policy, repo, updates, remote = null, cwd = process.cwd(), gitRunner = spawnSync } = {}) {
   const target = repo ?? repoForCwd(project, cwd)
   if (!target) {
     // Fail closed. This hook is only installed into managed repos, so failing to
@@ -533,15 +628,17 @@ export function checkPushContent({ project, policy, repo, updates, cwd = process
   const findings = []
   let totalBytes = 0
   for (const update of updates) {
-    const result = scanPushUpdate({ repoRoot: target.path, update, rules, exceptions, repo: target.name, gitRunner })
+    const result = scanPushUpdate({ repoRoot: target.path, update, rules, exceptions, repo: target.name, remote, gitRunner, maxBytes: CHECK_AGGREGATE_MAX_BYTES - totalBytes })
     findings.push(...result.findings, ...result.diagnostics)
     totalBytes += result.bytes
+    // The per-commit scan reports its own budget refusal; say it once.
+    if (result.diagnostics.some((item) => item.details?.reason === 'push-evidence-too-large')) break
     if (totalBytes > CHECK_AGGREGATE_MAX_BYTES) {
       findings.push(finding({
         severity: 'error',
         code: 'content-scan-incomplete',
         repo: target.name,
-        message: `push evidence exceeds the ${CHECK_AGGREGATE_MAX_BYTES}-byte aggregate limit`,
+        message: `push evidence exceeds the ${CHECK_AGGREGATE_MAX_BYTES}-byte aggregate limit; push it in smaller parts`,
       }))
       break
     }
@@ -635,7 +732,7 @@ function promotionFindings({ policy, project, graph }) {
   return findings
 }
 
-export function checkBoundaryPolicy({ project, policy, staged = false, stagedOnly = false, actor = null, gitExecutable = 'git', allowNetworkActorResolution = true, allowHistoryActorResolution = false, forceActorErrors = false } = {}) {
+export function checkBoundaryPolicy({ project, policy, staged = false, stagedOnly = false, actor = null, gitExecutable = 'git', allowNetworkActorResolution = true, allowHistoryActorResolution = false, forceActorErrors = false, delegations = null, ownerKeys = null, now = Date.now(), hookIndex = null } = {}) {
   const validationErrors = validateBoundaryPolicy(policy, project)
   let graph = null
   const findings = validationErrors.map((message) => finding({ severity: 'error', code: 'boundary-policy-invalid', message }))
@@ -645,12 +742,27 @@ export function checkBoundaryPolicy({ project, policy, staged = false, stagedOnl
     for (const node of graph.nodes ?? []) findings.push(...nodePlacementFindings({ node, policy }))
     findings.push(...promotionFindings({ policy, project, graph }))
   }
-  findings.push(...actorFindings({ policy, project, actor, gitExecutable, allowNetworkActorResolution, allowHistoryActorResolution, forceActorErrors }))
+  // Delegations come from their own document, never from the policy. An invalid
+  // document is an error and grants nothing.
+  const delegationErrors = delegations == null ? [] : validateDelegationsDocument(delegations, policy)
+  findings.push(...delegationErrors.map((message) => finding({ severity: 'error', code: 'boundary-delegations-invalid', message })))
+  const delegationList = delegations != null && !delegationErrors.length ? delegations.delegations : []
+  // A staged check is the commit path (the installed pre-commit hook runs it).
+  const operation = staged ? 'pre-commit' : 'boundary-check'
+  findings.push(...actorFindings({ policy, project, actor, gitExecutable, allowNetworkActorResolution, allowHistoryActorResolution, forceActorErrors, operation, delegations: delegationList, ownerKeys, now }))
   if (staged) {
-    const stagedPaths = stagedPathsForProject(project, { gitExecutable })
-    findings.push(...forbiddenPathFindings({ policy, stagedPaths }))
-    findings.push(...semanticDiffFindings({ policy, project, gitExecutable }))
-    findings.push(...stagedContentFindings({ policy, project, gitExecutable }))
+    const { targets, unresolved } = stagedTargets(project, hookIndex, gitExecutable)
+    if (unresolved) {
+      findings.push(finding({
+        code: 'pre-commit-repo-unresolved',
+        message: `${unresolved} is not a repo declared in ${project?.configPath ?? 'the project config'}, or several declared repos share its Git directory; the pre-commit guard cannot tell what is being committed`,
+      }))
+    }
+    const listed = stagedPathsResult(targets, { gitExecutable })
+    findings.push(...listed.failures.map(({ repo, reason }) => unscannableRepoFinding(repo, `staged paths could not be listed (${reason})`)))
+    findings.push(...forbiddenPathFindings({ policy, stagedPaths: listed.paths }))
+    findings.push(...semanticDiffFindings({ targets, gitExecutable }))
+    findings.push(...stagedContentFindings({ policy, targets, gitExecutable }))
   }
   const errors = findings.filter((item) => item.severity === 'error')
   const warnings = findings.filter((item) => item.severity !== 'error')
@@ -673,9 +785,14 @@ export function runBoundaryCheckCommand(argv = process.argv.slice(2)) {
   const project = commandProject({ argv })
   const loaded = loadBoundaryPolicy(project)
   const missingFindings = loaded.errors?.map((message) => finding({ code: 'boundary-policy-missing', message })) ?? []
-  const report = loaded.ok
-    ? checkBoundaryPolicy({ project, policy: loaded.policy, staged, stagedOnly, actor: firstString(args.actor) })
+  const sidecar = loaded.ok ? loadDelegationsFile(delegationsPathFor(loaded.policyPath)) : { present: false, document: null, errors: [] }
+  const sidecarFindings = sidecar.errors.map((message) => finding({ code: 'boundary-delegations-invalid', message }))
+  // Owner keys are read only when a delegations document exists.
+  const ownerKeys = sidecar.present && sidecar.document ? ownerKeysForCommand() : null
+  let report = loaded.ok
+    ? checkBoundaryPolicy({ project, policy: loaded.policy, staged, stagedOnly, actor: firstString(args.actor), delegations: sidecar.document, ownerKeys, hookIndex: staged ? hookIndexFromEnvironment() : null })
     : { ok: false, mode: null, schema: BOUNDARY_POLICY_SCHEMA, graphCounts: null, findings: missingFindings, errors: missingFindings, warnings: [] }
+  if (sidecarFindings.length) report = { ...report, ok: false, findings: [...sidecarFindings, ...report.findings], errors: [...sidecarFindings, ...report.errors] }
 
   if (json) {
     console.log(JSON.stringify(report, null, 2))
@@ -742,7 +859,7 @@ ATELIER_HOOK_PROJECT_CONFIG="$ATELIER_HOOK_REPO_ROOT"/${shellSingleQuote(portabl
   // pre-push reads the ref updates git writes to stdin and judges only that range;
   // pre-commit judges the staged diff. Neither scans the whole tree — that view is
   // `atelier boundary audit`, which reports without blocking.
-  const invocation = hookName === 'pre-push' ? `boundary push-check ${config}` : `boundary check --staged ${config}`
+  const invocation = hookName === 'pre-push' ? `boundary push-check ${config} --remote="\${1:-}"` : `boundary check --staged ${config}`
   return `#!/usr/bin/env bash
 # MNSTRY_ATELIER_BOUNDARY_GUARD ${hookName}
 set -euo pipefail
@@ -788,13 +905,17 @@ export function runBoundaryPushCheckCommand(argv = process.argv.slice(2), { stdi
     console.log('[boundary:push-check] no ref updates on stdin · nothing to judge')
     process.exit(0)
   }
-  const report = checkPushContent({ project, policy: loaded.policy, updates: parsed.updates, cwd: process.cwd() })
+  // The installed hook passes the remote Git names as its first argument.
+  const report = checkPushContent({ project, policy: loaded.policy, updates: parsed.updates, remote: firstString(args.remote), cwd: process.cwd() })
   if (args.json) {
     console.log(JSON.stringify(report, null, 2))
   } else {
     console.log(`[boundary:push-check] ${report.ok ? 'passed' : 'blocked'} · ${report.repo ?? 'unknown repo'} · ${report.errors.length} errors · ${report.warnings.length} warnings`)
-    for (const item of report.findings.slice(0, 50)) console.log(`${item.severity} ${item.rule ?? item.code}: ${item.message}`)
-    if (!report.ok && report.repo) {
+    for (const item of report.findings.slice(0, 50)) {
+      const also = item.commits?.length ? ` (also in commits ${item.commits.map((commit) => commit.slice(0, 12)).join(', ')})` : ''
+      console.log(`${item.severity} ${item.rule ?? item.code}: ${item.message}${also}`)
+    }
+    if (!report.ok && report.repo && report.errors.some((item) => item.code === 'content-rule-violation')) {
       console.log('')
       console.log('If this usage is intentional, declare it in the boundary policy:')
       console.log('  contentRuleExceptions: [{ rule, repo, paths: [...], reason: "why this is accepted" }]')

package/src/build/git.mjs

@@ -0,0 +1,18 @@
+import { execFileSync } from 'node:child_process'
+import { bytesAt, workspaceRoot, digest } from '../capabilities/files.mjs'
+import { harnessRef } from '../harnesses/contracts.mjs'
+import { inspectBuild } from './ledger.mjs'
+
+// Read-only local adapter. A host still owns commands, writer custody and CI.
+export function prepareGitCandidate({ workspaceRoot: input, records, artifact, writer }) {
+  const root = workspaceRoot(input), state = inspectBuild(records)
+  if (!state.establishment) throw new Error('build objective missing')
+  const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.toUpperCase().startsWith('GIT_')))
+  const git = args => execFileSync('git', ['-C', root, ...args], { env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim()
+  if (git(['status', '--porcelain', '--untracked-files=all'])) throw new Error('candidate requires clean repository sources')
+  const commit = git(['rev-parse', 'HEAD']), tree = git(['rev-parse', 'HEAD^{tree}'])
+  const artifactDigest = digest(bytesAt(root, artifact))
+  if (git(['rev-parse', 'HEAD']) !== commit || git(['status', '--porcelain', '--untracked-files=all']) || digest(bytesAt(root, artifact)) !== artifactDigest) throw new Error('candidate changed during capture')
+  return { data: { objective: harnessRef(state.establishment), repository: state.establishment.data.repository, commit, tree, artifactDigest, writer,
+    ...(state.candidate ? { supersedes: harnessRef(state.candidate) } : {}) }, artifact, assurance: 'local-bytes-and-git-observation; writer-is-caller-reported', authority: 'none' }
+}

package/src/build/index.mjs

@@ -0,0 +1,3 @@
+export { inspectBuild } from './ledger.mjs'
+export { prepareGitCandidate } from './git.mjs'
+export { buildReadiness, buildCoordinationProposal } from '../harnesses/exchange.mjs'

package/src/build/ledger.mjs

@@ -0,0 +1,88 @@
+import { replay, unique } from '../harnesses/history.mjs'
+import { assertAudience, assertHandoff } from '../harnesses/contracts.mjs'
+const terminal = new Set(['completed', 'failed', 'cancelled'])
+export function inspectBuild(records) {
+  const attempts = new Map(), gates = new Map(), decisions = []
+  let candidate
+  const state = replay(records, 'build', 'objective', (record, ctx) => {
+    const d = record.data, refs = []
+    const resolve = (pin, kinds) => { const r = ctx.resolve(pin, kinds); refs.push(r.id); return r }
+    const objective = ctx.first.data
+    switch (record.kind) {
+      case 'objective':
+        unique(d.gates.map(g => g.id), 'build gate'); unique(d.dependencies.map(d => d.id), 'build dependency'); unique(d.allowedEffects, 'allowed effect')
+        if (!d.gates.some(g => g.required)) throw new Error('build needs a required gate')
+        for (const dependency of d.dependencies) {
+          const h = assertHandoff(dependency.handoff)
+          if (h.source.profile === 'build' || h.target.profile !== 'build' || h.target.repository !== d.repository) throw new Error('build dependency requires knowledge or inquiry handoff to this repository')
+          assertAudience(d.audience, h.audience)
+        }
+        break
+      case 'candidate':
+        resolve(d.objective, ['objective'])
+        if (d.repository !== objective.repository) throw new Error('candidate repository mismatch')
+        if (candidate) {
+          if (!d.supersedes || ctx.resolve(d.supersedes, ['candidate']).id !== candidate.id) throw new Error('candidate must supersede current candidate')
+          if ([...attempts.values()].some(a => a.candidate === candidate.id && !terminal.has(a.state))) throw new Error('unsettled attempt prevents candidate replacement')
+          ctx.invalidate(candidate.id, `candidate-replaced:${record.id}`)
+        } else if (d.supersedes) throw new Error('initial candidate cannot supersede missing work')
+        candidate = record
+        break
+      case 'attempt':
+        resolve(d.candidate, ['candidate']); unique(d.effects, 'attempt effect')
+        if (d.effects.some(effect => !objective.allowedEffects.includes(effect))) throw new Error('attempt effect is outside declared scope')
+        if (attempts.size >= objective.maxAttempts) throw new Error('build attempt budget exhausted')
+        if ([...attempts.values()].some(a => a.candidate === d.candidate.id && a.operation === d.operation && !['failed', 'cancelled'].includes(a.state))) throw new Error('operation already completed or unsettled; reconcile before retry')
+        attempts.set(record.id, { candidate: d.candidate.id, operation: d.operation, state: 'intent', last: record.id })
+        break
+      case 'progress': {
+        const original = resolve(d.attempt, ['attempt']), previous = attempts.get(original.id)
+        const allowed = { intent: ['running', 'uncertain', 'completed', 'failed', 'cancelled'], running: ['uncertain', 'completed', 'failed', 'cancelled'], uncertain: ['completed', 'failed', 'cancelled'] }
+        if (!allowed[previous.state]?.includes(d.state)) throw new Error('invalid or terminal attempt transition')
+        refs.push(previous.last)
+        attempts.set(original.id, { ...previous, state: d.state, last: record.id })
+        break
+      }
+      case 'gate': {
+        resolve(d.candidate, ['candidate'])
+        if (!objective.gates.some(g => g.id === d.gate)) throw new Error('undeclared build gate')
+        if (d.attempt) {
+          const a = resolve(d.attempt, ['attempt']), status = attempts.get(a.id)
+          if (a.data.candidate.id !== d.candidate.id || (d.status === 'passed' && status.state !== 'completed')) throw new Error('gate requires completed attempt on exact candidate')
+          refs.push(status.last)
+        }
+        const key = `${d.candidate.id}/${d.gate}`, old = gates.get(key)
+        if (old) ctx.invalidate(old.id, `gate-replaced:${record.id}`)
+        gates.set(key, record)
+        break
+      }
+      case 'decision': {
+        resolve(d.candidate, ['candidate']); unique(d.gates.map(g => g.id), 'decision gate')
+        const named = d.gates.map(pin => resolve(pin, ['gate']))
+        if (named.some(g => g.data.candidate.id !== d.candidate.id)) throw new Error('gate names another candidate')
+        if (d.disposition === 'accepted') {
+          for (const required of objective.gates.filter(g => g.required)) {
+            const gate = gates.get(`${d.candidate.id}/${required.id}`)
+            if (!gate || gate.data.status !== 'passed' || !named.some(r => r.id === gate.id)) throw new Error('accepted build requires all current required gates')
+          }
+          if ([...attempts.values()].some(a => a.candidate === d.candidate.id && !terminal.has(a.state))) throw new Error('unsettled attempt prevents acceptance')
+        }
+        if (decisions.length) ctx.invalidate(decisions.at(-1).id, `decision-replaced:${record.id}`)
+        decisions.push(record)
+        break
+      }
+      case 'delivery': {
+        const decision = resolve(d.decision, ['decision'])
+        if (decision.data.disposition !== 'accepted' || decisions.at(-1)?.id !== decision.id) throw new Error('delivery requires latest accepted decision')
+        break
+      }
+    }
+    return refs
+  })
+  const stale = new Set(state.reconsider.map(r => r.id))
+  const decision = decisions.filter(r => !stale.has(r.id)).at(-1)
+  return { ...state, candidate: candidate ?? null, attempts: Object.fromEntries(attempts),
+    gates: [...gates.values()].filter(r => !stale.has(r.id)), decision: decision ?? null,
+    reportedAccepted: decision?.data.disposition === 'accepted',
+    dependencyFreshness: 'unverified-until-snapshots-supplied', executionAuthorized: false, authenticatedAcceptance: false }
+}