@mnstry/atelier 0.2.0-alpha.13 → 0.2.0-alpha.15

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,
@@ -299,6 +302,19 @@ function finding({ severity = 'error', code, message, repo = null, path: itemPat
   return { severity, code, message, repo, path: itemPath, node, details }
 }
 
+// Text output lists blocking errors before warnings, with incomplete or unresolved evidence first within each
+// severity group. The report and --json keep every finding in their original order.
+const PRINTED_FINDINGS_MAX = 50
+const INCOMPLETE_SCAN_CODES = new Set(['content-scan-incomplete', 'semantic-field-scan-incomplete', 'repo-unscannable', 'pre-commit-repo-unresolved', 'push-check-repo-unresolved'])
+
+function printedFindings(findings) {
+  const ordered = [true, false].flatMap((blocking) => {
+    const group = findings.filter((item) => (item.severity === 'error') === blocking)
+    return [...group.filter((item) => INCOMPLETE_SCAN_CODES.has(item.code)), ...group.filter((item) => !INCOMPLETE_SCAN_CODES.has(item.code))]
+  })
+  return { shown: ordered.slice(0, PRINTED_FINDINGS_MAX), hidden: Math.max(0, ordered.length - PRINTED_FINDINGS_MAX) }
+}
+
 function severityFor(policy) {
   return policy?.mode === 'legacy-warning' ? 'warning' : 'error'
 }
@@ -358,17 +374,90 @@ function actorFindings({ policy, project, actor, gitExecutable, allowNetworkActo
   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'))) {
+      failures.push({ repo, reason: 'configured-path-absent-or-not-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', '--no-renames', '--diff-filter=ACMRT'], { gitExecutable, indexFile: target.indexFile, maxBuffer: CHECK_AGGREGATE_MAX_BYTES })
+    if (!result.ok || (result.stdout && !result.stdout.endsWith('\0'))) {
+      failures.push({ repo, reason: result.code ?? 'unterminated-staged-path-evidence' })
+      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 } = {}) {
+  const { targets, unresolved } = stagedTargets(project, hookIndex, gitExecutable)
+  const result = stagedPathsResult(targets, { gitExecutable })
+  if (unresolved) throw new Error('the committing repository could not be resolved; staged paths are incomplete')
+  if (result.failures.length) throw new Error('staged paths could not be listed completely')
+  return result.paths
 }
 
 function forbiddenPathFindings({ policy, stagedPaths }) {
@@ -405,42 +494,48 @@ export function semanticFieldOnLine(line) {
   return { field: null, value: null, raw: line.trim() }
 }
 
+// A hunk cannot establish the quote/comment state at its first line. Every literal boundary assignment therefore
+// remains a review signal, including examples inside quoted text. A plain mention is not an assignment. Keep the
+// whole suffix: trimming a partial collection or comment could misread it as the private initialization default.
+function semanticFieldsOnLine(line) {
+  const raw = String(line).trim()
+  const values = []
+  const match = raw.match(/(?:^|[^\w.])["']?(kg\.audience|audience|handling|sensitivity|data_boundary)["']?\s*:/i)
+  if (match) values.push({ field: match[1].toLowerCase().replace(/^kg\./, ''), value: unquoteValue(raw.slice(match.index + match[0].length)), raw })
+  // Complete escaped JSON keys add signals without guessing the document context or changing the legacy helper.
+  for (const escaped of raw.matchAll(/("(?:\\.|[^"\\])*")\s*:/g)) {
+    if (!escaped[1].includes('\\')) continue
+    try {
+      const field = JSON.parse(escaped[1]).toLowerCase().replace(/^kg\./, '')
+      if (['audience', 'handling', 'sensitivity', 'data_boundary'].includes(field)) {
+        values.push({ field, value: unquoteValue(raw.slice(escaped.index + escaped[0].length)), raw })
+        break
+      }
+    } catch { /* Invalid quoted key text has no decoded field identity. */ }
+  }
+  return values
+}
+
 function isInitializationDefault(field, value) {
   const defaults = SEMANTIC_INITIALIZATION_DEFAULTS[field]
   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) {
   const changes = []
   for (const hunk of file.hunks ?? []) {
-    const pending = hunk.removed.map(semanticFieldOnLine).filter(Boolean)
-    for (const entry of hunk.added.map(semanticFieldOnLine).filter(Boolean)) {
+    const pending = hunk.removed.flatMap(semanticFieldsOnLine)
+    for (const entry of hunk.added.flatMap(semanticFieldsOnLine)) {
       const index = pending.findIndex((item) => item.field === entry.field)
       const prior = index === -1 ? null : pending.splice(index, 1)[0]
       if (prior) {
@@ -456,26 +551,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', '--no-renames']), '--', '*.md', '*.kg.json'], { gitExecutable, indexFile: target.indexFile, maxBuffer: CHECK_AGGREGATE_MAX_BYTES })
+    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({
@@ -492,17 +599,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) {
@@ -545,7 +652,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
@@ -563,15 +670,18 @@ 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, aggregateLimitBytes: CHECK_AGGREGATE_MAX_BYTES })
     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`,
+        details: { reason: 'push-evidence-too-large', limitBytes: CHECK_AGGREGATE_MAX_BYTES },
       }))
       break
     }
@@ -665,7 +775,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, delegations = null, ownerKeys = null, now = Date.now() } = {}) {
+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 }))
@@ -684,10 +794,18 @@ export function checkBoundaryPolicy({ project, policy, staged = false, stagedOnl
   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')
@@ -715,7 +833,7 @@ export function runBoundaryCheckCommand(argv = process.argv.slice(2)) {
   // 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 })
+    ? 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] }
 
@@ -724,9 +842,12 @@ export function runBoundaryCheckCommand(argv = process.argv.slice(2)) {
   } else {
     const label = report.ok ? 'passed' : 'failed'
     console.log(`[boundary:check] ${label} · ${report.errors.length ?? report.findings.filter((item) => item.severity === 'error').length} errors · ${report.warnings.length ?? report.findings.filter((item) => item.severity !== 'error').length} warnings`)
-    for (const item of report.findings.slice(0, 50)) console.log(`${item.severity ?? 'error'} ${item.code}: ${item.message}`)
+    const { shown, hidden } = printedFindings(report.findings)
+    for (const item of shown) console.log(`${item.severity ?? 'error'} ${item.code}: ${item.message}`)
+    if (hidden) console.log(`${hidden} more not shown; --json lists every finding`)
   }
-  process.exit(report.ok ? 0 : 1)
+  // Let queued stdout drain before the command process exits, including a complete JSON report through a pipe.
+  process.exitCode = report.ok ? 0 : 1
 }
 
 export function installBoundaryHooks({ project, force = false } = {}) {
@@ -784,7 +905,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
@@ -830,13 +951,19 @@ 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) {
+    const { shown, hidden } = printedFindings(report.findings)
+    for (const item of shown) {
+      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 (hidden) console.log(`${hidden} more not shown; --json lists every finding`)
+    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/cli/run.mjs

@@ -48,6 +48,11 @@ export const commandMap = new Map([
   ['config', ['src/commands/config.mjs']],
   ['config:check', ['src/commands/config.mjs']],
   ['manifest', ['src/commands/config.mjs']],
+  ['extension', ['src/commands/extension.mjs']],
+  ['extension:init', ['src/commands/extension.mjs', 'init']],
+  ['extension:validate', ['src/commands/extension.mjs', 'validate']],
+  ['extension:seal', ['src/commands/extension.mjs', 'seal']],
+  ['extension:bundle', ['src/commands/extension.mjs', 'bundle']],
   ['extension-pack', ['src/commands/extension-pack.mjs']],
   ['extension-pack:validate', ['src/commands/extension-pack.mjs', 'validate']],
   ['extension-pack:list', ['src/commands/extension-pack.mjs', 'list']],
@@ -101,7 +106,7 @@ export function buildHelpText(brand = DEFAULT_BRAND, atelierVersion = null) {
 
 Usage:
   atelier <command> [args]
-  mnstry-atelier <command> [args]   # legacy alias
+  mnstry-atelier <command> [args]   # supported npm alias
   mnstry atelier <command> [args]   # compatibility`
     : `${brand.displayName}
 powered by MNSTRY Atelier ${atelierVersion}
@@ -150,6 +155,7 @@ Core commands:
   upgrade explain --plan          Explain saved changes and consent without writes.
   upgrade apply --plan --confirm   Apply the selected plan through commit hooks.
   upgrade status|recover          Inspect receipts or preview recovery.
+  upgrade closure --npm-root      Plan a consumer dependency-closure check; reads only, proves nothing.
   upgrade --dry-run               Plan a legacy package/template upgrade.
   upgrade --apply                 Apply a branch-based reviewable upgrade.
   lock check|write                Verify or create atelier.lock.json.
@@ -167,6 +173,10 @@ Core commands:
   learn capture|propose|decide|activate|withdraw Manage scoped lessons and their evidence.
   ingest plan|run|status|query     Preserve selected sources and search bounded evidence.
   config check                    Validate project config.
+  extension init                 Scaffold a custom database extension.
+  extension validate             Check extension source and release digests.
+  extension seal                 Seal reviewed extension edits.
+  extension bundle               Export a sealed host-registration bundle.
   extension-pack validate         Validate declared extension packs.
   extension-pack list             List declared extension packs.
   distribution check              Check a distribution for MNSTRY attribution.
@@ -192,7 +202,7 @@ export function buildCommandHelpText(command, brand = DEFAULT_BRAND) {
   const c = brand.command
   const serverHelp = (name) => `Usage: ${c} ${name} [--project ./atelier.project.json] [--port=PORT] [--review] [--knowledge]
 
-Serves the project's built projection on 127.0.0.1 in the foreground until stopped. It builds nothing: run ${c} graph, then ${c} build, with the same --project path first. The port is --port=PORT, else the PORT environment variable, else 8137; 0 picks a free port, and the address printed on start names it. --review also serves the local review workspace at /review (docs/local-review.md). --knowledge adds guided knowledge dashboards and private coauthoring at /knowledge (docs/knowledge-workspace.md).`
+Serves the project's built projection on 127.0.0.1 in the foreground until stopped. It builds nothing: run ${c} graph, then ${c} build, with the same --project path first. The port is --port=PORT, else the PORT environment variable, else 8137; 0 picks a free port, and the address printed on start names it. --review also serves the local review workspace at /review (docs/guides/local-review.md). --knowledge adds guided knowledge dashboards and private coauthoring at /knowledge (docs/guides/knowledge-workspace.md).`
   const help = {
     capability: `Usage: ${c} capability seal|verify|inventory|plan|apply|status|observe|candidates|recover|fleet|graph|profiles
 Run ${c} capability help for options. Releases stay local; adoption is per repository
@@ -200,10 +210,10 @@ and requires an exact plan digest. Installed bytes, host loading and successful
 exercise are separate evidence. No model execution or tool permission grants.`,
     ingest: `Usage: ${c} ingest plan|run|status|query
 
-Read one bounded UTF-8 JSON object {workspaceId,input} from stdin inside the intended Git workspace. Plans bind explicit sources, scope and budgets. Run performs bounded local text, CSV and JSON extraction. Query returns source-bound lexical evidence with partial coverage; it does not synthesize or accept claims. Private state stays in ignored .atelier-local/. See docs/ingestion.md.`,
+Read one bounded UTF-8 JSON object {workspaceId,input} from stdin inside the intended Git workspace. Plans bind explicit sources, scope and budgets. Run performs bounded local text, CSV and JSON extraction. Query returns source-bound lexical evidence with partial coverage; it does not synthesize or accept claims. Private state stays in ignored .atelier-local/. See docs/guides/ingestion.md.`,
     learn: `Usage: ${c} learn capture|propose|decide|activate|withdraw|list|context|render|graph|export|plan
 
-Read a bounded JSON object from stdin in the intended Git workspace. Every request includes workspaceId. Writes include actor, requestId, expectedRevision and input. Context and render include query. Local actor identity is asserted, not authenticated. State stays in ignored .atelier-local/. Accepted content becomes context only after explicit activation for a named harness; no permission grant, file installation or sending occurs. See docs/learning.md.`,
+Read a bounded JSON object from stdin in the intended Git workspace. Every request includes workspaceId. Writes include actor, requestId, expectedRevision and input. Context and render include query. Local actor identity is asserted, not authenticated. State stays in ignored .atelier-local/. Accepted content becomes context only after explicit activation for a named harness; no permission grant, file installation or sending occurs. See docs/guides/learning.md.`,
     dev: serverHelp('dev'),
     server: serverHelp('server'),
     skills: `Usage: ${c} skills audit|observe|candidates|sync
@@ -222,7 +232,7 @@ check reports ontology-to-question coverage against the current canonical graph.
 context --question TEXT [--mode graph|lexical] [--max-bytes N] prints a bounded JSON packet of complete active Markdown sources.
 evaluate compares lexical and graph selection on the plan's pinned evidence cases; exit 1 means missing or stale expected evidence, missing relationships, or an expected abstention that retrieved or omitted matching evidence.
 The packet is local operator context, may contain private material, and grants no sharing or execution authority. Payload bytes are exact; token estimates are not measured usage. Session operations read JSON on stdin (except list); saved answers are private drafts.
-semantic reads one JSON object {workspaceId, run, request} on stdin (at most 256 KiB) in the intended Git workspace, the one ingest uses. Each operation accepts exactly its documented request fields: required fields non-null, every field of its declared kind; anything else refuses as SEMANTIC_OPERATION_INVALID before anything is written. Formats such as timestamps are the runner's to check. Atelier calls no model: the host supplies its raw output, candidates and usage (null when unknown), and every interpretation stays pending until receiver records accept it; those records are caller assertions, not authenticated identity. Failures print {ok:false, code, error}, with recorded or captured details for reopening when the runner attached them. See docs/knowledge-setup.md, docs/knowledge-workspace.md and docs/semantic-operation.md.`,
+semantic reads one JSON object {workspaceId, run, request} on stdin (at most 256 KiB) in the intended Git workspace, the one ingest uses. Each operation accepts exactly its documented request fields: required fields non-null, every field of its declared kind; anything else refuses as SEMANTIC_OPERATION_INVALID before anything is written. Formats such as timestamps are the runner's to check. Atelier calls no model: the host supplies its raw output, candidates and usage (null when unknown), and every interpretation stays pending until receiver records accept it; those records are caller assertions, not authenticated identity. Failures print {ok:false, code, error}, with recorded or captured details for reopening when the runner attached them. See docs/start/knowledge-setup.md, docs/guides/knowledge-workspace.md and docs/reference/semantic-operation.md.`,
     init: `Usage: ${c} init [--template private-domain|shared-project|sample-workspace|distribution|external-project|knowledge-workspace] [--target DIR] [--actor ID]
 
 Creates tracked starter files and an Atelier lockfile. It does not install hooks unless asked separately. An unrecognized --template exits 1 and writes nothing; omit --template for the blank scaffold.`,
@@ -253,6 +263,13 @@ Writes a minimal <file>.kg.json sidecar next to every .html, .pdf and .docx docu
   ${c} readiness export --dry-run [--project ./atelier.project.json]
 
 Runs the bundled MNSTRY readiness pack claim-first. Protocol state and packet drafts stay in ignored .atelier-local/readiness/ unless explicitly materialized by a reviewed future flow.`,
+    extension: `Usage:
+  ${c} extension init --directory NEW_PATH [--id sample.counter] [--profile postgres-sql|drizzle-db-first|drizzle-code-first|prisma-7-postgres] [--json]
+  ${c} extension validate --directory PATH [--json]
+  ${c} extension seal --directory PATH [--json]
+  ${c} extension bundle --directory PATH [--json]
+
+Generate a customer-owned Postgres project or validate/seal its source digests. Init requires a new directory. These commands create no account, database, process, deployment or installation. See docs/guides/extensions.md.`,
     'extension-pack': `Usage:
   ${c} extension-pack validate [--json] [--project ./atelier.project.json]
   ${c} extension-pack list [--json] [--project ./atelier.project.json]
@@ -260,7 +277,7 @@ Runs the bundled MNSTRY readiness pack claim-first. Protocol state and packet dr
 Loads every extension pack declared under ext["mnstry.atelier"].extensionPacks in the tracked project config and reports one line per pack. Packs load additively alongside the bundled MNSTRY protocols and can never replace them. list is the default subcommand. Shared --project-config and repeated --repo-path NAME=PATH options are supported in both space and equals forms.`,
     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.`,
+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/reference/attestation.md and docs/guides/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.`,
@@ -279,7 +296,7 @@ Assembles a local feedback report under ignored .atelier-local/feedback/ (mode 0
     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.`,
-    obsidian: `Usage: ${c} obsidian status|settings|location|scope|view|audience|mode|policy|service|open|uninstall|plugin|apply|conflicts|apply-policy|selection|proposals [--project atelier.project.json] [--data-root DIR] [--json] [--no-input]
+    obsidian: `Usage: ${c} obsidian status|settings|location|scope|view|audience|mode|policy|service|open|uninstall|plugin|apply|conflicts|apply-policy|selection|proposals [--project atelier.project.json | --personal-home DIR] [--data-root DIR] [--json] [--no-input]
 
   ${c} obsidian status
   ${c} obsidian settings
@@ -300,7 +317,7 @@ MNSTRY announcements are a pull-only channel: signed JSON documents under announ
   ${c} obsidian selection resolve ID | persist ID [allow-empty] | show ID | list
   ${c} obsidian proposals list | show OPERATION
 
-Every input is an argument. view add changes the project configuration, which you commit: it shows the change and how many notes the view would show, and asks a person at a terminal first (--yes answers beforehand); anyone else's command is their consent, and nothing is ever committed. With --json exactly one JSON document is printed, for a refusal too. status, settings, location show, scope, audience show, mode show, policy show, policy digest, plugin show and service status are read-only. open reports current only when the owned maintenance service ticked after the request, the view's trusted generation is the prepared one and reads back byte for byte, and the installed Obsidian meets the minimum version and answers for that vault; every other outcome is typed and exits 3. Reaching the installed app is never a default: open, service start and service unit need --adapter=obsidian-cli once for a workspace, which remembers it (never used under the test runner). service unit --install installs a login item on macOS (a launchd agent) or Linux (a systemd user unit) so maintenance starts when you log in, under a consent that covers startup; it runs the package installed in the project and is refused from a package runner's cache. Once installed, the service is started through it, and service start replaces a service of an earlier release. service unit --remove removes it and starts the service for this session only. uninstall removes the login item and stops the service, and keeps vaults, private state, the project file and Obsidian's vault list. Obsidian's own settings file is written only while no Obsidian runs, and every write is shown in open's answer: the view's vault is added to its list with a backup of the file as it was, its command line is turned on (cli: true), and for an Obsidian that never started the file is created. A running Obsidian that open cannot reach (its command line turned off, or no vault open) is quit and started again only with --restart-obsidian, which no other flag implies; otherwise open names that flag. --wait-ms bounds open's wait for maintenance's tick. The first start of the maintenance service records who allowed it: --consent-actor ID, or for a person at a terminal the account's name; --json, --no-input, CI or ATELIER_NONINTERACTIVE=1 mean nobody is at a terminal. Audiences (audience set me: only you, with the notes that carry no classification, which no other list shows), mode, the apply policy and what was decided are private machine settings, never project configuration and never a note. apply, conflicts, apply-policy, selection and proposals are contributed operations registered from modules shipped under src/runtime/obsidian/contributions/; the built-in names cannot be replaced. While no apply operation is registered every apply reports apply-unavailable. Exit codes: 0 done, 1 internal error, 2 refusal or usage, 3 ran and the answer is not success.`,
+Every input is an argument. view add changes the project configuration, which you commit: it shows the change and how many notes the view would show, and asks a person at a terminal first (--yes answers beforehand); anyone else's command is their consent, and nothing is ever committed. With --json exactly one JSON document is printed, for a refusal too. status, settings, location show, scope, audience show, mode show, policy show, policy digest, plugin show and service status are read-only. open reports current only when the owned maintenance service ticked after the request, the view's trusted generation is the prepared one and reads back byte for byte, and the installed Obsidian meets the minimum version and answers for that vault; every other outcome is typed and exits 3. Reaching the installed app is never a default: open, service start and service unit need --adapter=obsidian-cli once for a workspace, which remembers it (never used under the test runner). service unit --install installs a login item on macOS (a launchd agent) or Linux (a systemd user unit) so maintenance starts when you log in, under a consent that covers startup; it runs the package installed in the project and is refused from a package runner's cache. Once installed, the service is started through it, and service start replaces a service of an earlier release. service unit --remove removes it and starts the service for this session only. uninstall removes the login item and stops the service, and keeps vaults, private state, the project file and Obsidian's vault list. Obsidian's own settings file is written only while no Obsidian runs, and every write is shown in open's answer: the view's vault is added to its list with a backup of the file as it was, its command line is turned on (cli: true), and for an Obsidian that never started the file is created. A running Obsidian that open cannot reach (its command line turned off, or no vault open) is quit and started again only with --restart-obsidian, which no other flag implies; otherwise open names that flag. --wait-ms bounds open's wait for maintenance's tick. The first start of the maintenance service records who allowed it: --consent-actor ID, or for a person at a terminal the account's name; --json, --no-input, CI or ATELIER_NONINTERACTIVE=1 mean nobody is at a terminal. Audiences (audience set me: only you, with the notes that carry no classification, which no other list shows), mode, the apply policy and what was decided are private machine settings, never project configuration and never a note. apply, conflicts, apply-policy, selection and proposals are contributed operations registered from modules shipped under src/runtime/obsidian/contributions/; the built-in names cannot be replaced. While no apply operation is registered every apply reports apply-unavailable. --personal-home DIR, given instead of --project, follows the generation last confirmed in that private home of a personal workspace; nothing here confirms one, and while none is confirmed and current nothing is published and status, open and service start refuse with the reason. Who may see its vaults stays this machine's audience setting: owner only when undecided; an explicit clear stays empty. Exit codes: 0 done, 1 internal error, 2 refusal or usage, 3 ran and the answer is not success.`,
     sync: `Usage:
   ${c} sync enroll --repo DIR [--project atelier.project.json] [--git ABSOLUTE_PATH]
   ${c} sync status --repo DIR
@@ -372,7 +389,7 @@ export async function runCli({
 
   const [command, ...rest] = normalized.args
   if (rest[0] === '--help' || rest[0] === '-h') {
-    stdout(buildCommandHelpText(command, brand))
+    stdout(buildCommandHelpText(command.startsWith('extension:') ? 'extension' : command, brand))
     return 0
   }
   const target = commandMap.get(command)

package/src/commands/distribution.mjs

@@ -15,7 +15,7 @@ const ATTRIBUTION_BYTES = 'powered by MNSTRY Atelier'
 const ATTRIBUTION_EXT_KEY = 'mnstry.atelier/attribution'
 const PACK_MANIFEST_NAME = 'atelier.pack.json'
 const PREFIX = '[atelier-distribution:check]'
-const POLICY_POINTER = 'see TRADEMARKS.md ("Required attribution") and docs/attestation.md'
+const POLICY_POINTER = 'see TRADEMARKS.md ("Required attribution") and docs/reference/attestation.md'
 
 const log = (message) => console.log(`${PREFIX} ${message}`)
 const logError = (message) => console.error(`${PREFIX} ${message}`)

package/src/commands/extension.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { scaffoldSqlProject, scaffoldConvexProject, sealProject, validateProject, exportReleaseBundle } from '../extensions/project.mjs'
+
+const usage = 'Usage: atelier extension init|validate|seal|bundle --directory PATH [--id sample.counter] [--profile postgres-sql|drizzle-db-first|drizzle-code-first|prisma-7-postgres|convex-native] [--json]'
+const [command, ...args] = process.argv.slice(2)
+try {
+  if (command === '--help' || command === '-h' || !command) { console.log(usage) }
+  else {
+    if (!['init', 'validate', 'seal', 'bundle'].includes(command)) throw new Error('unknown extension command')
+    const options = {}
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i]
+      if (arg === '--json') { if (options.json) throw new Error('duplicate option'); options.json = true; continue }
+      if (!['--directory', '--id', '--profile'].includes(arg) || !args[i + 1] || args[i + 1].startsWith('--') || Object.hasOwn(options, arg)) throw new Error('invalid option')
+      options[arg] = args[++i]
+    }
+    if (!options['--directory'] || (command !== 'init' && (options['--id'] || options['--profile']))) throw new Error('invalid options')
+    if (options['--profile'] && !['postgres-sql','drizzle-db-first','drizzle-code-first','prisma-7-postgres','convex-native'].includes(options['--profile'])) throw new Error('profile not implemented')
+    const result = command === 'init' ? await (options['--profile']==='convex-native'?scaffoldConvexProject:scaffoldSqlProject)({ directory: options['--directory'], extensionId: options['--id'], profile: options['--profile'] }) :
+      command === 'bundle' ? await exportReleaseBundle(options['--directory']) :
+      command === 'validate' ? await validateProject(options['--directory']) : await sealProject(options['--directory']).then(manifest => ({ releaseDigest: manifest.releaseDigest, qualified: false }))
+    console.log(command === 'bundle' || options.json ? JSON.stringify(result) : `${command}: ${result.releaseDigest} (qualification pending)`)
+  }
+} catch {
+  // Do not echo a caller path, secret, source file or arbitrary exception text.
+  console.error(`Extension command failed. ${usage}`); process.exitCode = 1
+}

package/src/commands/ingest.mjs

@@ -9,7 +9,7 @@ ignored .atelier-local/ state. Plans bind explicit sources, scope and budgets.
 Run processes bounded local text, CSV and JSON. Status retains every selected
 source's disposition. Query returns source-bound lexical evidence with coverage;
 no operation accepts semantic claims, calls a provider or enrolls raw files into
-the graph. Output is private JSON. See docs/ingestion.md.`
+the graph. Output is private JSON. See docs/guides/ingestion.md.`
 
 try {
   const command = process.argv[2]

package/src/commands/learn.mjs

@@ -17,7 +17,7 @@ lesson digest. Activate makes approved content available to a named harness;
 it does not install files or grant tool permissions. Withdraw stops future use.
 List, context, render, graph, export and plan print private JSON to stdout.
 Export is an explicit private archive, never a send or publication operation.
-See docs/learning.md for complete examples.`
+See docs/guides/learning.md for complete examples.`
 
 function exactObject(value, allowed, required) {
   if (!value || typeof value !== 'object' || Array.isArray(value)