@t275005746/gse 0.1.0

package/scripts/discover-project-profile.mjs

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import path from 'node:path'
+
+const args = process.argv.slice(2)
+
+function readArg(name, fallback = null) {
+  const index = args.indexOf(name)
+  if (index === -1) return fallback
+  return args[index + 1] ?? fallback
+}
+
+const target = path.resolve(readArg('--target', process.cwd()))
+const write = args.includes('--write')
+const force = args.includes('--force')
+const json = args.includes('--json')
+const profilePath = path.join(target, '.gse', 'project-profile.md')
+
+function exists(relativePath) {
+  return fs.existsSync(path.join(target, relativePath))
+}
+
+function readText(relativePath) {
+  const filePath = path.join(target, relativePath)
+  if (!fs.existsSync(filePath)) return null
+  return fs.readFileSync(filePath, 'utf8')
+}
+
+function safeJson(relativePath) {
+  const text = readText(relativePath)
+  if (!text) return null
+  try {
+    return JSON.parse(text.replace(/^\uFEFF/, ''))
+  } catch {
+    return null
+  }
+}
+
+function listExisting(paths) {
+  return paths.filter((item) => exists(item))
+}
+
+function detectPackageManager() {
+  if (exists('pnpm-lock.yaml')) return 'pnpm'
+  if (exists('bun.lockb') || exists('bun.lock')) return 'bun'
+  if (exists('yarn.lock')) return 'yarn'
+  if (exists('package-lock.json')) return 'npm'
+  if (exists('package.json')) return 'npm or project-specific'
+  return ''
+}
+
+function detectFrameworks(pkg) {
+  if (!pkg) return []
+  const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) }
+  const frameworks = []
+  const checks = [
+    ['next', 'Next.js'],
+    ['react', 'React'],
+    ['vite', 'Vite'],
+    ['vue', 'Vue'],
+    ['svelte', 'Svelte'],
+    ['typescript', 'TypeScript'],
+    ['playwright', 'Playwright'],
+    ['@playwright/test', 'Playwright'],
+    ['vitest', 'Vitest'],
+    ['jest', 'Jest'],
+    ['eslint', 'ESLint'],
+    ['prettier', 'Prettier'],
+  ]
+  for (const [dep, label] of checks) {
+    if (deps[dep] && !frameworks.includes(label)) frameworks.push(label)
+  }
+  return frameworks
+}
+
+function detectScripts(pkg) {
+  const scripts = pkg?.scripts ?? {}
+  const wanted = ['install', 'dev', 'start', 'test', 'test:unit', 'test:e2e', 'lint', 'typecheck', 'check', 'build', 'format']
+  const names = new Set(wanted.filter((name) => scripts[name]))
+  for (const name of Object.keys(scripts)) {
+    if (/^(smoke|evidence|replay|eval|release|deploy|publish|electron):/.test(name)) names.add(name)
+  }
+  return [...names]
+    .filter((name) => scripts[name])
+    .map((name) => ({ name, command: scripts[name] }))
+}
+
+function detectWorkflows() {
+  const dir = path.join(target, '.github', 'workflows')
+  if (!fs.existsSync(dir)) return []
+  return fs.readdirSync(dir).filter((name) => /\.ya?ml$/i.test(name)).map((name) => `.github/workflows/${name}`)
+}
+
+function detectMcpFiles() {
+  return listExisting([
+    '.mcp.json',
+    'mcp.json',
+    '.cursor/mcp.json',
+    '.claude/mcp.json',
+    '.codex/mcp.json',
+  ])
+}
+
+function detectAgentRules() {
+  return listExisting([
+    'AGENTS.md',
+    'CLAUDE.md',
+    'GEMINI.md',
+    'CONTEXT.md',
+    'CONTEXT-MAP.md',
+    '.cursorrules',
+    '.windsurfrules',
+  ])
+}
+
+function detectDocs() {
+  return listExisting([
+    'README.md',
+    'CONTRIBUTING.md',
+    'CODING_STANDARDS.md',
+    'SECURITY.md',
+    'CHANGELOG.md',
+    'docs/adr',
+    'docs/architecture.md',
+  ])
+}
+
+function detectConfigFiles() {
+  return listExisting([
+    'package.json',
+    'tsconfig.json',
+    'Makefile',
+    'justfile',
+    'pyproject.toml',
+    'Cargo.toml',
+    'go.mod',
+    'playwright.config.ts',
+    'playwright.config.js',
+    'vite.config.ts',
+    'vite.config.js',
+    'next.config.js',
+    'eslint.config.js',
+    'eslint.config.mjs',
+    '.prettierrc',
+    '.pre-commit-config.yaml',
+    '.env.example',
+  ])
+}
+
+function inferRepoType(pkg, configs) {
+  if (pkg) return 'JavaScript/TypeScript package or web app'
+  if (configs.includes('pyproject.toml')) return 'Python project'
+  if (configs.includes('Cargo.toml')) return 'Rust project'
+  if (configs.includes('go.mod')) return 'Go project'
+  return 'unknown'
+}
+
+function table(rows) {
+  if (rows.length === 0) return '| Item | Value | Status | Evidence |\n|---|---|---|---|\n| - | - | unknown | - |'
+  return ['| Item | Value | Status | Evidence |', '|---|---|---|---|', ...rows.map((row) => `| ${row.item} | ${row.value} | ${row.status} | ${row.evidence} |`)].join('\n')
+}
+
+function renderMarkdown(model) {
+  const scriptLines = model.scripts.length
+    ? model.scripts.map((item) => `- ${item.name}: \`${item.command}\` (documented in package.json)`).join('\n')
+    : '- No package scripts detected.'
+
+  const toolRows = [
+    ...model.toolConnections.map((item) => ({
+      item: item.tool,
+      value: item.purpose,
+      status: item.status,
+      evidence: item.evidence,
+    })),
+  ]
+
+  return `# Project Profile
+
+Generated: ${model.generatedAt}
+
+Keep this file short and factual. Project-specific rules override generic GSE defaults.
+
+## Identity
+
+- Product/system name: ${model.identity.name}
+- Repository type: ${model.identity.repoType}
+- Main languages/frameworks: ${model.identity.frameworks.length ? model.identity.frameworks.join(', ') : 'unknown'}
+- Package manager: ${model.identity.packageManager || 'unknown'}
+
+## Evidence Sources
+
+- Agent rules: ${model.sources.agentRules.length ? model.sources.agentRules.join(', ') : '-'}
+- Docs: ${model.sources.docs.length ? model.sources.docs.join(', ') : '-'}
+- Config files: ${model.sources.configFiles.length ? model.sources.configFiles.join(', ') : '-'}
+- CI workflows: ${model.sources.workflows.length ? model.sources.workflows.join(', ') : '-'}
+
+## Development Commands
+
+${scriptLines}
+
+## Standards
+
+- Coding standards: ${model.sources.docs.includes('CODING_STANDARDS.md') ? 'documented in CODING_STANDARDS.md' : 'unknown'}
+- Formatting: ${model.formatting.length ? model.formatting.join(', ') : 'unknown'}
+- Testing expectations: ${model.testing.length ? model.testing.join(', ') : 'unknown'}
+- Documentation expectations: ${model.sources.docs.includes('CONTRIBUTING.md') ? 'documented in CONTRIBUTING.md' : 'unknown'}
+
+## Tool Connections
+
+${table(toolRows)}
+
+## Agent Host Adapters
+
+- Codex: ${model.sources.agentRules.includes('AGENTS.md') ? 'documented via AGENTS.md' : 'unknown'}
+- Claude Code: ${model.sources.agentRules.includes('CLAUDE.md') || exists('.claude') ? 'documented' : 'unknown'}
+- Hermes/AION-style runtime: unknown
+- WorkBuddy/other: unknown
+
+## Security And Permissions
+
+- Secrets handling: ${model.sources.configFiles.includes('.env.example') ? 'documented by .env.example presence; real secrets not inspected' : 'unknown'}
+- Write-capable tools: unknown
+- Destructive commands: unknown
+- External services: ${model.externalServices.length ? model.externalServices.join(', ') : 'unknown'}
+
+## Release And Rollback
+
+- Release command/process: ${model.release.length ? model.release.join(', ') : 'unknown'}
+- Rollback: unknown
+- Smoke checks: ${model.smoke.length ? model.smoke.join(', ') : 'unknown'}
+
+## Known Gotchas
+
+- Tool presence from config is marked documented, not verified. Run focused commands before relying on any tool.
+`
+}
+
+const pkg = safeJson('package.json')
+const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) }
+const configs = detectConfigFiles()
+const workflows = detectWorkflows()
+const scripts = detectScripts(pkg)
+const frameworks = detectFrameworks(pkg)
+const mcpFiles = detectMcpFiles()
+const agentRules = detectAgentRules()
+const docs = detectDocs()
+
+const formatting = []
+if (configs.some((item) => item.includes('prettier'))) formatting.push('Prettier documented by config')
+if (configs.some((item) => item.includes('eslint'))) formatting.push('ESLint documented by config')
+
+const testing = []
+for (const script of scripts) {
+  if (script.name.includes('test')) testing.push(`${script.name} script documented`)
+}
+if (configs.some((item) => item.startsWith('playwright.config'))) testing.push('Playwright config documented')
+
+const toolConnections = []
+if (mcpFiles.length) toolConnections.push({ tool: 'MCP', purpose: 'External tool/data connections', status: 'documented', evidence: mcpFiles.join(', ') })
+else toolConnections.push({ tool: 'MCP', purpose: 'External tool/data connections', status: 'unknown', evidence: '-' })
+const playwrightEvidence = []
+if (deps.playwright || deps['@playwright/test']) playwrightEvidence.push('package.json dependency')
+if (scripts.some((item) => item.name.includes('smoke') && /browser|ui|playwright/i.test(item.command + ' ' + item.name))) playwrightEvidence.push('package.json smoke script')
+if (configs.some((item) => item.startsWith('playwright.config'))) playwrightEvidence.push(configs.filter((item) => item.startsWith('playwright.config')).join(', '))
+if (playwrightEvidence.length) toolConnections.push({ tool: 'Browser/Playwright', purpose: 'UI smoke and browser automation', status: 'documented', evidence: playwrightEvidence.join(', ') })
+else toolConnections.push({ tool: 'Browser/Playwright', purpose: 'UI smoke and browser automation', status: 'unknown', evidence: '-' })
+if (workflows.length) toolConnections.push({ tool: 'CI', purpose: 'Automated gates', status: 'documented', evidence: workflows.join(', ') })
+else toolConnections.push({ tool: 'CI', purpose: 'Automated gates', status: 'unknown', evidence: '-' })
+toolConnections.push({ tool: 'LSP/index', purpose: 'Symbol navigation', status: 'unknown', evidence: '-' })
+
+const release = scripts.filter((item) => /release|deploy|publish/i.test(item.name)).map((item) => `${item.name}: ${item.command}`)
+const smoke = scripts.filter((item) => /smoke|check|test:e2e/i.test(item.name)).map((item) => `${item.name}: ${item.command}`)
+const externalServices = []
+if (configs.includes('.env.example')) externalServices.push('.env.example present')
+
+const model = {
+  target,
+  generatedAt: new Date().toISOString(),
+  identity: {
+    name: pkg?.name ?? path.basename(target),
+    repoType: inferRepoType(pkg, configs),
+    frameworks,
+    packageManager: detectPackageManager(),
+  },
+  sources: { agentRules, docs, configFiles: configs, workflows },
+  scripts,
+  formatting,
+  testing,
+  toolConnections,
+  release,
+  smoke,
+  externalServices,
+}
+
+const markdown = renderMarkdown(model)
+
+if (write) {
+  fs.mkdirSync(path.dirname(profilePath), { recursive: true })
+  if (!force && fs.existsSync(profilePath)) {
+    console.error(`Refusing to overwrite existing ${profilePath}. Pass --force to overwrite.`)
+    process.exit(2)
+  }
+  fs.writeFileSync(profilePath, markdown, 'utf8')
+}
+
+if (json) console.log(JSON.stringify(model, null, 2))
+else console.log(markdown)

