@open-mercato/cli 0.6.7-develop.6863.1.61001cf9a8 → 0.6.7

package/src/lib/agentic-setup.ts

@@ -6,35 +6,16 @@
  * This module reads those files at runtime — no embedded string constants.
  */
 
-import {
-  chmodSync,
-  copyFileSync,
-  existsSync,
-  lstatSync,
-  mkdirSync,
-  mkdtempSync,
-  readFileSync,
-  readdirSync,
-  realpathSync,
-  renameSync,
-  rmSync,
-  statSync,
-  writeFileSync,
-} from 'node:fs'
-import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, symlinkSync, lstatSync, unlinkSync, readdirSync } from 'node:fs'
 import { spawnSync } from 'node:child_process'
-import { tmpdir } from 'node:os'
-import { join, dirname, basename, relative, resolve, sep } from 'node:path'
+import { join, dirname, basename } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { Project, SyntaxKind } from 'ts-morph'
 
-const moduleDir = dirname(fileURLToPath(import.meta.url))
-// In the built output (dist/lib/agentic-setup.js), moduleDir is dist/lib/.
+const __dirname = dirname(fileURLToPath(import.meta.url))
+// In the built output (dist/lib/agentic-setup.js), __dirname is dist/lib/.
 // agentic/ is copied to dist/agentic/ by build.mjs.
-const bundledAgenticDir = join(moduleDir, '..', 'agentic')
-const AGENTIC_DIR = existsSync(bundledAgenticDir)
-  ? bundledAgenticDir
-  : join(moduleDir, '..', '..', '..', 'create-app', 'agentic')
+const AGENTIC_DIR = join(__dirname, '..', 'agentic')
 const GUIDES_DIR = join(AGENTIC_DIR, 'guides')
 
 type AskFn = (question: string) => Promise<string>
