@pixel-point/toolcraft 0.0.16 → 0.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixel-point/toolcraft",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "license": "SEE LICENSE IN LICENSE.md",
   "type": "module",
   "bin": {

package/src/generate-performance-iteration-execution.test.mjs

@@ -99,7 +99,7 @@ test("generated standalone app preserves authority-bound performance iteration l
   }
   const output = `${stdout}\n${stderr}`;
   assert.doesNotMatch(output, /ERR_MODULE_NOT_FOUND/u);
-  assert.match(output, /^# tests 9$/mu);
-  assert.match(output, /^# pass 9$/mu);
+  assert.match(output, /^# tests 11$/mu);
+  assert.match(output, /^# pass 11$/mu);
   assert.match(output, /^# fail 0$/mu);
 });

package/src/generate-test-demand-only-lifecycle.mjs

@@ -31,10 +31,20 @@ const materialBrowserTestNames = Object.freeze([
   "browser: frosting color changes material output",
   "browser: gloss changes material output",
   "browser: layer mode changes material output",
-  "browser: material appearance reaches exported pixels",
+  "browser: material appearance reaches decoded exported pixels",
   "browser: sprinkle color changes material output",
   "browser: sprinkles visibility changes material output",
 ]);
+const materialDeliveryBrowserTestNames = Object.freeze([
+  "browser: ambient speed changes product output",
+  ...materialBrowserTestNames,
+  "browser: timeline playback drives product output",
+]);
+const materialDeliveryAcceptanceIds = Object.freeze([
+  "animation.speed",
+  ...materialAcceptanceIds,
+  "runtime.timeline",
+]);
 const materialProductTestFiles = Object.freeze([
   "src/app/acceptance/validation-pipeline.test.ts",
   "src/app/app-acceptance.base-coverage.test.ts",
@@ -44,6 +54,7 @@ const materialProductTestFiles = Object.freeze([
   "src/app/app-automated-runtime-evidence.test.ts",
   "src/app/app-performance.fixture-helper.test.ts",
   "src/app/app-performance.gates.test.ts",
+  "src/app/app-performance.lifecycle.test.ts",
   "src/app/app-schema.test.ts",
   "src/app/material-output.test.tsx",
 ]);
@@ -294,8 +305,8 @@ export async function assertGeneratedFreshDemandOnlyLifecycle({
     browserEnv,
     checkpointPath,
     execFileAsync,
-    expectedAcceptanceIds: materialAcceptanceIds,
-    expectedBrowserTestNames: materialBrowserTestNames,
+    expectedAcceptanceIds: materialDeliveryAcceptanceIds,
+    expectedBrowserTestNames: materialDeliveryBrowserTestNames,
     expectedChangedFiles: generatedProductMaterialIterationFixturePaths,
     expectedProductTestFiles: materialProductTestFiles,
     targetDir,

package/src/generate-test-dependency-sandbox.mjs

@@ -115,15 +115,13 @@ function createGeneratedCommandEnvironment(packageManager, overrides = {}) {
   return childEnv;
 }
 
-export async function runGeneratedCommand(
+async function executeGeneratedPackageManager(
   execFileAsync,
   targetDir,
-  args,
+  packageManager,
+  packageManagerArgs,
   { env = {} } = {},
 ) {
-  const { packageManager } = await readGeneratedPackageManager(targetDir);
-  const packageManagerArgs =
-    packageManager === "npm" ? ["run", ...args] : args;
   try {
     return await execFileAsync(packageManager, packageManagerArgs, {
       cwd: targetDir,
@@ -143,6 +141,45 @@ export async function runGeneratedCommand(
   }
 }
 
+export async function runGeneratedCommand(
+  execFileAsync,
+  targetDir,
+  args,
+  options,
+) {
+  const { packageManager } = await readGeneratedPackageManager(targetDir);
+  const packageManagerArgs =
+    packageManager === "npm" ? ["run", ...args] : args;
+  return executeGeneratedPackageManager(
+    execFileAsync,
+    targetDir,
+    packageManager,
+    packageManagerArgs,
+    options,
+  );
+}
+
+export async function runGeneratedExecutable(
+  execFileAsync,
+  targetDir,
+  executableName,
+  args,
+  options,
+) {
+  const { packageManager } = await readGeneratedPackageManager(targetDir);
+  const packageManagerArgs =
+    packageManager === "npm"
+      ? ["exec", "--", executableName, ...args]
+      : ["exec", executableName, ...args];
+  return executeGeneratedPackageManager(
+    execFileAsync,
+    targetDir,
+    packageManager,
+    packageManagerArgs,
+    options,
+  );
+}
+
 export function runGeneratedScript(
   execFileAsync,
   targetDir,

package/src/generate-test-doc-assertions.mjs

@@ -2,6 +2,21 @@ import assert from "node:assert/strict";
 import fs from "node:fs/promises";
 import path from "node:path";
 
+import {
+  assertGeneratedExportIntentDocsDoNotInferVideo,
+  collectGeneratedAgentFacingDocs,
+  getMissingGeneratedPerformanceLifecycleMarkers,
+  getStaleAgentPerformanceWorkflowFailures,
+} from "./generate-test-doc-policy-assertions.mjs";
+
+export {
+  assertGeneratedExportIntentDocsDoNotInferVideo,
+  collectGeneratedAgentFacingDocs,
+  getMissingGeneratedPerformanceLifecycleMarkers,
+  getStaleAgentPerformanceWorkflowFailures,
+  staleAnimationDerivedVideoPattern,
+} from "./generate-test-doc-policy-assertions.mjs";
+
 const generatedDocPaths = [
   "README.md",
   "workflow.md",
@@ -23,53 +38,6 @@ const generatedDocPaths = [
   "core/reference-study.md",
 ];
 
-const staleAgentPerformanceWorkflowPattern =
-  /app-performance-impact|explicit-performance-work|test:browser:perf|verify:(?:final|quick|ui)|verify:perf:(?:playwright|record-iteration|refresh)|--reason=performance-iteration|--performance-test/iu;
-
-async function collectMarkdownPaths(rootDir, relativeDir = "") {
-  const currentDir = path.join(rootDir, relativeDir);
-  const entries = await fs.readdir(currentDir, { withFileTypes: true });
-  const markdownPaths = [];
-
-  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
-    const relativePath = path.join(relativeDir, entry.name);
-    if (entry.isDirectory()) {
-      markdownPaths.push(...(await collectMarkdownPaths(rootDir, relativePath)));
-    } else if (entry.isFile() && entry.name.endsWith(".md")) {
-      markdownPaths.push(relativePath);
-    }
-  }
-
-  return markdownPaths;
-}
-
-export async function collectGeneratedAgentFacingDocs(targetDir) {
-  const docsRoot = path.join(targetDir, "docs/toolcraft");
-  const docPaths = await collectMarkdownPaths(docsRoot);
-  const docs = await Promise.all(
-    docPaths.map(async (docPath) => ({
-      docPath: path.posix.join("docs/toolcraft", docPath.split(path.sep).join("/")),
-      source: await fs.readFile(path.join(docsRoot, docPath), "utf8"),
-    })),
-  );
-
-  return [
-    {
-      docPath: "AGENTS.md",
-      source: await fs.readFile(path.join(targetDir, "AGENTS.md"), "utf8"),
-    },
-    ...docs,
-  ];
-}
-
-export function getStaleAgentPerformanceWorkflowFailures(sources) {
-  return sources.flatMap(({ docPath, source }) =>
-    staleAgentPerformanceWorkflowPattern.test(source)
-      ? [`${docPath} contains removed performance workflow guidance`]
-      : [],
-  );
-}
-
 export async function assertGeneratedDocs(targetDir) {
   await Promise.all(
     generatedDocPaths.map((docPath) => fs.stat(path.join(targetDir, "docs/toolcraft", docPath))),
@@ -79,15 +47,21 @@ export async function assertGeneratedDocs(targetDir) {
   const licenseSource = await fs.readFile(path.join(targetDir, "LICENSE.md"), "utf8");
   const noticeSource = await fs.readFile(path.join(targetDir, "NOTICE.md"), "utf8");
   const localDocPaths = generatedDocPaths.filter((docPath) => docPath !== "README.md");
+  const generatedAgentFacingDocs = await collectGeneratedAgentFacingDocs(targetDir);
   const staleWorkflowFailures = getStaleAgentPerformanceWorkflowFailures(
-    await collectGeneratedAgentFacingDocs(targetDir),
+    generatedAgentFacingDocs,
   );
 
+  assert.match(noticeSource, /Mediabunny/u);
+  assert.match(noticeSource, /MPL-2\.0/u);
+  assert.match(noticeSource, /https:\/\/github\.com\/Vanilagy\/mediabunny/u);
+
   assert.deepEqual(
     staleWorkflowFailures,
     [],
     `Generated agent-facing docs contain stale performance workflow guidance:\n${staleWorkflowFailures.join("\n")}`,
   );
+  assertGeneratedExportIntentDocsDoNotInferVideo(generatedAgentFacingDocs);
 
   assert.match(agentsSource, /Quick Entry Contract/);
   assert.match(agentsSource, /Local Reference Docs/);
@@ -139,6 +113,7 @@ export async function assertGeneratedDocs(targetDir) {
   assert.match(agentsSource, /defineToolcraft/);
   assert.match(agentsSource, /ToolcraftApp/);
   assert.match(agentsSource, /canvasContent/);
+  assert.match(agentsSource, /exportRenderer/);
   assert.match(agentsSource, /renderDefaultCanvasMedia=\{false\}/);
   assert.match(agentsSource, /onPanelAction/);
   assert.match(agentsSource, /MIT License/);
@@ -213,18 +188,63 @@ export async function assertGeneratedDocs(targetDir) {
   assert.match(coreRuntimeBoundarySource, /immutable signed copy of the shared runtime/);
   assert.match(coreRuntimeBoundarySource, /copied runtime tree or its signed integrity manifest is missing/);
   assert.match(coreRuntimeBoundarySource, /modelPresentation/);
+  assert.match(coreRuntimeBoundarySource, /exportRenderer/);
+  assert.match(coreRuntimeBoundarySource, /runtime owns typed image\/video actions end to end/i);
   assert.match(coreRuntimeBoundarySource, /does not suppress runtime model layers/);
   assert.match(componentRulesSource, /Do not show Layers for a single-layer app/);
   assert.match(coreTimelineSource, /Any app with `Export Video` must enable the top Toolcraft timeline/);
-  assert.match(coreSetupExportSource, /Every product exposes `Export PNG`/);
+  assert.match(coreSetupExportSource, /productReadiness\.exportIntent/);
+  assert.match(
+    coreSetupExportSource,
+    /image[^\n]*`toolcraft-default`[^\n]*`user-requested`[^\n]*`user-removed`/i,
+  );
+  assert.match(
+    coreSetupExportSource,
+    /video[^\n]*`not-requested`[^\n]*`user-requested`/i,
+  );
+  assert.match(
+    coreSetupExportSource,
+    /image[^\n]*`user-requested`[^\n]*non-empty[^\n]*evidence/i,
+  );
+  assert.match(
+    coreSetupExportSource,
+    /image[^\n]*`user-removed`[^\n]*non-empty[^\n]*evidence/i,
+  );
+  assert.match(
+    coreSetupExportSource,
+    /video[^\n]*`user-requested`[^\n]*non-empty[^\n]*evidence/i,
+  );
+  for (const decisionStep of [
+    "Start every product with image export.",
+    "Add video export only when the user explicitly requests video delivery.",
+    "Do not infer video from animation, playback, keyframes, or timeline.",
+    "Keep image with video unless the user explicitly requests removal.",
+    "Record in `productReadiness.exportIntent`.",
+  ]) {
+    assert.equal(
+      coreSetupExportSource.split(decisionStep).length - 1,
+      1,
+      `Canonical export-intent step must appear exactly once: ${decisionStep}`,
+    );
+  }
   assert.match(
     coreSetupExportSource,
-    /Products whose requested delivery includes animation also expose `Export Video`/,
+    /Clipboard copy may be an additional product action, but it never changes or substitutes for the recorded artifact intent/,
   );
-  assert.match(coreSetupExportSource, /Clipboard copy is optional and never replaces export/);
   assert.match(coreSetupExportSource, /renderScaleCoverage/);
   assert.match(coreSetupExportSource, /selected-backing-pixels/);
   assert.match(coreSetupExportSource, /canvas-render-scale-backing/);
+  assert.match(coreSetupExportSource, /Mediabunny/);
+  assert.match(coreSetupExportSource, /fixed 30 FPS offline schedule/);
+  assert.match(coreSetupExportSource, /Product code must not instantiate `MediaRecorder` or `VideoEncoder`/);
+  assert.doesNotMatch(
+    coreSetupExportSource,
+    /createToolcraftPngExportCanvas|renderRuntimeSceneToCanvas|renderModelsToCanvas/,
+  );
+  assert.doesNotMatch(
+    coreMediaUploadSource,
+    /createToolcraftPngExportCanvas|renderRuntimeSceneToCanvas|renderModelsToCanvas/,
+  );
   assert.match(
     coreSetupExportSource,
     /interaction[\s\S]*steady[\s\S]*playback[\s\S]*timeline/i,
@@ -236,6 +256,10 @@ export async function assertGeneratedDocs(targetDir) {
   );
   assert.match(assemblyDocsSource, /@\/toolcraft\/runtime/);
   assert.match(assemblyDocsSource, /ToolcraftAppComposition/);
+  assert.match(
+    assemblyDocsSource,
+    /Every product declaration requires `productReadiness\.exportIntent`/,
+  );
   assert.match(assemblyDocsSource, /protected route/);
   assert.match(assemblyDocsSource, /transferMode: "reference-runtime-clone"/);
   assert.match(assemblyDocsSource, /`canvasContent` must not contain app UI/);
@@ -249,6 +273,7 @@ export async function assertGeneratedDocs(targetDir) {
   assert.match(acceptanceDocsSource, /automatedTestName/);
   assert.match(acceptanceDocsSource, /browserTestName/);
   assert.match(acceptanceDocsSource, /app-acceptance-data\.ts/);
+  assert.match(acceptanceDocsSource, /productReadiness\.exportIntent/);
   assert.match(
     acceptanceDocsSource,
     /Contract docs are signed except product-owned `agent-worklog\.md` and optional `workflow-observation\.md`; only the observation stays outside `sourceHash`/,
@@ -269,6 +294,8 @@ export async function assertGeneratedDocs(targetDir) {
     acceptanceDocsSource,
     /export-content proof is distinct from export mechanics/i,
   );
+  assert.match(acceptanceDocsSource, /actual encoded packet metadata/i);
+  assert.match(acceptanceDocsSource, /distinct decoded frame hashes/i);
   assert.match(
     acceptanceDocsSource,
     /Each browser file owns one acceptance domain/i,
@@ -312,24 +339,14 @@ export async function assertGeneratedDocs(targetDir) {
     path.join(targetDir, "docs/toolcraft/core/performance.md"),
     "utf8",
   );
-  const performanceLifecycleMarkers = [
-    "<!-- toolcraft-performance-lifecycle: first-delivery=functional; later-delivery=functional-targeted; complaint=one-authority-targeted-performance-iteration; full-audit=explicit-only -->",
-    "<!-- toolcraft-performance-iteration: authority=exact-request-evidence+canonical-path-ids; fixture=reachable-development; after-pass=return-app-to-user+stop -->",
-    "<!-- toolcraft-performance-full-authority: automatic=forbidden; recommendation=two-compatible-iterations-or-broad-unlocalizable-problem; command=pnpm verify:perf; authority=explicit-user-request-or-accepted-offer -->",
-  ];
-  for (const [docPath, source] of [
-    ["workflow.md", workflowDocsSource],
-    ["performance.md", performanceDocsSource],
-    ["core/performance.md", corePerformanceDocsSource],
-  ]) {
-    for (const marker of performanceLifecycleMarkers) {
-      assert.equal(
-        source.includes(marker),
-        true,
-        `docs/toolcraft/${docPath} must include canonical marker: ${marker}`,
-      );
-    }
-  }
+  assert.deepEqual(
+    getMissingGeneratedPerformanceLifecycleMarkers([
+      { docPath: "workflow.md", source: workflowDocsSource },
+      { docPath: "performance.md", source: performanceDocsSource },
+      { docPath: "core/performance.md", source: corePerformanceDocsSource },
+    ]),
+    [],
+  );
   assert.match(rendererDocsSource, /rendererTechnique/);
   assert.match(rendererDocsSource, /sourceRepresentation/);
   assert.match(rendererDocsSource, /whyNotAlternativeStrategies/);
@@ -339,6 +356,7 @@ export async function assertGeneratedDocs(targetDir) {
   assert.match(rendererDocsSource, /canonical paths/i);
   assert.match(rendererDocsSource, /combined fixtures/i);
   assert.match(rendererDocsSource, /modelPresentation/);
+  assert.match(rendererDocsSource, /ToolcraftAppComposition\.exportRenderer/);
   assert.match(rendererDocsSource, /useToolcraftModelPresentationConsumer/);
   assert.match(rendererDocsSource, /acquirePresentation/);
   assert.match(rendererDocsSource, /lease\.release/);
@@ -367,12 +385,34 @@ export async function assertGeneratedDocs(targetDir) {
     corePerformanceDocsSource,
     /functional failure[\s\S]*without measured performance/i,
   );
+  assert.match(corePerformanceDocsSource, /exact 30 FPS packet cadence[\s\S]*functional correctness/i);
+  assert.match(performanceDocsSource, /exact 30 FPS packet cadence[\s\S]*functional proof/i);
   assert.match(performanceDocsSource, /coherent (?:user-visible )?delivery batch/i);
   assert.match(performanceDocsSource, /verify:delivery/);
   assert.match(performanceDocsSource, /immediately previous successful delivery/i);
   assert.match(performanceDocsSource, /performance-iteration/);
   assert.match(performanceDocsSource, /renderScaleCoverage/);
   assert.match(performanceDocsSource, /canvas-render-scale-backing/);
+  assert.match(
+    performanceDocsSource,
+    /localized complaint[^\n]*without (?:a |asking the user)/iu,
+  );
+  assert.match(
+    performanceDocsSource,
+    /ambiguous complaint[\s\S]*one user-facing/iu,
+  );
+  assert.match(
+    performanceDocsSource,
+    /targeted diagnosis[\s\S]*complete (?:performance )?review/iu,
+  );
+  assert.match(
+    performanceDocsSource,
+    /every measured path[\s\S]*devicePixelRatio × 2/iu,
+  );
+  assert.match(
+    coreSetupExportSource,
+    /product code may customize only the slider step/iu,
+  );
   assert.match(performanceDocsSource, /Use bare `npm run verify:delivery` once/i);
   assert.match(
     workflowDocsSource,

package/src/generate-test-doc-assertions.test.mjs

@@ -5,10 +5,54 @@ import path from "node:path";
 import test from "node:test";
 
 import {
+  assertGeneratedExportIntentDocsDoNotInferVideo,
   collectGeneratedAgentFacingDocs,
+  getMissingGeneratedPerformanceLifecycleMarkers,
   getStaleAgentPerformanceWorkflowFailures,
 } from "./generate-test-doc-assertions.mjs";
 
+test("rejects animation-derived video rules without rejecting explicit authority", () => {
+  for (const source of [
+    [
+      "Products whose requested delivery includes",
+      "animation also expose",
+      "`Export Video`.",
+    ].join(" "),
+    ["Animated apps automatically show", "Export Video."].join(" "),
+    ["Animation also", "requires", "Export Video."].join(" "),
+    "Timeline playback enables Export Video.",
+    "Animated apps automatically expose video export.",
+    "Timeline playback enables video export.",
+    "Animation implies video delivery.",
+  ]) {
+    assert.throws(
+      () =>
+        assertGeneratedExportIntentDocsDoNotInferVideo([
+          { docPath: "docs/toolcraft/stale.md", source },
+        ]),
+      /docs\/toolcraft\/stale\.md contains animation-derived video export guidance/,
+    );
+  }
+
+  assert.doesNotThrow(() =>
+    assertGeneratedExportIntentDocsDoNotInferVideo([
+      {
+        docPath: "docs/toolcraft/allowed.md",
+        source: [
+          "Do not infer video from animation, playback, keyframes, or timeline.",
+          "Animation, playback, keyframes, and timeline presence never add Export Video.",
+          "Animated apps do not automatically expose video export.",
+          "Timeline playback never enables video export.",
+          "Animation does not imply video delivery.",
+          "An animated app includes Export Video because the user explicitly requested video delivery.",
+          "An animated app exposes video export because the user explicitly requested video delivery.",
+          "Any app with Export Video must enable the top Toolcraft timeline.",
+        ].join("\n"),
+      },
+    ]),
+  );
+});
+
 test("scans every generated agent-facing Markdown source independently", async (t) => {
   const targetDir = await fs.mkdtemp(path.join(os.tmpdir(), "toolcraft-doc-scan-"));
   t.after(() => fs.rm(targetDir, { force: true, recursive: true }));
@@ -41,3 +85,24 @@ test("scans every generated agent-facing Markdown source independently", async (
     "docs/toolcraft/core/performance.md contains removed performance workflow guidance",
   ]);
 });
+
+test("requires adaptive routing in every generated performance lifecycle document", () => {
+  const routingMarker =
+    "<!-- toolcraft-performance-routing: localized=agent-targeted; ambiguous=one-user-facing-choice; broad=offer-targeted-or-full; full=explicit-only -->";
+  const existingMarkers = [
+    "<!-- toolcraft-performance-lifecycle: first-delivery=functional; later-delivery=functional-targeted; complaint=one-authority-targeted-performance-iteration; full-audit=explicit-only -->",
+    "<!-- toolcraft-performance-iteration: authority=exact-request-evidence+canonical-path-ids; fixture=reachable-development; after-pass=return-app-to-user+stop -->",
+    "<!-- toolcraft-performance-full-authority: automatic=forbidden; recommendation=two-compatible-iterations-or-broad-unlocalizable-problem; command=pnpm verify:perf; authority=explicit-user-request-or-accepted-offer -->",
+  ].join("\n");
+
+  assert.deepEqual(
+    getMissingGeneratedPerformanceLifecycleMarkers([
+      { docPath: "workflow.md", source: `${existingMarkers}\n${routingMarker}` },
+      { docPath: "performance.md", source: existingMarkers },
+      { docPath: "core/performance.md", source: `${existingMarkers}\n${routingMarker}` },
+    ]),
+    [
+      `docs/toolcraft/performance.md must include canonical marker: ${routingMarker}`,
+    ],
+  );
+});

package/src/generate-test-doc-policy-assertions.mjs

@@ -0,0 +1,92 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const staleAgentPerformanceWorkflowPattern =
+  /app-performance-impact|explicit-performance-work|test:browser:perf|verify:(?:final|quick|ui)|verify:perf:(?:playwright|record-iteration|refresh)|--reason=performance-iteration|--performance-test/iu;
+
+const exportIntentSentencePatternSource = String.raw`[^\n.!?]`;
+const videoArtifactTargetPatternSource = String.raw`(?:Export Video|video\s+(?:export|delivery))`;
+const explicitVideoAuthorityPatternSource = String.raw`(?:explicit(?:ly)?\s+(?:(?:user[- ]?)?request(?:ed|s)?\s+)?${videoArtifactTargetPatternSource}|user\s+explicitly\s+request(?:ed|s)?\s+${videoArtifactTargetPatternSource}|user[- ]request(?:ed|s)?\s+${videoArtifactTargetPatternSource})`;
+const animationInferenceVerbPatternSource = String.raw`(?:exposes?|includes?|shows?|adds?|enables?|implies?|has|needs?|requires?|produces?|proves?)`;
+const staleAnimationInferencePatternSource = [
+  String.raw`products?\s+whose\s+requested\s+delivery\s+includes\s+animation`,
+  String.raw`animated\s+apps?\b(?!${exportIntentSentencePatternSource}{0,100}\b(?:do(?:es)?\s+not|never)\b)${exportIntentSentencePatternSource}{0,100}\b${animationInferenceVerbPatternSource}\b${exportIntentSentencePatternSource}{0,60}\b${videoArtifactTargetPatternSource}\b`,
+  String.raw`(?:animation|playback|keyframes?|timeline(?:\s+playback)?)\b\s+(?:also\s+)?${animationInferenceVerbPatternSource}\b${exportIntentSentencePatternSource}{0,60}\b${videoArtifactTargetPatternSource}\b`,
+].join("|");
+
+export const staleAnimationDerivedVideoPattern = new RegExp(
+  String.raw`(?:^|[\n.!?]\s*)(?!${exportIntentSentencePatternSource}{0,240}\b${explicitVideoAuthorityPatternSource}\b)${exportIntentSentencePatternSource}{0,240}(?:${staleAnimationInferencePatternSource})`,
+  "iu",
+);
+
+const generatedPerformanceLifecycleMarkers = [
+  "<!-- toolcraft-performance-lifecycle: first-delivery=functional; later-delivery=functional-targeted; complaint=one-authority-targeted-performance-iteration; full-audit=explicit-only -->",
+  "<!-- toolcraft-performance-iteration: authority=exact-request-evidence+canonical-path-ids; fixture=reachable-development; after-pass=return-app-to-user+stop -->",
+  "<!-- toolcraft-performance-full-authority: automatic=forbidden; recommendation=two-compatible-iterations-or-broad-unlocalizable-problem; command=pnpm verify:perf; authority=explicit-user-request-or-accepted-offer -->",
+  "<!-- toolcraft-performance-routing: localized=agent-targeted; ambiguous=one-user-facing-choice; broad=offer-targeted-or-full; full=explicit-only -->",
+];
+
+export function getMissingGeneratedPerformanceLifecycleMarkers(sources) {
+  return sources.flatMap(({ docPath, source }) =>
+    generatedPerformanceLifecycleMarkers.flatMap((marker) =>
+      source.includes(marker)
+        ? []
+        : [`docs/toolcraft/${docPath} must include canonical marker: ${marker}`],
+    ),
+  );
+}
+
+async function collectMarkdownPaths(rootDir, relativeDir = "") {
+  const currentDir = path.join(rootDir, relativeDir);
+  const entries = await fs.readdir(currentDir, { withFileTypes: true });
+  const markdownPaths = [];
+
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    const relativePath = path.join(relativeDir, entry.name);
+    if (entry.isDirectory()) {
+      markdownPaths.push(...(await collectMarkdownPaths(rootDir, relativePath)));
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      markdownPaths.push(relativePath);
+    }
+  }
+
+  return markdownPaths;
+}
+
+export async function collectGeneratedAgentFacingDocs(targetDir) {
+  const docsRoot = path.join(targetDir, "docs/toolcraft");
+  const docPaths = await collectMarkdownPaths(docsRoot);
+  const docs = await Promise.all(
+    docPaths.map(async (docPath) => ({
+      docPath: path.posix.join("docs/toolcraft", docPath.split(path.sep).join("/")),
+      source: await fs.readFile(path.join(docsRoot, docPath), "utf8"),
+    })),
+  );
+
+  return [
+    {
+      docPath: "AGENTS.md",
+      source: await fs.readFile(path.join(targetDir, "AGENTS.md"), "utf8"),
+    },
+    ...docs,
+  ];
+}
+
+export function getStaleAgentPerformanceWorkflowFailures(sources) {
+  return sources.flatMap(({ docPath, source }) =>
+    staleAgentPerformanceWorkflowPattern.test(source)
+      ? [`${docPath} contains removed performance workflow guidance`]
+      : [],
+  );
+}
+
+export function assertGeneratedExportIntentDocsDoNotInferVideo(sources) {
+  for (const { docPath, source } of sources) {
+    assert.doesNotMatch(
+      source,
+      staleAnimationDerivedVideoPattern,
+      `${docPath} contains animation-derived video export guidance`,
+    );
+  }
+}