@mnstry/atelier 0.2.0-alpha.4 → 0.2.0-alpha.6

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'
@@ -207,16 +207,16 @@ export function validateBoundaryPolicy(policy, project = null) {
   return errors
 }
 
-export function resolveCurrentActor({ policy, project, actor = null, env = process.env } = {}) {
+export function resolveCurrentActor({ policy, project, actor = null, env = process.env, gitExecutable = 'git', allowNetworkActorResolution = true, allowHistoryActorResolution = true } = {}) {
   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)
+  const gitEmails = gitEmailsForProject(project, { gitExecutable, env, allowHistoryActorResolution })
   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 login = env.GITHUB_ACTOR || ghLogin()
+  const login = env.GITHUB_ACTOR || (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 }
@@ -225,13 +225,17 @@ export function resolveCurrentActor({ policy, project, actor = null, env = proce
   return { actorId: null, source: 'unverified', gitEmails, githubLogin: login || null }
 }
 
-function gitEmailsForProject(project) {
+function gitEmailsForProject(project, { gitExecutable = 'git', env = process.env, allowHistoryActorResolution = true } = {}) {
   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)
 }
@@ -276,10 +280,10 @@ 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)
+  const current = resolveCurrentActor({ policy, project, actor, gitExecutable, allowNetworkActorResolution, allowHistoryActorResolution })
+  const severity = forceActorErrors ? 'error' : severityFor(policy)
   for (const [repoName, repo] of Object.entries(policy.repos ?? {})) {
     if (repo.kind !== 'private_domain') continue
     if (!repo.ownerActor) continue
@@ -292,11 +296,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 +312,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 +394,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 +430,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 +483,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 +496,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 +539,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 +603,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 = true, 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 +660,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 +681,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 +714,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 +732,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 +740,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 +771,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 +783,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/run.mjs

@@ -51,11 +51,14 @@ export const commandMap = new Map([
   ['extension-pack:list', ['src/commands/extension-pack.mjs', 'list']],
   ['distribution', ['src/commands/distribution.mjs']],
   ['distribution:check', ['src/commands/distribution.mjs', 'check']],
+  ['disclosure', ['src/commands/disclosure.mjs']],
+  ['disclosure:check', ['src/commands/disclosure.mjs', 'check']],
   ['attestation', ['src/commands/attestation.mjs']],
   ['feedback', ['src/commands/feedback.mjs']],
   ['feedback:check', ['src/commands/feedback.mjs', 'check']],
   ['announcements', ['src/commands/announcements.mjs']],
   ['announcements:list', ['src/commands/announcements.mjs', 'list']],
+  ['sync', ['src/commands/sync.mjs']],
 ])
 
 function isDefaultBrand(brand) {
@@ -113,6 +116,12 @@ Core commands:
   support bundle --dry-run        Preview a no-send support bundle.
   feedback --message TEXT         Write a local, never-sent feedback report.
   announcements list              List and verify MNSTRY announcements.
+  sync enroll                     Explicitly enroll one repository for supervision.
+  sync status                     Fully observe the enrolled repository.
+  sync reconcile                  Fetch and perform only proven fast-forwards.
+  sync plan                       Prepare one bounded, reviewable commit plan.
+  sync commit                     Execute an exactly confirmed commit plan.
+  sync run --once                 Run one full-state supervisor cycle.
   egress check                    Check extracted Atelier paths for forbidden egress.
   boundary check                  Enforce private/shared repo placement rules.
   boundary audit                  Report content-rule matches tree-wide without blocking.
@@ -125,6 +134,7 @@ Core commands:
   extension-pack validate         Validate declared extension packs.
   extension-pack list             List declared extension packs.
   distribution check              Check a distribution for MNSTRY attribution.
+  disclosure check                Scan tracked or staged content for disclosure risks.
 
 Attestation commands:
   attestation hash FILE           Print the canonical payload hash of a payload.
@@ -132,8 +142,10 @@ Attestation commands:
   attestation verify FILE         Verify an attestation against a public key file.
   attestation keygen --key-id ID  Generate a signing key pair.
 
-Every project-aware command accepts --project-config=PATH or
-MNSTRY_ATELIER_PROJECT_CONFIG=PATH. Machine-local repo paths belong in
+Commands whose usage names --project accept --project=PATH or --project PATH.
+The project resolver also accepts --project-config=PATH and
+MNSTRY_ATELIER_PROJECT_CONFIG=PATH; each command's own help is authoritative.
+Machine-local repo paths belong in
 .atelier-local/, atelier.local.json, or atelier.workspace.local.json.`
 }
 
@@ -152,9 +164,9 @@ Ensures ignored local Atelier state exists, verifies ignore coverage, and record
     doctor: `Usage: ${c} doctor [--project ./atelier.project.json] [--fix] [--dry-run]
 
 Reports project config, local overlay, and repo boundary readiness. --fix only repairs ignored local state.`,
-    boundary: `Usage: ${c} boundary check|push-check|audit|install-hooks [--project ./atelier.project.json] [--staged]
+    boundary: `Usage: ${c} boundary check|push-check|audit|install-hooks [--project ./atelier.project.json] [--staged] [--source=working-tree|head]
 
-check --staged judges the staged diff. push-check reads pre-push ref updates on stdin and judges only the pushed range. audit scans the whole tree and reports without blocking, so an accepted usage never strands unrelated work.`,
+check --staged judges the staged diff. push-check reads pre-push ref updates on stdin and judges only the pushed range. audit scans the working tree by default and reports without blocking; --source=head selects the committed snapshot.`,
     graph: `Usage: ${c} graph [--check] [--project ./atelier.project.json]
 
 Builds or checks the project knowledge graph from tracked sources plus ignored local path bindings.`,
@@ -175,21 +187,35 @@ Loads every extension pack declared under ext["mnstry.atelier"].extensionPacks i
     distribution: `Usage: ${c} distribution check [--target DIR] [--pack DIR]
 
 Checks a distribution package for the required MNSTRY attribution markers. Blocking: the distribution README.md byte check, and a CLI probe that EXECUTES the target's declared bin with --version (spawned with the current Node, cwd set to the target — only run this against distributions you trust) and requires the attribution in its output; a target that looks like a distribution but declares no probe-able bin, or ships a malformed package.json, is also blocking. The extension-pack manifest attribution key is advisory and reported only. The normative wording lives in TRADEMARKS.md under "Required attribution"; see also docs/attestation.md and docs/distributions.md.`,
+    disclosure: `Usage: ${c} disclosure check [--root DIR] [--staged] [--denylist FILE | --structural-only] [--fail-on-binary] [--untrusted]
+
+Scans Git-tracked files, or staged index blobs with --staged, without following symlinks. A private denylist is required by default and must be supplied through ATELIER_DENYLIST_JSON, --denylist, or ignored .atelier-local/disclosure-denylist.json. --structural-only is the explicit no-denylist lane. --untrusted suppresses finding details.`,
     attestation: `Usage:
   ${c} attestation hash <payload.json>
   ${c} attestation sign <attestation.json> [--key FILE] [--out FILE]
   ${c} attestation verify <attestation.json> --public-key FILE [--payload FILE] [--json]
   ${c} attestation keygen --key-id ID [--algorithm ed25519|es256] [--out FILE]
 
-Records and checks admission decisions. hash prints the canonical payload hash (RFC 8785 JCS, SHA-256). sign reads the local signing key file. verify reads a public key file and exits 1 when it judges the attestation invalid. keygen writes the signing key file mode 0600, refuses to overwrite, and prints only the public key document.`,
+Records and checks admission decisions. hash prints the canonical payload hash (RFC 8785 JCS, SHA-256). sign reads the local signing key file. verify reads a public key file and exits 1 when it judges the attestation invalid. keygen writes the signing key file mode 0600 on POSIX, refuses to overwrite, and prints only the public key document.`,
     feedback: `Usage:
   ${c} feedback create --message TEXT | --message-file PATH [--context FILE] [--include-gates]
   ${c} feedback check FILE
 
-Assembles a local feedback report under ignored .atelier-local/feedback/ (mode 0600), scanned with the support-bundle banned key and value patterns before writing; any match refuses the write naming pattern label and location only. Files given to --message-file and --context must be valid UTF-8 text of at most 262144 bytes. The scan is a backstop, not clearance: read the whole report before sharing it. The kit has no send path — sharing the file is always the user's own explicit act.`,
+Assembles a local feedback report under ignored .atelier-local/feedback/ (mode 0600 on POSIX), scanned with the support-bundle banned key and value patterns before writing; any match refuses the write naming pattern label and location only. Files given to --message-file and --context must be valid UTF-8 text of at most 262144 bytes. The scan is a backstop, not clearance: read the whole report before sharing it. The kit has no send path — sharing the file is always the user's own explicit act.`,
     announcements: `Usage: ${c} announcements list [--dir DIR] [--public-key FILE] | verify <file> [--public-key FILE] [--json] | show <file> [--public-key FILE]
 
 MNSTRY announcements are a pull-only channel: signed JSON documents under announcements/ in the repository. The trust anchor is always the committed MNSTRY key, or one you pass explicitly with --public-key; --dir changes only where documents are read from and never which key verifies them. Every run names the key and keyId it used. The kit never fetches anything — receiving announcements is the git pull you chose to run, and show refuses to print a body whose signature does not verify.`,
+    sync: `Usage:
+  ${c} sync enroll --repo DIR [--project atelier.project.json] [--git ABSOLUTE_PATH]
+  ${c} sync status --repo DIR
+  ${c} sync reconcile --repo DIR [--retries 3]
+  ${c} sync run --repo DIR [--once] [--interval 30]
+  ${c} sync plan --repo DIR --path FILE [--path FILE] --message TEXT [--publish]
+  ${c} sync commit --repo DIR --operation ID --confirm ID
+  ${c} sync pause|freeze|resume --repo DIR
+  ${c} sync trace --repo DIR
+
+Enrolls exactly one repository and keeps Git plus readable files authoritative. Reconciliation observes the complete repository every cycle and performs only fast-forward updates. Commit creation is a two-phase user-confirmed operation: plan shows one bounded change set, and commit refuses unless the repository is unchanged and --confirm exactly repeats the operation id. No semantic conflict resolution, force operation, browser apply endpoint, telemetry, or desktop shell is present.`,
   }
   return help[command] || `Usage: ${c} ${command} [args]\n\nRun ${c} --help for the command list.`
 }
@@ -219,6 +245,7 @@ function normalizeArgs(argv) {
   if (args[0] === 'extension-pack' && args[1] === 'validate') args.splice(0, 2, 'extension-pack:validate')
   if (args[0] === 'extension-pack' && args[1] === 'list') args.splice(0, 2, 'extension-pack:list')
   if (args[0] === 'distribution' && args[1] === 'check') args.splice(0, 2, 'distribution:check')
+  if (args[0] === 'disclosure' && args[1] === 'check') args.splice(0, 2, 'disclosure:check')
   if (args[0] === 'support' && args[1] === 'bundle') args.splice(0, 2, 'support:bundle')
   if (args[0] === 'support:bundle' && args[1] === '--dry-run') args.splice(1, 1)
   return { help: false, args }
@@ -261,12 +288,13 @@ export async function runCli({
 
   const [script, ...prefixArgs] = target
   const scriptPath = path.join(packageRoot, script)
+  const executorPath = path.join(packageRoot, 'src', 'cli', 'execute-command.mjs')
   if (!fs.existsSync(scriptPath)) {
     stderr(`${brand.displayName} command is not available in this package install: ${command}`)
     return 1
   }
 
-  const result = spawnSync(process.execPath, [scriptPath, ...prefixArgs, ...rest], {
+  const result = spawnSync(process.execPath, [executorPath, scriptPath, ...prefixArgs, ...rest], {
     cwd,
     stdio: 'inherit',
     env: {