@softize/opus 11.1.0 → 12.0.0

package/bin/lib/materialize.mjs

@@ -1,11 +1,23 @@
 import { createHash } from 'node:crypto'
 import { execFileSync } from 'node:child_process'
-import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
-import { dirname, extname, join, relative, resolve } from 'node:path'
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { dirname, extname, isAbsolute, join, posix, relative, resolve, sep, win32 } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import { validateSkill } from './validate-skill.mjs'
+import {
+  canonicalProjectDirectory,
+  ensureProjectDirectory,
+  projectPathErrorMessage,
+  readProjectDirectory,
+  readProjectFile,
+  removeProjectFileIfUnchanged,
+  safeProjectPath,
+  writeProjectFileAtomically,
+} from '@softize/base/project-path'
+import { validGitDirectory } from '@softize/base/project-root'
+
 import { expandDocIncludes } from './docs-include.mjs'
+import { referencedSkills, skillReferences, skillRouteErrors, validateSkill } from './validate-skill.mjs'
 
 export const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..')
 export const PACKAGE_NAME = '@softize/opus'
@@ -16,7 +28,25 @@ const BLOCK_SOURCE = 'registry/instructions/opus.md'
 const BLOCK_END = '<!-- softize-managed:end @softize/opus -->'
 const MANAGED_ROOTS = ['.agents/skills', '.claude/skills', '.claude/hooks', '.github/workflows', '.githooks/pre-push.d']
 
-const hash = (content) => createHash('sha256').update(content).digest('hex')
+const normalizedLineEndings = (content) => content.replace(/\r\n?/gu, '\n')
+const hash = (content) => createHash('sha256').update(normalizedLineEndings(content)).digest('hex')
+
+function lineEndingStyle(content) {
+  const withoutCrlf = content.replace(/\r\n/gu, '')
+  const hasCrlf = content.includes('\r\n')
+  const hasBareLf = withoutCrlf.includes('\n')
+  const hasBareCr = withoutCrlf.includes('\r')
+  if (hasBareCr || (hasCrlf && hasBareLf)) return 'mixed'
+  return hasCrlf ? 'crlf' : 'lf'
+}
+
+function managedTextEquivalent(left, right) {
+  return lineEndingStyle(left) !== 'mixed' && normalizedLineEndings(left) === normalizedLineEndings(right)
+}
+
+function withProjectLineEndings(content, projectContent) {
+  return lineEndingStyle(projectContent) === 'crlf' ? content.replace(/\n/gu, '\r\n') : content
+}
 const readJson = (path) => {
   try { return JSON.parse(readFileSync(path, 'utf8')) } catch { return null }
 }
