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

package/src/graph/knowledge-graph.mjs

@@ -1,7 +1,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { VALID_AUDIENCES } from '../projection/policy.mjs'
-import { generatedProjectionBasenames } from '../project/file-class.mjs'
+import { generatedProjectionBasenames, generatedProjectionDirectoryBasenames } from '../project/file-class.mjs'
 import { gitIgnoreFilter } from '../project/git-ignore.mjs'
 
 export const KNOWLEDGE_GRAPH_SCHEMA = 'mnstry.knowledge-graph@v1'
@@ -14,7 +14,7 @@ export const VALID_STATUSES = new Set(['active', 'draft', 'archived', 'template'
 export const VALID_KG_TYPES = new Set(['document', 'artifact', 'evidence', 'source', 'index', 'contract', 'guide', 'runbook', 'policy', 'report', 'prototype', 'research', 'decision', 'map', 'manifest', 'html', 'pdf', 'docx'])
 export const VALID_SIDECAR_KG_TYPES = new Set(['html', 'pdf', 'docx', 'artifact', 'evidence', 'source', 'prototype', 'research', 'report', 'manifest'])
 
-const SKIP_DIRS = new Set(['.git', '.agents', '.claude', '.github', 'node_modules', 'output', 'uploads', 'scripts', 'lib'])
+const SKIP_DIRS = new Set(['.git', '.agents', '.claude', '.github', 'node_modules', 'output', 'uploads', 'scripts', 'lib', ...generatedProjectionDirectoryBasenames()])
 // Derived from the kit's file-class declaration, never restated here.
 const GENERATED_FILES = generatedProjectionBasenames()
 const PRIVATE_AUDIENCES = new Set(['private', 'sensitive'])
@@ -100,7 +100,7 @@ function uniqueStringArrayErrors(value, label) {
 }
 
 export function splitFrontmatter(raw) {
-  const normalized = raw.replace(/\r\n/g, '\n')
+  const normalized = String(raw).replace(/\r\n?/g, '\n')
   if (!normalized.startsWith('---\n')) return null
   const rest = normalized.slice(4)
   const match = rest.match(/\n---\s*\n/)
@@ -188,11 +188,50 @@ export function markdownMetadata(raw) {
   return fm ? parseYamlSubset(fm.yaml) : {}
 }
 
+function markdownFrontmatterState(raw) {
+  const fm = splitFrontmatter(raw)
+  if (!fm) return { kind: 'absent', metadata: {} }
+  if (!fm.yaml.trim()) return { kind: 'empty', metadata: {} }
+
+  const metadata = parseYamlSubset(fm.yaml)
+  const lines = fm.yaml.replace(/\t/g, '  ').replace(/\r\n/g, '\n').split('\n')
+  let malformed = false
+  const containerIndents = [-1]
+  const containerKinds = ['object']
+  for (let index = 0; index < lines.length; index += 1) {
+    const rawLine = lines[index]
+    const trimmed = rawLine.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+    const indent = rawLine.match(/^\s*/)[0].length
+    while (containerIndents.length > 1 && indent <= containerIndents.at(-1)) {
+      containerIndents.pop()
+      containerKinds.pop()
+    }
+    if (trimmed.startsWith('- ')) {
+      if (containerKinds.at(-1) !== 'array' || !trimmed.slice(2).trim()) malformed = true
+      continue
+    }
+    const match = trimmed.match(/^([^:]+):(.*)$/)
+    if (!match || !match[1].trim()) {
+      malformed = true
+      continue
+    }
+    if (!match[2].trim()) {
+      const next = nextYamlValue(lines, index, indent)
+      containerIndents.push(indent)
+      containerKinds.push(Array.isArray(next) ? 'array' : 'object')
+    }
+  }
+  return { kind: malformed ? 'malformed' : 'valid', metadata }
+}
+
 function relationMap(value) {
   if (!isPlainObject(value)) return {}
   const relations = {}
   for (const [key, items] of Object.entries(value)) {
-    relations[key] = Array.isArray(items) ? asStringArray(items) : items
+    // Preserve the original graph command's shorthand while emitting one
+    // canonical shape: a scalar Markdown relation is a one-target list.
+    relations[key] = Array.isArray(items) ? asStringArray(items) : typeof items === 'string' ? asStringArray([items]) : items
   }
   return relations
 }
@@ -315,7 +354,6 @@ export function walkDocuments(dir, root, acc = [], isIgnored = gitIgnoreFilter(r
       // sidecar itself is metadata, never a source asset.
       if (ent.name.endsWith('.kg.json')) continue
       if (GENERATED_FILES.has(ent.name)) continue
-      if (rel === 'index.html') continue
       const ext = path.extname(ent.name).toLowerCase()
       // Opt-in requires a VISIBLE sidecar. A git-ignored one is machine-local:
       // it would enrol a node that exists in no tracked file, and hand it an
@@ -556,13 +594,21 @@ export function nodeForFile(repoName, repoRoot, coverage, file, repoAccessConfig
   let title = titleCase(path.basename(file.rel))
   let summary = ''
   let metadata = {}
+  let classification = 'classified'
+  let classificationReason = null
   let sidecar = null
   let hasSidecar = false
   let atelier = { section: coverage.sections.get(file.rel) || null, status: null, kind: null }
 
   if (file.ext === '.md') {
     const raw = fs.readFileSync(file.abs, 'utf8')
-    metadata = markdownMetadata(raw)
+    const frontmatter = markdownFrontmatterState(raw)
+    metadata = frontmatter.metadata
+    if (frontmatter.kind !== 'valid' || !isPlainObject(metadata.kg)) {
+      classification = 'unclassified'
+      classificationReason = frontmatter.kind === 'valid' ? 'missing-kg-block' : `${frontmatter.kind}-frontmatter`
+      metadata = {}
+    }
     title = asString(metadata.title, extractMarkdownTitle(raw, file.rel))
     summary = asString(metadata.summary, extractMarkdownSummary(raw))
   } else if (file.ext === '.html') {
@@ -594,7 +640,7 @@ export function nodeForFile(repoName, repoRoot, coverage, file, repoAccessConfig
   const domain = asString(kg.domain, inferredDomain)
   const lifecycle = asString(kg.lifecycle, inferredLifecycle)
   const status = asString(kg.status, inferredStatus)
-  const audience = asString(kg.audience, '')
+  const audience = classification === 'unclassified' ? 'private' : asString(kg.audience, '')
   const frontmatterHasLegacyVisibility = Object.hasOwn(kg, 'visibility')
   const type = asString(kg.type, file.ext === '.md' ? 'document' : file.ext.slice(1))
   const id = asString(kg.id, fallbackId(repoName, file.rel, file.ext))
@@ -615,6 +661,8 @@ export function nodeForFile(repoName, repoRoot, coverage, file, repoAccessConfig
     lifecycle,
     status,
     audience,
+    classification,
+    ...(classificationReason ? { classificationReason } : {}),
     ...(frontmatterHasLegacyVisibility ? { frontmatterHasLegacyVisibility: true } : {}),
     ...(file.ext === '.md' ? { markdownHasKgBlock: hasKgBlock, markdownHasKgId: hasExplicitKgId } : {}),
     ...(file.ext !== '.md'
@@ -694,6 +742,20 @@ export function uniqueEdges(edges) {
 export function graphDiagnostics(nodes) {
   const diagnostics = []
   for (const node of nodes) {
+    if (node.classification === 'unclassified') {
+      diagnostics.push({
+        severity: 'warning',
+        type: 'unclassified-content',
+        code: 'unclassified-content',
+        node: node.id,
+        repo: node.repo,
+        path: node.path,
+        audience: node.audience,
+        repoAccess: node.repoAccess,
+        reason: node.classificationReason,
+        message: `${node.repo}/${node.path}: Markdown classification metadata is ${node.classificationReason}; enrolled as private unclassified content`,
+      })
+    }
     const audienceRank = AUDIENCE_READ_RANK[node.audience]
     const readBoundary = node.repoAccess?.readBoundary
     const readBoundaryRank = AUDIENCE_READ_RANK[readBoundary]
@@ -730,14 +792,16 @@ export function activeOrphanSidecars(repoName, repoRoot, files, isIgnored = gitI
   return orphans
 }
 
-export function validateKnowledgeGraph(nodes, edges, orphanSidecars = []) {
+export function validateKnowledgeGraph(nodes, edges, orphanSidecars = [], { externalRelationPrefixes = [], externalRelationIds = [] } = {}) {
   const errors = []
   const seenIds = new Map()
+  const allowedExternalPrefixes = new Set(externalRelationPrefixes)
+  const allowedExternalIds = new Set(externalRelationIds)
 
   for (const node of nodes) {
     if (!node.id) errors.push(`${node.repo}/${node.path}: missing kg.id`)
-    if (node.extension === 'md' && node.markdownHasKgBlock && !node.markdownHasKgId) {
-      errors.push(`${node.repo}/${node.path}: Markdown kg block must declare kg.id`)
+    if (node.extension === 'md' && node.classification !== 'unclassified' && node.markdownHasKgBlock && !node.markdownHasKgId) {
+      errors.push(`${node.repo}/${node.path}: kg.id is required in a Markdown kg block`)
     }
     if (node.extension !== 'md' && !node.hasSidecar) {
       errors.push(`${node.repo}/${node.path}: missing non-Markdown sidecar ${node.sidecar || `${node.path}.kg.json`}`)
@@ -753,7 +817,7 @@ export function validateKnowledgeGraph(nodes, edges, orphanSidecars = []) {
       seenIds.set(node.id, `${node.repo}/${node.path}`)
     }
     if (node.frontmatterHasLegacyVisibility) {
-      errors.push(`${node.repo}/${node.path}: legacy kg.visibility is reserved for runtime export; use kg.audience`)
+      errors.push(`${node.repo}/${node.path}: kg.visibility is invalid for graph classification; use kg.audience`)
     }
     if (!VALID_AUDIENCES.has(node.audience)) {
       errors.push(`${node.repo}/${node.path}: invalid or missing kg.audience "${node.audience ?? ''}"`)
@@ -776,7 +840,8 @@ export function validateKnowledgeGraph(nodes, edges, orphanSidecars = []) {
 
   for (const edge of edges) {
     if (!edge.declared) continue
-    if (!seenIds.has(edge.target)) {
+    const externalPrefix = String(edge.target).split(':')[0]
+    if (!seenIds.has(edge.target) && !allowedExternalIds.has(edge.target) && !allowedExternalPrefixes.has(externalPrefix)) {
       const sourcePath = seenIds.get(edge.source) || edge.source
       errors.push(`${sourcePath}: declared ${edge.type} target "${edge.target}" was not found`)
     }
@@ -793,17 +858,24 @@ export function buildKnowledgeGraph({
   workspaceRoot,
   repoAccessConfig,
   repoRoots = null,
+  repoEntries = null,
   repoAccessConfigPath = 'repo-access config',
   externalRepos = [],
+  externalRelationPrefixes = [],
+  externalRelationIds = [],
 } = {}) {
   if (!workspaceRoot) throw new Error('workspaceRoot is required')
   const resolvedWorkspaceRoot = path.resolve(workspaceRoot)
   const external = new Set(externalRepos)
-  const discovered = repoRoots ? repoRoots.map((repoRoot) => path.resolve(repoRoot)).sort() : listRepos(resolvedWorkspaceRoot)
+  const discoveredEntries = repoEntries
+    ? repoEntries.map((entry) => ({ name: entry.name, path: path.resolve(entry.path) })).sort((a, b) => String(a.name).localeCompare(String(b.name)))
+    : (repoRoots ? repoRoots.map((repoRoot) => path.resolve(repoRoot)) : listRepos(resolvedWorkspaceRoot))
+        .sort()
+        .map((repoRoot) => ({ name: path.basename(repoRoot), path: repoRoot }))
   // External repos are acknowledged but never walked: no document census, no
   // sidecar demands, no projection.
-  const roots = discovered.filter((repoRoot) => !external.has(path.basename(repoRoot)))
-  const repoNames = roots.map((repoRoot) => path.basename(repoRoot))
+  const roots = discoveredEntries.filter((entry) => !external.has(entry.name))
+  const repoNames = roots.map((entry) => entry.name)
   const accessConfig = repoAccessConfig ?? {
     schema: REPO_ACCESS_SCHEMA,
     defaultReadBoundary: 'team',
@@ -825,8 +897,9 @@ export function buildKnowledgeGraph({
   const workspaceIgnoredSidecars = []
   const repoGraphs = []
 
-  for (const repoRoot of roots) {
-    const repoName = path.basename(repoRoot)
+  for (const entry of roots) {
+    const repoRoot = entry.path
+    const repoName = entry.name
     // One batched ignore lookup per repo, shared by every walk below.
     const isIgnored = gitIgnoreFilter(repoRoot)
     const files = walkDocuments(repoRoot, repoRoot, [], isIgnored)
@@ -858,7 +931,10 @@ export function buildKnowledgeGraph({
     workspaceEdges.push(...graph.edges)
   }
 
-  const validationErrors = validateKnowledgeGraph(workspaceNodes, workspaceEdges, workspaceOrphanSidecars)
+  const validationErrors = validateKnowledgeGraph(workspaceNodes, workspaceEdges, workspaceOrphanSidecars, {
+    externalRelationPrefixes,
+    externalRelationIds,
+  })
   const workspaceGraph = {
     schema: KNOWLEDGE_GRAPH_SCHEMA,
     workspace: path.basename(resolvedWorkspaceRoot),

package/src/harness/context-client.mjs

@@ -39,7 +39,13 @@ export async function jsonGet(baseUrl, route, params = null, headers = {}) {
   const url = new URL(route, `${base.href}/`)
   if (params) appendParams(url, params)
   // @atelier-egress-local-computed
-  const response = await fetch(url, { headers })
+  const response = await fetch(url, {
+    headers: {
+      Origin: base.origin,
+      'Sec-Fetch-Site': 'same-origin',
+      ...headers,
+    },
+  })
   return readJsonResponse(response, route)
 }
 
@@ -51,6 +57,8 @@ export async function jsonPost(baseUrl, route, body = {}, headers = {}) {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
+      Origin: base.origin,
+      'Sec-Fetch-Site': 'same-origin',
       ...headers,
     },
     body: JSON.stringify(body),

package/src/index.mjs

@@ -52,6 +52,12 @@ export {
   contextEnvelope,
 } from './harness/context.mjs'
 
+export {
+  ATELIER_COLLABORATION_EVENT_SCHEMA,
+  createCollaborationEventLedger,
+  validateCollaborationEvent,
+} from './collaboration/index.mjs'
+
 export {
   buildSupportBundlePreview,
   validateSupportBundlePayload,
@@ -61,6 +67,12 @@ export {
   checkForbiddenEgress,
 } from './egress/forbidden-egress.mjs'
 
+export {
+  STRUCTURAL_DISCLOSURE_PATTERNS,
+  compileDisclosurePatterns,
+  scanDisclosureContent,
+} from './disclosure/content-scan.mjs'
+
 export {
   BOUNDARY_POLICY_SCHEMA,
   checkBoundaryPolicy,
@@ -86,3 +98,32 @@ export {
 export {
   analysisAdapterDryRun,
 } from './analysis/adapter.mjs'
+
+export {
+  GitCommandError,
+  classifyRemoteAuthentication,
+  inspectGitEngine,
+  parseGitVersion,
+  resolveGitExecutable,
+  runGit,
+  sanitizeRemoteUrl,
+} from './runtime/git-adapter.mjs'
+
+export {
+  ATELIER_REPOSITORY_OBSERVATION_SCHEMA,
+  classifyFilesystemRoot,
+  observeRepository,
+  resolveRepositoryRoot,
+  validateRepositoryObservation,
+} from './runtime/repository-observation.mjs'
+
+export {
+  ATELIER_COMMIT_PLAN_SCHEMA,
+  enrollRepository,
+  executeUserConfirmedCommit,
+  operationTrace,
+  planUserConfirmedCommit,
+  reconcileRepository,
+  runtimeStatus,
+  setRepositoryPaused,
+} from './runtime/supervisor.mjs'

package/src/project/config.mjs

@@ -1,6 +1,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { spawnSync } from 'node:child_process'
+import { sanitizedGitEnvironment } from '../runtime/git-adapter.mjs'
 
 export const PROJECT_CONFIG_ARG_PREFIX = '--project-config='
 export const PROJECT_CONFIG_ENV = 'MNSTRY_ATELIER_PROJECT_CONFIG'
@@ -17,6 +18,16 @@ export const LOCAL_OVERLAY_FILES = ['atelier.local.json', 'atelier.workspace.loc
 // a way to silence checks on a repo you do manage.
 export const EXTERNAL_REPO_KIND = 'external'
 
+export class AtelierDiagnosticError extends Error {
+  constructor(code, message, { hint = null, exitCode = 2, cause = null } = {}) {
+    super(message, cause ? { cause } : undefined)
+    this.name = 'AtelierDiagnosticError'
+    this.code = code
+    this.hint = hint
+    this.exitCode = exitCode
+  }
+}
+
 export const isExternalRepo = (repo) => firstString(repo?.kind) === EXTERNAL_REPO_KIND
 
 // Kept here rather than imported from repo-identity.mjs so config validation stays
@@ -59,10 +70,19 @@ export function resolvePathValue(value, baseDir) {
 }
 
 export function readJson(file) {
+  if (!fs.existsSync(file)) {
+    const graphArtifact = path.basename(file) === 'knowledge.graph.json'
+    throw new AtelierDiagnosticError('artifact-missing', `required JSON artifact not found: ${file}`, {
+      hint: graphArtifact ? 'Run atelier graph with this project config, then retry.' : 'Create or regenerate the named artifact, then retry.',
+    })
+  }
   try {
     return JSON.parse(fs.readFileSync(file, 'utf8'))
   } catch (error) {
-    throw new Error(`invalid JSON at ${file}: ${error.message}`)
+    throw new AtelierDiagnosticError('json-invalid', `JSON is malformed at ${file}: ${error.message}`, {
+      hint: 'Repair or regenerate the named JSON file, then retry.',
+      cause: error,
+    })
   }
 }
 
@@ -90,9 +110,30 @@ export function stripProjectConfigArgs(argv = [], prefix = PROJECT_CONFIG_ARG_PR
 }
 
 export function readProjectConfig(configPath) {
-  const doc = readJson(configPath)
+  let doc
+  try {
+    doc = readJson(configPath)
+  } catch (error) {
+    if (error instanceof AtelierDiagnosticError) {
+      throw new AtelierDiagnosticError(
+        error.code === 'artifact-missing' ? 'project-config-missing' : 'project-config-json-invalid',
+        error.code === 'artifact-missing'
+          ? `atelier project config not found: ${configPath}`
+          : `atelier project config is malformed: ${configPath}`,
+        {
+          hint: error.code === 'artifact-missing'
+            ? 'Pass --project PATH to a tracked atelier.project.json file.'
+            : 'Repair the JSON syntax, then run atelier config check with the same --project path.',
+          cause: error,
+        },
+      )
+    }
+    throw error
+  }
   if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
-    throw new Error(`atelier project config must be a JSON object: ${configPath}`)
+    throw new AtelierDiagnosticError('project-config-shape-invalid', `Atelier project config must be a JSON object: ${configPath}`, {
+      hint: 'Repair the document shape, then run atelier config check with the same --project path.',
+    })
   }
   return doc
 }
@@ -155,25 +196,25 @@ function overlayRepoPath(overlay, repoName) {
   return firstString(direct, repo.path, repo.localPath)
 }
 
-function resolveRepoPath({ repo, repoName, configDir, workspaceRoot, overlay, cliRepoPaths }) {
+function resolveRepoPath({ repo, repoName, configDir, workspaceRoot, overlay, cliRepoPaths, gitExecutable, env }) {
   if (repoName && cliRepoPaths.has(repoName)) return cliRepoPaths.get(repoName)
   const overlayPath = overlayRepoPath(overlay, repoName)
   const fromOverlay = resolvePathValue(overlayPath, configDir)
   if (fromOverlay) return fromOverlay
   const fromConfig = resolvePathValue(repo.path, configDir) || resolvePathValue(repo.path, workspaceRoot)
   if (fromConfig) return fromConfig
-  return discoverSiblingRepoPath({ repo, repoName, configDir, workspaceRoot })
+  return discoverSiblingRepoPath({ repo, repoName, configDir, workspaceRoot, gitExecutable, env })
 }
 
-function repoPathSource({ repo, repoName, overlay, cliRepoPaths, workspaceRoot, configDir }) {
+function repoPathSource({ repo, repoName, overlay, cliRepoPaths, workspaceRoot, configDir, gitExecutable, env }) {
   if (repoName && cliRepoPaths.has(repoName)) return 'cli'
   if (overlayRepoPath(overlay, repoName)) return 'local-overlay'
   if (firstString(repo.path)) return 'tracked-config'
-  if (discoverSiblingRepoPath({ repo, repoName, configDir, workspaceRoot })) return 'sibling-discovery'
+  if (discoverSiblingRepoPath({ repo, repoName, configDir, workspaceRoot, gitExecutable, env })) return 'sibling-discovery'
   return null
 }
 
-function discoverSiblingRepoPath({ repo, repoName, configDir, workspaceRoot }) {
+function discoverSiblingRepoPath({ repo, repoName, configDir, workspaceRoot, gitExecutable = 'git', env = process.env }) {
   if (!repoName) return null
   const candidates = [
     path.join(workspaceRoot, repoName),
@@ -182,14 +223,14 @@ function discoverSiblingRepoPath({ repo, repoName, configDir, workspaceRoot }) {
   ]
   for (const candidate of candidates) {
     if (!fs.existsSync(candidate)) continue
-    if (repo.remote && !gitRemoteMatches(candidate, repo.remote)) continue
+    if (repo.remote && !gitRemoteMatches(candidate, repo.remote, { gitExecutable, env })) continue
     return path.resolve(candidate)
   }
   return null
 }
 
-function gitRemoteMatches(repoPath, expected) {
-  const result = spawnSync('git', ['-C', repoPath, 'remote', 'get-url', 'origin'], { encoding: 'utf8' })
+function gitRemoteMatches(repoPath, expected, { gitExecutable = 'git', env = process.env } = {}) {
+  const result = spawnSync(gitExecutable, ['-C', repoPath, 'remote', 'get-url', 'origin'], { encoding: 'utf8', env: sanitizedGitEnvironment(env) })
   if (result.status !== 0) return false
   const actual = normalizeRemote(result.stdout.trim())
   return actual === normalizeRemote(expected)
@@ -203,9 +244,9 @@ function normalizeRemote(value) {
     .toLowerCase()
 }
 
-export function gitRemoteUrl(repoPath) {
+export function gitRemoteUrl(repoPath, { gitExecutable = 'git', env = process.env } = {}) {
   if (!repoPath || !fs.existsSync(repoPath)) return null
-  const result = spawnSync('git', ['-C', repoPath, 'remote', 'get-url', 'origin'], { encoding: 'utf8' })
+  const result = spawnSync(gitExecutable, ['-C', repoPath, 'remote', 'get-url', 'origin'], { encoding: 'utf8', env: sanitizedGitEnvironment(env) })
   return result.status === 0 ? firstString(result.stdout) : null
 }
 
@@ -228,6 +269,7 @@ export function resolveProjectConfig({
   env = process.env,
   cwd = process.cwd(),
   configArgPrefix = PROJECT_CONFIG_ARG_PREFIX,
+  gitExecutable = 'git',
   configEnv = PROJECT_CONFIG_ENV,
   defaults = {},
 } = {}) {
@@ -253,7 +295,9 @@ export function resolveProjectConfig({
       missingConfigPath = configPath
       configPath = null
     } else {
-      throw new Error(`atelier project config not found: ${configPath || requestedPath}`)
+      throw new AtelierDiagnosticError('project-config-missing', `atelier project config not found: ${configPath || requestedPath}`, {
+        hint: 'Pass --project PATH to a tracked atelier.project.json file.',
+      })
     }
   }
 
@@ -331,7 +375,7 @@ export function resolveProjectConfig({
     localOverlay,
     repos: (Array.isArray(config.repos) ? config.repos : []).map((repo) => {
       const repoName = firstString(repo.name) || (repo.path ? path.basename(repo.path) : null)
-      const repoPath = resolveRepoPath({ repo, repoName, configDir, workspaceRoot, overlay: localOverlay.overlay, cliRepoPaths })
+      const repoPath = resolveRepoPath({ repo, repoName, configDir, workspaceRoot, overlay: localOverlay.overlay, cliRepoPaths, gitExecutable, env })
       const external = isExternalRepo(repo)
       return {
         ...repo,
@@ -339,23 +383,25 @@ export function resolveProjectConfig({
         path: repoPath,
         external,
         readBoundary: external ? null : firstString(repo.readBoundary) || 'team',
-        pathSource: repoPath ? repoPathSource({ repo, repoName, overlay: localOverlay.overlay, cliRepoPaths, workspaceRoot, configDir }) : null,
+        pathSource: repoPath ? repoPathSource({ repo, repoName, overlay: localOverlay.overlay, cliRepoPaths, workspaceRoot, configDir, gitExecutable, env }) : null,
       }
     }),
   }
-  resolved.localState = ensureLocalState(resolved, { write: true })
+  resolved.localState = ensureLocalState(resolved, { write: true, gitExecutable, env })
   return resolved
 }
 
-export function commandProject({ argv = process.argv.slice(2), env = process.env, cwd = process.cwd() } = {}) {
-  const project = resolveProjectConfig({ argv, env, cwd })
+export function commandProject({ argv = process.argv.slice(2), env = process.env, cwd = process.cwd(), gitExecutable = 'git' } = {}) {
+  const project = resolveProjectConfig({ argv, env, cwd, gitExecutable })
   // Fail closed at CLI entry, but only when a real config file was loaded; the
   // defaults/no-file path resolves with an empty config that would spuriously
   // fail document validation.
   if (project.configPath != null) {
     const configErrors = validateProjectConfigDoc(project.config)
     if (configErrors.length) {
-      throw new Error(`invalid atelier project config at ${project.configPath}:\n${configErrors.join('\n')}`)
+      throw new AtelierDiagnosticError('project-config-contract-invalid', `invalid atelier project config at ${project.configPath}:\n${configErrors.join('\n')}`, {
+        hint: 'Fix the listed fields, then run atelier config check with the same --project path.',
+      })
     }
   }
   if (project.schema !== PROJECT_CONFIG_SCHEMA) {
@@ -375,21 +421,36 @@ export function localStateRoot(projectOrDir) {
   return path.join(configDir || process.cwd(), LOCAL_STATE_DIR)
 }
 
-function gitRootFor(dir) {
-  const result = spawnSync('git', ['-C', dir, 'rev-parse', '--show-toplevel'], { encoding: 'utf8' })
+function gitRootFor(dir, { gitExecutable = 'git', env = process.env } = {}) {
+  const result = spawnSync(gitExecutable, ['-C', dir, 'rev-parse', '--show-toplevel'], { encoding: 'utf8', env: sanitizedGitEnvironment(env) })
+  return result.status === 0 ? result.stdout.trim() : null
+}
+
+function gitPrefixFor(dir, { gitExecutable = 'git', env = process.env } = {}) {
+  const result = spawnSync(gitExecutable, ['-C', dir, 'rev-parse', '--show-prefix'], { encoding: 'utf8', env: sanitizedGitEnvironment(env) })
   return result.status === 0 ? result.stdout.trim() : null
 }
 
-function isIgnoredByGit(gitRoot, rel) {
-  const result = spawnSync('git', ['-C', gitRoot, 'check-ignore', '-q', rel], { encoding: 'utf8' })
+function isIgnoredByGit(gitRoot, rel, { gitExecutable = 'git', env = process.env } = {}) {
+  const result = spawnSync(gitExecutable, ['-C', gitRoot, 'check-ignore', '-q', rel], { encoding: 'utf8', env: sanitizedGitEnvironment(env) })
   return result.status === 0
 }
 
-export function ensureLocalState(project, { write = false } = {}) {
+export function ensureLocalState(project, { write = false, gitExecutable = 'git', env = process.env } = {}) {
   const root = localStateRoot(project)
-  const gitRoot = gitRootFor(project.configDir)
-  const rel = gitRoot ? path.relative(gitRoot, root).split(path.sep).join('/') : LOCAL_STATE_DIR
-  const ignored = gitRoot ? isIgnoredByGit(gitRoot, `${rel}/`) || isIgnoredByGit(gitRoot, rel) : true
+  const gitRoot = gitRootFor(project.configDir, { gitExecutable, env })
+  // Git owns the repository-relative spelling. Deriving it by comparing
+  // filesystem paths breaks when Windows exposes the cwd through an 8.3 short
+  // name (RUNNER~1) but Git reports the same root through its long name.
+  const gitPrefix = gitRoot ? gitPrefixFor(project.configDir, { gitExecutable, env }) : null
+  const rel = gitRoot && gitPrefix !== null ? `${gitPrefix}${LOCAL_STATE_DIR}` : LOCAL_STATE_DIR
+  // A directory-only ignore rule such as `.atelier-local/` is not evaluated
+  // consistently by Git for an absent directory on every host. Probe a
+  // hypothetical child as well: it proves the directory rule before Atelier
+  // creates any local state, including on Git for Windows.
+  const ignored = gitRoot && gitPrefix !== null
+    ? isIgnoredByGit(gitRoot, `${rel}/.atelier-ignore-probe`, { gitExecutable, env }) || isIgnoredByGit(gitRoot, `${rel}/`, { gitExecutable, env }) || isIgnoredByGit(gitRoot, rel, { gitExecutable, env })
+    : gitRoot === null
   const report = {
     root,
     ignored,

package/src/project/file-class.mjs

@@ -111,3 +111,17 @@ export function generatedProjectionBasenames(fileClasses = KIT_FILE_CLASSES) {
   }
   return names
 }
+
+// Directory basenames whose complete subtree is generated. Graph walkers can
+// prune these without restating output-root names beside the declaration.
+export function generatedProjectionDirectoryBasenames(fileClasses = KIT_FILE_CLASSES) {
+  const names = new Set()
+  for (const entry of fileClasses) {
+    if (entry.class !== GENERATED_PROJECTION) continue
+    const normalized = normalizeRelPath(entry.pattern)
+    if (!normalized.endsWith('/**')) continue
+    const parent = normalized.slice(0, -3).split('/').at(-1)
+    if (parent && !parent.includes('*')) names.add(parent)
+  }
+  return names
+}

package/src/project/package-root.mjs

@@ -0,0 +1,10 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export function nativePathFromFileUrl(value) {
+  return fileURLToPath(value instanceof URL ? value : new URL(value))
+}
+
+export function packageRootFrom(moduleUrl) {
+  return path.resolve(nativePathFromFileUrl(new URL('../..', moduleUrl)))
+}

package/src/project/path-match.mjs

@@ -4,27 +4,50 @@ export const normalizeRelPath = (value) =>
   String(value ?? '')
     .replaceAll('\\', '/')
     .replace(/^\.\/+/, '')
+    .replace(/\/{2,}/g, '/')
 
 const escapeRe = (value) => String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 
-// Shared by the boundary policy and the file-class resolver. Both used to carry
-// their own copy; two glob dialects in one kit is exactly the drift this file exists
-// to prevent.
+function globSource(pattern) {
+  let source = ''
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index]
+    if (char !== '*') {
+      source += escapeRe(char)
+      continue
+    }
+
+    const globstar = pattern[index + 1] === '*'
+    if (!globstar) {
+      source += '[^/]*'
+      continue
+    }
+
+    index += 1
+    if (pattern[index + 1] === '/') {
+      index += 1
+      source += '(?:.*/)?'
+    } else if (source.endsWith('/')) {
+      source = source.slice(0, -1)
+      source += '(?:/.*)?'
+    } else {
+      source += '.*'
+    }
+  }
+  return source
+}
+
+// Shared by the boundary policy and the file-class resolver. The dialect is
+// intentionally portable: case does not depend on the host filesystem, `*`
+// stays inside one segment, and `**` crosses segments. Slashless patterns keep
+// their historical match-base behavior, so `*.md` applies at any depth without
+// making `private/*.md` consume nested directories.
 export function matchesPathPattern(pattern, rel) {
   const normalizedPattern = normalizeRelPath(pattern)
   const normalizedRel = normalizeRelPath(rel)
-  if (normalizedPattern === normalizedRel) return true
-  if (normalizedPattern.endsWith('/**')) {
-    return normalizedRel === normalizedPattern.slice(0, -3) || normalizedRel.startsWith(normalizedPattern.slice(0, -2))
-  }
-  if (normalizedPattern.startsWith('**/')) {
-    const tail = normalizedPattern.slice(3)
-    return normalizedRel === tail || normalizedRel.endsWith(`/${tail}`) || matchesPathPattern(tail, normalizedRel)
-  }
-  if (normalizedPattern.includes('*')) {
-    return new RegExp(`^${normalizedPattern.split('*').map(escapeRe).join('.*')}$`).test(normalizedRel)
-  }
-  return false
+  if (!normalizedPattern || !normalizedRel) return false
+  const candidate = normalizedPattern.includes('/') ? normalizedRel : path.posix.basename(normalizedRel)
+  return new RegExp(`^${globSource(normalizedPattern)}$`, 'i').test(candidate)
 }
 
 export const basenameOf = (pattern) => path.posix.basename(normalizeRelPath(pattern))