@open-mercato/cli 0.6.7 → 0.6.8-canary.319.1.5b4be4bc52

package/src/lib/agentic-setup.ts

@@ -6,16 +6,35 @@
  * This module reads those files at runtime — no embedded string constants.
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, symlinkSync, lstatSync, unlinkSync, readdirSync } from 'node:fs'
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs'
+import { createHash } from 'node:crypto'
 import { spawnSync } from 'node:child_process'
-import { join, dirname, basename } from 'node:path'
+import { tmpdir } from 'node:os'
+import { join, dirname, basename, relative, resolve, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { Project, SyntaxKind } from 'ts-morph'
 
-const __dirname = dirname(fileURLToPath(import.meta.url))
-// In the built output (dist/lib/agentic-setup.js), __dirname is dist/lib/.
+const moduleDir = dirname(fileURLToPath(import.meta.url))
+// In the built output (dist/lib/agentic-setup.js), moduleDir is dist/lib/.
 // agentic/ is copied to dist/agentic/ by build.mjs.
-const AGENTIC_DIR = join(__dirname, '..', 'agentic')
+const bundledAgenticDir = join(moduleDir, '..', 'agentic')
+const AGENTIC_DIR = existsSync(bundledAgenticDir)
+  ? bundledAgenticDir
+  : join(moduleDir, '..', '..', '..', 'create-app', 'agentic')
 const GUIDES_DIR = join(AGENTIC_DIR, 'guides')
 
 type AskFn = (question: string) => Promise<string>
@@ -23,6 +42,7 @@ type AskFn = (question: string) => Promise<string>
 interface AgenticSetupOptions {
   tool?: string
   force?: boolean
+  updateHarness?: boolean
 }
 
 interface AgenticConfig {
@@ -30,6 +50,19 @@ 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 {
@@ -59,14 +92,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): string[] {
-  if (!existsSync(modulesPath)) return []
+function readEnabledModuleIds(modulesPath: string): { parsed: boolean; ids: string[] } {
+  if (!existsSync(modulesPath)) return { parsed: false, ids: [] }
   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 []
+    if (!arrayLiteral) return { parsed: false, ids: [] }
     const ids: string[] = []
     for (const element of arrayLiteral.getElements()) {
       const objectLiteral = element.asKind(SyntaxKind.ObjectLiteralExpression)
@@ -75,9 +108,9 @@ function readEnabledModuleIds(modulesPath: string): string[] {
       const idValue = idProperty?.getInitializerIfKind(SyntaxKind.StringLiteral)?.getLiteralValue()
       if (idValue) ids.push(idValue)
     }
-    return ids
+    return { parsed: true, ids }
   } catch {
-    return []
+    return { parsed: false, ids: [] }
   }
 }
 
@@ -92,48 +125,40 @@ function selectModuleFactSheets(targetDir: string, modulesSubdir: string): strin
         .map((file) => file.replace(/\.md$/, ''))
     : []
   if (available.length === 0) return []
-  const enabled = new Set(readEnabledModuleIds(join(targetDir, 'src', 'modules.ts')))
+  const parsed = readEnabledModuleIds(join(targetDir, 'src', 'modules.ts'))
+  if (!parsed.parsed) return available
+  const enabled = new Set(parsed.ids)
   const selected = available.filter((moduleId) => enabled.has(moduleId))
-  return selected.length > 0 ? selected : available
+  return selected
 }
 
 const MODULE_GUIDES_START = '<!-- om:module-guides:start -->'
 const MODULE_GUIDES_END = '<!-- om:module-guides:end -->'
 
-// 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 {}
-  }
+// The generated standalone root must stay well under Codex's 32 KiB
+// project_doc_max_bytes so a routed chain (root + guide + skill) still fits.
+export const STANDALONE_ROOT_TARGET_BYTES = 12 * 1024
+
+export type ModuleGuidesRenderOptions = {
+  // Emit the O(1) pointer form instead of enumerating every id. The inline index
+  // is the better prompt, so callers only ask for this when the enumerated one
+  // would push the root past its byte target.
+  compact?: boolean
 }
 
-function renderModuleGuidesBlock(selected: string[], labels: Record<string, string>): string {
+export function renderModuleGuidesBlock(
+  selected: string[],
+  options: ModuleGuidesRenderOptions = {},
+): string {
   if (selected.length === 0) return '_No module fact-sheets are bundled for this app._'
-  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')
+  const index = options.compact
+    ? `Enabled module facts: ${selected.length} sheets bundled, too many to index inline — list the module facts directory to see which modules have one.`
+    : `Enabled module facts: ${selected.map((moduleId) => `\`${moduleId}\``).join(',')}.`
+  return [
+    index,
+    '',
+    'Load `.ai/guides/modules/<id>.md` only for a named or targeted installed module/host; never preload all module facts.',
+  ].join('\n')
 }
 
 // Regenerate the marker-delimited Module-Specific Guides block in the written
@@ -142,7 +167,7 @@ function renderModuleGuidesBlock(selected: string[], labels: Record<string, stri
 function injectModuleGuides(
   agentsMdPath: string,
   selected: string[],
-  labels: Record<string, string> = {},
+  options: ModuleGuidesRenderOptions = {},
 ): void {
   if (!existsSync(agentsMdPath)) return
   const content = readFileSync(agentsMdPath, 'utf-8')
@@ -156,188 +181,443 @@ function injectModuleGuides(
   }
   const before = content.slice(0, startIndex + MODULE_GUIDES_START.length)
   const after = content.slice(endIndex)
-  const next = `${before}\n${renderModuleGuidesBlock(selected, labels)}\n${after}`
+  const next = `${before}\n${renderModuleGuidesBlock(selected, options)}\n${after}`
   if (next !== content) writeFileSync(agentsMdPath, next)
 }
 
-// ─── Generators ──────────────────────────────────────────────────────────
+// Last step of harness generation: every tool generator has finished patching
+// AGENTS.md, so this is the only point where the final root size is known. The
+// enumerated module index is the one block that grows with the app, so it is
+// also the one that sheds bytes when the root would otherwise blow its target.
+export function enforceRootInstructionBudget(
+  agentsMdPath: string,
+  selected: string[],
+  maxBytes: number = STANDALONE_ROOT_TARGET_BYTES,
+): boolean {
+  if (!existsSync(agentsMdPath)) return false
+  if (Buffer.byteLength(readFileSync(agentsMdPath)) <= maxBytes) return false
+  injectModuleGuides(agentsMdPath, selected, { compact: true })
+  return true
+}
 
-function generateShared(config: AgenticConfig): void {
-  const { targetDir } = config
-  const srcDir = join(AGENTIC_DIR, 'shared')
+const TEXT_EXTENSIONS = new Set(['.cjs', '.json', '.md', '.mdc', '.mjs', '.sh', '.ts', '.txt'])
 
-  // 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 isTextAsset(path: string): boolean {
+  const dot = path.lastIndexOf('.')
+  return dot === -1 || TEXT_EXTENSIONS.has(path.slice(dot))
+}
 
-  // 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 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)
   }
-  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 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)
   }
+}
 
-  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 hashFile(path: string): string {
+  return createHash('sha256').update(readFileSync(path)).digest('hex')
+}
 
-  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 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
+}
 
-  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'),
-  )
+/**
+ * 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}`)
+    }
+  }
+}
 