@@ -59,39 +89,193 @@ export function addMarker(path, source, content) {
 }
 
 function metadata(content) {
-  const match = /^(?:<!-- |\/\/ |# )softize-managed: (\{[^\n]+\})(?: -->)?$/m.exec(content)
+  const match = /^(?:<!-- |\/\/ |# )softize-managed: (\{[^\r\n]+\})(?: -->)?\r?$/m.exec(content)
   if (match === null) return null
   try { return JSON.parse(match[1]) } catch { return null }
 }
 
 function stripMarker(content) {
-  return content.replace(/^(?:<!-- |\/\/ |# )softize-managed: \{[^\n]+\}(?: -->)?\r?\n/m, '')
+  return content.replace(/^(?:<!-- |\/\/ |# )softize-managed: \{[^\r\n]+\}(?: -->)?\r?\n/m, '')
+}
+
+function inside(root, candidate) {
+  const local = relative(root, candidate)
+  return local !== '..' && !local.startsWith(`..${sep}`) && !isAbsolute(local)
+}
+
+function canonicalRelativeDirectory(value) {
+  if (typeof value !== 'string' || value === '' || value.trim() !== value) return false
+  if (value !== value.normalize('NFC') || value.includes('\\') || /[\u0000-\u001f\u007f]/u.test(value)) return false
+  if (value === '.') return true
+  if (posix.isAbsolute(value) || win32.isAbsolute(value) || /^[A-Za-z]:/u.test(value)) return false
+  if (value === '..' || posix.normalize(value) !== value) return false
+  return value.split('/').every((part) => part !== '' && part !== '.' && part !== '..')
+}
+
+function stableDirectory(root, value) {
+  if (!canonicalRelativeDirectory(value)) return null
+  try {
+    const checked = safeProjectPath(root, value, { mustExist: true })
+    if (checked.kind !== 'directory') return null
+    return checked.path
+  } catch { return null }
+}
+
+function declaresOpus(root, directory) {
+  let packageJson
+  try {
+    const local = relative(resolve(root), resolve(directory)) || '.'
+    const file = readProjectFile(root, join(local, 'package.json'), { allowMissing: true })
+    packageJson = file.exists ? JSON.parse(file.content) : null
+  } catch {
+    return false
+  }
+  return packageJson?.name === PACKAGE_NAME || ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies']
+    .some((field) => typeof packageJson?.[field]?.[PACKAGE_NAME] === 'string')
 }
 
-function config(root, mode, errors, changes) {
-  const path = join(root, 'base.json')
-  const original = existsSync(path) ? readFileSync(path, 'utf8') : ''
-  const current = original === '' ? { schemaVersion: 1, packages: {} } : readJson(path)
-  if (current === null || current.schemaVersion !== 1 || typeof current.packages !== 'object') {
+function inferredResolveFrom(root, invocationDirectory) {
+  const source = join(root, 'packages', 'opus')
+  if (declaresOpus(root, source)) return 'packages/opus'
+  let cursor = resolve(invocationDirectory ?? root)
+  if (!inside(root, cursor)) cursor = root
+  for (;;) {
+    if (declaresOpus(root, cursor)) return relative(root, cursor).split(sep).join('/') || '.'
+    if (cursor === root) break
+    cursor = dirname(cursor)
+  }
+  return relative(root, resolve(invocationDirectory ?? root)).split(sep).join('/') || '.'
+}
+
+function config(root, mode, errors, changes, required, invocationDirectory, mutate = true) {
+  const errorsBeforeConfiguration = errors.length
+  const configurationChanges = []
+  let file
+  try {
+    file = readProjectFile(root, 'base.json', { allowMissing: true })
+  } catch (error) {
+    errors.push(`base.json: ${projectPathErrorMessage(error)}`)
+    return []
+  }
+  const original = file.exists ? file.content : ''
+  let current
+  try {
+    current = file.exists ? JSON.parse(original) : { schemaVersion: 1, packages: {} }
+  } catch {
+    current = null
+  }
+  if (
+    current === null ||
+    current.schemaVersion !== 1 ||
+    current.packages === null ||
+    typeof current.packages !== 'object' ||
+    Array.isArray(current.packages)
+  ) {
     errors.push('base.json: formato inválido; esperado schemaVersion 1 e packages.')
     return []
   }
-  const previous = current.packages[PACKAGE_NAME] ?? {}
-  const exclude = Array.isArray(previous.exclude) ? previous.exclude : []
+  const configured = current.packages[PACKAGE_NAME]
+  const validPackageConfig =
+    configured === undefined || (configured !== null && typeof configured === 'object' && !Array.isArray(configured))
+  if (!validPackageConfig) errors.push(`base.json: ${PACKAGE_NAME} deve ser um objeto; preservado.`)
+  const previous = validPackageConfig ? (configured ?? {}) : {}
+  let exclude = Array.isArray(previous.exclude) ? previous.exclude : []
   if (previous.exclude !== undefined && !Array.isArray(previous.exclude)) errors.push('base.json: exclude deve ser uma lista de slugs.')
   const available = new Set(sourceSkills())
   for (const slug of exclude) if (typeof slug !== 'string' || !available.has(slug)) errors.push(`base.json: skill excluída desconhecida: ${String(slug)}.`)
+  const blocked = exclude.filter((slug) => required.has(slug))
+  if (blocked.length > 0) {
+    if (mode === 'setup') {
+      exclude = exclude.filter((slug) => !required.has(slug))
+      configurationChanges.push(`removidas exclusões obrigatórias (${blocked.join(', ')})`)
+    } else {
+      errors.push(`base.json: skills exigidas por rota permanente foram excluídas: ${blocked.join(', ')}.`)
+    }
+  }
+  if (current.copy === undefined) {
+    if (mode === 'setup') current.copy = { inventory: '.base/copy-inventory.json', allowedUppercase: [] }
+    else errors.push('base.json: seção copy ausente; rode `opus setup`.')
+  } else if (current.copy === null || typeof current.copy !== 'object' || Array.isArray(current.copy)) {
+    errors.push('base.json: copy deve ser um objeto; preservado.')
+  } else if (current.copy.inventory === undefined) {
+    if (mode === 'setup') current.copy.inventory = '.base/copy-inventory.json'
+    else errors.push('base.json: copy.inventory ausente; rode `opus setup`.')
+  } else if (typeof current.copy.inventory !== 'string' || current.copy.inventory.trim() === '') {
+    errors.push('base.json: copy.inventory deve ser um caminho não vazio; preservado.')
+  } else {
+    try {
+      safeProjectPath(root, current.copy.inventory)
+    } catch (error) {
+      errors.push(`base.json: copy.inventory inseguro: ${projectPathErrorMessage(error)}`)
+    }
+  }
+  if (current.copy !== null && typeof current.copy === 'object' && !Array.isArray(current.copy)) {
+    for (const field of ['allowedUppercase', 'exclude', 'exemptions', 'transforms']) {
+      if (current.copy[field] !== undefined && !Array.isArray(current.copy[field])) {
+        errors.push(`base.json: copy.${field} deve ser uma lista; preservado.`)
+      }
+    }
+  }
+  const configuredResolveFrom = previous.resolveFrom
+  const validConfiguredDirectory = stableDirectory(root, configuredResolveFrom)
+  const inferred = inferredResolveFrom(root, invocationDirectory)
+  // Em migrações manuais/fixtures sem package.json, o setup histórico registrava o
+  // próprio diretório de invocação. Ele continua estável quando coincide exatamente
+  // com a inferência atual; valores fornecidos que apontam para outro lugar falham.
+  const validConfiguredWorkspace = validConfiguredDirectory !== null && (
+    declaresOpus(root, validConfiguredDirectory) || configuredResolveFrom === inferred
+  )
+  if (configuredResolveFrom !== undefined && !validConfiguredWorkspace) {
+    errors.push('base.json: resolveFrom do Opus deve apontar para o workspace que declara @softize/opus; preservado.')
+  }
+  const resolveFrom = configuredResolveFrom === undefined
+    ? inferred
+    : configuredResolveFrom
   if (mode === 'setup') {
-    current.packages[PACKAGE_NAME] = { version: PACKAGE_VERSION, exclude }
-    const rendered = `${JSON.stringify(current, null, 2)}\n`
-    if (rendered !== original) {
-      writeFileSync(path, rendered)
-      changes.push(`${original === '' ? 'criado' : 'atualizado'} base.json`)
+    if (stableDirectory(root, resolveFrom) === null) errors.push('base.json: resolveFrom do Opus não aponta para um diretório interno regular.')
+    if (errors.length > errorsBeforeConfiguration) return []
+    current.packages[PACKAGE_NAME] = { version: PACKAGE_VERSION, exclude, resolveFrom }
+    const canonical = `${JSON.stringify(current, null, 2)}\n`
+    const rendered = original === '' ? canonical : withProjectLineEndings(canonical, original)
+    if (rendered !== original && mutate) {
+      try {
+        writeProjectFileAtomically(root, 'base.json', rendered, { exists: file.exists, content: original })
+        changes.push(...configurationChanges)
+        changes.push(`${file.exists ? 'atualizado' : 'criado'} base.json`)
+      } catch (error) {
+        errors.push(`base.json: ${projectPathErrorMessage(error)}`)
+      }
+    } else {
+      changes.push(...configurationChanges)
+    }
+  } else {
+    if (previous.version !== PACKAGE_VERSION) errors.push(`base.json: Opus aplicado ${previous.version ?? 'ausente'}, instalado ${PACKAGE_VERSION}.`)
+    if (validConfiguredDirectory === null || !declaresOpus(root, validConfiguredDirectory)) {
+      errors.push('base.json: resolveFrom do Opus deve apontar para o workspace que declara @softize/opus.')
     }
-  } else if (previous.version !== PACKAGE_VERSION) errors.push(`base.json: Opus aplicado ${previous.version ?? 'ausente'}, instalado ${PACKAGE_VERSION}.`)
+  }
   return exclude.filter((slug) => available.has(slug))
 }
 
+function requiredSkills(available, errors) {
+  const instructions = readFileSync(join(REGISTRY, 'instructions/opus.md'), 'utf8')
+  for (const error of skillRouteErrors(instructions)) errors.push(`registry/instructions/opus.md: ${error}`)
+  const required = new Set()
+  const visit = (slug, source) => {
+    if (!available.has(slug)) {
+      errors.push(`${source}: skill encaminhada ausente: $${slug}.`)
+      return
+    }
+    if (required.has(slug)) return
+    required.add(slug)
+    for (const reference of skillReferences(join(REGISTRY, 'skills', slug))) {
+      visit(reference.dependency, `registry/skills/${slug}/${reference.source}`)
+    }
+  }
+  for (const slug of referencedSkills(instructions)) visit(slug, 'registry/instructions/opus.md')
+  return required
+}
+
 function expectedFiles(exclude) {
   const expected = new Map()
   const addTree = (sourceRoot, destinationRoot) => {
@@ -110,7 +294,9 @@ function expectedFiles(exclude) {
   }
   for (const [source, destination] of [
     ['registry/hooks/opus-check-on-stop.mjs', '.claude/hooks/opus-check-on-stop.mjs'],
+    ['registry/git/pre-push.d/00-opus-copy', '.githooks/pre-push.d/00-opus-copy'],
     ['registry/git/pre-push.d/opus', '.githooks/pre-push.d/opus'],
+    ['registry/git/run-opus-pre-push.mjs', '.githooks/run-opus-pre-push.mjs'],
   ]) {
     const content = readFileSync(join(PACKAGE_ROOT, source), 'utf8')
     expected.set(destination, { source, content, output: addMarker(destination, source, content) })
@@ -118,45 +304,161 @@ function expectedFiles(exclude) {
   return expected
 }
 
+function portableProjectPath(value) {
+  return value.split(sep).join('/')
+}
+
+function projectPathFailure(errors, destination, error) {
+  errors.push(`${portableProjectPath(destination)}: ${projectPathErrorMessage(error)}`)
+}
+
+function readMaterializedFile(root, destination, errors, label = destination) {
+  try {
+    return readProjectFile(root, destination, { allowMissing: true })
+  } catch (error) {
+    projectPathFailure(errors, label, error)
+    return null
+  }
+}
+
+function ensureMaterializedParents(root, destination) {
+  const pending = []
+  let parent = dirname(destination)
+  while (parent !== '.') {
+    pending.unshift(parent)
+    const next = dirname(parent)
+    if (next === parent) throw new Error('diretório de destino não é relativo ao projeto.')
+    parent = next
+  }
+  for (const directory of pending) ensureProjectDirectory(root, directory)
+}
+
+function replaceMaterializedFile(root, destination, output, current, errors, options = {}, label = destination) {
+  try {
+    ensureMaterializedParents(root, destination)
+    writeProjectFileAtomically(
+      root,
+      destination,
+      output,
+      { exists: current.exists, content: current.content },
+      options,
+    )
+    return true
+  } catch (error) {
+    projectPathFailure(errors, label, error)
+    return false
+  }
+}
+
 function reconcileFile(root, destination, item, mode, errors, changes) {
-  const path = join(root, destination)
-  if (!existsSync(path)) {
+  const currentFile = readMaterializedFile(root, destination, errors)
+  if (currentFile === null) return
+  const executable = destination.startsWith('.githooks/')
+  const requiredMode = executable ? 0o755 : undefined
+  const modeIsCurrent = !executable || (currentFile.mode & 0o777) === requiredMode
+  const contentIsCurrent =
+    currentFile.exists &&
+    (executable ? currentFile.content === item.output : managedTextEquivalent(currentFile.content, item.output))
+
+  if (!currentFile.exists) {
     if (mode === 'check') errors.push(`${destination}: ausente.`)
-    else {
-      mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, item.output)
-      if (destination.startsWith('.githooks/')) chmodSync(path, 0o755)
+    else if (replaceMaterializedFile(root, destination, item.output, currentFile, errors, { mode: requiredMode })) {
       changes.push(`criado ${destination}`)
     }
     return
   }
-  const current = readFileSync(path, 'utf8')
-  if (current === item.output) return
+
+  const current = currentFile.content
+  if (contentIsCurrent && modeIsCurrent) return
   const owner = metadata(current)
-  if (owner?.package !== PACKAGE_NAME) { errors.push(`${destination}: colisão com arquivo não gerenciado pelo Opus.`); return }
-  if (hash(stripMarker(current)) !== owner.sha256) { errors.push(`${destination}: arquivo gerenciado foi editado; preservado.`); return }
-  if (mode === 'check') errors.push(`${destination}: desatualizado.`)
-  else {
-    writeFileSync(path, item.output)
-    if (destination.startsWith('.githooks/')) chmodSync(path, 0o755)
-    changes.push(`atualizado ${destination}`)
+  if (owner?.package !== PACKAGE_NAME) {
+    errors.push(`${destination}: colisão com arquivo não gerenciado pelo Opus.`)
+    return
+  }
+  if (hash(stripMarker(current)) !== owner.sha256) {
+    errors.push(`${destination}: arquivo gerenciado foi editado; preservado.`)
+    return
+  }
+  if (mode === 'check') {
+    errors.push(`${destination}: ${contentIsCurrent ? 'modo executável incorreto' : 'desatualizado'}.`)
+  } else if (
+    replaceMaterializedFile(
+      root,
+      destination,
+      executable ? item.output : withProjectLineEndings(item.output, current),
+      currentFile,
+      errors,
+      { mode: requiredMode },
+    )
+  ) {
+    changes.push(`${contentIsCurrent ? 'corrigido modo executável de' : 'atualizado'} ${destination}`)
+  }
+}
+
+function projectFilesUnder(root, directory, errors) {
+  const files = []
+
+  function visit(current) {
+    let listing
+    try {
+      listing = readProjectDirectory(root, current, { allowMissing: true })
+    } catch (error) {
+      projectPathFailure(errors, current, error)
+      return
+    }
+    if (!listing.exists) return
+
+    for (const entry of listing.entries.sort((left, right) => left.name.localeCompare(right.name))) {
+      const path = join(current, entry.name)
+      let inspected
+      try {
+        inspected = safeProjectPath(root, path, { mustExist: true })
+      } catch (error) {
+        projectPathFailure(errors, path, error)
+        continue
+      }
+      if (inspected.kind === 'directory') visit(path)
+      else if (inspected.kind === 'file') files.push(portableProjectPath(path))
+      else errors.push(`${portableProjectPath(path)}: entrada gerenciada deve ser arquivo regular ou diretório.`)
+    }
   }
+
+  visit(directory)
+  return files
 }
 
 function removeObsolete(root, expected, mode, errors, changes) {
-  for (const managedRoot of MANAGED_ROOTS) for (const file of filesUnder(join(root, managedRoot), root)) {
-    const content = readFileSync(file.path, 'utf8')
-    const owner = metadata(content)
-    if (owner?.package !== PACKAGE_NAME || expected.has(file.relative)) continue
-    if (hash(stripMarker(content)) !== owner.sha256) errors.push(`${file.relative}: obsoleto, mas editado; preservado.`)
-    else if (mode === 'check') errors.push(`${file.relative}: artefato obsoleto.`)
-    else { rmSync(file.path); changes.push(`removido ${file.relative}`) }
+  for (const managedRoot of MANAGED_ROOTS) {
+    for (const destination of projectFilesUnder(root, managedRoot, errors)) {
+      const file = readMaterializedFile(root, destination, errors)
+      if (file === null || !file.exists) continue
+      const content = file.content
+      const owner = metadata(content)
+      if (owner?.package !== PACKAGE_NAME || expected.has(destination)) continue
+      if (hash(stripMarker(content)) !== owner.sha256) {
+        errors.push(`${destination}: obsoleto, mas editado; preservado.`)
+      } else if (mode === 'check') {
+        errors.push(`${destination}: artefato obsoleto.`)
+      } else {
+        try {
+          removeProjectFileIfUnchanged(root, destination, file)
+          changes.push(`removido ${destination}`)
+        } catch (error) {
+          projectPathFailure(errors, destination, error)
+        }
+      }
+    }
   }
 }
 
 function detectLegacyArtifacts(root, errors) {
   for (const destination of ['.agents/skills/create-action', '.claude/skills/create-action']) {
-    if (existsSync(join(root, destination))) {
-      errors.push(`${destination}: skill legada detectada; remova-a após revisar qualquer edição local. Use create-opus-action.`)
+    try {
+      if (safeProjectPath(root, destination).exists) {
+        errors.push(`${destination}: skill legada detectada; remova-a após revisar qualquer edição local. Use create-opus-action.`)
+      }
+    } catch (error) {
+      projectPathFailure(errors, destination, error)
     }
   }
 }
@@ -169,46 +471,100 @@ function expectedBlock() {
 
 function findBlock(content) {
   const pattern = /<!-- softize-managed:start (\{[^\n]+\}) -->/g
+  const starts = []
   for (const match of content.matchAll(pattern)) {
     let owner = null
     try { owner = JSON.parse(match[1]) } catch { /* outro marcador inválido */ }
-    if (owner?.package !== PACKAGE_NAME) continue
-    const start = match.index
-    const openEnd = start + match[0].length
-    const end = content.indexOf(BLOCK_END, openEnd)
-    if (end === -1) return { malformed: true }
-    const bodyStart = openEnd + 1
-    const bodyEnd = content[end - 1] === '\n' ? end - 1 : end
-    return { start, end: end + BLOCK_END.length, body: content.slice(bodyStart, bodyEnd), owner }
+    if (owner?.package === PACKAGE_NAME) starts.push({ start: match.index, openEnd: match.index + match[0].length, owner })
+  }
+  const ends = []
+  let endAt = content.indexOf(BLOCK_END)
+  while (endAt !== -1) {
+    ends.push(endAt)
+    endAt = content.indexOf(BLOCK_END, endAt + BLOCK_END.length)
   }
-  if (/<!-- softize-managed:start [^\n]*@softize\/opus/.test(content)) return { malformed: true }
-  return null
+  const attempts = content
+    .split(/\r?\n/)
+    .filter((line) => line.includes('softize-managed:') && line.includes(PACKAGE_NAME)).length
+
+  if (starts.length === 0 && ends.length === 0 && attempts === 0) return null
+  if (starts.length !== 1 || ends.length !== 1 || attempts !== 2) return { malformed: true }
+  const [{ start, openEnd, owner }] = starts
+  const [end] = ends
+  if (end <= openEnd || content.slice(openEnd, end).includes('softize-managed:start')) return { malformed: true }
+  const openingBreak = content.startsWith('\r\n', openEnd) ? 2 : content[openEnd] === '\n' ? 1 : 0
+  if (openingBreak === 0) return { malformed: true }
+  const bodyStart = openEnd + openingBreak
+  const bodyEnd = content.slice(Math.max(0, end - 2), end) === '\r\n' ? end - 2 : end > 0 && content[end - 1] === '\n' ? end - 1 : end
+  return { start, end: end + BLOCK_END.length, body: content.slice(bodyStart, bodyEnd), owner }
 }
 
 function reconcileInstructions(root, file, mode, errors, changes) {
-  const path = join(root, file)
   const expected = expectedBlock()
-  const current = existsSync(path) ? readFileSync(path, 'utf8') : ''
+  const currentFile = readMaterializedFile(root, file, errors)
+  if (currentFile === null) return
+  const current = currentFile.exists ? currentFile.content : ''
   const block = findBlock(current)
   if (block?.malformed) { errors.push(`${file}: bloco Opus malformado.`); return }
   if (block === null) {
     if (mode === 'check') errors.push(`${file}: bloco Opus ausente.`)
-    else { writeFileSync(path, `${current.trimEnd()}${current.trimEnd() === '' ? '' : '\n\n'}${expected.text}\n`); changes.push(`atualizado ${file}`) }
+    else {
+      const suffix = current.trimEnd()
+      const newline = lineEndingStyle(current) === 'crlf' ? '\r\n' : '\n'
+      const renderedBlock = withProjectLineEndings(expected.text, current)
+      const output = `${suffix === '' ? '' : `${suffix}${newline}${newline}`}${renderedBlock}${newline}`
+      if (replaceMaterializedFile(root, file, output, currentFile, errors)) changes.push(`atualizado ${file}`)
+    }
+    return
+  }
+  if (block.owner?.package !== PACKAGE_NAME || hash(block.body) !== block.owner.sha256) {
+    errors.push(`${file}: bloco Opus foi editado ou perdeu sua identificação de origem; preservado.`)
     return
   }
-  if (hash(block.body) !== block.owner.sha256) { errors.push(`${file}: bloco Opus foi editado; preservado.`); return }
   const actual = current.slice(block.start, block.end)
-  if (actual === expected.text) return
+  if (managedTextEquivalent(actual, expected.text)) return
   if (mode === 'check') errors.push(`${file}: bloco Opus desatualizado.`)
-  else { writeFileSync(path, `${current.slice(0, block.start)}${expected.text}${current.slice(block.end)}`); changes.push(`atualizado ${file}`) }
+  else {
+    const output = `${current.slice(0, block.start)}${withProjectLineEndings(expected.text, actual)}${current.slice(block.end)}`
+    if (replaceMaterializedFile(root, file, output, currentFile, errors)) changes.push(`atualizado ${file}`)
+  }
 }
 
 function isOpusHook(hook) { return typeof hook?.command === 'string' && hook.command.includes('.claude/hooks/opus-check-on-stop.mjs') }
+
+function isPlainObject(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}
+
+function validSettings(settings) {
+  if (!isPlainObject(settings)) return false
+  if (settings.hooks === undefined) return true
+  if (!isPlainObject(settings.hooks)) return false
+  return Object.values(settings.hooks).every(
+    (groups) =>
+      Array.isArray(groups) &&
+      groups.every(
+        (group) =>
+          isPlainObject(group) &&
+          Array.isArray(group.hooks) &&
+          group.hooks.every((hook) => isPlainObject(hook)),
+      ),
+  )
+}
+
 function reconcileSettings(root, mode, errors, changes) {
   const destination = '.claude/settings.json'
-  const path = join(root, destination)
-  const current = existsSync(path) ? readJson(path) : {}
-  if (current === null || typeof current !== 'object') { errors.push(`${destination}: JSON inválido; preservado.`); return }
+  const currentFile = readMaterializedFile(root, destination, errors)
+  if (currentFile === null) return
+  let current
+  try {
+    current = currentFile.exists ? JSON.parse(currentFile.content) : {}
+  } catch {
+    current = null
+  }
+  if (!validSettings(current)) { errors.push(`${destination}: JSON ou estrutura de hooks inválida; preservado.`); return }
   const expected = structuredClone(current); expected.hooks ??= {}
   for (const event of Object.keys(expected.hooks)) expected.hooks[event] = expected.hooks[event]
     .map((group) => ({ ...group, hooks: (group.hooks ?? []).filter((hook) => !isOpusHook(hook)) }))
@@ -216,57 +572,217 @@ function reconcileSettings(root, mode, errors, changes) {
   expected.hooks.Stop = [...(expected.hooks.Stop ?? []), { hooks: [{ type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/opus-check-on-stop.mjs"', timeout: 120 }] }]
   if (JSON.stringify(current) === JSON.stringify(expected)) return
   if (mode === 'check') errors.push(`${destination}: hook Opus ausente ou desatualizado.`)
-  else { mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, `${JSON.stringify(expected, null, 2)}\n`); changes.push(`atualizado ${destination}`) }
+  else {
+    const canonical = `${JSON.stringify(expected, null, 2)}\n`
+    const rendered = currentFile.exists ? withProjectLineEndings(canonical, currentFile.content) : canonical
+    if (replaceMaterializedFile(root, destination, rendered, currentFile, errors)) changes.push(`atualizado ${destination}`)
+  }
 }
 
 function reconcileSharedPrePush(root, mode, errors, changes) {
   const destination = '.githooks/pre-push'
-  const path = join(root, destination)
   const expected = readFileSync(join(REGISTRY, 'git/pre-push'), 'utf8')
-  if (!existsSync(path)) {
+  const current = readMaterializedFile(root, destination, errors)
+  if (current === null) return
+  if (!current.exists) {
     if (mode === 'check') errors.push(`${destination}: dispatcher compartilhado ausente.`)
-    else { mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, expected); chmodSync(path, 0o755); changes.push(`criado ${destination}`) }
-  } else if (readFileSync(path, 'utf8') !== expected) errors.push(`${destination}: dispatcher compartilhado incompatível; preservado.`)
-  else if (mode === 'setup' && (statSync(path).mode & 0o111) === 0) { chmodSync(path, 0o755); changes.push(`corrigido modo executável de ${destination}`) }
+    else if (replaceMaterializedFile(root, destination, expected, current, errors, { mode: 0o755 })) {
+      changes.push(`criado ${destination}`)
+    }
+    return
+  }
+  if (current.content !== expected) {
+    if (!managedTextEquivalent(current.content, expected)) {
+      errors.push(`${destination}: dispatcher compartilhado incompatível; preservado.`)
+    } else if (mode === 'check') {
+      errors.push(`${destination}: desatualizado; executáveis Git exigem LF.`)
+    } else if (replaceMaterializedFile(root, destination, expected, current, errors, { mode: 0o755 })) {
+      changes.push(`atualizado ${destination}`)
+    }
+    return
+  }
+  if ((current.mode & 0o777) !== 0o755) {
+    if (mode === 'check') errors.push(`${destination}: modo executável incorreto.`)
+    else if (replaceMaterializedFile(root, destination, expected, current, errors, { mode: 0o755 })) {
+      changes.push(`corrigido modo executável de ${destination}`)
+    }
+  }
 }
 
-function configureGit(root, mode, errors, changes) {
-  if (!existsSync(join(root, '.git'))) return
+function sameProjectFile(left, right) {
+  return (
+    left.exists === right.exists &&
+    (!left.exists ||
+      (left.identity.dev === right.identity.dev &&
+        left.identity.ino === right.identity.ino &&
+        left.mode === right.mode &&
+        left.modifiedAtMs === right.modifiedAtMs &&
+        left.content === right.content))
+  )
+}
+
+function gitAdministrativeRoots(root, errors) {
+  let dotGit
   try {
-    try { execFileSync('git', ['rev-parse', '--git-dir'], { cwd: root, stdio: 'ignore' }) } catch { return }
-    let hooksPath = ''
-    try { hooksPath = execFileSync('git', ['config', '--local', '--get', 'core.hooksPath'], { cwd: root, encoding: 'utf8' }).trim() } catch { /* ausente */ }
-    if (mode === 'setup' && hooksPath === '') execFileSync('git', ['config', '--local', 'core.hooksPath', '.githooks'], { cwd: root })
-    else if (hooksPath !== '.githooks') errors.push(`git core.hooksPath ${hooksPath === '' ? 'não configurado' : `aponta para ${hooksPath}`}.`)
-
-    const excludePath = execFileSync('git', ['rev-parse', '--git-path', 'info/exclude'], { cwd: root, encoding: 'utf8' }).trim()
-    const absolute = resolve(root, excludePath)
-    if (existsSync(absolute)) {
-      const current = readFileSync(absolute, 'utf8')
-      const forbidden = new Set([
-        '.claude/',
-        '.claude/skills/',
-        '.claude/hooks/opus-check-on-stop.mjs',
-        '.agents/',
-        '.agents/skills/',
-      ])
-      const lines = current.split(/\r?\n/)
-      const blocked = lines.filter((line) => forbidden.has(line.trim()))
-      if (blocked.length > 0 && mode === 'check') errors.push(`git info/exclude oculta artefatos de agentes: ${blocked.join(', ')}.`)
-      else if (blocked.length > 0) {
-        const kept = lines.filter((line) => !forbidden.has(line.trim())).join('\n').replace(/\n+$/, '')
-        writeFileSync(absolute, kept === '' ? '' : `${kept}\n`)
-        changes.push('removidas exclusões locais de artefatos de agentes')
+    dotGit = safeProjectPath(root, '.git')
+  } catch (error) {
+    projectPathFailure(errors, '.git', error)
+    return null
+  }
+  if (!dotGit.exists) return undefined
+
+  let administrativeRoot
+  if (dotGit.kind === 'directory') {
+    try {
+      administrativeRoot = canonicalProjectDirectory(dotGit.path)
+    } catch (error) {
+      projectPathFailure(errors, '.git', error)
+      return null
+    }
+  } else if (dotGit.kind === 'file') {
+    let gitFile
+    try {
+      gitFile = readProjectFile(root, '.git')
+    } catch (error) {
+      projectPathFailure(errors, '.git', error)
+      return null
+    }
+    const match = /^gitdir: ([^\0\r\n]+)\r?\n?$/u.exec(gitFile.content)
+    if (match === null || match[1].trim() !== match[1]) {
+      errors.push('.git: gitfile inválido; esperado um único caminho gitdir.')
+      return null
+    }
+    try {
+      administrativeRoot = canonicalProjectDirectory(resolve(root, match[1]))
+    } catch (error) {
+      projectPathFailure(errors, '.git', error)
+      return null
+    }
+  } else {
+    errors.push('.git: deve ser diretório administrativo ou gitfile regular.')
+    return null
+  }
+  if (!validGitDirectory(administrativeRoot)) {
+    errors.push('.git: diretório administrativo inválido ou HEAD inseguro.')
+    return null
+  }
+
+  let commonDirectory
+  try {
+    commonDirectory = readProjectFile(administrativeRoot, 'commondir', { allowMissing: true })
+  } catch (error) {
+    projectPathFailure(errors, '.git/commondir', error)
+    return null
+  }
+  if (!commonDirectory.exists) return { administrativeRoot, commonRoot: administrativeRoot }
+  const commonMatch = /^([^\0\r\n]+)\r?\n?$/u.exec(commonDirectory.content)
+  if (commonMatch === null || commonMatch[1].trim() !== commonMatch[1]) {
+    errors.push('.git/commondir: caminho inválido.')
+    return null
+  }
+  try {
+    return { administrativeRoot, commonRoot: canonicalProjectDirectory(resolve(administrativeRoot, commonMatch[1])) }
+  } catch (error) {
+    projectPathFailure(errors, '.git/commondir', error)
+    return null
+  }
+}
+
+function appendGitHooksPath(content) {
+  const newline = lineEndingStyle(content) === 'crlf' ? '\r\n' : '\n'
+  const separator = content === '' ? '' : content.endsWith('\n') ? newline : `${newline}${newline}`
+  return `${content}${separator}[core]${newline}\thooksPath = .githooks${newline}`
+}
+
+function effectiveGitHooksPath(root, git, commonConfig, worktreeConfig, errors) {
+  let effective
+  try {
+    const output = execFileSync('git', ['config', '--get', 'core.hooksPath'], { cwd: root, encoding: 'utf8' })
+    const parsed = /^([^\0\r\n]*)(?:\r?\n)?$/u.exec(output)
+    if (parsed === null) {
+      errors.push('git core.hooksPath efetivo: valor multilinha ou malformado.')
+      return null
+    }
+    effective = parsed[1]
+  } catch (error) {
+    if (error?.status === 1) effective = ''
+    else {
+      errors.push(`git core.hooksPath efetivo: ${String(error).slice(0, 160)}.`)
+      return null
+    }
+  }
+  const commonAfter = readMaterializedFile(git.commonRoot, 'config', errors, '.git/config')
+  const worktreeAfter = readMaterializedFile(git.administrativeRoot, 'config.worktree', errors, '.git/config.worktree')
+  if (commonAfter === null || worktreeAfter === null) return null
+  if (!sameProjectFile(commonConfig, commonAfter) || !sameProjectFile(worktreeConfig, worktreeAfter)) {
+    errors.push('git core.hooksPath efetivo: configuração mudou durante a leitura.')
+    return null
+  }
+  return effective
+}
+
+function configureGit(root, mode, errors, changes) {
+  const git = gitAdministrativeRoots(root, errors)
+  if (git === undefined || git === null) return
+
+  const config = readMaterializedFile(git.commonRoot, 'config', errors, '.git/config')
+  if (config === null) return
+  const worktreeConfig = readMaterializedFile(git.administrativeRoot, 'config.worktree', errors, '.git/config.worktree')
+  if (worktreeConfig === null) return
+  const current = effectiveGitHooksPath(root, git, config, worktreeConfig, errors)
+  if (current === null) return
+  if (current === '') {
+    if (mode === 'check') errors.push('git core.hooksPath não configurado.')
+    else {
+      const output = appendGitHooksPath(config.exists ? config.content : '')
+      if (replaceMaterializedFile(git.commonRoot, 'config', output, config, errors, {}, '.git/config')) {
+        changes.push('configurado git core.hooksPath')
+        const updated = readMaterializedFile(git.commonRoot, 'config', errors, '.git/config')
+        if (updated === null) return
+        const effective = effectiveGitHooksPath(root, git, updated, worktreeConfig, errors)
+        if (effective !== null && effective !== '.githooks') {
+          errors.push(`git core.hooksPath efetivo é ${effective || 'ausente'} após a configuração.`)
+        }
       }
     }
-  } catch (error) { errors.push(`git: ${String(error).slice(0, 140)}.`) }
+  } else if (current !== '.githooks') {
+    errors.push(`git core.hooksPath já aponta para ${current}; não alterado.`)
+  }
+
+  const destination = 'info/exclude'
+  const label = '.git/info/exclude'
+  const exclude = readMaterializedFile(git.commonRoot, destination, errors, label)
+  if (exclude === null || !exclude.exists) return
+  const forbidden = new Set([
+    '.claude/',
+    '.claude/skills/',
+    '.claude/hooks/opus-check-on-stop.mjs',
+    '.agents/',
+    '.agents/skills/',
+  ])
+  const lines = exclude.content.split(/\r?\n/)
+  const blocked = lines.filter((line) => forbidden.has(line.trim()))
+  if (blocked.length > 0 && mode === 'check') {
+    errors.push(`git info/exclude oculta artefatos de agentes: ${blocked.join(', ')}.`)
+  } else if (blocked.length > 0) {
+    const newline = lineEndingStyle(exclude.content) === 'crlf' ? '\r\n' : '\n'
+    const kept = lines.filter((line) => !forbidden.has(line.trim())).join(newline).replace(/(?:\r?\n)+$/u, '')
+    const output = kept === '' ? '' : `${kept}${newline}`
+    if (replaceMaterializedFile(git.commonRoot, destination, output, exclude, errors, {}, label)) {
+      changes.push('removidas exclusões locais de artefatos de agentes')
+    }
+  }
 }
 
-export function materializeOpus(root, mode = 'setup') {
+export function materializeOpus(root, mode = 'setup', options = {}) {
   const target = resolve(root)
-  const errors = sourceSkills().flatMap((slug) => validateSkill(join(REGISTRY, 'skills', slug)).map((error) => `skills/${slug}: ${error}`))
+  const skills = sourceSkills()
+  const errors = skills.flatMap((slug) => validateSkill(join(REGISTRY, 'skills', slug)).map((error) => `skills/${slug}: ${error}`))
+  const required = requiredSkills(new Set(skills), errors)
   const changes = []
-  const exclude = config(target, mode, errors, changes)
+  if (errors.length > 0) return { ok: false, errors, changes, expected: [] }
+  const exclude = config(target, mode, errors, changes, required, options.invocationDirectory)
+  if (errors.length > 0) return { ok: false, errors, changes, expected: [] }
   const expected = expectedFiles(exclude)
   reconcileSharedPrePush(target, mode, errors, changes)
   for (const [destination, item] of expected) reconcileFile(target, destination, item, mode, errors, changes)
@@ -278,3 +794,13 @@ export function materializeOpus(root, mode = 'setup') {
   configureGit(target, mode, errors, changes)
   return { ok: errors.length === 0, errors, changes, expected: [...expected.keys()] }
 }
+
+/** Valida sources e configuração reparável do setup sem tocar no projeto. */
+export function validateOpusSetup(root, options = {}) {
+  const target = resolve(root)
+  const skills = sourceSkills()
+  const errors = skills.flatMap((slug) => validateSkill(join(REGISTRY, 'skills', slug)).map((error) => `skills/${slug}: ${error}`))
+  const required = requiredSkills(new Set(skills), errors)
+  if (errors.length === 0) config(target, 'setup', errors, [], required, options.invocationDirectory, false)
+  return errors
+}