@@ -42,7 +23,6 @@ type AskFn = (question: string) => Promise<string>
 interface AgenticSetupOptions {
   tool?: string
   force?: boolean
-  updateHarness?: boolean
 }
 
 interface AgenticConfig {
@@ -50,19 +30,6 @@ interface AgenticConfig {
   targetDir: string
 }
 
-interface HarnessManifestFile {
-  path: string
-  sha256: string
-  source: string
-  userEditable: boolean
-}
-
-interface HarnessManifest {
-  version: number
-  generator: string
-  files: HarnessManifestFile[]
-}
-
 // ─── Helpers ─────────────────────────────────────────────────────────────
 
 function resolvePlaceholders(content: string, config: AgenticConfig): string {
@@ -92,14 +59,14 @@ function copyFile(srcDir: string, srcRelative: string, destPath: string): void {
 // AST-parse the static `enabledModules` array literal in the app's src/modules.ts
 // and collect each entry's `id`. Only the static literal is read (conditional
 // .push()/spread entries are intentionally not seen — see spec D6).
-function readEnabledModuleIds(modulesPath: string): { parsed: boolean; ids: string[] } {
-  if (!existsSync(modulesPath)) return { parsed: false, ids: [] }
+function readEnabledModuleIds(modulesPath: string): string[] {
+  if (!existsSync(modulesPath)) return []
   try {
     const project = new Project({ useInMemoryFileSystem: true })
     const sourceFile = project.createSourceFile('modules.ts', readFileSync(modulesPath, 'utf-8'))
     const declaration = sourceFile.getVariableDeclaration('enabledModules')
     const arrayLiteral = declaration?.getInitializerIfKind(SyntaxKind.ArrayLiteralExpression)
-    if (!arrayLiteral) return { parsed: false, ids: [] }
+    if (!arrayLiteral) return []
     const ids: string[] = []
     for (const element of arrayLiteral.getElements()) {
       const objectLiteral = element.asKind(SyntaxKind.ObjectLiteralExpression)
@@ -108,9 +75,9 @@ function readEnabledModuleIds(modulesPath: string): { parsed: boolean; ids: stri
       const idValue = idProperty?.getInitializerIfKind(SyntaxKind.StringLiteral)?.getLiteralValue()
       if (idValue) ids.push(idValue)
     }
-    return { parsed: true, ids }
+    return ids
   } catch {
-    return { parsed: false, ids: [] }
+    return []
   }
 }
 
@@ -125,23 +92,48 @@ function selectModuleFactSheets(targetDir: string, modulesSubdir: string): strin
         .map((file) => file.replace(/\.md$/, ''))
     : []
   if (available.length === 0) return []
-  const parsed = readEnabledModuleIds(join(targetDir, 'src', 'modules.ts'))
-  if (!parsed.parsed) return available
-  const enabled = new Set(parsed.ids)
+  const enabled = new Set(readEnabledModuleIds(join(targetDir, 'src', 'modules.ts')))
   const selected = available.filter((moduleId) => enabled.has(moduleId))
-  return selected
+  return selected.length > 0 ? selected : available
 }
 
 const MODULE_GUIDES_START = '<!-- om:module-guides:start -->'
 const MODULE_GUIDES_END = '<!-- om:module-guides:end -->'
 
-export function renderModuleGuidesBlock(selected: string[]): string {
+// Read each module's guide label from the bundled `module-facts.json` (emitted by
+// build.mjs from the generator's extraction of each module's own `metadata`). The
+// label falls back description → title → generic, so the CLI never re-declares
+// specific module names or descriptions. A missing/malformed sidecar degrades to an
+// empty map (generic labels), never a throw.
+function readModuleGuideLabels(guidesDir: string): Record<string, string> {
+  const factsPath = join(guidesDir, 'module-facts.json')
+  if (!existsSync(factsPath)) return {}
+  try {
+    const parsed = JSON.parse(readFileSync(factsPath, 'utf-8')) as Record<
+      string,
+      { description?: unknown; title?: unknown }
+    >
+    const labels: Record<string, string> = {}
+    for (const [moduleId, entry] of Object.entries(parsed)) {
+      const label =
+        (entry && typeof entry.description === 'string' && entry.description) ||
+        (entry && typeof entry.title === 'string' && entry.title) ||
+        ''
+      if (label) labels[moduleId] = label
+    }
+    return labels
+  } catch {
+    return {}
+  }
+}
+
+function renderModuleGuidesBlock(selected: string[], labels: Record<string, string>): string {
   if (selected.length === 0) return '_No module fact-sheets are bundled for this app._'
-  return [
-    `Enabled module facts: ${selected.map((moduleId) => `\`${moduleId}\``).join(',')}.`,
-    '',
-    'Load `.ai/guides/modules/<id>.md` only for a named or targeted installed module/host; never preload all module facts.',
-  ].join('\n')
+  const rows = selected.map((moduleId) => {
+    const label = labels[moduleId] ?? `Use the ${moduleId} module`
+    return `| ${label} | \`.ai/guides/modules/${moduleId}.md\` |`
+  })
+  return ['| Task | Load |', '|---|---|', ...rows].join('\n')
 }
 
 // Regenerate the marker-delimited Module-Specific Guides block in the written
@@ -150,6 +142,7 @@ export function renderModuleGuidesBlock(selected: string[]): string {
 function injectModuleGuides(
   agentsMdPath: string,
   selected: string[],
+  labels: Record<string, string> = {},
 ): void {
   if (!existsSync(agentsMdPath)) return
   const content = readFileSync(agentsMdPath, 'utf-8')
@@ -163,428 +156,188 @@ function injectModuleGuides(
   }
   const before = content.slice(0, startIndex + MODULE_GUIDES_START.length)
   const after = content.slice(endIndex)
-  const next = `${before}\n${renderModuleGuidesBlock(selected)}\n${after}`
+  const next = `${before}\n${renderModuleGuidesBlock(selected, labels)}\n${after}`
   if (next !== content) writeFileSync(agentsMdPath, next)
 }
 
-const TEXT_EXTENSIONS = new Set(['.cjs', '.json', '.md', '.mdc', '.mjs', '.sh', '.ts', '.txt'])
-
-function isTextAsset(path: string): boolean {
-  const dot = path.lastIndexOf('.')
-  return dot === -1 || TEXT_EXTENSIONS.has(path.slice(dot))
-}
-
-function listFiles(root: string): string[] {
-  if (!existsSync(root)) return []
-  const files: string[] = []
-  for (const entry of readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
-    const absolute = join(root, entry.name)
-    if (entry.isDirectory()) files.push(...listFiles(absolute))
-    else if (entry.isFile()) files.push(absolute)
-  }
-  return files
-}
-
-function copyTree(sourceRoot: string, destinationRoot: string, config: AgenticConfig): void {
-  for (const sourcePath of listFiles(sourceRoot)) {
-    const destinationPath = join(destinationRoot, relative(sourceRoot, sourcePath))
-    ensureDir(destinationPath)
-    if (isTextAsset(sourcePath)) {
-      writeFileSync(destinationPath, resolvePlaceholders(readFileSync(sourcePath, 'utf8'), config))
-    } else {
-      copyFileSync(sourcePath, destinationPath)
-    }
-    if (process.platform !== 'win32') chmodSync(destinationPath, statSync(sourcePath).mode & 0o777)
-  }
-}
-
-function hashFile(path: string): string {
-  return createHash('sha256').update(readFileSync(path)).digest('hex')
-}
-
-function canonicalHarnessRoot(root: string): string {
-  const resolved = resolve(root)
-  if (!existsSync(resolved)) {
-    throw new Error(`Harness root must be an existing directory: ${resolved}`)
-  }
-  const canonical = realpathSync(resolved)
-  const entry = lstatSync(canonical, { throwIfNoEntry: false })
-  if (!entry || !entry.isDirectory()) {
-    throw new Error(`Harness root must be an existing directory: ${resolved}`)
-  }
-  return canonical
-}
-
-/**
- * Validate a managed path without following any link below the canonical app
- * root. A lexical containment check alone is insufficient: `app/.ai -> /tmp`
- * would otherwise make an apparently safe update write outside the app.
- */
-function assertManagedPath(root: string, path: string, options: { leaf?: 'file' | 'any' } = {}): void {
-  const absolutePath = resolve(path)
-  const normalizedRelative = relative(root, absolutePath)
-  if (
-    normalizedRelative === '..' ||
-    normalizedRelative.startsWith(`..${sep}`)
-  ) {
-    throw new Error(`Harness-managed path escapes its root: ${absolutePath}`)
-  }
-  if (normalizedRelative === '') return
-
-  const components = normalizedRelative.split(sep).filter(Boolean)
-  let current = root
-  for (let index = 0; index < components.length; index += 1) {
-    current = join(current, components[index])
-    const entry = lstatSync(current, { throwIfNoEntry: false })
-    if (!entry) return
-    if (entry.isSymbolicLink()) {
-      throw new Error(`Harness-managed path contains a symbolic-link component: ${current}`)
-    }
-    const isLeaf = index === components.length - 1
-    if (!isLeaf && !entry.isDirectory()) {
-      throw new Error(`Harness-managed path component is not a directory: ${current}`)
-    }
-    if (isLeaf && options.leaf === 'file' && !entry.isFile()) {
-      throw new Error(`Harness-managed file is not a regular file: ${current}`)
-    }
-  }
-}
-
-function ensureManagedParent(root: string, filePath: string): void {
-  const parent = dirname(filePath)
-  const normalizedRelative = relative(root, parent)
-  if (normalizedRelative === '..' || normalizedRelative.startsWith(`..${sep}`)) {
-    throw new Error(`Harness-managed path escapes its root: ${filePath}`)
-  }
-  let current = root
-  for (const component of normalizedRelative.split(sep).filter(Boolean)) {
-    assertManagedPath(root, current)
-    current = join(current, component)
-    const entry = lstatSync(current, { throwIfNoEntry: false })
-    if (!entry) mkdirSync(current)
-    const created = lstatSync(current, { throwIfNoEntry: false })
-    if (!created || created.isSymbolicLink() || !created.isDirectory()) {
-      throw new Error(`Harness-managed path component is not a real directory: ${current}`)
-    }
-  }
-}
-
-function harnessGeneratorId(): string {
-  try {
-    const upstream = JSON.parse(readFileSync(join(GUIDES_DIR, 'upstream', 'manifest.json'), 'utf8')) as {
-      generator?: unknown
-    }
-    const generator = typeof upstream.generator === 'string' ? upstream.generator : ''
-    const version = generator.slice(generator.lastIndexOf('@') + 1)
-    if (version && version !== generator) return `open-mercato-agentic@${version}`
-  } catch {
-    // Source-mode tests may not have built upstream snapshots yet.
-  }
-  return 'open-mercato-agentic@unknown'
-}
+// ─── Generators ──────────────────────────────────────────────────────────
 
-function externalSkillNames(targetDir: string): Set<string> {
-  try {
-    const tiers = JSON.parse(readFileSync(join(targetDir, '.ai', 'skills', 'tiers.json'), 'utf8')) as {
-      external?: { skills?: unknown }
-    }
-    return new Set(Array.isArray(tiers.external?.skills) ? tiers.external.skills.filter((name): name is string => typeof name === 'string') : [])
-  } catch {
-    return new Set()
-  }
-}
+function generateShared(config: AgenticConfig): void {
+  const { targetDir } = config
+  const srcDir = join(AGENTIC_DIR, 'shared')
 
-function atomicCopyFile(sourcePath: string, destinationPath: string, managedRoot?: string): void {
-  if (managedRoot) {
-    assertManagedPath(managedRoot, destinationPath, { leaf: 'file' })
-    ensureManagedParent(managedRoot, destinationPath)
-  } else {
-    ensureDir(destinationPath)
-  }
-  const temporaryPath = `${destinationPath}.tmp-${process.pid}-${Date.now()}`
-  try {
-    if (managedRoot) assertManagedPath(managedRoot, temporaryPath, { leaf: 'file' })
-    copyFileSync(sourcePath, temporaryPath)
-    if (process.platform !== 'win32') chmodSync(temporaryPath, statSync(sourcePath).mode & 0o777)
-    if (managedRoot) {
-      assertManagedPath(managedRoot, dirname(destinationPath))
-      assertManagedPath(managedRoot, destinationPath, { leaf: 'file' })
-      assertManagedPath(managedRoot, temporaryPath, { leaf: 'file' })
-    }
-    renameSync(temporaryPath, destinationPath)
-  } finally {
-    if (!managedRoot || !lstatSync(temporaryPath, { throwIfNoEntry: false })?.isSymbolicLink()) {
-      rmSync(temporaryPath, { force: true })
-    }
-  }
-}
+  // Resolve which per-module fact-sheets this app gets (enabled ∩ bundled allowlist).
+  const selectedModules = selectModuleFactSheets(targetDir, join(GUIDES_DIR, 'modules'))
+  const moduleGuideLabels = readModuleGuideLabels(GUIDES_DIR)
 
-function atomicWriteFile(destinationPath: string, content: string, managedRoot?: string): void {
-  if (managedRoot) {
-    assertManagedPath(managedRoot, destinationPath, { leaf: 'file' })
-    ensureManagedParent(managedRoot, destinationPath)
-  } else {
-    ensureDir(destinationPath)
-  }
-  const temporaryPath = `${destinationPath}.tmp-${process.pid}-${Date.now()}`
-  try {
-    if (managedRoot) assertManagedPath(managedRoot, temporaryPath, { leaf: 'file' })
-    writeFileSync(temporaryPath, content)
-    if (managedRoot) {
-      assertManagedPath(managedRoot, dirname(destinationPath))
-      assertManagedPath(managedRoot, destinationPath, { leaf: 'file' })
-      assertManagedPath(managedRoot, temporaryPath, { leaf: 'file' })
-    }
-    renameSync(temporaryPath, destinationPath)
-  } finally {
-    if (!managedRoot || !lstatSync(temporaryPath, { throwIfNoEntry: false })?.isSymbolicLink()) {
-      rmSync(temporaryPath, { force: true })
-    }
+  // AGENTS.md
+  writeTemplate(srcDir, 'AGENTS.md.template', join(targetDir, 'AGENTS.md'), config)
+  injectModuleGuides(join(targetDir, 'AGENTS.md'), selectedModules, moduleGuideLabels)
+
+  // .ai/ structure
+  writeTemplate(srcDir, 'ai/specs/README.md', join(targetDir, '.ai', 'specs', 'README.md'), config)
+  copyFile(srcDir, 'ai/specs/SPEC-000-template.md', join(targetDir, '.ai', 'specs', 'SPEC-000-template.md'))
+  copyFile(srcDir, 'ai/lessons.md', join(targetDir, '.ai', 'lessons.md'))
+
+  // .ai/skills/ — the shared skills-mixin manifest + tracker + external installer.
+  // Skills owned by the external open-mercato/skills collection (code review, spec
+  // writing, integration tests, prepare-issue, the auto-* PR family) are NOT copied
+  // here; the user installs them with `yarn install-skills` (npx skills add). Only
+  // standalone-only + kept-local skills and repo-local override folders are copied.
+  copyFile(srcDir, 'ai/skills/tiers.json', join(targetDir, '.ai', 'skills', 'tiers.json'))
+  copyFile(srcDir, 'ai/skills/tiers.schema.json', join(targetDir, '.ai', 'skills', 'tiers.schema.json'))
+  copyFile(srcDir, 'ai/agentic.config.json', join(targetDir, '.ai', 'agentic.config.json'))
+  copyFile(srcDir, 'ai/trackers/github.md', join(targetDir, '.ai', 'trackers', 'github.md'))
+  copyFile(srcDir, 'scripts/install-skills.sh', join(targetDir, 'scripts', 'install-skills.sh'))
+
+  copyFile(
+    srcDir,
+    'ai/skills/om-backend-ui-design/SKILL.md',
+    join(targetDir, '.ai', 'skills', 'om-backend-ui-design', 'SKILL.md'),
+  )
+  copyFile(
+    srcDir,
+    'ai/skills/om-backend-ui-design/references/ui-components.md',
+    join(targetDir, '.ai', 'skills', 'om-backend-ui-design', 'references', 'ui-components.md'),
+  )
+  copyFile(srcDir, 'ai/skills/om-integration-builder/SKILL.md', join(targetDir, '.ai', 'skills', 'om-integration-builder', 'SKILL.md'))
+  if (existsSync(join(srcDir, 'ai', 'skills', 'om-integration-builder', 'STANDALONE.md'))) {
+    copyFile(
+      srcDir,
+      'ai/skills/om-integration-builder/STANDALONE.md',
+      join(targetDir, '.ai', 'skills', 'om-integration-builder', 'STANDALONE.md'),
+    )
   }
-}
-
-function resolveManifestPath(root: string, relativePath: string): string | null {
-  if (!relativePath || relativePath.includes('\0')) return null
-  const absolutePath = resolve(root, relativePath)
-  const normalizedRelative = relative(root, absolutePath)
-  if (
-    normalizedRelative === '' ||
-    normalizedRelative === '..' ||
-    normalizedRelative.startsWith(`..${sep}`)
-  ) {
-    return null
+  copyFile(
+    srcDir,
+    'ai/skills/om-integration-builder/references/adapter-contracts.md',
+    join(targetDir, '.ai', 'skills', 'om-integration-builder', 'references', 'adapter-contracts.md'),
+  )
+  if (existsSync(join(srcDir, 'ai', 'skills', 'om-integration-builder', 'STANDALONE.md'))) {
+    copyFile(
+      srcDir,
+      'ai/skills/om-integration-builder/STANDALONE.md',
+      join(targetDir, '.ai', 'skills', 'om-integration-builder', 'STANDALONE.md'),
+    )
   }
-  return absolutePath
-}
 
-function normalizeManifestRelativePath(path: string): string {
-  return path.replace(/\\/g, '/')
-}
+  copyFile(
+    srcDir,
+    'ai/skills/om-system-extension/SKILL.md',
+    join(targetDir, '.ai', 'skills', 'om-system-extension', 'SKILL.md'),
+  )
+  copyFile(
+    srcDir,
+    'ai/skills/om-system-extension/references/extension-contracts.md',
+    join(targetDir, '.ai', 'skills', 'om-system-extension', 'references', 'extension-contracts.md'),
+  )
 
-function readHarnessManifest(manifestPath: string): HarnessManifest | null {
-  if (!existsSync(manifestPath)) return null
-  try {
-    const parsed = JSON.parse(readFileSync(manifestPath, 'utf8')) as Partial<HarnessManifest>
-    if (
-      typeof parsed.version !== 'number' ||
-      typeof parsed.generator !== 'string' ||
-      !Array.isArray(parsed.files)
-    ) {
-      return null
-    }
-    const files: HarnessManifestFile[] = []
-    for (const entry of parsed.files) {
-      if (
-        !entry ||
-        typeof entry.path !== 'string' ||
-        typeof entry.sha256 !== 'string' ||
-        !/^[a-f0-9]{64}$/.test(entry.sha256) ||
-        typeof entry.source !== 'string' ||
-        typeof entry.userEditable !== 'boolean'
-      ) {
-        return null
-      }
-      files.push({ ...entry, path: normalizeManifestRelativePath(entry.path) })
-    }
-    return { version: parsed.version, generator: parsed.generator, files }
-  } catch {
-    return null
-  }
-}
+  copyFile(
+    srcDir,
+    'ai/skills/om-module-scaffold/SKILL.md',
+    join(targetDir, '.ai', 'skills', 'om-module-scaffold', 'SKILL.md'),
+  )
+  copyFile(
+    srcDir,
+    'ai/skills/om-module-scaffold/references/naming-conventions.md',
+    join(targetDir, '.ai', 'skills', 'om-module-scaffold', 'references', 'naming-conventions.md'),
+  )
+  copyFile(
+    srcDir,
+    'ai/skills/om-module-scaffold/references/navigation-patterns.md',
+    join(targetDir, '.ai', 'skills', 'om-module-scaffold', 'references', 'navigation-patterns.md'),
+  )
 
-function targetPathsForTree(sourceRoot: string, destinationRoot: string): string[] {
-  return listFiles(sourceRoot).map((sourcePath) => join(destinationRoot, relative(sourceRoot, sourcePath)))
-}
+  copyFile(
+    srcDir,
+    'ai/skills/om-troubleshooter/SKILL.md',
+    join(targetDir, '.ai', 'skills', 'om-troubleshooter', 'SKILL.md'),
+  )
+  copyFile(
+    srcDir,
+    'ai/skills/om-troubleshooter/references/diagnostic-commands.md',
+    join(targetDir, '.ai', 'skills', 'om-troubleshooter', 'references', 'diagnostic-commands.md'),
+  )
 
-function finalizeHarnessManifest(config: AgenticConfig, selectedTools: string[]): void {
-  const { targetDir } = config
-  const srcDir = join(AGENTIC_DIR, 'shared')
-  const selectedModules = selectModuleFactSheets(targetDir, join(GUIDES_DIR, 'modules'))
-  const paths = new Set<string>([
-    join(targetDir, 'AGENTS.md'),
-    ...targetPathsForTree(join(srcDir, 'ai'), join(targetDir, '.ai')),
-    ...targetPathsForTree(join(srcDir, 'scripts'), join(targetDir, 'scripts')),
-  ])
-  for (const file of readdirSync(GUIDES_DIR)) {
-    if (file.endsWith('.md') || file === 'module-facts.json') paths.add(join(targetDir, '.ai', 'guides', file))
-  }
-  for (const file of listFiles(join(GUIDES_DIR, 'upstream'))) {
-    paths.add(join(targetDir, '.ai', 'guides', 'upstream', relative(join(GUIDES_DIR, 'upstream'), file)))
-  }
-  for (const moduleId of selectedModules) paths.add(join(targetDir, '.ai', 'guides', 'modules', `${moduleId}.md`))
-  if (selectedTools.includes('claude-code')) {
-    paths.add(join(targetDir, 'CLAUDE.md'))
-    paths.add(join(targetDir, '.claude', 'settings.json'))
-    paths.add(join(targetDir, '.claude', 'hooks', 'entity-migration-check.ts'))
-    paths.add(join(targetDir, '.mcp.json.example'))
-  }
-  if (selectedTools.includes('codex')) paths.add(join(targetDir, '.codex', 'mcp.json.example'))
-  if (selectedTools.includes('cursor')) {
-    for (const file of listFiles(join(AGENTIC_DIR, 'cursor'))) {
-      const rel = relative(join(AGENTIC_DIR, 'cursor'), file)
-      paths.add(join(targetDir, '.cursor', rel))
-    }
-  }
-  const manifestPath = join(targetDir, '.ai', 'harness', 'manifest.json')
-  const externalSkills = externalSkillNames(targetDir)
-  paths.delete(manifestPath)
-  const files = [...paths]
-    .filter((path) => existsSync(path))
-    .sort((left, right) => left.localeCompare(right))
-    .map((path) => {
-      const relativePath = normalizeManifestRelativePath(relative(targetDir, path))
-      const skillName = relativePath.match(/^\.ai\/skills\/([^/]+)\//)?.[1]
-      return {
-        path: relativePath,
-        sha256: hashFile(path),
-        source: skillName ? (externalSkills.has(skillName) ? 'external-override' : 'local-skill') : 'generated',
-        userEditable:
-          relativePath === 'AGENTS.md'
-          || relativePath === '.ai/agentic.config.json'
-          || relativePath === '.ai/lessons.md'
-          || relativePath.startsWith('.ai/lessons/'),
-      }
-    })
-  atomicWriteFile(
-    manifestPath,
-    `${JSON.stringify({ version: 1, generator: harnessGeneratorId(), files }, null, 2)}\n`,
+  copyFile(
+    srcDir,
+    'ai/skills/om-eject-and-customize/SKILL.md',
+    join(targetDir, '.ai', 'skills', 'om-eject-and-customize', 'SKILL.md'),
   )
-}
 
-/**
- * Publish a fully generated harness candidate using the previous ownership
- * manifest as the only source of ownership. Modified owned files and exact-path
- * collisions with unknown files stay untouched; their candidate is written next
- * to them as `<path>.incoming` for explicit review.
- */
-export type HarnessUpdateConflict = { path: string; candidate: string | null }
-
-function preserveIncomingCandidate(
-  targetRoot: string,
-  destinationPath: string,
-  sourcePath: string,
-  relativePath: string,
-): string {
-  for (let suffix = 1; ; suffix += 1) {
-    const label = suffix === 1 ? '.incoming' : `.incoming.${suffix}`
-    const candidatePath = `${destinationPath}${label}`
-    assertManagedPath(targetRoot, candidatePath, { leaf: 'file' })
-    if (!existsSync(candidatePath)) {
-      atomicCopyFile(sourcePath, candidatePath, targetRoot)
-      return `${relativePath}${label}`
-    }
-    if (hashFile(candidatePath) === hashFile(sourcePath)) return `${relativePath}${label}`
-  }
-}
+  copyFile(
+    srcDir,
+    'ai/skills/om-data-model-design/SKILL.md',
+    join(targetDir, '.ai', 'skills', 'om-data-model-design', 'SKILL.md'),
+  )
+  copyFile(
+    srcDir,
+    'ai/skills/om-data-model-design/references/mikro-orm-cheatsheet.md',
+    join(targetDir, '.ai', 'skills', 'om-data-model-design', 'references', 'mikro-orm-cheatsheet.md'),
+  )
 
-export function applyHarnessUpdate(
-  targetDir: string,
-  stagingDir: string,
-  options: { force?: boolean } = {},
-): HarnessUpdateConflict[] {
-  const targetRoot = canonicalHarnessRoot(targetDir)
-  const stagingRoot = canonicalHarnessRoot(stagingDir)
-  const targetManifestPath = join(targetRoot, '.ai', 'harness', 'manifest.json')
-  const stagingManifestPath = join(stagingRoot, '.ai', 'harness', 'manifest.json')
-  assertManagedPath(targetRoot, targetManifestPath, { leaf: 'file' })
-  assertManagedPath(stagingRoot, stagingManifestPath, { leaf: 'file' })
-  const candidateManifest = readHarnessManifest(stagingManifestPath)
-  if (!candidateManifest) {
-    throw new Error('Generated harness candidate has a missing or invalid ownership manifest.')
-  }
+  copyFile(
+    srcDir,
+    'ai/skills/om-implement-spec/SKILL.md',
+    join(targetDir, '.ai', 'skills', 'om-implement-spec', 'SKILL.md'),
+  )
 
-  const previousManifest = readHarnessManifest(targetManifestPath)
-  const previousFiles = new Map(previousManifest?.files.map((entry) => [entry.path, entry]) ?? [])
-  const candidatePaths = new Set(candidateManifest.files.map((entry) => entry.path))
-  const candidates: Array<{
-    entry: HarnessManifestFile
-    sourcePath: string
-    destinationPath: string
-  }> = []
-
-  // Validate the complete candidate before writing anything into the app.
-  for (const entry of candidateManifest.files) {
-    const sourcePath = resolveManifestPath(stagingRoot, entry.path)
-    const destinationPath = resolveManifestPath(targetRoot, entry.path)
-    if (sourcePath) assertManagedPath(stagingRoot, sourcePath, { leaf: 'file' })
-    if (destinationPath) assertManagedPath(targetRoot, destinationPath, { leaf: 'file' })
-    if (!sourcePath || !destinationPath || !existsSync(sourcePath) || hashFile(sourcePath) !== entry.sha256) {
-      throw new Error(`Generated harness candidate is invalid for ${JSON.stringify(entry.path)}.`)
-    }
-    candidates.push({ entry, sourcePath, destinationPath })
-  }
+  copyFile(
+    srcDir,
+    'ai/skills/om-help/SKILL.md',
+    join(targetDir, '.ai', 'skills', 'om-help', 'SKILL.md'),
+  )
+  copyFile(
+    srcDir,
+    'ai/skills/om-help/references/skills-catalog.md',
+    join(targetDir, '.ai', 'skills', 'om-help', 'references', 'skills-catalog.md'),
+  )
+  copyFile(
+    srcDir,
+    'ai/skills/om-help/references/workflow-sequences.md',
+    join(targetDir, '.ai', 'skills', 'om-help', 'references', 'workflow-sequences.md'),
+  )
 
-  const conflicts: HarnessUpdateConflict[] = []
-  for (const { entry, sourcePath, destinationPath } of candidates) {
-    if (options.force) {
-      atomicCopyFile(sourcePath, destinationPath, targetRoot)
-      continue
-    }
-    if (!existsSync(destinationPath)) {
-      atomicCopyFile(sourcePath, destinationPath, targetRoot)
-      continue
-    }
+  copyFile(
+    srcDir,
+    'ai/skills/om-auto-upgrade-0.4.10-to-0.5.0/SKILL.md',
+    join(targetDir, '.ai', 'skills', 'om-auto-upgrade-0.4.10-to-0.5.0', 'SKILL.md'),
+  )
 
-    const currentHash = hashFile(destinationPath)
-    const previousEntry = previousFiles.get(entry.path)
-    if (currentHash === entry.sha256 || (previousEntry && currentHash === previousEntry.sha256)) {
-      atomicCopyFile(sourcePath, destinationPath, targetRoot)
+  // Slim repo-local OVERRIDE folders (SKILL.md only) for the external auto-* PR
+  // family + single autofix skill. The workflow bodies live in open-mercato/skills
+  // (installed via `yarn install-skills`); these overrides adjust them for a
+  // standalone app and are read on top of the external skill's built-in workflow.
+  // om-prepare-test-env's override carries environment knowledge (cross-platform
+  // mercato CLI runner commands) rather than tracker adjustments.
+  for (const autoSkill of [
+    'om-auto-create-pr',
+    'om-auto-continue-pr',
+    'om-auto-create-pr-loop',
+    'om-auto-continue-pr-loop',
+    'om-auto-review-pr',
+    'om-auto-fix-issue',
+    'om-prepare-test-env',
+  ]) {
+    if (!existsSync(join(srcDir, 'ai', 'skills', autoSkill, 'SKILL.md'))) {
       continue
     }
-
-    const candidate = preserveIncomingCandidate(targetRoot, destinationPath, sourcePath, entry.path)
-    conflicts.push({ path: entry.path, candidate })
-  }
-
-  const retainedRetiredEntries: HarnessManifestFile[] = []
-  for (const previousEntry of previousManifest?.files ?? []) {
-    if (candidatePaths.has(previousEntry.path)) continue
-    const destinationPath = resolveManifestPath(targetRoot, previousEntry.path)
-    if (!destinationPath || !existsSync(destinationPath)) continue
-    assertManagedPath(targetRoot, destinationPath, { leaf: 'file' })
-    let unchanged = false
-    try {
-      unchanged = hashFile(destinationPath) === previousEntry.sha256
-    } catch {
-      // A user may replace a generated file with another filesystem object.
-      // Preserve it and retain the ownership tombstone for a later review.
-    }
-    if (unchanged) {
-      assertManagedPath(targetRoot, dirname(destinationPath))
-      assertManagedPath(targetRoot, destinationPath, { leaf: 'file' })
-      rmSync(destinationPath, { force: true })
-    } else {
-      retainedRetiredEntries.push(previousEntry)
-      conflicts.push({ path: previousEntry.path, candidate: null })
-    }
+    copyFile(
+      srcDir,
+      `ai/skills/${autoSkill}/SKILL.md`,
+      join(targetDir, '.ai', 'skills', autoSkill, 'SKILL.md'),
+    )
   }
 
-  // The candidate hashes deliberately remain in the manifest for conflicts. If
-  // the user accepts an .incoming file, a later update can recognize it as an
-  // unmodified owned file. Until then the hash mismatch keeps preserving it.
-  const finalManifest: HarnessManifest = {
-    ...candidateManifest,
-    files: [...candidateManifest.files, ...retainedRetiredEntries],
-  }
-  atomicWriteFile(targetManifestPath, `${JSON.stringify(finalManifest, null, 2)}\n`, targetRoot)
-  return conflicts
-}
-
-// ─── Generators ──────────────────────────────────────────────────────────
-
-function generateShared(config: AgenticConfig): void {
-  const { targetDir } = config
-  const srcDir = join(AGENTIC_DIR, 'shared')
-
-  // Resolve which per-module fact-sheets this app gets (enabled ∩ bundled allowlist).
-  const selectedModules = selectModuleFactSheets(targetDir, join(GUIDES_DIR, 'modules'))
+  copyFile(
+    srcDir,
+    'ai/skills/om-trim-unused-modules/SKILL.md',
+    join(targetDir, '.ai', 'skills', 'om-trim-unused-modules', 'SKILL.md'),
+  )
 
-  // One recursive mapping mirrors create-app's shared emitter.
-  writeTemplate(srcDir, 'AGENTS.md.template', join(targetDir, 'AGENTS.md'), config)
-  copyTree(join(srcDir, 'ai'), join(targetDir, '.ai'), config)
-  copyTree(join(srcDir, 'scripts'), join(targetDir, 'scripts'), config)
+  copyFile(srcDir, 'ai/qa/tests/playwright.config.ts', join(targetDir, '.ai', 'qa', 'tests', 'playwright.config.ts'))
 
-  // Routed conceptual guides are copied wholesale (framework-wide). Per-module
+  // Package & conceptual guides are copied wholesale (framework-wide). Per-module
   // fact-sheets (.ai/guides/modules/<module>.md) are filtered to the app's enabled
   // module set; the combined module-facts.json sidecar is copied as-is.
   if (existsSync(GUIDES_DIR)) {
@@ -604,9 +357,6 @@ function generateShared(config: AgenticConfig): void {
       copyFileSync(moduleFactsPath, destPath)
     }
 
-
-    copyTree(join(GUIDES_DIR, 'upstream'), join(guidesDestDir, 'upstream'), config)
-
     const modulesSubdir = join(GUIDES_DIR, 'modules')
     for (const moduleId of selectedModules) {
       const destPath = join(guidesDestDir, 'modules', `${moduleId}.md`)
@@ -614,8 +364,6 @@ function generateShared(config: AgenticConfig): void {
       copyFileSync(join(modulesSubdir, `${moduleId}.md`), destPath)
     }
   }
-
-  injectModuleGuides(join(targetDir, 'AGENTS.md'), selectedModules)
 }
 
 function generateClaudeCode(config: AgenticConfig): void {
@@ -627,7 +375,8 @@ function generateClaudeCode(config: AgenticConfig): void {
   copyFile(srcDir, 'hooks/entity-migration-check.ts', join(targetDir, '.claude', 'hooks', 'entity-migration-check.ts'))
   copyFile(srcDir, 'mcp.json.example', join(targetDir, '.mcp.json.example'))
 
-  // The installer exclusively owns Claude's per-skill compatibility links.
+  // Symlink .claude/skills → ../.ai/skills
+  ensureSkillsLink(join(targetDir, '.claude', 'skills'), join('..', '.ai', 'skills'))
 }
 
 function generateCodex(config: AgenticConfig): void {
@@ -679,6 +428,17 @@ function generateCursor(config: AgenticConfig): void {
   // which scripts/install-skills.sh populates.
 }
 
+function ensureSkillsLink(linkPath: string, target: string): void {
+  ensureDir(linkPath)
+  if (existsSync(linkPath) && !lstatSync(linkPath).isSymbolicLink()) {
+    return
+  }
+  if (lstatSync(linkPath, { throwIfNoEntry: false })?.isSymbolicLink()) {
+    unlinkSync(linkPath)
+  }
+  symlinkSync(target, linkPath)
+}
+
 // ─── Wizard ──────────────────────────────────────────────────────────────
 
 const TOOLS = [
@@ -691,35 +451,6 @@ const TOOLS = [
 
 const SELECTABLE = TOOLS.filter((t) => t.id !== 'multiple' && t.id !== 'skip')
 
-function persistedAgentSelection(targetDir: string): string[] | null {
-  const selectableIds = SELECTABLE.map((tool) => tool.id)
-  const tiersPath = join(targetDir, '.ai', 'skills', 'tiers.json')
-  try {
-    const tiers = JSON.parse(readFileSync(tiersPath, 'utf8')) as { agents?: { ignore?: unknown } }
-    if (Array.isArray(tiers.agents?.ignore)
-      && tiers.agents.ignore.every((id): id is string => typeof id === 'string')) {
-      const ignored = new Set(tiers.agents.ignore)
-      return selectableIds.filter((id) => !ignored.has(id))
-    }
-  } catch {
-    // Fall through to the ownership manifest and existing generated assets.
-  }
-
-  const manifest = readHarnessManifest(join(targetDir, '.ai', 'harness', 'manifest.json'))
-  const owned = new Set(manifest?.files.map((entry) => entry.path) ?? [])
-  const selected = SELECTABLE.filter((tool) => {
-    if (tool.id === 'claude-code') {
-      return owned.has('CLAUDE.md') || owned.has('.claude/settings.json')
-        || existsSync(join(targetDir, 'CLAUDE.md')) || existsSync(join(targetDir, '.claude', 'settings.json'))
-    }
-    if (tool.id === 'codex') {
-      return owned.has('.codex/mcp.json.example') || existsSync(join(targetDir, '.codex', 'mcp.json.example'))
-    }
-    return owned.has('.cursor/hooks.json') || existsSync(join(targetDir, '.cursor', 'hooks.json'))
-  }).map((tool) => tool.id)
-  return selected.length > 0 ? selected : null
-}
-
 async function promptSelection(ask: AskFn): Promise<string[]> {
   console.log('')
   console.log('🤖  Agentic workflow setup')
@@ -766,8 +497,6 @@ export async function runAgenticSetup(
 
   if (options?.tool) {
     selectedIds = options.tool.split(',').map((t) => t.trim())
-  } else if (options?.updateHarness) {
-    selectedIds = persistedAgentSelection(targetDir) ?? await promptSelection(ask)
   } else {
     selectedIds = await promptSelection(ask)
   }
@@ -784,37 +513,12 @@ export async function runAgenticSetup(
     targetDir,
   }
 
-  const stagingDir = mkdtempSync(join(tmpdir(), 'open-mercato-harness-'))
-  try {
-    const modulesSourcePath = join(targetDir, 'src', 'modules.ts')
-    const modulesCandidatePath = join(stagingDir, 'src', 'modules.ts')
-    if (existsSync(modulesSourcePath)) {
-      ensureDir(modulesCandidatePath)
-      copyFileSync(modulesSourcePath, modulesCandidatePath)
-    }
-
-    const stagingConfig: AgenticConfig = {
-      projectName: config.projectName,
-      targetDir: stagingDir,
-    }
-    generateHarness(stagingConfig, selectedIds)
-    const conflicts = applyHarnessUpdate(targetDir, stagingDir, {
-      force: options?.force,
-    })
-    if (conflicts.length > 0) {
-      console.warn('')
-      console.warn('   ⚠ Preserved locally modified harness files:')
-      for (const conflict of conflicts) {
-        const detail = conflict.candidate
-          ? `candidate: ${conflict.candidate}`
-          : 'retired asset kept because it has local changes'
-        console.warn(`   • ${conflict.path} (${detail})`)
-      }
-    }
-  } finally {
-    rmSync(stagingDir, { recursive: true, force: true })
-  }
+  generateShared(config)
+  if (selectedIds.includes('claude-code')) generateClaudeCode(config)
+  if (selectedIds.includes('codex')) generateCodex(config)
+  if (selectedIds.includes('cursor')) generateCursor(config)
 
+  persistAgentSelection(targetDir, selectedIds)
   installSkills(targetDir)
 
   console.log('')
@@ -836,16 +540,6 @@ export async function runAgenticSetup(
   console.log('')
 }
 
-function generateHarness(config: AgenticConfig, selectedIds: string[]): void {
-  generateShared(config)
-  if (selectedIds.includes('claude-code')) generateClaudeCode(config)
-  if (selectedIds.includes('codex')) generateCodex(config)
-  if (selectedIds.includes('cursor')) generateCursor(config)
-
-  persistAgentSelection(config.targetDir, selectedIds)
-  finalizeHarnessManifest(config, selectedIds)
-}
-
 /**
  * Persist the agent selection so later `yarn install-skills` runs keep honoring
  * it: agents the user did not pick go into `agents.ignore` in tiers.json and
@@ -865,11 +559,11 @@ function persistAgentSelection(targetDir: string, selectedIds: string[]): void {
 }
 
 function installSkills(targetDir: string): void {
-  const installScript = join(targetDir, 'scripts', 'install-skills.mjs')
+  const installScript = join(targetDir, 'scripts', 'install-skills.sh')
   if (!existsSync(installScript)) return
   console.log('')
   console.log('   Installing agent skills (local tiers + external open-mercato/skills subset)...')
-  const result = spawnSync(process.execPath, [installScript], { cwd: targetDir, stdio: 'inherit' })
+  const result = spawnSync('sh', [installScript], { cwd: targetDir, stdio: 'inherit' })
   if (result.error || result.status !== 0) {
     console.log('   ⚠ Skill installation did not complete; run `yarn install-skills` inside the app when online.')
   }