@playcraft/cli 0.0.44 → 0.0.47

package/project-templates/phaser/skills/_shared/scripts/ensure-project.mjs

@@ -0,0 +1,532 @@
+#!/usr/bin/env node
+/**
+ * Agent Phase 0: ensure playable project is ready for skills pipeline.
+ * Idempotent — safe to run before every skill invocation.
+ *
+ * Usage (from testN/):
+ *   node ../skills/_shared/scripts/ensure-project.mjs --root=.
+ */
+
+import { access, copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { spawn, spawnSync } from 'node:child_process';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { checkEnv, resolvePythonBin } from './verify-env.mjs';
+import { disclosureForState } from './disclosure-config.mjs';
+import { persistState, readState, resolveStateJsonPath } from './state-store.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SKILLS_ROOT = resolve(__dirname, '../..');
+const TEMPLATE_ROOT = resolve(SKILLS_ROOT, '..');
+const DOC_TEMPLATES = resolve(TEMPLATE_ROOT, 'templates');
+
+export function skillsRel(projectRoot) {
+  const rel = relative(resolve(projectRoot), SKILLS_ROOT);
+  if (!rel || rel === '.') return 'skills';
+  if (rel.startsWith('..')) return SKILLS_ROOT;
+  return rel.split('\\').join('/');
+}
+
+export function standardScripts(projectRoot, projectType) {
+  const s = skillsRel(projectRoot);
+  const isVite = projectType === 'vite';
+  return {
+    'dev:start': `node ${s}/_shared/scripts/dev-start.mjs --root=.`,
+    'dev:stop': `node ${s}/_shared/scripts/dev-start.mjs --root=. --stop`,
+    'verify:ui': `python3 ${s}/playable-verify-ui/scripts/run_all.py`,
+    'verify:ui:assets':
+      `python3 ${s}/playable-verify-ui/scripts/run_all.py --only assets`,
+    'verify:ui:layout':
+      `python3 ${s}/playable-verify-ui/scripts/run_all.py --only layout`,
+    'ring:gate': `node ${s}/../.claude/hooks/gate-runner.mjs`,
+    'state:set': `node ${s}/_shared/scripts/state-set.mjs --root=.`,
+    'state:get': `node ${s}/_shared/scripts/state-get.mjs --root=.`,
+    'state:advance-ring': `node ${s}/_shared/scripts/state-advance-ring.mjs --root=.`,
+    'slice:set': `node ${s}/_shared/scripts/slice-set.mjs --root=.`,
+    'verify:slice': isVite
+      ? `node ${s}/playable-record/scripts/verify-slice.mjs --root=. --use-dev`
+      : `node ${s}/playable-record/scripts/verify-slice.mjs --root=.`,
+    'verify:slice-artist': `node ${s}/playable-record/scripts/verify-slice-artist.mjs --root=.`,
+    'verify:slice-ta': `node ${s}/playable-record/scripts/verify-slice-ta.mjs --root=.`,
+    'typecheck': 'tsc --noEmit',
+    'verify:env': `node ${s}/_shared/scripts/verify-env.mjs --root=.`,
+    'ensure:project': `node ${s}/_shared/scripts/ensure-project.mjs --root=.`,
+    'workflow:doctor': `node ${s}/_shared/scripts/workflow-doctor.mjs --root=.`,
+    'workflow:doctor:strict': `node ${s}/_shared/scripts/workflow-doctor.mjs --root=. --strict`,
+    'harness:smoke': `node ${s}/_shared/scripts/harness-smoke.mjs --root=.`,
+    'context:budget': `node ${s}/_shared/scripts/context-budget.mjs --root=.`,
+    'skills:check': `node ${s}/_shared/scripts/skills-check.mjs --root=.`,
+    'bootstrap:playground':
+      `node ${s}/playable-focus/scripts/bootstrap-playground.mjs --root=.`,
+    'record:mp4': isVite
+      ? `node ${s}/playable-record/scripts/record-playable.mjs --root=. --use-dev`
+      : `node ${s}/playable-record/scripts/record-playable.mjs --root=.`,
+    'record:focus': isVite
+      ? `node ${s}/playable-record/scripts/record-playable.mjs --root=. --use-dev --focus`
+      : `node ${s}/playable-record/scripts/record-playable.mjs --root=. --focus`,
+    'verify:contract': isVite
+      ? `node ${s}/playable-record/scripts/verify-contract.mjs --root=. --use-dev`
+      : `node ${s}/playable-record/scripts/verify-contract.mjs --root=.`,
+    'verify:lifecycle': isVite
+      ? `node ${s}/playable-record/scripts/verify-lifecycle.mjs --root=. --use-dev`
+      : `node ${s}/playable-record/scripts/verify-lifecycle.mjs --root=.`,
+    'verify:firstwin': isVite
+      ? `node ${s}/playable-record/scripts/verify-firstwin.mjs --root=. --use-dev`
+      : `node ${s}/playable-record/scripts/verify-firstwin.mjs --root=.`,
+    'verify:fusion': isVite
+      ? `node ${s}/playable-record/scripts/verify-fusion.mjs --root=. --use-dev`
+      : `node ${s}/playable-record/scripts/verify-fusion.mjs --root=.`,
+    'verify:visual-ring1': isVite
+      ? `node ${s}/playable-record/scripts/verify-visual-ring1.mjs --root=. --use-dev`
+      : `node ${s}/playable-record/scripts/verify-visual-ring1.mjs --root=.`,
+    'verify:visual-ring2': isVite
+      ? `node ${s}/playable-record/scripts/verify-visual-ring.mjs --root=. --ring=2 --use-dev`
+      : `node ${s}/playable-record/scripts/verify-visual-ring.mjs --root=. --ring=2`,
+    'verify:visual-ring3': isVite
+      ? `node ${s}/playable-record/scripts/verify-visual-ring.mjs --root=. --ring=3 --use-dev`
+      : `node ${s}/playable-record/scripts/verify-visual-ring.mjs --root=. --ring=3`,
+    'verify:vlm-video': `node ${s}/playable-record/scripts/verify-vlm-video.mjs --root=.`,
+    'playground': `node ${s}/playable-focus/scripts/playground.mjs --root=.`,
+    'sweep:L1':
+      `node ${s}/playable-focus/scripts/playground.mjs --root=. sweep L1`,
+    'sweep:G1':
+      `node ${s}/playable-focus/scripts/playground.mjs --root=. sweep G1`,
+    'repack:frames':
+      `python3 ${s}/playable-fx-peak/scripts/repack-frame-sequence.py`,
+    'validate:frame-anchors':
+      `python3 ${s}/playable-fx-peak/scripts/validate-frame-anchors.py`,
+    'mark:slices':
+      `python3 ${s}/playable-art/scripts/import-gpt-art-sheets-v2.py --mark-only`,
+    'import:gpt-art':
+      `python3 ${s}/playable-art/scripts/import-gpt-art-sheets-v2.py`,
+    'review:assets':
+      `python3 ${s}/playable-art/scripts/review-processed-assets.py --root=.`,
+    'verify:asset-review':
+      `python3 ${s}/playable-art/scripts/review-processed-assets.py --root=. --strict --json`,
+    'verify:slice-plan':
+      `python3 ${s}/playable-verify-ui/scripts/verify_slice_plan.py --root=.`,
+    'build-atlas': `python3 ${s}/playable-art/scripts/build-atlas.py`,
+    'placeholder:gen': `python3 ${s}/_shared/scripts/gen-placeholder.py`,
+    'placeholder:gen-audio': `python3 ${s}/_shared/scripts/gen-placeholder-audio.py`,
+    'verify:visual': `python3 ${s}/playable-verify-ui/scripts/verify_visual.py --root=.`,
+    // Ring-4 visual / sync gates required by ring-config SCRIPT_VERIFIERS — must be
+    // written here so `ensure:project` repairs older projects (otherwise Ring Gate
+    // fails at the npm-script layer with "missing script").
+    'verify:bg-clean': `python3 ${s}/playable-verify-ui/scripts/verify_bg_clean.py --root=.`,
+    'verify:tile-consistency': `python3 ${s}/playable-verify-ui/scripts/verify_tile_consistency.py --root=.`,
+    'verify:text-overlap': `python3 ${s}/playable-verify-ui/scripts/verify_text_overlap.py --root=.`,
+    'verify:vision': `python3 ${s}/playable-verify-ui/scripts/verify_vision_evidence.py --root=.`,
+    'verify:placeholders': `node ${s}/_shared/scripts/verify-placeholders.mjs --root=.`,
+    'verify:asset-code-sync': `node ${s}/_shared/scripts/verify-asset-code-sync.mjs --root=.`,
+    'placeholder:pack-sheet': `node ${s}/_shared/scripts/placeholder-pack-sheet.mjs --root=.`,
+    'verify:atom-conformance': `node ${s}/_shared/scripts/verify-atom-conformance.mjs --project=.`,
+    'record:mp4:install': 'playwright install chromium',
+  };
+}
+
+function parseArgs(argv) {
+  const opts = {
+    root: process.cwd(),
+    install: true,
+    json: false,
+  };
+  for (const arg of argv) {
+    if (arg.startsWith('--root=')) {
+      const v = arg.slice(7);
+      opts.root = v.startsWith('/') ? v : resolve(process.cwd(), v);
+    } else if (arg === '--no-install') opts.install = false;
+    else if (arg === '--json') opts.json = true;
+  }
+  return opts;
+}
+
+async function exists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function run(cmd, args, cwd, options = {}) {
+  return new Promise((res, rej) => {
+    const c = spawn(cmd, args, { cwd, stdio: options.quiet ? 'pipe' : 'inherit' });
+    const stdout = [];
+    const stderr = [];
+    if (options.quiet) {
+      c.stdout?.on('data', (chunk) => stdout.push(Buffer.from(chunk)));
+      c.stderr?.on('data', (chunk) => stderr.push(Buffer.from(chunk)));
+    }
+    c.on('error', rej);
+    c.on('close', (code) => {
+      if (code === 0) {
+        res();
+        return;
+      }
+      const out = Buffer.concat(stdout).toString('utf8').trim();
+      const err = Buffer.concat(stderr).toString('utf8').trim();
+      const detail = [err, out].filter(Boolean).join('\n').slice(0, 2000);
+      rej(new Error(`${cmd} ${args.join(' ')} exit ${code}${detail ? `\n${detail}` : ''}`));
+    });
+  });
+}
+
+async function mergePackageScripts(projectRoot, projectType) {
+  const pkgPath = join(projectRoot, 'package.json');
+  if (!(await exists(pkgPath))) {
+    return { merged: false, reason: 'no package.json' };
+  }
+  const scripts = standardScripts(projectRoot, projectType);
+  const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+  pkg.scripts = pkg.scripts || {};
+  let changed = false;
+  for (const [key, val] of Object.entries(scripts)) {
+    if (pkg.scripts[key] !== val) {
+      pkg.scripts[key] = val;
+      changed = true;
+    }
+  }
+  if (changed) {
+    await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
+  }
+  return { merged: changed, scripts: Object.keys(scripts) };
+}
+
+async function ensureProfile(projectRoot) {
+  const dest = join(projectRoot, 'playable.ui.profile.yaml');
+  if (await exists(dest)) return { created: false };
+  const template = join(
+    SKILLS_ROOT,
+    'playable-verify-ui/profiles/template.profile.yaml',
+  );
+  if (!(await exists(template))) {
+    return { created: false, error: 'template missing' };
+  }
+  await copyFile(template, dest);
+  return { created: true, path: 'playable.ui.profile.yaml' };
+}
+
+async function ensurePlayground(projectRoot, quiet) {
+  const registry = join(projectRoot, 'playground/registry.json');
+  if (await exists(registry)) return { bootstrapped: false };
+  const bootstrap = join(
+    SKILLS_ROOT,
+    'playable-focus/scripts/bootstrap-playground.mjs',
+  );
+  await run('node', [bootstrap, `--root=${projectRoot}`], projectRoot, { quiet });
+  return { bootstrapped: true };
+}
+
+async function ensureDirs(projectRoot) {
+  for (const d of [
+    'docs',
+    'logs',
+    'recordings',
+    'validate',
+    'validate/frames',
+    'validate/ring1',
+    'validate/ring1/frames',
+    'validate/ring2',
+    'validate/ring3',
+    'validate/ring4',
+  ]) {
+    await mkdir(join(projectRoot, d), { recursive: true });
+  }
+}
+
+async function copyTemplateIfMissing(projectRoot, templateName, destRel, transform = null) {
+  const dest = join(projectRoot, destRel);
+  if (await exists(dest)) return { created: false, path: destRel };
+
+  const source = join(DOC_TEMPLATES, templateName);
+  if (!(await exists(source))) {
+    return { created: false, path: destRel, error: `template missing: ${templateName}` };
+  }
+
+  await mkdir(dirname(dest), { recursive: true });
+  if (transform) {
+    const content = await readFile(source, 'utf8');
+    await writeFile(dest, transform(content), 'utf8');
+  } else {
+    await copyFile(source, dest);
+  }
+  return { created: true, path: destRel };
+}
+
+function initializeProjectStateTemplate(content) {
+  return content
+    .replace(
+      '**Iteration {{current_iteration}}** — {{iteration_description}}',
+      '**Iteration 1** — engine-root + core gameplay (placeholder art)',
+    )
+    .replaceAll('| {{passed/pending}} |', '| pending |')
+    .replace(
+      '| selectedMcOption | {{A / B / C — set during ring 3+ style lock}}      |',
+      '| selectedMcOption | unset |',
+    )
+    .replace('| uiReworkRound    | {{0–5 — incremented by Reviewer on ui_diff fail}}  |', '| uiReworkRound    | 0 |')
+    .replace('| assetMappingLocked | {{false / true — locked only after ring 4}}      |', '| assetMappingLocked | false |')
+    .replace('| devScript      | {{from package.json scripts.dev}}                                            |', '| devScript      | vite |')
+    .replace('| devUrl         | {{http://... — Developer records when ready; orchestrator uses for Ring Gate}} |', '| devUrl         | unset |')
+    .replace('| devStatus      | pending / ready / blocked_upstream / failed                                  |', '| devStatus      | pending |')
+    .replace('| devBlockers    | {{list: assetPath, issue, routeTo (TA/Artist/Game Designer), status}}        |', '| devBlockers    | none |')
+    .replace('| devStartedBy   | developer / reviewer / orchestrator                                          |', '| devStartedBy   | none |')
+    .replace('| devLastChecked | {{ISO timestamp}}                                                            |', '| devLastChecked | unset |')
+    .replace('| loadCheck      | pending / passed / failed                                                    |', '| loadCheck      | pending |')
+    .replace('| loadCheckNotes | {{console errors, white screen, load time}}                                  |', '| loadCheckNotes | unset |')
+    .replace('| uiReviewStatus   | pending / passed / failed                  |', '| uiReviewStatus   | deferred |')
+    .replace('| uiDiffNotes      | {{summary of future screenshot comparison}} |', '| uiDiffNotes      | deferred |')
+    .replace('| ringGateCurrent        | {{1 / 2 / 3 / 4 / none}}                           |', '| ringGateCurrent        | none |')
+    .replace('| ringGateVerdict        | {{pass / fail / not_run}}                          |', '| ringGateVerdict        | not_run |')
+    .replace('| ringGateCheckedAt      | {{ISO timestamp}}                                  |', '| ringGateCheckedAt      | unset |')
+    .replace('| ringGateBlockingIssues | {{0..N}}                                           |', '| ringGateBlockingIssues | 0 |')
+    .replace('| ringGateCanAskUser     | {{yes / no}}                                       |', '| ringGateCanAskUser     | no |')
+    .replace('| ringGateRouteTo        | {{developer / reviewer / game-designer / none}}    |', '| ringGateRouteTo        | none |')
+    .replace('| ringGateFailReason     | {{one-line reason or none}}                        |', '| ringGateFailReason     | none |')
+    .replace('| ringGateNonRegression  | {{pass / fail / n-a}}                              |', '| ringGateNonRegression  | n-a |')
+    .replace('| 1    | Artist           | {{status}} | Audio + digit + reuse / coverage notes       |', '| 1    | Artist           | pending | Audio + digit + reuse / coverage notes |')
+    .replace('| 2    | Technical Artist | {{status}} | Spec Quick-Check → bulk → Compliance green   |', '| 2    | Technical Artist | pending | Spec Quick-Check → bulk → Compliance green |')
+    .replace('| Open questions in intent-clarifications.md | {{count}}  |', '| Open questions in intent-clarifications.md | 0 |')
+    .replace('| Unresolved for > 10 min                    | {{count}}  |', '| Unresolved for > 10 min                    | 0 |')
+    .replace('| Artist questions received                  | {{count}}  |', '| Artist questions received                  | 0 |')
+    .replace('| TA questions received                      | {{count}}  |', '| TA questions received                      | 0 |')
+    .replace('| Developer questions received               | {{count}}  |', '| Developer questions received               | 0 |')
+    .replace('| Game Designer intervention needed          | {{yes/no}} |', '| Game Designer intervention needed          | no |');
+}
+
+async function ensureWorkflowFiles(projectRoot) {
+  const created = [];
+  const warnings = [];
+
+  const files = [
+    ['design.template.md', 'docs/DESIGN.md'],
+    ['intent-clarifications.template.md', 'docs/intent-clarifications.md'],
+    ['developer-log.template.md', 'logs/developer-log.md'],
+  ];
+
+  // Ring 2+ docs are created on demand when the project advances — not at bootstrap.
+  const deferredFiles = [
+    ['atom-tree.template.json', 'docs/atom-tree.json'],
+    ['artist-log.template.md', 'logs/artist-log.md'],
+    ['ta-log.template.md', 'logs/ta-log.md'],
+    ['review-report.template.md', 'logs/review-report.md'],
+    ['layout-spec.template.md', 'docs/layout-spec.md'],
+    ['style-exploration.template.md', 'docs/style-exploration.md'],
+    ['plan.template.md', 'docs/implementation-plan.md'],
+  ];
+
+  const state = await copyTemplateIfMissing(
+    projectRoot,
+    'project-state.template.md',
+    'docs/project-state.md',
+    initializeProjectStateTemplate,
+  );
+  if (state.created) created.push('docs/project-state.md');
+  if (state.error) warnings.push(state.error);
+
+  // docs/project-state.json is the machine source of truth. If it's absent
+  // (fresh project, or a legacy md-only project), derive it from whatever md
+  // exists (importer) and re-render the md to its generated form. Idempotent.
+  if (!(await exists(resolveStateJsonPath(projectRoot)))) {
+    try {
+      persistState(projectRoot, readState(projectRoot));
+      created.push('docs/project-state.json');
+    } catch (err) {
+      warnings.push(`project-state.json bootstrap: ${err.message}`);
+    }
+  }
+
+  for (const [templateName, destRel] of files) {
+    const result = await copyTemplateIfMissing(projectRoot, templateName, destRel);
+    if (result.created) created.push(destRel);
+    if (result.error) warnings.push(result.error);
+  }
+
+  // docs/design-brief.md is NOT scaffolded at bootstrap — Game Designer creates it
+  // from templates/design-brief.template.md during Ring 1 clarify (progressive
+  // discovery). It complements docs/DESIGN.md; it does not replace the seed contract.
+
+  return { created, warnings };
+}
+
+async function ensureDeps(projectRoot, doInstall, quiet) {
+  const nm = join(projectRoot, 'node_modules');
+  if (await exists(nm)) return { npmInstall: false };
+  if (!doInstall) return { npmInstall: false, skipped: true };
+  if (!(await exists(join(projectRoot, 'package.json')))) {
+    return { npmInstall: false, reason: 'no package.json' };
+  }
+  await run('npm', ['install'], projectRoot, { quiet });
+  return { npmInstall: true };
+}
+
+async function ensurePythonDeps(projectRoot, doInstall, quiet) {
+  const req = join(SKILLS_ROOT, 'playable-verify-ui/requirements.txt');
+  if (!(await exists(req))) {
+    return { pythonDeps: false, reason: 'requirements.txt missing' };
+  }
+  const bin = resolvePythonBin();
+  if (!bin) {
+    return { pythonDeps: false, reason: 'python3 not found' };
+  }
+  const probe = spawnSync(bin, ['-c', 'from PIL import Image; import yaml; import jsonschema'], {
+    encoding: 'utf8',
+  });
+  if (!probe.error && probe.status === 0) {
+    return { pythonDeps: false, skipped: true, note: 'python deps already present' };
+  }
+  if (!doInstall) {
+    return { pythonDeps: false, skipped: true, reason: 'missing python deps (--no-install)' };
+  }
+  await run(bin, ['-m', 'pip', 'install', '-r', req], projectRoot, { quiet });
+  return { pythonDeps: true, requirements: req };
+}
+
+async function ensurePlaywright(projectRoot) {
+  const r = spawnSync(
+    'npx',
+    ['playwright', 'install', 'chromium'],
+    { cwd: projectRoot, stdio: 'pipe', encoding: 'utf8' },
+  );
+  return { playwright: r.status === 0, stderr: r.stderr?.slice(0, 200) };
+}
+
+async function detectProjectType(projectRoot) {
+  const hasViteConfig =
+    (await exists(join(projectRoot, 'vite.config.ts'))) ||
+    (await exists(join(projectRoot, 'vite.config.js')));
+  const hasPackage = await exists(join(projectRoot, 'package.json'));
+  const hasGameIndex = await exists(join(projectRoot, 'game/index.html'));
+  const hasRootIndex = await exists(join(projectRoot, 'index.html'));
+
+  if (hasViteConfig && hasPackage && hasRootIndex) return { type: 'vite', entry: 'index.html' };
+  if (hasGameIndex) return { type: 'standalone', entry: 'game/index.html' };
+  if (hasRootIndex) return { type: 'generic', entry: 'index.html' };
+  return null;
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const projectRoot = resolve(opts.root);
+  const warnings = [];
+  const actions = [];
+
+  const projectType = await detectProjectType(projectRoot);
+  if (!projectType) {
+    const result = {
+      ready: false,
+      projectRoot,
+      skillsRoot: SKILLS_ROOT,
+      error: 'Not a playable project root (missing index.html or game/index.html)',
+      hint: 'cd project-root/ or pass --root=path/to/playable',
+    };
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(1);
+  }
+
+  if (projectType.type === 'vite') {
+    actions.push(`project type: vite (${projectType.entry})`);
+  }
+
+  if (!(await exists(SKILLS_ROOT))) {
+    warnings.push(`skills root not found at ${SKILLS_ROOT}`);
+  }
+
+  // Environment pre-flight: surface a missing toolchain loudly instead of
+  // letting verify:ui / asset scripts fail silently downstream. Playwright is
+  // checked separately below, so skip it here.
+  const env = await Promise.resolve(checkEnv(projectRoot, { playwright: false }));
+  const envSummary = env.checks.map((c) => `${c.name} ${c.status === 'pass' ? '✓' : '✗'}`).join(', ');
+  actions.push(`env preflight (${envSummary})`);
+  for (const c of env.checks) {
+    if (c.required && c.status === 'fail') {
+      warnings.push(`BLOCKING: ${c.message}`);
+    }
+  }
+
+  await ensureDirs(projectRoot);
+  actions.push('dirs');
+
+  const workflow = await ensureWorkflowFiles(projectRoot);
+  if (workflow.created.length > 0) {
+    actions.push(`workflow files: ${workflow.created.join(', ')}`);
+  }
+  warnings.push(...workflow.warnings);
+
+  const profile = await ensureProfile(projectRoot);
+  if (profile.created) actions.push('playable.ui.profile.yaml (from template — Agent must fill paths)');
+
+  const pg = await ensurePlayground(projectRoot, opts.json);
+  if (pg.bootstrapped) actions.push('playground bootstrap');
+
+  const pkg = await mergePackageScripts(projectRoot, projectType.type);
+  if (pkg.merged) actions.push('package.json scripts merged');
+
+  try {
+    const deps = await ensureDeps(projectRoot, opts.install, opts.json);
+    if (deps.npmInstall) actions.push('npm install');
+  } catch (e) {
+    warnings.push(`npm install: ${e.message}`);
+  }
+
+  try {
+    const py = await ensurePythonDeps(projectRoot, opts.install, opts.json);
+    if (py.pythonDeps) actions.push('python deps (playable-verify-ui/requirements.txt)');
+  } catch (e) {
+    warnings.push(`python deps: ${e.message}`);
+  }
+
+  if (opts.install && (await exists(join(projectRoot, 'package.json')))) {
+    try {
+      await ensurePlaywright(projectRoot);
+      actions.push('playwright chromium');
+    } catch {
+      warnings.push('playwright install failed — record:mp4 may fail until fixed');
+    }
+  }
+
+  if (profile.created) {
+    warnings.push(
+      'New playable.ui.profile.yaml — fill it when the current ring asks for asset/layout validation',
+    );
+  }
+
+  const next = disclosureForState({ iteration: 1, loop: 'clarify' }).nextCommands;
+
+  if (projectType.type === 'vite') actions.push('Vite devUrl will be disclosed when record:mp4 is active');
+
+  const result = {
+    ready:
+      env.ok &&
+      !warnings.some(
+        (w) => w.startsWith('BLOCKING:') || w.includes('skills root not found'),
+      ),
+    projectRoot,
+    projectType: projectType.type,
+    skillsRoot: SKILLS_ROOT,
+    repoRoot: projectRoot,
+    relSkills: skillsRel(projectRoot),
+    actions,
+    warnings,
+    next,
+  };
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log('[ensure-project] project:', projectRoot);
+    console.log('[ensure-project] skills:', SKILLS_ROOT);
+    for (const a of actions) console.log(`  + ${a}`);
+    for (const w of warnings) console.log(`  ! ${w}`);
+    console.log('[ensure-project] ready:', result.ready);
+  }
+}
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}