@mnstry/atelier 0.2.0-alpha.1 → 0.2.0-alpha.11

package/src/boundary/policy.mjs

@@ -4,14 +4,14 @@ import path from 'node:path'
 import { buildGraph } from '../graph/graph.mjs'
 import { commandProject, firstString, parseArgs, readJson, resolvePathValue, writeJson } from '../project/config.mjs'
 import { matchesPathPattern } from '../project/path-match.mjs'
+import { sanitizedGitEnvironment } from '../runtime/git-adapter.mjs'
 import {
-  diffForPushRange,
-  parseAddedContent,
-  parsePushRefUpdates,
+  CHECK_AGGREGATE_MAX_BYTES,
+  parsePushRefInput,
   resolveContentRules,
-  scanAddedContent,
+  scanPushUpdate,
+  scanStagedRepository,
   scanTree,
-  stagedDiff,
   validateContentRuleExceptions,
   validateContentRules,
 } from './content-rules.mjs'
@@ -146,7 +146,7 @@ export function validateBoundaryPolicy(policy, project = null) {
     const declaredRepos = isObject(repos) ? repos : {}
     for (const [index, exception] of policy.contentRuleExceptions.entries()) {
       const name = firstString(exception?.repo)
-      if (name && Object.keys(declaredRepos).length && !declaredRepos[name]) {
+      if (name && Object.keys(declaredRepos).length && !Object.hasOwn(declaredRepos, name)) {
         errors.push(`contentRuleExceptions[${index}].repo ${name} is not declared in repos`)
       }
     }
@@ -163,7 +163,7 @@ export function validateBoundaryPolicy(policy, project = null) {
     }
     if (!firstString(actor.privateDomainRepo)) errors.push(`actors.${actorId}.privateDomainRepo is required`)
     if (firstString(actor.privateDomainRepo) && isObject(repos)) {
-      const privateRepo = repos[actor.privateDomainRepo]
+      const privateRepo = Object.hasOwn(repos, actor.privateDomainRepo) ? repos[actor.privateDomainRepo] : null
       if (!privateRepo) {
         errors.push(`actors.${actorId}.privateDomainRepo ${actor.privateDomainRepo} is not declared in repos`)
       } else if (privateRepo.kind !== 'private_domain') {
@@ -188,7 +188,7 @@ export function validateBoundaryPolicy(policy, project = null) {
     errors.push(...validAudienceList(repo.forbiddenAudiences, `repos.${repoName}.forbiddenAudiences`))
     if (repo.kind === 'private_domain') {
       if (!firstString(repo.ownerActor)) errors.push(`repos.${repoName}.ownerActor is required for private_domain repos`)
-      if (repo.ownerActor && isObject(actors) && !actors[repo.ownerActor]) errors.push(`repos.${repoName}.ownerActor ${repo.ownerActor} is not declared`)
+      if (repo.ownerActor && isObject(actors) && !Object.hasOwn(actors, repo.ownerActor)) errors.push(`repos.${repoName}.ownerActor ${repo.ownerActor} is not declared`)
     }
   }
 
@@ -197,41 +197,71 @@ export function validateBoundaryPolicy(policy, project = null) {
       if (repo.external) {
         // Declaring a boundary for a repo nobody manages is the confusion the
         // external kind exists to remove.
-        if (repos[repo.name]) errors.push(`policy repos.${repo.name} must not be declared; it is an external (unmanaged) repo`)
+        if (Object.hasOwn(repos, repo.name)) errors.push(`policy repos.${repo.name} must not be declared; it is an external (unmanaged) repo`)
         continue
       }
-      if (!repos[repo.name]) errors.push(`policy repos.${repo.name} must be declared`)
+      if (!Object.hasOwn(repos, repo.name)) errors.push(`policy repos.${repo.name} must be declared`)
     }
   }
 
   return errors
 }
 
-export function resolveCurrentActor({ policy, project, actor = null, env = process.env } = {}) {
+function resolveExplicitActor({ policy, actor, env }) {
   const actors = policy?.actors ?? {}
-  const explicit = actor || env.MNSTRY_ATELIER_ACTOR || env.GITHUB_ACTOR
-  if (explicit && actors[explicit]) return { actorId: explicit, source: 'explicit' }
-  const gitEmails = gitEmailsForProject(project)
-  for (const [actorId, info] of Object.entries(actors)) {
-    const actorEmails = new Set(asArray(info.gitEmails).map((email) => email.toLowerCase()))
-    if (gitEmails.some((email) => actorEmails.has(email.toLowerCase()))) return { actorId, source: 'git-email', gitEmails }
+  const explicit = actor || env.MNSTRY_ATELIER_ACTOR
+  const unverified = (reason) => ({ actorId: null, source: 'unverified', reason })
+  if (actor && env.MNSTRY_ATELIER_ACTOR && actor !== env.MNSTRY_ATELIER_ACTOR) {
+    return unverified('conflicting-explicit-actors')
   }
-  const login = env.GITHUB_ACTOR || ghLogin()
+  if (explicit && !Object.hasOwn(actors, explicit)) return unverified('unknown-explicit-actor')
+  return explicit ? { actorId: explicit, source: 'explicit' } : null
+}
+
+export function resolveCurrentActor({ policy, project, actor = null, env = process.env, gitExecutable = 'git', allowNetworkActorResolution = true, allowHistoryActorResolution = false } = {}) {
+  const actors = policy?.actors ?? {}
+  const explicit = resolveExplicitActor({ policy, actor, env })
+  if (explicit) return explicit
+  const unverified = (reason) => ({ actorId: null, source: 'unverified', reason })
+  // Without an explicit local selector, a platform login precedes Git metadata.
+  // It is platform attribution only; this function cannot authenticate its env.
+  const platformLogin = env.GITHUB_ACTOR
+  if (platformLogin) {
+    const matches = Object.entries(actors).filter(([, info]) =>
+      !String(info.githubLogin || '').endsWith('_GITHUB_LOGIN_PLACEHOLDER') &&
+      String(info.githubLogin || '').toLowerCase() === String(platformLogin).toLowerCase())
+    if (matches.length !== 1) return unverified(matches.length ? 'ambiguous-platform-actor' : 'unknown-platform-actor')
+    return { actorId: matches[0][0], source: 'github-login', githubLogin: platformLogin }
+  }
+  // Keep the legacy option accepted by the API, but history is never evidence
+  // of the person currently operating a checkout.
+  const gitEmails = gitEmailsForProject(project, { gitExecutable, env, allowHistoryActorResolution: false })
+  const matches = Object.entries(actors).filter(([, info]) => {
+    const actorEmails = new Set(asArray(info.gitEmails).map((email) => email.toLowerCase()))
+    return gitEmails.some((email) => actorEmails.has(email.toLowerCase()))
+  })
+  if (matches.length > 1) return unverified('ambiguous-git-actor')
+  if (matches.length === 1) return { actorId: matches[0][0], source: 'git-email', gitEmails }
+  const login = allowNetworkActorResolution ? ghLogin() : null
   if (login) {
-    for (const [actorId, info] of Object.entries(actors)) {
-      if (String(info.githubLogin || '').toLowerCase() === String(login).toLowerCase()) return { actorId, source: 'github-login', githubLogin: login }
-    }
+    const matches = Object.entries(actors).filter(([, info]) => !String(info.githubLogin || '').endsWith('_GITHUB_LOGIN_PLACEHOLDER') && String(info.githubLogin || '').toLowerCase() === String(login).toLowerCase())
+    if (matches.length !== 1) return unverified(matches.length ? 'ambiguous-platform-actor' : 'unknown-platform-actor')
+    return { actorId: matches[0][0], source: 'github-login', githubLogin: login }
   }
-  return { actorId: null, source: 'unverified', gitEmails, githubLogin: login || null }
+  return { actorId: null, source: 'unverified', gitEmails, githubLogin: null }
 }
 
-function gitEmailsForProject(project) {
+function gitEmailsForProject(project, { gitExecutable = 'git', env = process.env, allowHistoryActorResolution = false } = {}) {
   const roots = unique([project?.repoOpsRoot, project?.workspaceRoot, ...managedRepos(project).map((repo) => repo.path)])
   const emails = []
   for (const root of roots) {
     if (!root || !fs.existsSync(root)) continue
-    const result = spawnSync('git', ['-C', root, 'config', 'user.email'], { encoding: 'utf8' })
-    if (result.status === 0 && result.stdout.trim()) emails.push(result.stdout.trim())
+    const probes = [['config', 'user.email']]
+    if (allowHistoryActorResolution) probes.push(['log', '-1', '--format=%ae'])
+    for (const args of probes) {
+      const result = spawnSync(gitExecutable, ['-C', root, ...args], { encoding: 'utf8', env: sanitizedGitEnvironment(env) })
+      if (result.status === 0 && result.stdout.trim()) emails.push(result.stdout.trim())
+    }
   }
   return unique(emails)
 }
@@ -245,7 +275,7 @@ function ghLogin() {
 }
 
 function repoPolicy(policy, repoName) {
-  return policy?.repos?.[repoName] ?? null
+  return policy?.repos && Object.hasOwn(policy.repos, repoName) ? policy.repos[repoName] : null
 }
 
 function finding({ severity = 'error', code, message, repo = null, path: itemPath = null, node = null, details = {} }) {
@@ -276,15 +306,21 @@ function nodePlacementFindings({ node, policy }) {
   return findings
 }
 
-function actorFindings({ policy, project, actor }) {
+function actorFindings({ policy, project, actor, gitExecutable, allowNetworkActorResolution, allowHistoryActorResolution, forceActorErrors }) {
   const findings = []
-  const current = resolveCurrentActor({ policy, project, actor })
-  const severity = severityFor(policy)
-  for (const [repoName, repo] of Object.entries(policy.repos ?? {})) {
-    if (repo.kind !== 'private_domain') continue
-    if (!repo.ownerActor) continue
+  const operatedRepos = new Set(managedRepos(project).map((repo) => repo.name))
+  const ownedRepos = Object.entries(policy.repos ?? {}).filter(([name, repo]) =>
+    operatedRepos.has(name) && repo?.kind === 'private_domain' && repo.ownerActor)
+  const explicit = resolveExplicitActor({ policy, actor, env: process.env })
+  if (explicit?.reason) return [finding({ severity: 'error', code: 'actor-resolution-refused', message: explicit.reason })]
+  // Shared-only work needs no derived identity and must not invoke Git or gh.
+  if (!ownedRepos.length) return findings
+  const current = explicit || resolveCurrentActor({ policy, project, actor, gitExecutable, allowNetworkActorResolution, allowHistoryActorResolution })
+  const severity = forceActorErrors ? 'error' : severityFor(policy)
+  for (const [repoName, repo] of ownedRepos) {
     if (!current.actorId) {
-      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}` }))
+      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}` }))
     }
@@ -292,11 +328,11 @@ function actorFindings({ policy, project, actor }) {
   return findings
 }
 
-export function stagedPathsForProject(project) {
+export function stagedPathsForProject(project, { gitExecutable = 'git' } = {}) {
   const paths = []
   for (const repo of managedRepos(project)) {
     if (!repo.path || !fs.existsSync(path.join(repo.path, '.git'))) continue
-    const result = spawnSync('git', ['-C', repo.path, 'diff', '--cached', '--name-only', '--diff-filter=ACMR'], { encoding: 'utf8' })
+    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) })
@@ -308,7 +344,7 @@ export function stagedPathsForProject(project) {
 function forbiddenPathFindings({ policy, stagedPaths }) {
   const patterns = [...DEFAULT_FORBIDDEN_PATHS, ...asArray(policy.forbiddenPaths)]
   const findings = []
-  const severity = severityFor(policy)
+  const severity = 'error'
   for (const item of stagedPaths) {
     const matched = patterns.find((pattern) => matchesPathPattern(pattern, item.path))
     if (matched) {
@@ -390,13 +426,20 @@ export function semanticChangesInFile(file) {
   return changes
 }
 
-function semanticDiffFindings({ policy, project }) {
+function semanticDiffFindings({ policy, project, gitExecutable = 'git' }) {
   const findings = []
-  const severity = severityFor(policy)
+  const severity = 'error'
   for (const repo of managedRepos(project)) {
-    if (!repo.path || !fs.existsSync(path.join(repo.path, '.git'))) continue
-    const result = spawnSync('git', ['-C', repo.path, 'diff', '--cached', '--unified=0', '--', '*.md', '*.kg.json'], { encoding: 'utf8' })
-    if (result.status !== 0 || !result.stdout.trim()) continue
+    if (!repo.path || !fs.existsSync(path.join(repo.path, '.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) {
+      findings.push(unscannableRepoFinding(repo, 'git diff --cached failed'))
+      continue
+    }
+    if (!result.stdout.trim()) continue
     for (const file of diffFileSections(result.stdout)) {
       const changes = semanticChangesInFile(file)
       if (!changes.length) continue
@@ -419,27 +462,32 @@ function semanticDiffFindings({ policy, project }) {
   return findings
 }
 
-function contentRuleFindings({ policy, project, files }) {
+function stagedContentFindings({ policy, project, gitExecutable = 'git' }) {
   const rules = resolveContentRules(policy)
   const exceptions = asArray(policy?.contentRuleExceptions)
   const findings = []
-  for (const entry of files) {
-    for (const item of scanAddedContent({ files: entry.files, rules, exceptions, repo: entry.repo })) {
-      // The rule id and line stay on the finding: they are what a person needs to
-      // either fix the line or write the exception.
-      findings.push({ ...finding({ ...item, details: { rule: item.rule, line: item.line } }), rule: item.rule, line: item.line })
+  let totalBytes = 0
+  for (const repo of managedRepos(project)) {
+    if (!repo.path || !fs.existsSync(path.join(repo.path, '.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 })
+    findings.push(...result.findings, ...result.diagnostics)
+    totalBytes += result.bytes
+    if (totalBytes > CHECK_AGGREGATE_MAX_BYTES) {
+      findings.push(finding({
+        severity: 'error',
+        code: 'content-scan-incomplete',
+        repo: repo.name,
+        message: `staged evidence exceeds the ${CHECK_AGGREGATE_MAX_BYTES}-byte aggregate limit`,
+      }))
+      break
     }
   }
   return findings
 }
 
-function stagedContentFindings({ policy, project }) {
-  const files = managedRepos(project)
-    .filter((repo) => repo.path && fs.existsSync(path.join(repo.path, '.git')))
-    .map((repo) => ({ repo: repo.name, files: parseAddedContent(stagedDiff(repo.path)) }))
-  return contentRuleFindings({ policy, project, files })
-}
-
 function realPath(value) {
   try {
     return fs.realpathSync(path.resolve(value))
@@ -467,7 +515,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() } = {}) {
+export function checkPushContent({ project, policy, repo, updates, 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
@@ -480,20 +528,41 @@ export function checkPushContent({ project, policy, repo, updates, cwd = process
     })
     return { ok: false, repo: null, findings: [unresolved], errors: [unresolved], warnings: [] }
   }
-  const files = []
-  for (const update of updates) files.push(...parseAddedContent(diffForPushRange(target.path, update)))
-  const findings = contentRuleFindings({ policy, project, files: [{ repo: target.name, files }] })
+  const rules = resolveContentRules(policy)
+  const exceptions = asArray(policy?.contentRuleExceptions)
+  const findings = []
+  let totalBytes = 0
+  for (const update of updates) {
+    const result = scanPushUpdate({ repoRoot: target.path, update, rules, exceptions, repo: target.name, gitRunner })
+    findings.push(...result.findings, ...result.diagnostics)
+    totalBytes += result.bytes
+    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`,
+      }))
+      break
+    }
+  }
   const errors = findings.filter((item) => item.severity === 'error')
   return { ok: errors.length === 0, repo: target.name, updates, findings, errors, warnings: findings.filter((item) => item.severity !== 'error') }
 }
 
-export function auditContentRules({ project, policy } = {}) {
+export function auditContentRules({ project, policy, source = 'working-tree' } = {}) {
   const rules = resolveContentRules(policy)
   const exceptions = asArray(policy?.contentRuleExceptions)
   const findings = []
+  const diagnostics = []
   for (const repo of managedRepos(project)) {
-    if (!repo.path || !fs.existsSync(path.join(repo.path, '.git'))) continue
-    findings.push(...scanTree(repo.path, { rules, exceptions, repo: repo.name }))
+    if (!repo.path || !fs.existsSync(path.join(repo.path, '.git'))) {
+      diagnostics.push(unscannableRepoFinding(repo, 'configured path is absent or is not a Git checkout'))
+      continue
+    }
+    const result = scanTree(repo.path, { rules, exceptions, repo: repo.name, source })
+    findings.push(...result.findings)
+    diagnostics.push(...result.diagnostics)
   }
   const accepted = []
   for (const repo of managedRepos(project)) {
@@ -502,7 +571,16 @@ export function auditContentRules({ project, policy } = {}) {
       accepted.push({ repo: repo.name, rule: exception.rule, paths: exception.paths, reason: exception.reason })
     }
   }
-  return { schema: BOUNDARY_POLICY_SCHEMA, findings, accepted }
+  return { schema: BOUNDARY_POLICY_SCHEMA, source, findings, diagnostics, accepted }
+}
+
+function unscannableRepoFinding(repo, reason) {
+  return finding({
+    severity: 'error',
+    code: 'repo-unscannable',
+    repo: repo?.name ?? null,
+    message: `${repo?.name ?? '(unnamed repo)'} cannot be scanned: ${reason}`,
+  })
 }
 
 function promotionRecords(project, policy) {
@@ -557,24 +635,22 @@ function promotionFindings({ policy, project, graph }) {
   return findings
 }
 
-export function checkBoundaryPolicy({ project, policy, staged = false, stagedOnly = false, actor = null } = {}) {
+export function checkBoundaryPolicy({ project, policy, staged = false, stagedOnly = false, actor = null, gitExecutable = 'git', allowNetworkActorResolution = true, allowHistoryActorResolution = false, forceActorErrors = false } = {}) {
   const validationErrors = validateBoundaryPolicy(policy, project)
   let graph = null
-  const findings = validationErrors.map((message) => finding({ severity: severityFor(policy), code: 'boundary-policy-invalid', message }))
-  if (validationErrors.length === 0) {
-    if (!stagedOnly) {
-      graph = buildGraph(project)
-      findings.push(...graph.errors.map((message) => finding({ severity: severityFor(policy), code: 'knowledge-graph-invalid', message })))
-      for (const node of graph.nodes ?? []) findings.push(...nodePlacementFindings({ node, policy }))
-      findings.push(...promotionFindings({ policy, project, graph }))
-    }
-    findings.push(...actorFindings({ policy, project, actor }))
-    if (staged) {
-      const stagedPaths = stagedPathsForProject(project)
-      findings.push(...forbiddenPathFindings({ policy, stagedPaths }))
-      findings.push(...semanticDiffFindings({ policy, project }))
-      findings.push(...stagedContentFindings({ policy, project }))
-    }
+  const findings = validationErrors.map((message) => finding({ severity: 'error', code: 'boundary-policy-invalid', message }))
+  if (!stagedOnly) {
+    graph = buildGraph(project)
+    findings.push(...graph.errors.map((message) => finding({ severity: 'error', code: 'knowledge-graph-invalid', message })))
+    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 }))
+  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 errors = findings.filter((item) => item.severity === 'error')
   const warnings = findings.filter((item) => item.severity !== 'error')
@@ -616,12 +692,12 @@ export function installBoundaryHooks({ project, force = false } = {}) {
   const skipped = []
   for (const repo of managedRepos(project)) {
     if (!repo.path || !fs.existsSync(path.join(repo.path, '.git'))) continue
-    const hooksDir = path.join(repo.path, '.git', 'hooks')
+    const hooksDir = gitHooksDir(repo.path)
     fs.mkdirSync(hooksDir, { recursive: true })
     for (const hookName of ['pre-commit', 'pre-push']) {
       const hookPath = path.join(hooksDir, hookName)
       const existing = fs.existsSync(hookPath) ? fs.readFileSync(hookPath, 'utf8') : ''
-      const script = hookScript(project.configPath, hookName)
+      const script = boundaryHookScript(project.configPath, hookName, repo.path)
       if (existing && !existing.includes('MNSTRY_ATELIER_BOUNDARY_GUARD') && !force) {
         const sidecar = `${hookPath}.mnstry-atelier-boundary`
         fs.writeFileSync(sidecar, script)
@@ -637,8 +713,32 @@ export function installBoundaryHooks({ project, force = false } = {}) {
   return { installed, skipped }
 }
 
-function hookScript(projectConfigPath, hookName) {
-  const config = projectConfigPath ? `--project-config=${projectConfigPath.replaceAll('"', '\\"')}` : ''
+function gitHooksDir(repoPath) {
+  const result = spawnSync('git', ['-C', repoPath, 'rev-parse', '--git-path', 'hooks'], { encoding: 'utf8' })
+  if (result.status !== 0 || !result.stdout.trim()) throw new Error(`cannot resolve Git hooks directory for ${repoPath}`)
+  const value = result.stdout.trim()
+  return path.isAbsolute(value) ? value : path.resolve(repoPath, value)
+}
+
+function shellSingleQuote(value) {
+  const text = String(value ?? '')
+  if (!text || /[\0\r\n]/.test(text)) throw new Error('project config path contains unsupported control characters')
+  return `'${text.replaceAll("'", `'"'"'`)}'`
+}
+
+export function boundaryHookScript(projectConfigPath, hookName, repoPath) {
+  const relativeConfigPath = projectConfigPath && repoPath ? path.relative(repoPath, projectConfigPath) : null
+  const configLivesInRepo = relativeConfigPath && relativeConfigPath !== '..' && !relativeConfigPath.startsWith(`..${path.sep}`) && !path.isAbsolute(relativeConfigPath)
+  const portableRelativeConfig = configLivesInRepo ? relativeConfigPath.replaceAll(path.sep, '/') : null
+  const configSetup = configLivesInRepo
+    ? `ATELIER_HOOK_REPO_ROOT="$(git rev-parse --show-toplevel)"
+ATELIER_HOOK_PROJECT_CONFIG="$ATELIER_HOOK_REPO_ROOT"/${shellSingleQuote(portableRelativeConfig)}`
+    : ''
+  const config = configLivesInRepo
+    ? '--project-config="$ATELIER_HOOK_PROJECT_CONFIG"'
+    : projectConfigPath
+      ? `--project-config=${shellSingleQuote(projectConfigPath)}`
+      : ''
   // 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.
@@ -646,6 +746,7 @@ function hookScript(projectConfigPath, hookName) {
   return `#!/usr/bin/env bash
 # MNSTRY_ATELIER_BOUNDARY_GUARD ${hookName}
 set -euo pipefail
+${configSetup}
 if command -v atelier >/dev/null 2>&1; then
   exec atelier ${invocation}
 elif [ -x "./node_modules/.bin/atelier" ]; then
@@ -663,7 +764,7 @@ fi
 `
 }
 
-export function runBoundaryPushCheckCommand(argv = process.argv.slice(2), { stdin = readStdin() } = {}) {
+export function runBoundaryPushCheckCommand(argv = process.argv.slice(2), { stdin = readBoundaryPushInput() } = {}) {
   const args = parseArgs(argv)
   const project = commandProject({ argv })
   const loaded = loadBoundaryPolicy(project)
@@ -671,12 +772,23 @@ export function runBoundaryPushCheckCommand(argv = process.argv.slice(2), { stdi
     console.error(loaded.errors.join('\n'))
     process.exit(1)
   }
-  const updates = parsePushRefUpdates(stdin)
-  if (!updates.length) {
+  const input = stdin && typeof stdin === 'object' && Object.hasOwn(stdin, 'ok')
+    ? stdin
+    : { ok: true, text: String(stdin ?? '') }
+  if (!input.ok) {
+    console.error('[boundary:push-check] could not read pre-push ref updates')
+    process.exit(1)
+  }
+  const parsed = parsePushRefInput(input.text)
+  if (!parsed.ok) {
+    console.error(`[boundary:push-check] invalid pre-push input: ${parsed.issues.join('; ')}`)
+    process.exit(1)
+  }
+  if (parsed.kind === 'empty') {
     console.log('[boundary:push-check] no ref updates on stdin · nothing to judge')
     process.exit(0)
   }
-  const report = checkPushContent({ project, policy: loaded.policy, updates, cwd: process.cwd() })
+  const report = checkPushContent({ project, policy: loaded.policy, updates: parsed.updates, cwd: process.cwd() })
   if (args.json) {
     console.log(JSON.stringify(report, null, 2))
   } else {
@@ -691,6 +803,10 @@ export function runBoundaryPushCheckCommand(argv = process.argv.slice(2), { stdi
   process.exit(report.ok ? 0 : 1)
 }
 
+export function resolveBoundaryAuditSource(args = {}) {
+  return args.head ? 'head' : firstString(args.source) || 'working-tree'
+}
+
 export function runBoundaryAuditCommand(argv = process.argv.slice(2)) {
   const args = parseArgs(argv)
   const project = commandProject({ argv })
@@ -699,23 +815,29 @@ export function runBoundaryAuditCommand(argv = process.argv.slice(2)) {
     console.error(loaded.errors.join('\n'))
     process.exit(1)
   }
-  const report = auditContentRules({ project, policy: loaded.policy })
+  const source = resolveBoundaryAuditSource(args)
+  if (!['working-tree', 'head'].includes(source)) {
+    console.error('boundary audit --source must be working-tree or head')
+    process.exit(1)
+  }
+  const report = auditContentRules({ project, policy: loaded.policy, source })
   if (args.json) {
     console.log(JSON.stringify(report, null, 2))
   } else {
-    console.log(`[boundary:audit] ${report.findings.length} content-rule matches across the tree · ${report.accepted.length} declared exceptions`)
+    console.log(`[boundary:audit] ${report.findings.length} content-rule matches · ${report.diagnostics.length} incomplete reads · ${report.accepted.length} declared exceptions · source ${report.source}`)
     for (const item of report.findings.slice(0, 100)) console.log(`${item.severity} ${item.rule}: ${item.message}`)
+    for (const item of report.diagnostics.slice(0, 100)) console.log(`${item.severity} ${item.code}: ${item.message}`)
     for (const item of report.accepted) console.log(`accepted ${item.rule} in ${item.repo} (${item.paths.join(', ')}): ${item.reason}`)
   }
   // Reporting only. A pre-existing accepted usage must never block unrelated work.
   process.exit(0)
 }
 
-function readStdin() {
+export function readBoundaryPushInput(reader = () => fs.readFileSync(0, 'utf8')) {
   try {
-    return fs.readFileSync(0, 'utf8')
+    return { ok: true, text: reader() }
   } catch {
-    return ''
+    return { ok: false, text: '', error: 'stdin-read-failed' }
   }
 }
 

package/src/cli/execute-command.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+const [, , requestedScript, ...args] = process.argv
+
+function renderError(error) {
+  const debug = process.env.ATELIER_DEBUG === '1'
+  if (debug) {
+    console.error(error?.stack || String(error))
+    return Number.isInteger(error?.exitCode) ? error.exitCode : 1
+  }
+  if (typeof error?.code === 'string' && error.code) {
+    console.error(`[${error.code}] ${error.message}`)
+    if (error.hint) console.error(`Next: ${error.hint}`)
+    return Number.isInteger(error.exitCode) ? error.exitCode : 2
+  }
+  console.error('[internal-error] command failed without a safe diagnostic')
+  console.error('Next: rerun with ATELIER_DEBUG=1 to inspect the stack locally.')
+  return 1
+}
+
+if (!requestedScript) {
+  console.error('[command-missing] no command module was selected')
+  process.exit(2)
+}
+
+const scriptPath = path.resolve(requestedScript)
+process.argv = [process.execPath, scriptPath, ...args]
+
+try {
+  await import(pathToFileURL(scriptPath).href)
+} catch (error) {
+  process.exitCode = renderError(error)
+}

package/src/cli/project-options.mjs

@@ -0,0 +1,58 @@
+// Shared project-location syntax. Command-specific arguments remain owned by
+// their command; this parser does not make unknown options globally valid.
+export const PROJECT_OPTION_SPEC = Object.freeze({
+  project: 'value',
+  'project-config': 'value',
+  'repo-path': 'value',
+})
+
+function invalid(message) {
+  const error = new Error(message)
+  error.code = 'project-option-invalid'
+  error.exitCode = 2
+  throw error
+}
+
+export function projectOptionAt(argv, index, configArgPrefix = '--project-config=') {
+  const arg = argv[index]
+  if (typeof arg !== 'string' || !arg.startsWith('--')) return null
+  const name = arg.slice(2).split('=')[0]
+  const custom = configArgPrefix !== '--project-config=' && arg.startsWith(configArgPrefix)
+  if (!custom && !Object.hasOwn(PROJECT_OPTION_SPEC, name)) return null
+  const inline = custom || arg.includes('=')
+  const value = custom ? arg.slice(configArgPrefix.length) : inline ? arg.slice(arg.indexOf('=') + 1) : argv[index + 1]
+  if (typeof value !== 'string' || !value.trim() || value.startsWith('--')) {
+    invalid(`--${custom ? 'project-config' : name} requires a non-empty value`)
+  }
+  const option = custom ? 'project-config' : name
+  if (option === 'repo-path') {
+    const separator = value.indexOf('=')
+    if (separator < 1 || !value.slice(0, separator).trim() || !value.slice(separator + 1).trim()) {
+      invalid('--repo-path requires NAME=PATH')
+    }
+  }
+  return { name: option, value, nextIndex: index + (inline ? 1 : 2) }
+}
+
+export function parseProjectOptions(argv = [], configArgPrefix = '--project-config=') {
+  let project = null
+  const repoPaths = new Map()
+  const remaining = []
+  for (let index = 0; index < argv.length;) {
+    const option = projectOptionAt(argv, index, configArgPrefix)
+    if (!option) {
+      remaining.push(argv[index++])
+      continue
+    }
+    if (option.name === 'repo-path') {
+      const separator = option.value.indexOf('=')
+      repoPaths.set(option.value.slice(0, separator).trim(), option.value.slice(separator + 1))
+    } else if (project === null) {
+      // Preserve the resolver's first project selection and last named repo
+      // override behavior, including aliases in the same invocation.
+      project = option.value.trim()
+    }
+    index = option.nextIndex
+  }
+  return { project, repoPaths, remaining }
+}