gennady 0.8.3 → 0.8.4-draft.2

package/ai/inspector/core/scan.ts

@@ -0,0 +1,109 @@
+// @file: ai/inspector — shared scanning primitives for SKILL.md and *.directive.xml (tag walk, refs, tools).
+// The directives/skills are XML-tag-delimited markdown. We target KNOWN PascalCase structural tags; prose
+// placeholders like <scope-name> are lowercase and never match, so markdown bodies do not confuse the scanner.
+
+import type { TraceNode } from './model.ts';
+
+const PASCAL_OPEN = /<([A-Z][A-Za-z0-9]*)\b([^>]*?)(\/?)>/;
+const TOOL_RE = /\bsdd-(?:state|task|extract|verify|log|sync|check)\b|\borient\b/g;
+// Sub-directive references are written inconsistently: READ_AND_USE_DIRECTIVE("path"), a backticked path,
+// or a ~/abs path. Every real reference is anchored under ai/directives/ (verified: no READ_AND_USE_DIRECTIVE
+// ref points elsewhere), so match any such .xml token — both *.directive.xml AND formats/*.xml contracts —
+// then normalise to the repo-relative ai/directives/... tail.
+const DIRECTIVE_REF_RE = /[\w./~-]*ai\/directives\/[\w./-]+\.xml/g;
+
+/** Содержимое тега для показа: срезать HTML-комментарии (но НЕ внутри `code`-спанов, там это literal-контент), dedent, схлопнуть пустые строки, обрезать. */
+export function clean(s: string): string {
+  // odd parts (index % 2 === 1) are `code spans` — keep them verbatim, strip comments only outside
+  const noComments = s
+    .split(/(`[^`]+`)/)
+    .map((p, i) => (i % 2 ? p : p.replace(/<!--[\s\S]*?-->/g, '')))
+    .join('');
+  const lines = noComments.replace(/\n{3,}/g, '\n\n').split('\n');
+  const indents = lines.filter((l) => l.trim()).map((l) => (/^[ \t]*/.exec(l)?.[0] ?? '').length);
+  const min = indents.length ? Math.min(...indents) : 0;
+  return lines
+    .map((l) => l.slice(min))
+    .join('\n')
+    .trim();
+}
+
+/** Первое предложение: убрать комментарии, схлопнуть пробелы, обрезать. */
+export function firstSentence(s: string): string {
+  const t = s
+    .replace(/<!--[\s\S]*?-->/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  const m = /^(.*?[.!?])(\s|$)/.exec(t);
+  return (m ? (m[1] as string) : t).slice(0, 180);
+}
+
+/** Атрибуты открывающего тега → map. */
+export function parseAttrs(raw: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const m of raw.matchAll(/([a-zA-Z_:][\w:-]*)\s*=\s*"([^"]*)"/g))
+    out[m[1] as string] = m[2] as string;
+  return out;
+}
+
+/** Нормализовать путь директивы к репо-относительному (ai/directives/...). */
+export function normalizeDirectivePath(raw: string): string {
+  const i = raw.indexOf('ai/directives/');
+  return i >= 0 ? raw.slice(i) : raw;
+}
+
+export interface RawEl {
+  name: string;
+  attrsRaw: string;
+  inner: string;
+  end: number;
+}
+
+/** Следующий PascalCase-элемент от позиции `from`; закрытие — первый `</name>` (без вложенности тех же имён). */
+export function nextElement(s: string, from: number): RawEl | null {
+  const sub = s.slice(from);
+  const m = PASCAL_OPEN.exec(sub);
+  if (!m) return null;
+  const name = m[1] as string;
+  const openEnd = from + m.index + m[0].length;
+  if (m[3] === '/') return { name, attrsRaw: m[2] as string, inner: '', end: openEnd };
+  const cm = new RegExp('</' + name + '>').exec(s.slice(openEnd));
+  if (!cm) return { name, attrsRaw: m[2] as string, inner: s.slice(openEnd), end: s.length };
+  return {
+    name,
+    attrsRaw: m[2] as string,
+    inner: s.slice(openEnd, openEnd + cm.index),
+    end: openEnd + cm.index + cm[0].length,
+  };
+}
+
+/** Все элементы верхнего уровня строки в порядке появления. */
+export function topLevelElements(
+  inner: string
+): { name: string; attrs: Record<string, string>; inner: string }[] {
+  const out: { name: string; attrs: Record<string, string>; inner: string }[] = [];
+  let cursor = 0;
+  while (cursor < inner.length) {
+    const el = nextElement(inner, cursor);
+    if (!el) break;
+    out.push({ name: el.name, attrs: parseAttrs(el.attrsRaw), inner: el.inner });
+    cursor = el.end;
+  }
+  return out;
+}
+
+/** Из произвольного текста: ссылки на под-директивы (run) + РЕАЛЬНЫЕ вызовы тулов (dedup). */
+export function scanRefsAndTools(text: string): TraceNode[] {
+  const out: TraceNode[] = [];
+  const refs = new Set<string>();
+  for (const m of text.matchAll(DIRECTIVE_REF_RE)) refs.add(normalizeDirectivePath(m[0]));
+  for (const ref of refs)
+    out.push({ kind: 'run', label: ref, ref, note: 'активировать директиву' });
+  // Тул считается ВЫЗОВОМ только внутри inline-code (`...`) — команды пишут в обратных кавычках;
+  // голое упоминание в прозе («state — from sdd-state») вызовом не является и не попадает в дерево.
+  const code = Array.from(text.matchAll(/`([^`]+)`/g), (m) => m[1] as string).join('\n');
+  const tools = new Set<string>();
+  for (const m of code.matchAll(TOOL_RE)) tools.add(m[0]);
+  for (const t of tools) out.push({ kind: 'tool', label: t });
+  return out;
+}

package/ai/inspector/e2e/inspector.spec.ts

@@ -0,0 +1,117 @@
+// @file: ai/inspector — e2e: skill list renders, sdd-execute trace descends, screenshot for visual check.
+
+import { test, expect } from '@playwright/test';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const shotDir = dirname(fileURLToPath(import.meta.url));
+
+test('lists skills and descends the sdd-execute trace', async ({ page }) => {
+  await page.goto('/');
+
+  // entry: every skill under ai/skills is listed (XML-form parsed, markdown marked unsupported)
+  const skills = page.locator('.skill-btn');
+  expect(await skills.count()).toBeGreaterThanOrEqual(9);
+  await expect(page.locator('.skill-btn.unsupported').first()).toBeVisible();
+
+  // ordering: supported skills on top (the first is auto-selected), unsupported sink to the bottom
+  await expect(skills.first()).not.toHaveClass(/unsupported/);
+  await expect(skills.first()).toHaveClass(/active/);
+  const classes = await skills.evaluateAll((els) => els.map((e) => e.className));
+  const firstUnsupported = classes.findIndex((c) => c.includes('unsupported'));
+  const lastSupported = classes.map((c) => c.includes('unsupported')).lastIndexOf(false);
+  expect(firstUnsupported).toBeGreaterThan(lastSupported); // no supported skill appears after an unsupported one
+
+  // pick sdd-execute
+  await page.getByRole('button', { name: '/sdd-execute' }).click();
+  await expect(page.locator('.structure .row[data-kind="skill"]').first()).toBeVisible();
+
+  // its loader steps are present
+  await expect(
+    page.locator('.structure .lab .tag', { hasText: '<ExecutionPlan>' }).first()
+  ).toBeVisible();
+  await expect(page.locator('.structure .lab .tag', { hasText: '<Step GATHER>' })).toBeVisible();
+
+  // descend the flow: GATHER → run(execute.directive) → directive root → its BeliefState
+  await page.locator('.structure .lab .tag', { hasText: '<Step GATHER>' }).click();
+  await page.locator('.structure .lab .tag', { hasText: 'execute.directive.xml' }).first().click();
+  await page.locator('.structure .lab .tag', { hasText: '<SddExecuteOrchestrator>' }).click();
+  await expect(
+    page.locator('.structure .lab .tag', { hasText: '<BeliefState>' }).first()
+  ).toBeVisible();
+
+  // nodes with a source location carry an "open in editor" control (title = file:line)
+  await expect(page.locator('.structure .opensrc').first()).toHaveAttribute(
+    'href',
+    /^\w[\w-]*:\/\/file\/.+:\d+$/
+  );
+
+  // sdd-state is a bash command: opening it shows its captured --help
+  await page.locator('.structure .lab .tag', { hasText: 'sdd-state' }).first().click();
+  await expect(
+    page.locator('.structure .detail', { hasText: 'npx gennady sdd-state' }).first()
+  ).toBeVisible();
+
+  await page.screenshot({ path: join(shotDir, 'screen-execute.png'), fullPage: true });
+});
+
+test('the /sdd router LOGIC_SWITCH descends into branch directives', async ({ page }) => {
+  await page.goto('/');
+  await page.getByRole('button', { name: '/sdd', exact: true }).click();
+
+  // descend: GATHER → run(router.directive) → directive root → its <LogicSwitch>
+  await page.locator('.structure .lab .tag', { hasText: '<Step GATHER>' }).click();
+  await page.locator('.structure .lab .tag', { hasText: 'router.directive.xml' }).first().click();
+  await page.locator('.structure .lab .tag', { hasText: '<SddRouter>' }).click();
+  // the top-level routing switch is the last <LogicSwitch> in the tree (STEP_0 also embeds one now)
+  const sw = page.locator('.structure .lab .tag', { hasText: '<LogicSwitch>' }).last();
+  await expect(sw).toBeVisible();
+
+  // open the switch, then its first branch — which carries a run node into another directive
+  await sw.click();
+  await page.locator('.structure .lab .tag', { hasText: 'project-setup' }).first().click();
+  await expect(
+    page.locator('.structure .lab .tag', { hasText: 'root.directive.xml' }).first()
+  ).toBeVisible();
+
+  await page.screenshot({ path: join(shotDir, 'screen-router-switch.png'), fullPage: true });
+});
+
+test('debug mode: step into a directive and advance the flow', async ({ page }) => {
+  await page.goto('/');
+  await page.getByRole('button', { name: '/sdd', exact: true }).click();
+  const dbg = page.locator('.dbg');
+
+  // GATHER loads router.directive — shown as a collapsed, inspectable block (READ_AND_USE)
+  await expect(dbg.locator('.dbg-loaded')).toContainText('router.directive.xml');
+
+  // GATHER just loads (sdd-state + read directive); advancing reaches EMBODY which AUTO-enters router.directive
+  await dbg.locator('.dbg-br', { hasText: 'следующий шаг' }).first().click();
+  await expect(page.locator('.dbg-stack')).toContainText('SddRouter');
+  await expect(dbg.locator('.dbg-div', { hasText: 'загружена' }).first()).toBeVisible();
+
+  // we're now inside the directive at STEP_0_STATE — its preflight switch branches are real choices
+  await expect(dbg.locator('.dbg-br', { hasText: 'migration-v1-v2' }).first()).toBeVisible();
+  await expect(dbg.locator('.dbg-br', { hasText: 'DEFAULT' }).first()).toBeVisible();
+
+  // enter a switch branch (FLOW_VERSION=v1 → migration): the entered directive is inspectable at the entry divider
+  await dbg.locator('.dbg-br', { hasText: 'migration-v1-v2' }).first().click();
+  await expect(page.locator('.dbg-stack')).toContainText('SddMigrationV1V2');
+  // entered directive sits collapsed right under the entry divider, no extra frame
+  await expect(dbg.locator('.dbg-div', { hasText: 'ветка → загружена' }).first()).toBeVisible();
+  await expect(
+    dbg.locator('.row[data-kind="directive"]:visible .tag', { hasText: 'SddMigrationV1V2' }).first()
+  ).toBeVisible();
+
+  await page.screenshot({ path: join(shotDir, 'screen-debug.png'), fullPage: true });
+});
+
+test('a non-XML skill is listed but marked unsupported (no tree/debugger)', async ({ page }) => {
+  await page.goto('/');
+  await page.locator('.skill-btn.unsupported').first().click();
+  await expect(page.locator('.unsupported-panel')).toBeVisible();
+  await expect(page.locator('.unsupported-title')).toContainText('не поддерживается');
+  // no structure tree / debugger for unsupported skills
+  await expect(page.locator('.structure')).toHaveCount(0);
+  await expect(page.locator('.dbg')).toHaveCount(0);
+});

package/ai/inspector/generate.ts

@@ -0,0 +1,154 @@
+// @file: ai/inspector — build the trace model from real skills + directives → web/trace.json.
+// Run: npx tsx ai/inspector/generate.ts
+
+import { readdirSync, readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseSkill } from './core/parse-skill.ts';
+import { resolveTree, type DirectiveReader } from './core/resolve.ts';
+import type { TraceNode } from './core/model.ts';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(here, '..', '..');
+const skillsDir = join(repoRoot, 'ai', 'skills');
+const gennady = join(repoRoot, 'cli', 'gennady.ts');
+const outFile = join(here, 'web', 'trace.json');
+
+/** Читатель директив: ref репо-относительный → содержимое или null. */
+const read: DirectiveReader = (ref) => {
+  const p = resolve(repoRoot, ref);
+  return existsSync(p) ? readFileSync(p, 'utf8') : null;
+};
+
+/** Кэш `--help` по команде — каждая запускается один раз. */
+const helpCache = new Map<string, string>();
+function toolHelp(cmd: string): string {
+  const cached = helpCache.get(cmd);
+  if (cached !== undefined) return cached;
+  let out: string;
+  try {
+    out = execSync(`npx tsx ${JSON.stringify(gennady)} ${cmd} --help`, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    out = `(нет вывода --help для ${cmd})`;
+  }
+  if (!out) out = `(пустой --help для ${cmd})`;
+  helpCache.set(cmd, out);
+  return out;
+}
+
+/** Номер строки первого вхождения токена (1-based), либо null. */
+function lineOf(content: string, token: string | null): number | null {
+  if (!token) return null;
+  const i = content.indexOf(token);
+  return i < 0 ? null : content.slice(0, i).split('\n').length;
+}
+
+/** Токен, по которому ищем строку узла в исходном файле. */
+function tokenFor(node: TraceNode): string | null {
+  switch (node.kind) {
+    case 'axiom':
+    case 'halt':
+      return node.label; // AX_* / H_*
+    case 'step':
+      return node.attrs?.id ? `id="${node.attrs.id}"` : node.label;
+    case 'switch':
+      return 'LogicSwitch';
+    case 'skill':
+      return node.attrs?.root ? `<${node.attrs.root}` : null;
+    case 'section':
+    case 'directive':
+      return node.label.replace(/[<>]/g, '').split(/\s/)[0] ?? null; // tag name
+    default:
+      return null;
+  }
+}
+
+/** Проставить loc {file,line} каждому узлу. Файл переключается при входе в директиву/скил (по ref). */
+function attachLoc(node: TraceNode, file: string, content: string): void {
+  let f = file;
+  let c = content;
+  if ((node.kind === 'directive' || node.kind === 'skill') && node.ref) {
+    const got = read(node.ref);
+    if (got != null) {
+      f = node.ref;
+      c = got;
+    }
+  }
+  const ln = lineOf(c, tokenFor(node));
+  if (ln) node.loc = { file: f, line: ln };
+  (node.children ?? []).forEach((ch) => attachLoc(ch, f, c));
+}
+
+/** Пометить tool-узлы: это bash-команда gennady — как зовут + что вернёт (--help). */
+function annotateTools(node: TraceNode): void {
+  if (node.kind === 'tool') {
+    node.note = `bash · npx gennady ${node.label}`;
+    node.detail = `$ npx gennady ${node.label}\n\n${toolHelp(node.label)}`;
+  }
+  (node.children ?? []).forEach(annotateTools);
+}
+
+/** Все скилы: каждый каталог ai/skills/* с SKILL.md. */
+function skillFiles(): string[] {
+  return readdirSync(skillsDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => join(skillsDir, d.name, 'SKILL.md'))
+    .filter((p) => existsSync(p));
+}
+
+/**
+ * Инспектор разбирает только скилы с XML/HTML-формой (корневой элемент после frontmatter).
+ * Markdown-скилы показываем в списке, но помечаем «не поддерживается».
+ */
+function isMarkupSkill(md: string): boolean {
+  const body = md.replace(/^---\n[\s\S]*?\n---\n?/, ''); // срезать frontmatter
+  const t = body.replace(/^\s*(?:<!--[\s\S]*?-->\s*)*/, ''); // и ведущие комментарии/пробелы
+  return /^<[A-Za-z][\w-]*[\s>/]/.test(t);
+}
+
+/** Узел-заглушка для скила, который инспектор не разбирает (не XML/HTML). */
+function unsupportedSkill(rel: string, md: string): TraceNode {
+  const name = (/^name:\s*(.+)$/m.exec(md)?.[1] ?? rel).trim();
+  const desc = (/^description:\s*(.+)$/m.exec(md)?.[1] ?? '').trim();
+  return {
+    kind: 'skill',
+    label: `/${name}`,
+    note: 'не поддерживается — не XML/HTML-форма',
+    detail: desc || undefined,
+    attrs: { name, unsupported: 'true' },
+    ref: rel,
+    children: [],
+  };
+}
+
+const skills: TraceNode[] = [];
+for (const file of skillFiles()) {
+  const rel = file.slice(repoRoot.length + 1);
+  const md = readFileSync(file, 'utf8');
+  if (!isMarkupSkill(md)) {
+    skills.push(unsupportedSkill(rel, md));
+    continue;
+  }
+  const tree = parseSkill(rel, md);
+  resolveTree(tree, read);
+  annotateTools(tree);
+  attachLoc(tree, rel, md);
+  skills.push(tree);
+}
+
+// Supported (XML/HTML-form) skills first, unsupported sink to the bottom; alphabetical within each
+// group. The UI selects index 0 by default — so it lands on the first supported skill, not a stub.
+const isUnsupported = (s: TraceNode) => s.attrs?.unsupported === 'true';
+skills.sort((a, b) => {
+  const ua = isUnsupported(a) ? 1 : 0;
+  const ub = isUnsupported(b) ? 1 : 0;
+  return ua - ub || a.label.localeCompare(b.label);
+});
+
+if (!existsSync(dirname(outFile))) mkdirSync(dirname(outFile), { recursive: true });
+writeFileSync(outFile, JSON.stringify({ repoRoot, skills }, null, 2), 'utf8');
+console.log(`[inspector] ${skills.length} skill(s) → ${outFile.slice(repoRoot.length + 1)}`);

package/ai/inspector/playwright.config.ts

@@ -0,0 +1,20 @@
+// @file: ai/inspector — Playwright config: serve web/ via serve.ts, run e2e from ./e2e.
+
+import { defineConfig } from '@playwright/test';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig({
+  testDir: './e2e',
+  outputDir: join(root, 'test-results'),
+  use: { baseURL: 'http://localhost:4173' },
+  webServer: {
+    command: 'npx tsx serve.ts',
+    cwd: root,
+    port: 4173,
+    reuseExistingServer: true,
+    timeout: 20_000,
+  },
+});

package/ai/inspector/serve.ts

@@ -0,0 +1,30 @@
+// @file: ai/inspector — zero-dep static server for web/ (so the UI can fetch trace.json over http).
+// Run: npx tsx ai/inspector/serve.ts   (PORT env optional, default 4173)
+// "Open in editor" is handled client-side via the editor URL scheme (vscode://file/...), no server spawn.
+
+import { createServer } from 'node:http';
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { join, extname, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const dir = resolve(dirname(fileURLToPath(import.meta.url)), 'web');
+const PORT = Number(process.env.PORT) || 4173;
+const MIME: Record<string, string> = {
+  '.html': 'text/html',
+  '.js': 'text/javascript',
+  '.css': 'text/css',
+  '.json': 'application/json',
+};
+
+createServer((req, res) => {
+  let p = decodeURIComponent((req.url || '/').split('?')[0] as string);
+  if (p === '/') p = '/index.html';
+  const f = join(dir, p);
+  if (!f.startsWith(dir) || !existsSync(f) || !statSync(f).isFile()) {
+    res.statusCode = 404;
+    res.end('not found');
+    return;
+  }
+  res.setHeader('content-type', MIME[extname(f)] ?? 'text/plain');
+  res.end(readFileSync(f));
+}).listen(PORT, () => console.log(`[inspector] http://localhost:${PORT}`));

package/ai/inspector/web/__tests__/debug.test.ts

@@ -0,0 +1,173 @@
+// @file: ai/inspector — deterministic debugger-flow scenarios over the REAL /sdd skill + directives.
+// The inspector is a deterministic replay machine: same skill + same moves => same log/stack. These
+// tests pin the exact scenarios we walk through by hand (auto-enter at EMBODY, LOGIC_SWITCH branch,
+// step-into descent, DEFAULT proceed) so the flow can't silently regress.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { parseSkill } from '../../core/parse-skill.ts';
+import { resolveTree, type DirectiveReader } from '../../core/resolve.ts';
+// the module under test — the pure, DOM-free debugger model the UI draws from
+import { simulate, unitsOf, mainDirective, transitionsFor, base } from '../debug.js';
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..');
+const read: DirectiveReader = (ref) => {
+  const p = resolve(repoRoot, ref);
+  return existsSync(p) ? readFileSync(p, 'utf8') : null;
+};
+
+/** Parse + resolve a skill exactly as generate.ts does, so tests run against the real tree. */
+function loadSkill(name: string) {
+  const rel = `ai/skills/${name}/SKILL.md`;
+  const tree = parseSkill(rel, readFileSync(join(repoRoot, rel), 'utf8'));
+  resolveTree(tree, read);
+  return tree;
+}
+
+const stackLabels = (sim: ReturnType<typeof simulate>) => sim.stack.map((f: any) => f.node.label);
+const divs = (sim: ReturnType<typeof simulate>) =>
+  sim.log.filter((e: any) => e.div).map((e: any) => e.div);
+
+/** Drive the debugger deterministically: prefer a transition matching `prefer`, else DEFAULT, else advance —
+ *  until `stop(sim)` is true or moves run dry. Returns { sim, moves } so the caller can extend the path. */
+function driveUntil(skill: any, stop: (sim: any) => boolean, prefer: RegExp[] = [], maxSteps = 40) {
+  const moves: any[] = [];
+  for (let i = 0; i < maxSteps; i++) {
+    const sim = simulate(skill, moves);
+    if (!sim.current || stop(sim)) return { sim, moves };
+    const trans = sim.current.transitions;
+    const picked =
+      prefer.map((re) => trans.find((t: any) => re.test(t.run?.ref ?? t.label))).find(Boolean) ??
+      trans.find((t: any) => /DEFAULT/.test(t.label)) ??
+      trans.find((t: any) => t.type === 'next') ??
+      trans[0];
+    moves.push({ type: picked.type, i: picked.i });
+  }
+  return { sim: simulate(skill, moves), moves };
+}
+
+test('regression: a formats/*.xml contract reference (not *.directive.xml) is offered as step-into', () => {
+  // STEP_4_PORTAL_WRITE's Action reads `READ_AND_USE_DIRECTIVE("ai/directives/sdd-v2/formats/portal-structure.xml")`.
+  // formats/*.xml files are NOT *.directive.xml — the scanner used to miss them entirely, so this step
+  // silently advanced past the reference instead of offering a descent. Pin the fix at both layers:
+  // the ref is scanned as a 'run' node, resolved into a <Contract> leaf carrying its markdown body, and
+  // offered as a real 'into' transition from the step.
+  const sdd = loadSkill('sdd');
+  const { sim, moves } = driveUntil(
+    sdd,
+    (s) => s.current.unit.attrs?.id === 'STEP_4_PORTAL_WRITE',
+    [/root\.directive\.xml/]
+  );
+  assert.equal(sim.current.unit.attrs?.id, 'STEP_4_PORTAL_WRITE');
+
+  const into = sim.current.transitions.find(
+    (t: any) => t.run && /portal-structure\.xml/.test(t.run.ref)
+  );
+  assert.ok(into, 'portal-structure.xml is offered as a step-into transition');
+
+  const after = simulate(sdd, [...moves, { type: into.type, i: into.i }]);
+  const loaded = after.log.find((e: any) => e.dir && e.dir.label === '<Contract>');
+  assert.ok(loaded, 'entering the ref attaches the resolved <Contract> node for inspection');
+  assert.match(
+    loaded.dir.detail ?? '',
+    /Vision/,
+    'the contract carries its markdown template body, not an empty leaf'
+  );
+  // the contract has no <ExecutionPlan> (it is a format, not a directive with steps) — auto-unwind cascades
+  assert.ok(after.done, 'flow completes after the content-only contract immediately unwinds');
+});
+
+test('/sdd skill exposes the GATHER / EMBODY / ROUTE loader steps and embodies the router', () => {
+  const sdd = loadSkill('sdd');
+  const units = unitsOf(sdd);
+  const ids = units.map((u: any) => u.attrs?.id);
+  assert.ok(ids.includes('GATHER'), 'has GATHER');
+  assert.ok(ids.includes('EMBODY'), 'has EMBODY');
+  const main = mainDirective(sdd);
+  assert.ok(main, 'embodies a main directive');
+  assert.equal(base(main.run.ref), 'router.directive.xml');
+  assert.equal(main.dir.label, '<SddRouter>');
+});
+
+test('scenario: advancing past GATHER auto-enters the router at EMBODY (stack /sdd › <SddRouter>)', () => {
+  const sdd = loadSkill('sdd');
+  // GATHER just loads; the loader BECOMES the router at EMBODY — one "next" reaches EMBODY and auto-descends
+  const sim = simulate(sdd, [{ type: 'next' }]);
+  assert.deepEqual(stackLabels(sim), ['/sdd', '<SddRouter>']);
+  // the descent is announced in the log and the loaded directive is attached for inspection
+  assert.ok(divs(sim).some((d: string) => d.startsWith('загружен скил /sdd')));
+  assert.ok(
+    divs(sim).some((d: string) => d.includes('<SddRouter>') && d.includes('router.directive.xml'))
+  );
+  const loaded = sim.log.find((e: any) => e.dir && e.dir.label === '<SddRouter>');
+  assert.ok(loaded, 'router node carried on the entry divider for the collapsed inspect block');
+});
+
+test('scenario: at STEP_0_STATE the LOGIC_SWITCH offers migration / readiness / DEFAULT branches', () => {
+  const sdd = loadSkill('sdd');
+  const sim = simulate(sdd, [{ type: 'next' }]);
+  assert.ok(sim.current, 'a current unit is active');
+  assert.equal(sim.current.unit.attrs?.id, 'STEP_0_STATE');
+  const trans = sim.current.transitions;
+  assert.ok(
+    trans.every((t: any) => t.type === 'branch'),
+    'preflight switch yields branch choices, not a linear next'
+  );
+  const labels = trans.map((t: any) => t.label).join(' | ');
+  assert.match(labels, /FLOW_VERSION=v1/); // → migration branch
+  assert.match(labels, /READINESS=not-ready/); // → readiness branch
+  assert.match(labels, /DEFAULT/);
+  // the conditional branches carry the directive they would load
+  const migBranch = trans.find((t: any) => t.run && /migration-v1-v2/.test(t.run.ref));
+  assert.ok(migBranch, 'FLOW_VERSION=v1 branch loads migration-v1-v2.directive.xml');
+});
+
+test('scenario: taking the FLOW_VERSION=v1 branch descends into the migration directive (3-level stack)', () => {
+  const sdd = loadSkill('sdd');
+  const sim = simulate(sdd, [{ type: 'next' }]);
+  const migIdx = sim.current.transitions.findIndex(
+    (t: any) => t.run && /migration-v1-v2/.test(t.run.ref)
+  );
+  assert.ok(migIdx >= 0, 'migration branch present');
+  const after = simulate(sdd, [{ type: 'next' }, { type: 'branch', i: migIdx }]);
+  assert.deepEqual(stackLabels(after), ['/sdd', '<SddRouter>', '<SddMigrationV1V2>']);
+  assert.ok(divs(after).some((d: string) => d.startsWith('ветка → загружена <SddMigrationV1V2>')));
+  // indentation is driven by stack depth: deeper frames carry larger depth on their log entries
+  const migDiv = after.log.find((e: any) => e.div && e.div.includes('<SddMigrationV1V2>'));
+  assert.equal(migDiv.depth, 2, 'migration entry sits at depth 2 (shifted two levels in)');
+});
+
+test('scenario: the DEFAULT branch proceeds inside the router (no descent) to the next step', () => {
+  const sdd = loadSkill('sdd');
+  const sim = simulate(sdd, [{ type: 'next' }]);
+  const defIdx = sim.current.transitions.findIndex((t: any) => /DEFAULT/.test(t.label));
+  const after = simulate(sdd, [{ type: 'next' }, { type: 'branch', i: defIdx }]);
+  // DEFAULT has no directive to load → we stay in the router frame and advance past STEP_0_STATE
+  assert.deepEqual(stackLabels(after), ['/sdd', '<SddRouter>']);
+  assert.notEqual(after.current?.unit.attrs?.id, 'STEP_0_STATE', 'advanced beyond the preflight');
+});
+
+test('determinism: identical moves reproduce an identical log', () => {
+  const sdd = loadSkill('sdd');
+  const a = simulate(sdd, [{ type: 'next' }, { type: 'branch', i: 0 }]);
+  const b = simulate(sdd, [{ type: 'next' }, { type: 'branch', i: 0 }]);
+  assert.deepEqual(
+    a.log.map((e: any) => [e.div ?? null, e.step?.label ?? null, e.depth]),
+    b.log.map((e: any) => [e.div ?? null, e.step?.label ?? null, e.depth])
+  );
+});
+
+test('the embodied router is auto-entered, so it is NOT offered as a manual step-into on loader steps', () => {
+  const sdd = loadSkill('sdd');
+  const frame = { node: sdd } as any;
+  const gather = unitsOf(sdd).find((u: any) => u.attrs?.id === 'GATHER');
+  const trans = transitionsFor(frame, gather);
+  assert.ok(
+    !trans.some((t: any) => t.type === 'into' && base(t.label) === 'router.directive.xml'),
+    'router is not a manual step-into (it auto-enters at EMBODY)'
+  );
+});