package/scripts/forward-test-gse.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+const args = process.argv.slice(2)
+
+function readArg(name, fallback = null) {
+  const index = args.indexOf(name)
+  if (index === -1) return fallback
+  return args[index + 1] ?? fallback
+}
+
+const root = path.resolve(readArg('--root', path.join(import.meta.dirname, '..')))
+const jsonOnly = args.includes('--json')
+
+function exists(relativePath) {
+  return fs.existsSync(path.join(root, relativePath))
+}
+
+function readText(relativePath) {
+  const fullPath = path.join(root, relativePath)
+  if (!fs.existsSync(fullPath)) return ''
+  return fs.readFileSync(fullPath, 'utf8')
+}
+
+function runNode(script, commandArgs) {
+  return spawnSync(process.execPath, [script, ...commandArgs], {
+    cwd: root,
+    encoding: 'utf8',
+    windowsHide: true,
+  })
+}
+
+function parseJson(text) {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return null
+  }
+}
+
+function check(id, label, ok, evidence, risk = '') {
+  return { id, label, status: ok ? 'passed' : 'failed', evidence, risk }
+}
+
+const requiredDocs = [
+  'SKILL.md',
+  'references/router.md',
+  'references/forward-test.md',
+  'references/evidence-taxonomy.md',
+  'examples/README.md',
+]
+
+const startupText = readText('SKILL.md')
+const routerText = readText('references/router.md')
+const forwardText = readText('references/forward-test.md')
+const taxonomyText = readText('references/evidence-taxonomy.md')
+const examplesText = readText('examples/README.md')
+
+const smallAppTarget = path.join(root, 'examples', 'small-app')
+const profileRun = runNode(path.join(root, 'scripts', 'discover-project-profile.mjs'), ['--target', smallAppTarget, '--json'])
+const profile = profileRun.status === 0 ? parseJson(profileRun.stdout) : null
+const frameworkSet = new Set(profile?.identity?.frameworks ?? [])
+const toolStatuses = new Set((profile?.toolConnections ?? []).map((item) => item.status))
+
+const codexAdapter = readText('examples/agent-runtime-host/.codex/gse-adapter.md')
+const claudeAdapter = readText('examples/agent-runtime-host/.claude/gse-adapter.md')
+const runtimeProfile = readText('examples/agent-runtime-host/.gse/project-profile.md')
+const runtimeTooling = readText('examples/agent-runtime-host/.gse/tooling.md')
+const modelRouting = readText('examples/agent-runtime-host/docs/model-routing.md')
+
+const checks = [
+  check('FT01', 'documented startup inputs exist', requiredDocs.every(exists), requiredDocs.join(', ')),
+  check('FT02', 'SKILL startup routes GSE changes through validation', startupText.includes('scripts/validate-gse.mjs') && startupText.includes('references/router.md'), 'SKILL.md startup flow'),
+  check('FT03', 'router exposes GSE self-development route', routerText.includes('GSE self-development') && routerText.includes('.gse/gse-design-master-plan.md') && routerText.includes('current-slice'), 'references/router.md'),
+  check('FT04', 'forward-test protocol defines fixture versus fresh-session gates', forwardText.includes('Fixture forward test') && forwardText.includes('Fresh-session forward test') && forwardText.includes('accepted by: fresh-session'), 'references/forward-test.md'),
+  check('FT05', 'evidence taxonomy distinguishes result verified accepted', taxonomyText.includes('result -> verified -> accepted') && taxonomyText.includes('Not enough for `accepted`'), 'references/evidence-taxonomy.md'),
+  check('FT06', 'fixture docs forbid claiming fresh-session acceptance from fixture presence', examplesText.includes('do not claim fresh-session acceptance') && examplesText.includes('audit-fixtures.mjs'), 'examples/README.md'),
+  check('FT07', 'small-app fixture profile discovery runs from documented command', profileRun.status === 0 && Boolean(profile), 'discover-project-profile.mjs --target examples/small-app --json'),
+  check('FT08', 'small-app profile discovery detects representative app shape', frameworkSet.has('React') && frameworkSet.has('Vite') && frameworkSet.has('TypeScript') && frameworkSet.has('Playwright'), 'frameworks: ' + [...frameworkSet].join(', ')),
+  check('FT09', 'small-app keeps configured tools documented not over-verified', toolStatuses.has('documented') && toolStatuses.has('unknown') && ![...(profile?.toolConnections ?? [])].some((item) => item.status === 'verified'), 'tool statuses: ' + [...toolStatuses].join(', ')),
+  check('FT10', 'agent-runtime host adapters point back to .gse source of truth', codexAdapter.includes('Source of truth: `.gse/`.') && claudeAdapter.includes('Source of truth: `.gse/`.'), 'Codex and Claude adapter notes'),
+  check('FT11', 'agent-runtime fixture avoids unsupported capability claims', runtimeProfile.includes('unknown') && runtimeTooling.includes('not verified') && modelRouting.includes('provider support from docs alone'), 'runtime profile/tooling/model routing status text'),
+]
+
+const passed = checks.filter((item) => item.status === 'passed').length
+const failed = checks.length - passed
+const report = {
+  root,
+  generatedAt: new Date().toISOString(),
+  level: 'fixture forward test',
+  scenario: 'Documented GSE startup plus small-app and agent-runtime-host fixture adoption',
+  changedBehavior: 'Future agents can use SKILL.md, router, forward-test, evidence taxonomy, and fixtures without hidden author memory.',
+  evidenceStatus: failed === 0 ? 'verified' : 'result',
+  acceptedBy: 'not accepted; fresh-session acceptance requires a separate agent/session or explicit acceptance policy',
+  summary: { status: failed === 0 ? 'passed' : 'failed', passed, failed, total: checks.length },
+  commandsOrInspection: [
+    'Read SKILL.md, references/router.md, references/forward-test.md, references/evidence-taxonomy.md, examples/README.md',
+    'Run node scripts/discover-project-profile.mjs --target examples/small-app --json',
+    'Inspect examples/agent-runtime-host host adapters and tool/model status files',
+  ],
+  residualRisk: [
+    'This is fixture-level verification, not a true fresh-session run.',
+    'No package install, CI, browser, MCP, LSP, or external service was executed.',
+    'Real repository adoption still needs a later smoke against an existing repo fixture or project.',
+  ],
+  nextAction: 'Add real-repo adoption smoke or run a true fresh-session forward test when a separate-session tool is available.',
+  checks,
+}
+
+function renderMarkdown(data) {
+  const lines = []
+  lines.push('# GSE Forward Test')
+  lines.push('')
+  lines.push('Generated: ' + data.generatedAt)
+  lines.push('Root: ' + data.root)
+  lines.push('')
+  lines.push('## Record')
+  lines.push('')
+  lines.push('- Forward-test level: ' + data.level)
+  lines.push('- Scenario: ' + data.scenario)
+  lines.push('- Changed behavior: ' + data.changedBehavior)
+  lines.push('- Result evidence: documented inputs and fixture checks exist')
+  lines.push('- Verification evidence: ' + data.summary.passed + '/' + data.summary.total + ' checks passed')
+  lines.push('- Evidence status: ' + data.evidenceStatus)
+  lines.push('- Accepted by: ' + data.acceptedBy)
+  lines.push('- Next action: ' + data.nextAction)
+  lines.push('')
+  lines.push('## Checks')
+  lines.push('')
+  for (const item of data.checks) {
+    const marker = item.status === 'passed' ? '[x]' : '[ ]'
+    lines.push('- ' + marker + ' ' + item.id + ' ' + item.label + ': ' + item.evidence)
+  }
+  lines.push('')
+  lines.push('## Residual Risk')
+  lines.push('')
+  for (const item of data.residualRisk) lines.push('- ' + item)
+  return lines.join('\n') + '\n'
+}
+
+if (jsonOnly) console.log(JSON.stringify(report, null, 2))
+else console.log(renderMarkdown(report))
+
+if (failed > 0) process.exit(1)

