@funnelsgrove/cli 0.1.87 → 0.1.89

package/template_scaffold/tests/funnel-agent-docs.test.ts

@@ -1,751 +0,0 @@
-import { createHash } from 'node:crypto';
-import { execFile as execFileCallback } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { mkdir, mkdtemp, readFile, rm, stat, symlink, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { dirname, join, relative } from 'node:path';
-import { promisify } from 'node:util';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { describe, expect, it } from 'vitest';
-
-const templateRoot = dirname(dirname(fileURLToPath(import.meta.url)));
-const findRepositoryRoot = (): string => {
-  let current = templateRoot;
-  while (dirname(current) !== current) {
-    if (existsSync(join(current, 'apps/funnel-runtime/package.json'))) {
-      return current;
-    }
-    current = dirname(current);
-  }
-  throw new Error('FunnelsGrove repository root not found');
-};
-const repoRoot = findRepositoryRoot();
-const cliDocsRoot = join(repoRoot, 'apps/cli/template_docs');
-const contract = JSON.parse(
-  await readFile(join(repoRoot, 'apps/funnel-runtime/contracts/step-contract-v2.json'), 'utf8'),
-);
-
-const requiredOutline = [
-  '## Use when / do not use when',
-  '## Exact metadata contract',
-  '## Interaction and persisted answer shape',
-  '## Automatic lifecycle events',
-  '## Required semantic conversions',
-  '## Approved shared helpers',
-  '## MUST rules',
-  '## NEVER rules',
-  '## Golden template or fixture',
-  '## Validation command',
-  '## Manual QA and completion criteria',
-] as const;
-
-const sha256 = (content: string): string => createHash('sha256').update(content).digest('hex');
-const execFile = promisify(execFileCallback);
-const renderCodes = (values: readonly unknown[]): string => (
-  values.length === 0 ? '_None_' : values.map((value) => `\`${String(value)}\``).join(', ')
-);
-
-async function loadGenerator() {
-  return import(pathToFileURL(join(repoRoot, 'scripts/generate-funnel-agent-docs.mjs')).href);
-}
-
-describe('funnel agent documentation supply', () => {
-  it('provides one complete generated-contract page per exact step type', async () => {
-    const stepTypes = Object.keys(contract.stepContracts).sort();
-
-    await Promise.all(stepTypes.map(async (stepType) => {
-      expect(stepType).toMatch(/^[a-z0-9_]+$/);
-      const content = await readFile(
-        join(templateRoot, `docs/funnelsgrove/steps/${stepType}.md`),
-        'utf8',
-      );
-
-      const headings = content.split('\n').filter((line) => line.startsWith('## '));
-      expect(headings).toEqual(requiredOutline);
-
-      expect(content).toContain(`contract-v3/step/${stepType}`);
-      expect(content).toContain('#### Golden fixture source');
-      expect(content).toContain('export const goldenFixture');
-      expect(content).toContain('[embedded canonical fixture](#golden-fixture-source)');
-      expect(content).not.toContain('../../../src/contract/golden/');
-      expect(content).toContain('fgrove validate');
-    }));
-  });
-
-  it('rejects missing, duplicate, nested, mismatched, and unknown generated markers', async () => {
-    const { parseGeneratedBlock } = await loadGenerator();
-    const valid = [
-      'before',
-      '<!-- funnelsgrove:generated:start contract-v3/step/intro_hero -->',
-      'generated',
-      '<!-- funnelsgrove:generated:end contract-v3/step/intro_hero -->',
-      'after',
-      '',
-    ].join('\n');
-
-    expect(parseGeneratedBlock(valid, 'step/intro_hero')).toMatchObject({
-      logicalId: 'step/intro_hero',
-      body: 'generated\n',
-    });
-    expect(() => parseGeneratedBlock('no marker\n', 'step/intro_hero')).toThrow(/missing/i);
-    expect(() => parseGeneratedBlock(`${valid}${valid}`, 'step/intro_hero')).toThrow(/duplicate/i);
-    expect(() => parseGeneratedBlock(valid.replace(
-      'generated\n',
-      'generated\n<!-- funnelsgrove:generated:start contract-v3/step/intro_hero -->\n',
-    ), 'step/intro_hero')).toThrow(/nested|duplicate/i);
-    expect(() => parseGeneratedBlock(valid.replace(
-      'end contract-v3/step/intro_hero',
-      'end contract-v3/step/value_prop_story',
-    ), 'step/intro_hero')).toThrow(/mismatch/i);
-    expect(() => parseGeneratedBlock(
-      valid.replace('<!-- funnelsgrove:generated:start', '<!--  funnelsgrove:generated:start'),
-      'step/intro_hero',
-    )).toThrow(/malformed/i);
-    expect(() => parseGeneratedBlock(
-      valid.replace(
-        '<!-- funnelsgrove:generated:start contract-v3/step/intro_hero -->',
-        'inline <!-- funnelsgrove:generated:start contract-v3/step/intro_hero -->',
-      ),
-      'step/intro_hero',
-    )).toThrow(/standalone|full line/i);
-    expect(() => parseGeneratedBlock(
-      `<!-- funnelsgrove:generated:start contract-v3/not-known -->\n${valid}\n<!-- funnelsgrove:generated:end contract-v3/not-known -->`,
-      'step/intro_hero',
-    )).toThrow(/unknown/i);
-    expect(() => parseGeneratedBlock(
-      `<!-- funnelsgrove:generated:start contract-v3/INVALID -->\n${valid}`,
-      'step/intro_hero',
-    )).toThrow(/malformed/i);
-    expect(() => parseGeneratedBlock(valid, 'unknown/id')).toThrow(/unknown/i);
-  });
-
-  it('renders every normative contract field into generated step blocks', async () => {
-    const { buildBundle } = await loadGenerator();
-    const bundle = await buildBundle();
-
-    for (const [stepType, definition] of Object.entries(contract.stepContracts)) {
-      const path = `docs/funnelsgrove/steps/${stepType}.md`;
-      const page = bundle.files.get(path);
-      expect(page, `missing ${path}`).toBeDefined();
-      expect(page).toContain(`Step contract version: \`${contract.stepContractVersion}\``);
-      expect(page).toContain(`Contract hash: \`${contract.contractHash}\``);
-      expect(page).toContain(`Type: \`${stepType}\``);
-      expect(page).toContain(`Family: \`${definition.family}\``);
-      expect(page).toContain(definition.description);
-      expect(page).toContain(`Action owner: \`${definition.actionOwner}\``);
-      expect(page).toContain(`Terminal: \`${String(definition.terminal)}\``);
-      expect(page).toContain(`Analytics role: ${'analyticsRole' in definition ? `\`${definition.analyticsRole}\`` : '_none_'}`);
-      expect(page).toContain(`Required kind: ${'requiredKind' in definition ? `\`${definition.requiredKind}\`` : '_none_'}`);
-      expect(page).toContain(`Allowed kinds: ${renderCodes(definition.allowedKinds)}`);
-      expect(page).toContain(`Allowed semantic events: ${renderCodes(definition.allowedCustomEvents)}`);
-      expect(page).toContain(`Forbidden capabilities: ${renderCodes(definition.forbiddenCapabilities)}`);
-      if ('choice' in definition) {
-        expect(page).toContain(`Cardinality: \`${definition.choice.cardinality}\``);
-        expect(page).toContain(`Presentation: \`${definition.choice.presentation}\``);
-        expect(page).toContain(`Completion: \`${definition.choice.completion}\``);
-        expect(page).toContain(`Allow empty config: \`${String(definition.choice.allowEmptyConfig)}\``);
-      }
-    }
-  });
-
-  it('renders package release order from the current package manifests', async () => {
-    const { buildBundle, parseGeneratedBlock } = await loadGenerator();
-    const [runtimePackage, analyticsPackage, paymentsPackage, cliPackage] = await Promise.all([
-      readFile(join(repoRoot, 'apps/funnel-runtime/package.json'), 'utf8').then(JSON.parse),
-      readFile(join(repoRoot, 'apps/funnel-analytics/package.json'), 'utf8').then(JSON.parse),
-      readFile(join(repoRoot, 'apps/funnel-payments/package.json'), 'utf8').then(JSON.parse),
-      readFile(join(repoRoot, 'apps/cli/package.json'), 'utf8').then(JSON.parse),
-    ]);
-    const migration = (await buildBundle()).files.get(
-      'docs/funnelsgrove/migrations/step-contract-v3.md',
-    )!;
-    const generated = parseGeneratedBlock(migration, 'migration/step-contract-v3').body;
-
-    expect(generated).toContain('### Package release order');
-    expect(generated).toContain(
-      `Release \`@funnelsgrove/runtime\` \`${runtimePackage.version}\` first, `
-      + `then \`@funnelsgrove/analytics\` \`${analyticsPackage.version}\`, `
-      + `then \`@funnelsgrove/payments\` \`${paymentsPackage.version}\`. `
-      + 'Deploy the API and funnel template, then confirm production `/health` reports the new docs identity. '
-      + `Only then publish \`@funnelsgrove/cli\` \`${cliPackage.version}\`.`,
-    );
-  });
-
-  it('renders every capability and reserved-identity field exactly', async () => {
-    const { buildBundle } = await loadGenerator();
-    const bundle = await buildBundle();
-    const capabilityPage = bundle.files.get('docs/funnelsgrove/qa/local.md')!;
-    const reservedPage = bundle.files.get('docs/funnelsgrove/contracts/step-metadata.md')!;
-
-    for (const [name, rule] of Object.entries(contract.capabilityRules)) {
-      expect(capabilityPage).toContain([
-        `| \`${name}\``,
-        rule.allowedStepTypes === 'any' ? '`any`' : renderCodes(rule.allowedStepTypes),
-        rule.allowedStepIdentities === 'any' ? '`any`' : renderCodes(rule.allowedStepIdentities),
-        `\`${rule.requiredOwner}\` |`,
-      ].join(' | '));
-    }
-
-    for (const [name, definition] of Object.entries(contract.reservedStepContracts)) {
-      expect(reservedPage).toContain([
-        `| \`${name}\``,
-        `\`${definition.match}\``,
-        `\`${'id' in definition ? definition.id : definition.idPattern}\``,
-        `\`${'name' in definition ? definition.name : definition.namePattern}\``,
-        `\`${definition.type}\``,
-        'kind' in definition ? `\`${definition.kind}\`` : '—',
-        'primary' in definition ? `\`${String(definition.primary)}\`` : '—',
-        `\`${String(definition.unique)}\` |`,
-      ].join(' | '));
-    }
-  });
-
-  it('renders complete analytics event scopes and ownership from the contract', async () => {
-    const { buildBundle } = await loadGenerator();
-    const bundle = await buildBundle();
-    const page = bundle.files.get('docs/funnelsgrove/contracts/analytics-events.md')!;
-    const renderScope = (value: unknown): string => {
-      if (value === 'any') return '`any`';
-      if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
-        throw new Error('Invalid analytics event scope fixture');
-      }
-      return renderCodes(value);
-    };
-
-    for (const [key, event] of Object.entries(contract.analyticsEventContracts)) {
-      expect(page).toContain(`${[
-        `| \`${key}\``,
-        `\`${event.publicName}\``,
-        `\`${event.rawName}\``,
-        renderScope(event.allowedStepTypes),
-        renderScope(event.allowedStepIdentities),
-        `\`${event.owner}\``,
-        `\`${String(event.automatic)}\``,
-        `\`${event.dedupeScope}\``,
-        `${renderCodes(event.requiredMetadata)} |`,
-      ].join(' | ')}`);
-    }
-  });
-
-  it('documents experiment routing before visit creation without phantom lifecycle events', async () => {
-    const content = await readFile(
-      join(templateRoot, 'docs/funnelsgrove/recipes/add-experiment.md'),
-      'utf8',
-    );
-
-    expect(content).toContain(
-      'Resolve assignment and any redirect before creating the destination step visit.',
-    );
-    expect(content).toContain(
-      'Pre-activation, missing-assignment, invalid-assignment, and fallback paths must not create phantom `step_started`, `step_completed`, or `step_exited` events.',
-    );
-  });
-
-  it('documents the complete JSON-driven experiment creation workflow', async () => {
-    const content = await readFile(
-      join(templateRoot, 'docs/funnelsgrove/recipes/add-experiment.md'),
-      'utf8',
-    );
-    const examples = [...content.matchAll(/```json\n([\s\S]*?)\n```/g)]
-      .map((match) => JSON.parse(match[1]) as { type?: unknown });
-
-    expect(examples.map(({ type }) => type)).toEqual(['step', 'paywall', 'pricing']);
-    expect(content).toContain('fgrove experiments create --spec experiment.json --dir .');
-    expect(content).toContain('fgrove experiments create --spec experiment.json --dir . --json');
-    expect(content).toContain('`experimentId`, `experimentKey`, `draftVersionId`, and `writtenPaths`');
-    expect(content).toContain(
-      'Pricing variants additionally require `offerSetId` as a UUID.',
-    );
-    expect(content).not.toContain('offerSetKey');
-    expect(content).toContain('does not create or activate a PostHog flag');
-    expect(content).toContain('included in the version-bound runtime artifact');
-    expect(content).toContain('deprecated compatibility files');
-    expect(content).toContain('[FG-EXPERIMENT-STALE-DRAFT]');
-    expect(content).toContain('[FG-EXPERIMENT-DRAFT-CONFLICT]');
-    expect(content).toContain('[FG-EXPERIMENT-SPEC]');
-    expect(content).toContain('fgrove sync up');
-    expect(content).toContain('fgrove github pull');
-    expect(content).toContain('`.funnelsgrove-sync.json` stays local and ignored');
-  });
-
-  it('keeps intro engagement explicitly non-automatic', async () => {
-    const content = await readFile(
-      join(templateRoot, 'docs/funnelsgrove/steps/intro_hero.md'),
-      'utf8',
-    );
-
-    expect(content).toContain(
-      '`step_engaged` is registered as non-automatic and is not emitted by default.',
-    );
-    expect(content).toContain(
-      'Only an explicit, centralized, tested engagement policy may emit it through the approved controller/helper boundary; step components never emit it manually.',
-    );
-    expect(content).not.toContain('owns view, start, engagement, completion, and exit lifecycle tracking');
-    expect(content).not.toContain('after the engagement threshold is met');
-  });
-
-  it('documents distinct terminal and non-terminal handoff completion modes', async () => {
-    const terminal = await readFile(
-      join(templateRoot, 'docs/funnelsgrove/steps/purchase_completed.md'),
-      'utf8',
-    );
-    const handoff = await readFile(
-      join(templateRoot, 'docs/funnelsgrove/steps/subscription_handoff.md'),
-      'utf8',
-    );
-
-    expect(terminal).toContain('`completeFunnel(stepId)` atomically claims the active terminal visit');
-    expect(terminal).toContain('flushes before outbound handoff');
-    expect(terminal).toContain('completionMode="funnel"');
-    expect(terminal).toContain('`purchase_completed` is trusted-server-only');
-    expect(terminal).toContain('terminal reach, `funnel_completed`');
-    expect(handoff).toContain('completion mode of `step`');
-    expect(handoff).toContain('never opt a non-terminal handoff into `completionMode="funnel"`');
-  });
-
-  it('keeps legacy terminal names out of current v3 authoring instructions', async () => {
-    const { buildBundle } = await loadGenerator();
-    const bundle = await buildBundle();
-
-    for (const [path, content] of bundle.files) {
-      if (!path.endsWith('.md') || path.endsWith('/migrations/step-contract-v3.md')) continue;
-      expect(content, path).not.toMatch(/complete[-_]registration/i);
-    }
-  });
-
-  it('defines Quiz completed by unique paywall reach without conflating purchase verification', async () => {
-    const paths = [
-      'docs/funnelsgrove/qa/analytics.md',
-      'docs/funnelsgrove/contracts/analytics-events.md',
-      'docs/funnelsgrove/START-HERE.md',
-      'docs/funnelsgrove/contracts/payments.md',
-    ];
-    const contents = await Promise.all(paths.map(async (path) => ({
-      path,
-      content: await readFile(join(templateRoot, path), 'utf8'),
-    })));
-
-    for (const { path, content } of contents) {
-      expect(content, path).toContain(
-        'Quiz completed counts each unique user who reaches a paywall step.',
-      );
-      expect(content, path).toContain(
-        '`purchase_completed` remains trusted-server-only purchase verification and does not define Quiz completed.',
-      );
-      expect(content, path).toContain(
-        'Browser terminal reach and `funnel_completed` remain lifecycle-only and are not purchase conversions.',
-      );
-      expect(content, path).not.toMatch(/Quiz completed requires[^.]*purchase_completed/i);
-      expect(content, path).not.toMatch(/terminal reach[^.]*not (?:count|counts) as Quiz completed/i);
-    }
-  });
-
-  it('preserves the implementation-owned visitor metric while linking event ownership', async () => {
-    const content = await readFile(join(repoRoot, 'docs/product-specs/analytics.md'), 'utf8');
-
-    expect(content).toContain(
-      'Visitors are the sum of daily unique PostHog `distinct_id` values with a `first_step_viewed` or `step_engaged` event.',
-    );
-    expect(content).toContain(
-      '`step_engaged` is an optional qualified input, not a default 1-second runtime emission.',
-    );
-    expect(content).toContain(
-      '../../apps/funnel-template/docs/funnelsgrove/contracts/analytics-events.md',
-    );
-  });
-
-  it('builds a deterministic LF-only manifest over the full sorted managed set', async () => {
-    const { buildBundle, MANIFEST_PATH } = await loadGenerator();
-    const bundle = await buildBundle();
-    const manifestContent = bundle.files.get(MANIFEST_PATH);
-    expect(manifestContent).toBeDefined();
-    const manifest = JSON.parse(manifestContent!);
-
-    expect(manifest).toMatchObject({
-      schemaVersion: 1,
-      bundleVersion: '2.0.76',
-      stepContractVersion: contract.stepContractVersion,
-      contractHash: contract.contractHash,
-    });
-    expect(manifest.managedFiles.map((entry: { path: string }) => entry.path)).toEqual(
-      [...bundle.managedPaths].sort(),
-    );
-    for (const entry of manifest.managedFiles) {
-      expect(entry.sha256).toBe(sha256(bundle.files.get(entry.path)!));
-    }
-    for (const content of bundle.files.values()) {
-      expect(content).not.toContain('\r');
-      expect(content).not.toMatch(/[ \t]+$/m);
-      expect(content.endsWith('\n')).toBe(true);
-    }
-    expect([...bundle.files.keys()].at(-1)).toBe(MANIFEST_PATH);
-    expect(bundle.files.has(MANIFEST_PATH)).toBe(true);
-    expect(bundle.managedPaths).not.toContain(MANIFEST_PATH);
-    expect(manifest.managedFiles).not.toContainEqual(expect.objectContaining({ path: MANIFEST_PATH }));
-    expect(bundle.config.fullyGenerated).toContain(MANIFEST_PATH);
-    expect(bundle.config).toMatchObject({
-      contractSource: 'funnelsgrove-repository://apps/funnel-runtime/contracts/step-contract-v2.json',
-    });
-    expect(bundle.config).not.toHaveProperty('contractPath');
-  });
-
-  it('matches the generated in-memory bundle, resolves links, and mirrors every byte to the CLI', async () => {
-    const { buildBundle, validateBundleLinks } = await loadGenerator();
-    const bundle = await buildBundle();
-    await expect(validateBundleLinks(bundle, templateRoot)).resolves.toEqual([]);
-    const isolatedRoot = await mkdtemp(join(tmpdir(), 'fg-docs-self-contained-'));
-    try {
-      await expect(validateBundleLinks(bundle, isolatedRoot)).resolves.toEqual([]);
-    } finally {
-      await rm(isolatedRoot, { recursive: true, force: true });
-    }
-
-    for (const [path, expected] of bundle.files) {
-      await expect(readFile(join(templateRoot, path), 'utf8')).resolves.toBe(expected);
-      await expect(readFile(join(cliDocsRoot, path), 'utf8')).resolves.toBe(expected);
-    }
-    expect(bundle.files.has('AGENTS.project.md')).toBe(false);
-    await expect(stat(join(cliDocsRoot, 'AGENTS.project.md'))).rejects.toThrow();
-  });
-
-  it('detects broken managed links', async () => {
-    const { buildBundle, validateBundleLinks } = await loadGenerator();
-    const bundle = await buildBundle();
-    bundle.files.set('AGENTS.md', bundle.files.get('AGENTS.md')!
-      .replace('docs/funnelsgrove/START-HERE.md', 'docs/funnelsgrove/MISSING.md'));
-
-    await expect(validateBundleLinks(bundle, templateRoot)).resolves.toEqual([
-      'AGENTS.md: broken link: docs/funnelsgrove/MISSING.md',
-    ]);
-  });
-
-  it('validates anchor-only and cross-file Markdown fragments', async () => {
-    const { buildBundle, validateBundleLinks } = await loadGenerator();
-    const bundle = await buildBundle();
-    const stepPath = 'docs/funnelsgrove/steps/paywall_offer.md';
-    bundle.files.set(stepPath, bundle.files.get(stepPath)!
-      .replace('#golden-fixture-source', '#missing-golden-fixture'));
-    bundle.files.set('AGENTS.md', `${bundle.files.get('AGENTS.md')}\n[Missing section](docs/funnelsgrove/START-HERE.md#missing-section)\n`);
-
-    await expect(validateBundleLinks(bundle, templateRoot)).resolves.toEqual([
-      'AGENTS.md: broken anchor: docs/funnelsgrove/START-HERE.md#missing-section',
-      `${stepPath}: broken anchor: #missing-golden-fixture`,
-    ]);
-  });
-
-  it('rejects symlinks and special entries while traversing a documentation mirror', async () => {
-    const { listFiles } = await loadGenerator();
-    const mirrorRoot = await mkdtemp(join(tmpdir(), 'fg-docs-unsafe-mirror-'));
-    try {
-      await symlink('/etc/passwd', join(mirrorRoot, 'escaped-link'));
-      await expect(listFiles(mirrorRoot)).rejects.toThrow(/escaped-link.*symlink/i);
-    } finally {
-      await rm(mirrorRoot, { recursive: true, force: true });
-    }
-  });
-
-  it('refuses generation through managed-file or ancestor symlinks before writing anything', async () => {
-    const { buildBundle, writeBundleRoot } = await loadGenerator();
-    const bundle = await buildBundle();
-    const sandbox = await mkdtemp(join(tmpdir(), 'fg-docs-safe-write-'));
-    const managedRoot = join(sandbox, 'managed');
-    const ancestorRoot = join(sandbox, 'ancestor');
-    const outsideFile = join(sandbox, 'outside.md');
-    const outsideDirectory = join(sandbox, 'outside-directory');
-    const lateManagedPath = 'docs/funnelsgrove/steps/value_prop_story.md';
-
-    try {
-      await mkdir(dirname(join(managedRoot, lateManagedPath)), { recursive: true });
-      await writeFile(outsideFile, 'outside stays unchanged\n');
-      await symlink(outsideFile, join(managedRoot, lateManagedPath));
-
-      await expect(writeBundleRoot(managedRoot, bundle, false)).rejects.toThrow(
-        /value_prop_story\.md.*symlink/i,
-      );
-      await expect(readFile(outsideFile, 'utf8')).resolves.toBe('outside stays unchanged\n');
-      await expect(stat(join(managedRoot, 'AGENTS.md'))).rejects.toThrow();
-
-      await mkdir(ancestorRoot, { recursive: true });
-      await mkdir(outsideDirectory, { recursive: true });
-      await symlink(outsideDirectory, join(ancestorRoot, 'docs'));
-      await expect(writeBundleRoot(ancestorRoot, bundle, false)).rejects.toThrow(
-        /docs.*symlink/i,
-      );
-      await expect(stat(join(ancestorRoot, 'AGENTS.md'))).rejects.toThrow();
-    } finally {
-      await rm(sandbox, { recursive: true, force: true });
-    }
-  });
-
-  it('rejects stray files in canonical managed namespaces without claiming legacy docs', async () => {
-    const { buildBundle, findUnexpectedCanonicalFiles } = await loadGenerator();
-    const bundle = await buildBundle();
-    const candidateRoot = await mkdtemp(join(tmpdir(), 'fg-docs-canonical-'));
-    try {
-      await mkdir(join(candidateRoot, 'docs/funnelsgrove'), { recursive: true });
-      await writeFile(join(candidateRoot, 'docs/funnelsgrove/stray.md'), 'stray\n');
-      await mkdir(join(candidateRoot, 'docs/legacy'), { recursive: true });
-      await writeFile(join(candidateRoot, 'docs/legacy/compat.md'), 'unmanaged\n');
-      await writeFile(join(candidateRoot, 'AGENTS.project.md'), 'product context\n');
-
-      await expect(findUnexpectedCanonicalFiles(bundle, candidateRoot)).resolves.toEqual([
-        'template unmanaged canonical file: docs/funnelsgrove/stray.md',
-      ]);
-    } finally {
-      await rm(candidateRoot, { recursive: true, force: true });
-    }
-  });
-
-  it('applies optional project guidance without allowing it to override the managed contract', async () => {
-    const { buildBundle } = await loadGenerator();
-    const agents = (await buildBundle()).files.get('AGENTS.md')!;
-
-    expect(agents).toContain('read and apply `AGENTS.project.md` after this managed contract');
-    expect(agents).toContain('the managed contract wins');
-  });
-
-  it('preserves privacy boundaries for analytics and transactional email capture', async () => {
-    const pages = await Promise.all([
-      'docs/funnelsgrove/contracts/analytics-events.md',
-      'docs/funnelsgrove/steps/form_input.md',
-      'docs/funnelsgrove/qa/analytics.md',
-    ].map((path) => readFile(join(templateRoot, path), 'utf8')));
-
-    for (const page of pages) {
-      expect(page).toContain('Never put raw email or other PII in analytics event metadata or logs.');
-      expect(page).toContain('Only the server delivery boundary may use raw email as Meta hashing input.');
-      expect(page).toContain('PostHog properties must remain non-PII.');
-    }
-  });
-
-  it('preserves sync, planning, theme, asset, image, and responsive safety guidance', async () => {
-    const { buildBundle } = await loadGenerator();
-    const files = (await buildBundle()).files;
-    const agents = files.get('AGENTS.md')!;
-    const content = files.get('docs/funnelsgrove/contracts/content-answers.md')!;
-    const start = files.get('docs/funnelsgrove/START-HERE.md')!;
-    const flow = files.get('docs/funnelsgrove/contracts/flow-routing.md')!;
-    const localQa = files.get('docs/funnelsgrove/qa/local.md')!;
-    const publishQa = files.get('docs/funnelsgrove/qa/publish.md')!;
-
-    for (const token of [
-      'fgrove status',
-      'git status --short',
-      'fgrove sync down',
-      'remote compare-and-swap',
-      'fgrove github pull',
-      'fgrove sync up',
-      'fgrove env pull',
-    ]) expect(agents).toContain(token);
-    for (const token of ['PRODUCT_SENSE.md', '## Strategic Pre-Work', 'PLAN.md', '## Funnel Fuel']) {
-      expect(content).toContain(token);
-    }
-    for (const token of ['src/theme/theme.ts', 'FunnelTheme', 'createThemeCssVariables', 'CSS variables']) {
-      expect(start).toContain(token);
-    }
-    for (const token of ['funnelManifest.assets', 'assetIds', "preload: 'idle'", 'AVIF/WebP']) {
-      expect(flow).toContain(token);
-    }
-    for (const token of ['no horizontal scrolling', '44×44 CSS px', 'assetId']) {
-      expect(localQa).toContain(token);
-    }
-    for (const token of ['imageVariants', 'AVIF/WebP', 'original raster']) {
-      expect(publishQa).toContain(token);
-    }
-  });
-
-  it('keeps root guidance on real workspace commands and package names', async () => {
-    const paths = [
-      'docs/guides/build-funnel-step-by-step.md',
-      'docs/guides/edit-funnel-template-safely.md',
-      'docs/product-specs/funnel-template-step-authoring.md',
-      'docs/product-specs/funnel-template-agent-editing.md',
-    ];
-    const content = (await Promise.all(paths.map((path) => readFile(join(repoRoot, path), 'utf8'))))
-      .join('\n');
-
-    expect(content).not.toContain('npx tsc --noEmit --workspace funnel-template');
-    expect(content).not.toContain('@funnelsgrove/funnel-analytics');
-    expect(content).toContain('npm run build --workspace funnel-template');
-    expect(content).toContain('@funnelsgrove/analytics');
-  });
-
-  it('requires a bundle-version bump when managed bytes change', async () => {
-    const { validateBundleVersionReuse } = await loadGenerator();
-    const previous = {
-      bundleVersion: '2.0.0',
-      managedFiles: [{ path: 'AGENTS.md', sha256: 'old' }],
-    };
-
-    expect(validateBundleVersionReuse(previous, {
-      bundleVersion: '2.0.0',
-      managedFiles: [{ path: 'AGENTS.md', sha256: 'new' }],
-    })).toEqual(['Managed documentation bytes changed without changing bundleVersion 2.0.0']);
-    expect(validateBundleVersionReuse(previous, {
-      bundleVersion: '2.0.1',
-      managedFiles: [{ path: 'AGENTS.md', sha256: 'new' }],
-    })).toEqual([]);
-
-    expect(validateBundleVersionReuse({
-      ...previous,
-      contractHash: 'old-contract',
-    }, {
-      ...previous,
-      contractHash: 'new-contract',
-    })).toEqual(['Managed documentation bytes changed without changing bundleVersion 2.0.0']);
-  });
-
-  it('compares bundle versions to a real base revision even after changed bytes are committed', async () => {
-    const {
-      readManifestAtRevision,
-      resolveBundleBaseRevision,
-      validateBundleVersionAgainstBase,
-    } = await loadGenerator();
-    const gitRoot = await mkdtemp(join(tmpdir(), 'fg-docs-version-git-'));
-    const manifestPath = join(gitRoot, 'apps/funnel-template/.funnelsgrove-docs.json');
-    const oldManifest = {
-      schemaVersion: 1,
-      bundleVersion: '2.0.0',
-      stepContractVersion: 2,
-      contractHash: 'a'.repeat(64),
-      managedFiles: [{ path: 'AGENTS.md', sha256: 'b'.repeat(64) }],
-    };
-    const changedManifest = {
-      ...oldManifest,
-      managedFiles: [{ path: 'AGENTS.md', sha256: 'c'.repeat(64) }],
-    };
-
-    try {
-      await execFile('git', ['init', '--quiet'], { cwd: gitRoot });
-      await execFile('git', ['config', 'user.name', 'Funnel Docs Test'], { cwd: gitRoot });
-      await execFile('git', ['config', 'user.email', 'docs-test@example.invalid'], { cwd: gitRoot });
-      await writeFile(join(gitRoot, 'README.md'), 'first\n');
-      await execFile('git', ['add', '.'], { cwd: gitRoot });
-      await execFile('git', ['commit', '--quiet', '-m', 'initial'], { cwd: gitRoot });
-      const { stdout: introductionBaseOutput } = await execFile('git', ['rev-parse', 'HEAD'], { cwd: gitRoot });
-      const introductionBase = introductionBaseOutput.trim();
-
-      await expect(readManifestAtRevision({ cwd: gitRoot, revision: introductionBase }))
-        .resolves.toBeNull();
-      await expect(validateBundleVersionAgainstBase(oldManifest, {
-        cwd: gitRoot,
-        baseRevision: introductionBase,
-        env: {},
-      })).resolves.toEqual([]);
-
-      await mkdir(dirname(manifestPath), { recursive: true });
-      await writeFile(manifestPath, `${JSON.stringify(oldManifest, null, 2)}\n`);
-      await execFile('git', ['add', '.'], { cwd: gitRoot });
-      await execFile('git', ['commit', '--quiet', '-m', 'introduce docs'], { cwd: gitRoot });
-      const { stdout: oldRevisionOutput } = await execFile('git', ['rev-parse', 'HEAD'], { cwd: gitRoot });
-      const oldRevision = oldRevisionOutput.trim();
-
-      const compactOldManifest = `${JSON.stringify(oldManifest)}\n`;
-      await writeFile(manifestPath, compactOldManifest);
-      await expect(validateBundleVersionAgainstBase(oldManifest, {
-        cwd: gitRoot,
-        currentManifestBytes: compactOldManifest,
-        env: {},
-      })).resolves.toEqual([
-        'Managed documentation bytes changed without changing bundleVersion 2.0.0',
-      ]);
-
-      await writeFile(manifestPath, `${JSON.stringify(changedManifest, null, 2)}\n`);
-      await execFile('git', ['add', '.'], { cwd: gitRoot });
-      await execFile('git', ['commit', '--quiet', '-m', 'change docs without bump'], { cwd: gitRoot });
-
-      await expect(resolveBundleBaseRevision({
-        cwd: gitRoot,
-        currentManifest: changedManifest,
-        env: { FUNNEL_DOCS_BASE_REF: oldRevision },
-      })).resolves.toBe(oldRevision);
-      await expect(resolveBundleBaseRevision({
-        cwd: gitRoot,
-        currentManifest: changedManifest,
-        env: {},
-      })).resolves.toBe(oldRevision);
-      await expect(validateBundleVersionAgainstBase(changedManifest, {
-        cwd: gitRoot,
-        env: {},
-      })).resolves.toEqual([
-        'Managed documentation bytes changed without changing bundleVersion 2.0.0',
-      ]);
-
-      await writeFile(join(gitRoot, 'README.md'), 'unrelated follow-up\n');
-      await execFile('git', ['add', '.'], { cwd: gitRoot });
-      await execFile('git', ['commit', '--quiet', '-m', 'unrelated follow-up'], { cwd: gitRoot });
-      await expect(resolveBundleBaseRevision({
-        cwd: gitRoot,
-        currentManifest: changedManifest,
-        env: {},
-      })).resolves.toBe(oldRevision);
-      await expect(validateBundleVersionAgainstBase(changedManifest, {
-        cwd: gitRoot,
-        env: {},
-      })).resolves.toEqual([
-        'Managed documentation bytes changed without changing bundleVersion 2.0.0',
-      ]);
-
-      await expect(validateBundleVersionAgainstBase({
-        ...changedManifest,
-        bundleVersion: '2.0.1',
-      }, {
-        cwd: gitRoot,
-        baseRevision: oldRevision,
-        env: {},
-      })).resolves.toEqual([]);
-      await expect(validateBundleVersionAgainstBase(oldManifest, {
-        cwd: gitRoot,
-        baseRevision: oldRevision,
-        currentManifestBytes: `${JSON.stringify(oldManifest)}\n`,
-        env: {},
-      })).resolves.toEqual([
-        'Managed documentation bytes changed without changing bundleVersion 2.0.0',
-      ]);
-
-      await expect(validateBundleVersionAgainstBase(changedManifest, {
-        cwd: gitRoot,
-        baseRevision: 'missing-base-ref',
-        env: {},
-      })).rejects.toThrow(/missing-base-ref/);
-
-      await writeFile(manifestPath, '{ corrupt json\n');
-      await execFile('git', ['add', '.'], { cwd: gitRoot });
-      await execFile('git', ['commit', '--quiet', '-m', 'corrupt manifest'], { cwd: gitRoot });
-      const { stdout: corruptRevisionOutput } = await execFile('git', ['rev-parse', 'HEAD'], { cwd: gitRoot });
-      await expect(readManifestAtRevision({
-        cwd: gitRoot,
-        revision: corruptRevisionOutput.trim(),
-      })).rejects.toThrow(/invalid JSON/i);
-    } finally {
-      await rm(gitRoot, { recursive: true, force: true });
-    }
-  });
-
-  it('keeps legacy template documentation as non-normative compatibility links', async () => {
-    const links = new Map([
-      ['docs/AGENT_FUNNEL_IMPLEMENTATION_SPEC.md', 'funnelsgrove/START-HERE.md'],
-      ['docs/ARCHITECTURE.md', 'funnelsgrove/contracts/step-metadata.md'],
-      ['docs/FLOW_CONFIG_AND_ROUTING.md', 'funnelsgrove/contracts/flow-routing.md'],
-      ['docs/PAYWALL_AND_PAYMENTS.md', 'funnelsgrove/contracts/payments.md'],
-      ['docs/README.md', 'funnelsgrove/START-HERE.md'],
-      ['docs/references/funnel-sdk-user-answers.md', '../funnelsgrove/contracts/content-answers.md'],
-    ]);
-
-    for (const [path, target] of links) {
-      const content = await readFile(join(templateRoot, path), 'utf8');
-      expect(content).toContain(target);
-      expect(content).toContain('Compatibility');
-      expect(content).not.toContain('| Step type |');
-    }
-  });
-
-  it('keeps all managed paths inside the template and reports them repo-relatively', async () => {
-    const { buildBundle } = await loadGenerator();
-    const bundle = await buildBundle();
-    for (const path of bundle.files.keys()) {
-      const absolutePath = join(templateRoot, path);
-      expect(relative(templateRoot, absolutePath)).not.toMatch(/^\.\./);
-    }
-  });
-});