-  copyFile(
-    srcDir,
-    'ai/skills/om-eject-and-customize/SKILL.md',
-    join(targetDir, '.ai', 'skills', 'om-eject-and-customize', 'SKILL.md'),
-  )
+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}`)
+    }
+  }
+}
 
-  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'),
-  )
+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'
+}
 
-  copyFile(
-    srcDir,
-    'ai/skills/om-implement-spec/SKILL.md',
-    join(targetDir, '.ai', 'skills', 'om-implement-spec', 'SKILL.md'),
-  )
+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()
+  }
+}
 
-  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'),
-  )
+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 })
+    }
+  }
+}
 
-  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'),
+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 })
+    }
+  }
+}
+
+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
+  }
+  return absolutePath
+}
+
+function normalizeManifestRelativePath(path: string): string {
+  return path.replace(/\\/g, '/')
+}
+
+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
+  }
+}
+
+function targetPathsForTree(sourceRoot: string, destinationRoot: string): string[] {
+  return listFiles(sourceRoot).map((sourcePath) => join(destinationRoot, relative(sourceRoot, sourcePath)))
+}
+
+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`,
   )
+}
+
+/**
+ * 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}`
+  }
+}
 
-  // 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'))) {
+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.')
+  }
+
+  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 })
+  }
+
+  const conflicts: HarnessUpdateConflict[] = []
+  for (const { entry, sourcePath, destinationPath } of candidates) {
+    if (options.force) {
+      atomicCopyFile(sourcePath, destinationPath, targetRoot)
       continue
     }
-    copyFile(
-      srcDir,
-      `ai/skills/${autoSkill}/SKILL.md`,
-      join(targetDir, '.ai', 'skills', autoSkill, 'SKILL.md'),
-    )
+    if (!existsSync(destinationPath)) {
+      atomicCopyFile(sourcePath, destinationPath, targetRoot)
+      continue
+    }
+
+    const currentHash = hashFile(destinationPath)
+    const previousEntry = previousFiles.get(entry.path)
+    if (currentHash === entry.sha256 || (previousEntry && currentHash === previousEntry.sha256)) {
+      atomicCopyFile(sourcePath, destinationPath, targetRoot)
+      continue
+    }
+
+    const candidate = preserveIncomingCandidate(targetRoot, destinationPath, sourcePath, entry.path)
+    conflicts.push({ path: entry.path, candidate })
   }
 
-  copyFile(
-    srcDir,
-    'ai/skills/om-trim-unused-modules/SKILL.md',
-    join(targetDir, '.ai', 'skills', 'om-trim-unused-modules', 'SKILL.md'),
-  )
+  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/qa/tests/playwright.config.ts', join(targetDir, '.ai', 'qa', 'tests', 'playwright.config.ts'))
+  // 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
+}
 
-  // Package & conceptual guides are copied wholesale (framework-wide). Per-module
+// ─── 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'))
+
+  // 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)
+
+  // Routed 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)) {
@@ -357,6 +637,9 @@ 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`)
@@ -364,6 +647,8 @@ function generateShared(config: AgenticConfig): void {
       copyFileSync(join(modulesSubdir, `${moduleId}.md`), destPath)
     }
   }
+
+  injectModuleGuides(join(targetDir, 'AGENTS.md'), selectedModules)
 }
 
 function generateClaudeCode(config: AgenticConfig): void {
@@ -375,8 +660,7 @@ 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'))
 
-  // Symlink .claude/skills → ../.ai/skills
-  ensureSkillsLink(join(targetDir, '.claude', 'skills'), join('..', '.ai', 'skills'))
+  // The installer exclusively owns Claude's per-skill compatibility links.
 }
 
 function generateCodex(config: AgenticConfig): void {
@@ -428,17 +712,6 @@ 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 = [
@@ -451,6 +724,35 @@ 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')
@@ -497,6 +799,8 @@ 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)
   }
@@ -513,12 +817,37 @@ export async function runAgenticSetup(
     targetDir,
   }
 
-  generateShared(config)
-  if (selectedIds.includes('claude-code')) generateClaudeCode(config)
-  if (selectedIds.includes('codex')) generateCodex(config)
-  if (selectedIds.includes('cursor')) generateCursor(config)
+  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 })
+  }
 
-  persistAgentSelection(targetDir, selectedIds)
   installSkills(targetDir)
 
   console.log('')
@@ -540,6 +869,28 @@ 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)
+
+  enforceGeneratedRootBudget(config)
+
+  persistAgentSelection(config.targetDir, selectedIds)
+  finalizeHarnessManifest(config, selectedIds)
+}
+
+/** Run after every tool generator has patched AGENTS.md, before the manifest is hashed. */
+function enforceGeneratedRootBudget(
+  config: AgenticConfig,
+  maxBytes: number = STANDALONE_ROOT_TARGET_BYTES,
+): boolean {
+  const { targetDir } = config
+  const selectedModules = selectModuleFactSheets(targetDir, join(GUIDES_DIR, 'modules'))
+  return enforceRootInstructionBudget(join(targetDir, 'AGENTS.md'), selectedModules, maxBytes)
+}
+
 /**
  * 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
@@ -559,11 +910,11 @@ function persistAgentSelection(targetDir: string, selectedIds: string[]): void {
 }
 
 function installSkills(targetDir: string): void {
-  const installScript = join(targetDir, 'scripts', 'install-skills.sh')
+  const installScript = join(targetDir, 'scripts', 'install-skills.mjs')
   if (!existsSync(installScript)) return
   console.log('')
   console.log('   Installing agent skills (local tiers + external open-mercato/skills subset)...')
-  const result = spawnSync('sh', [installScript], { cwd: targetDir, stdio: 'inherit' })
+  const result = spawnSync(process.execPath, [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.')
   }