package/scripts/generate-command-adapter.mjs

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import path from 'node:path'
+
+const args = process.argv.slice(2)
+
+function readArg(name, fallback = null) {
+  const index = args.indexOf(name)
+  if (index === -1) return fallback
+  return args[index + 1] ?? fallback
+}
+
+const target = path.resolve(readArg('--target', process.cwd()))
+const hostArg = readArg('--host', 'all')
+const force = args.includes('--force')
+const dryRun = args.includes('--dry-run')
+const jsonOnly = args.includes('--json')
+
+const portableReadOrder = [
+  'Project instructions such as AGENTS.md, CLAUDE.md, README, or repository-specific rules.',
+  '.gse/README.md',
+  '.gse/project-profile.md',
+  '.gse/state.json',
+  '.gse/goal-map.md',
+  '.gse/quality-gates.md',
+]
+
+function portablePointerContent({ title, hostName, extraNotes = [] }) {
+  const notes = extraNotes.length
+    ? '\n\nHost-specific notes:\n\n' + extraNotes.map((item) => '- ' + item).join('\n')
+    : ''
+  return `# ${title}
+
+Source of truth: .gse/.
+
+This file is a ${hostName} pointer for GSE. It does not prove native /gse slash-command support or verified runtime tools.
+
+Read in order:
+
+${portableReadOrder.map((item, index) => `${index + 1}. ${item}`).join('\n')}
+
+Route /gse ..., gse: ..., and "continue with GSE" requests through references/commands.md in the installed GSE skill.
+
+Portable execution path:
+
+\`\`\`text
+node <gse-skill>/scripts/run-gse-command.mjs --target <project-root> --command "/gse help"
+\`\`\`
+
+Capability status vocabulary: verified, documented, unknown, unavailable.
+
+Do not mark subagents, MCP, browser, LSP/index, hooks, workers, model routing, or native slash commands as verified unless this host/session produced current evidence.
+${notes}
+`
+}
+
+const adapters = {
+  claude: {
+    nativeSlashCommand: true,
+    relativePath: path.join('.claude', 'commands', 'gse.md'),
+    content: `# /gse
+
+Use GSE for this project.
+
+Read in order:
+
+1. Project instructions such as AGENTS.md, CLAUDE.md, or repository-specific rules.
+2. .gse/README.md
+3. .gse/project-profile.md
+4. .gse/state.json
+5. .gse/goal-map.md
+6. .gse/quality-gates.md
+
+Route the user's arguments through references/commands.md in the installed GSE skill.
+
+Portable execution path:
+
+\`\`\`text
+node <gse-skill>/scripts/run-gse-command.mjs --target <project-root> --command "/gse help"
+\`\`\`
+
+Do not duplicate the goal map, evidence log, or quality gates in .claude/.
+Do not mark tools, subagents, MCP, browser, LSP, hooks, or slash commands as verified unless this session checked them.
+
+Expected command shapes:
+
+- /gse help
+- /gse init
+- /gse adopt
+- /gse continue
+- /gse change
+- /gse slice
+- /gse verify
+- /gse audit
+- /gse close
+`,
+  },
+  codex: {
+    nativeSlashCommand: false,
+    relativePath: path.join('.codex', 'gse-command.md'),
+    content: `# GSE Command Adapter For Codex
+
+Source of truth: .gse/.
+
+This file is a Codex-facing pointer, not proof of a native project-level /gse slash-command mechanism.
+
+Use the installed GSE skill and references/commands.md when the user writes /gse ..., gse: ..., or asks to continue with GSE.
+
+Portable execution path:
+
+\`\`\`text
+node <gse-skill>/scripts/run-gse-command.mjs --target <project-root> --command "/gse help"
+\`\`\`
+
+Read in order:
+
+1. AGENTS.md
+2. .gse/README.md
+3. .gse/project-profile.md
+4. .gse/state.json
+5. .gse/goal-map.md
+6. .gse/quality-gates.md
+
+Capability status vocabulary: verified, documented, unknown, unavailable.
+`,
+  },
+  hermes: {
+    nativeSlashCommand: false,
+    relativePath: path.join('.gse', 'host-adapters', 'hermes-runtime.md'),
+    content: portablePointerContent({
+      title: 'Hermes/AION Runtime GSE Adapter',
+      hostName: 'Hermes/AION-style runtime',
+      extraNotes: [
+        'Keep user-facing product identity in the product docs; runtime names belong only to internal implementation notes.',
+        'Treat workers, memory, tools, model routing, and browser loops as unknown until the target project records evidence.',
+      ],
+    }),
+  },
+  workbuddy: {
+    nativeSlashCommand: false,
+    relativePath: path.join('.gse', 'host-adapters', 'workbuddy.md'),
+    content: portablePointerContent({
+      title: 'WorkBuddy GSE Adapter',
+      hostName: 'WorkBuddy-style IDE agent',
+      extraNotes: [
+        'Use the IDE or plugin command surface only after the project records how WorkBuddy discovers this file.',
+        'Keep local tool, MCP, index, browser, and subagent claims unknown until checked in that workspace.',
+      ],
+    }),
+  },
+  copilot: {
+    nativeSlashCommand: false,
+    relativePath: path.join('.github', 'copilot-instructions.md'),
+    content: portablePointerContent({
+      title: 'GitHub Copilot GSE Adapter',
+      hostName: 'GitHub Copilot-style assistant',
+      extraNotes: [
+        'Use this repository instruction file as a short pointer to the project-local GSE workspace.',
+        'Keep issue, PR, CI, and repository settings claims unknown until the public repository records evidence.',
+      ],
+    }),
+  },
+  gemini: {
+    nativeSlashCommand: false,
+    relativePath: 'GEMINI.md',
+    content: portablePointerContent({
+      title: 'Gemini GSE Adapter',
+      hostName: 'Gemini-style assistant',
+      extraNotes: [
+        'Use this file as a short pointer when the host reads repository-level Gemini instructions.',
+        'Keep command, tool, MCP, browser, and subagent claims unknown until the current host records evidence.',
+      ],
+    }),
+  },
+  generic: {
+    nativeSlashCommand: false,
+    relativePath: path.join('.gse', 'host-adapters', 'generic-agent.md'),
+    content: portablePointerContent({
+      title: 'Generic Agent GSE Adapter',
+      hostName: 'generic or unknown agent host',
+      extraNotes: [
+        'Use this adapter when a host has no known native command location yet.',
+        'Replace this file with a host-specific adapter only after that host has a real folder, hook, command, skill, plugin, or MCP mechanism.',
+      ],
+    }),
+  },
+}
+
+function writeFile(relativePath, content) {
+  const fullPath = path.join(target, relativePath)
+  if (fs.existsSync(fullPath) && !force) return { status: 'skipped', fullPath }
+  if (!dryRun) {
+    fs.mkdirSync(path.dirname(fullPath), { recursive: true })
+    fs.writeFileSync(fullPath, content.trimStart().replace(/\n/g, '\r\n'), 'utf8')
+  }
+  return { status: dryRun ? 'would-write' : 'written', fullPath }
+}
+
+const hosts = hostArg === 'all' ? Object.keys(adapters) : hostArg.split(',').map((item) => item.trim()).filter(Boolean)
+const invalid = hosts.filter((host) => !adapters[host])
+if (invalid.length) {
+  console.error('Invalid --host value: ' + invalid.join(', ') + '. Expected claude, codex, hermes, workbuddy, copilot, gemini, generic, or all.')
+  process.exit(1)
+}
+
+const results = hosts.map((host) => {
+  const adapter = adapters[host]
+  const write = writeFile(adapter.relativePath, adapter.content)
+  return {
+    host,
+    nativeSlashCommand: adapter.nativeSlashCommand,
+    status: write.status,
+    path: write.fullPath,
+    relativePath: adapter.relativePath.replace(/\\/g, '/'),
+  }
+})
+
+const report = {
+  target,
+  dryRun,
+  force,
+  hosts,
+  results,
+  limits: [
+    'Claude adapter emits a native project slash-command file under .claude/commands.',
+    'Codex adapter is a skill/text-command pointer until a project-level native slash-command file mechanism is verified.',
+    'Hermes, WorkBuddy, Copilot, Gemini, and generic adapters are portable pointers only; they do not prove host runtime invocation.',
+  ],
+}
+
+console.log(JSON.stringify(report, null, 2))