@pixel-point/toolcraft 0.0.15 → 0.0.16

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

@@ -23,6 +23,53 @@ 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))),
@@ -32,6 +79,15 @@ 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 staleWorkflowFailures = getStaleAgentPerformanceWorkflowFailures(
+    await collectGeneratedAgentFacingDocs(targetDir),
+  );
+
+  assert.deepEqual(
+    staleWorkflowFailures,
+    [],
+    `Generated agent-facing docs contain stale performance workflow guidance:\n${staleWorkflowFailures.join("\n")}`,
+  );
 
   assert.match(agentsSource, /Quick Entry Contract/);
   assert.match(agentsSource, /Local Reference Docs/);
@@ -43,19 +99,35 @@ export async function assertGeneratedDocs(targetDir) {
   assert.match(agentsSource, /src\/app\/app-performance\.ts/);
   assert.match(agentsSource, /Do not edit `src\/toolcraft`/);
   assert.match(agentsSource, /immutable signed copy of the shared Toolcraft runtime/);
+  assert.match(agentsSource, /persistence.*enabled locally by default/i);
+  assert.match(agentsSource, /storage: "none".*only opt-out/i);
+  assert.match(agentsSource, /never writes localStorage or IndexedDB directly/i);
   assert.match(agentsSource, /AI Workflow Skills And Local Fallback/);
   assert.match(agentsSource, /Verification Tier Classifier/);
   assert.match(agentsSource, /Verification tier: Tier N/);
-  assert.match(agentsSource, /npm run verify:quick/);
-  assert.match(agentsSource, /npm run verify:final/);
-  assert.match(agentsSource, /node scripts\/check-toolcraft-integrity\.mjs/);
-  assert.match(agentsSource, /do not rely only on a package script/i);
-  assert.match(agentsSource, /npm run ai:check/);
+  assert.match(agentsSource, /npm run verify:delivery/);
+  assert.match(agentsSource, /coherent user-visible delivery batch/i);
+  assert.match(
+    agentsSource,
+    /toolcraft-performance-lifecycle: first-delivery=functional; later-delivery=functional-targeted; complaint=one-authority-targeted-performance-iteration; full-audit=explicit-only/,
+  );
+  assert.match(agentsSource, /bare `npm run verify:delivery` derives the required proof/i);
+  assert.match(
+    agentsSource,
+    /only exact request authority[^\n]*measured targeted performance/i,
+  );
+  assert.doesNotMatch(
+    agentsSource,
+    /during development[^\n]*affected performance scenarios|targeted performance scenarios only for touched/i,
+  );
+  assert.match(agentsSource, /app-verification-impact\.json/);
+  assert.match(agentsSource, /does not depend only on a mutable package script/i);
+  assert.match(agentsSource, /pnpm ai:check/);
   assert.match(agentsSource, /use `brainstorming`/);
   assert.match(agentsSource, /use `writing-plans`/);
   assert.match(agentsSource, /use `systematic-debugging`/);
   assert.match(agentsSource, /browser` workflow/);
-  assert.match(agentsSource, /npm run test:browser/);
+  assert.match(agentsSource, /pnpm test:browser/);
   assert.match(agentsSource, /signed local `AGENTS\.md` and `docs\/toolcraft\/\*` files are the mandatory workflow authority/i);
   assert.match(agentsSource, /generated with `--no-skills`, continue through the equivalent signed local workflow/i);
   assert.match(agentsSource, /Do not silently ignore a missing workflow capability/);
@@ -116,17 +188,47 @@ export async function assertGeneratedDocs(targetDir) {
   assert.match(componentRulesSource, /Segmented Controls/);
   assert.match(coreLayoutSource, /Bad titles: `Controls`, `Settings`, `Options`, `Sliders`, `Inputs`, `Buttons`, `Color`, `Colors`/);
   assert.match(coreMediaUploadSource, /Use `fileDrop` for source material uploads/);
+  assert.match(coreMediaUploadSource, /bounded ZIP/);
+  assert.match(coreMediaUploadSource, /Blender-compatible fallback/);
+  assert.match(coreMediaUploadSource, /modelPresentation/);
+  assert.doesNotMatch(coreMediaUploadSource, /\bgeometry-only (?:3D )?model/iu);
+  for (const format of ["GLB", "glTF", "FBX", "OBJ", "STL", "PLY"]) {
+    assert.match(
+      coreMediaUploadSource,
+      new RegExp(`\\b${format}\\b`, "iu"),
+      `Media upload docs must advertise ${format}.`,
+    );
+  }
+  for (const lifecycle of ["clean", "repairable", "fixed", "unavailable"]) {
+    assert.match(
+      coreMediaUploadSource,
+      new RegExp(`\\b${lifecycle}\\b`, "u"),
+      `Media upload docs must define the ${lifecycle} model lifecycle.`,
+    );
+  }
   assert.match(coreControlSelectionSource, /Use `fileDrop` for source material uploads/);
   assert.match(coreRuntimeBoundarySource, /appSchema\.assembly/);
   assert.match(coreRuntimeBoundarySource, /app-composition\.tsx/);
   assert.match(coreRuntimeBoundarySource, /signed framework bootstrap/);
   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, /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, /Still products expose `Export PNG`/);
-  assert.match(coreSetupExportSource, /Animated products expose `Export Video` plus `Export PNG`/);
+  assert.match(coreSetupExportSource, /Every product exposes `Export PNG`/);
+  assert.match(
+    coreSetupExportSource,
+    /Products whose requested delivery includes animation also expose `Export Video`/,
+  );
   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,
+    /interaction[\s\S]*steady[\s\S]*playback[\s\S]*timeline/i,
+  );
 
   const assemblyDocsSource = await fs.readFile(
     path.join(targetDir, "docs/toolcraft/assembly-workflow.md"),
@@ -147,16 +249,190 @@ export async function assertGeneratedDocs(targetDir) {
   assert.match(acceptanceDocsSource, /automatedTestName/);
   assert.match(acceptanceDocsSource, /browserTestName/);
   assert.match(acceptanceDocsSource, /app-acceptance-data\.ts/);
-  assert.match(acceptanceDocsSource, /framework-owned and covered by the signed integrity manifest/);
+  assert.match(
+    acceptanceDocsSource,
+    /Contract docs are signed except product-owned `agent-worklog\.md` and optional `workflow-observation\.md`; only the observation stays outside `sourceHash`/,
+  );
   assert.match(acceptanceDocsSource, /Framework meta-tests are product-invariant/);
   assert.match(acceptanceDocsSource, /protected neutral contract fixtures/);
-  assert.match(acceptanceDocsSource, /do not edit supplied `app-performance\.\*` meta-tests/);
+  assert.match(acceptanceDocsSource, /do not edit supplied `app-performance\.\*` meta-tests/i);
+  assert.match(acceptanceDocsSource, /app-verification-impact\.json/);
+  assert.match(acceptanceDocsSource, /app-kernel-benchmarks\.ts/);
+  assert.match(acceptanceDocsSource, /renderScaleCoverage/);
+  assert.match(acceptanceDocsSource, /selected-backing-pixels/);
+  assert.match(acceptanceDocsSource, /canvas-render-scale-backing/);
+  assert.match(
+    acceptanceDocsSource,
+    /expectToolcraftCanvasRenderScaleEvidence/,
+  );
+  assert.match(
+    acceptanceDocsSource,
+    /export-content proof is distinct from export mechanics/i,
+  );
+  assert.match(
+    acceptanceDocsSource,
+    /Each browser file owns one acceptance domain/i,
+  );
+  assert.match(
+    acceptanceDocsSource,
+    /proof and test paths cannot own them/i,
+  );
+  for (const coverage of [
+    "package-extraction",
+    "deterministic-root-selection",
+    "appearance-preservation",
+    "fallback-appearance",
+    "presentation-consumer-readiness",
+    "pixel-output",
+  ]) {
+    assert.match(acceptanceDocsSource, new RegExp(`\\b${coverage}\\b`, "u"));
+  }
 
   const rendererDocsSource = await fs.readFile(
     path.join(targetDir, "docs/toolcraft/renderer-technique.md"),
     "utf8",
   );
+  const readmeDocsSource = await fs.readFile(
+    path.join(targetDir, "docs/toolcraft/README.md"),
+    "utf8",
+  );
+  const workflowDocsSource = await fs.readFile(
+    path.join(targetDir, "docs/toolcraft/workflow.md"),
+    "utf8",
+  );
+  const worklogDocsSource = await fs.readFile(
+    path.join(targetDir, "docs/toolcraft/agent-worklog.md"),
+    "utf8",
+  );
+  const performanceDocsSource = await fs.readFile(
+    path.join(targetDir, "docs/toolcraft/performance.md"),
+    "utf8",
+  );
+  const corePerformanceDocsSource = await fs.readFile(
+    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.match(rendererDocsSource, /rendererTechnique/);
   assert.match(rendererDocsSource, /sourceRepresentation/);
   assert.match(rendererDocsSource, /whyNotAlternativeStrategies/);
+  assert.match(rendererDocsSource, /reachable controls/i);
+  assert.match(rendererDocsSource, /workload dimensions/i);
+  assert.match(rendererDocsSource, /assessToolcraftRenderPlan/);
+  assert.match(rendererDocsSource, /canonical paths/i);
+  assert.match(rendererDocsSource, /combined fixtures/i);
+  assert.match(rendererDocsSource, /modelPresentation/);
+  assert.match(rendererDocsSource, /useToolcraftModelPresentationConsumer/);
+  assert.match(rendererDocsSource, /acquirePresentation/);
+  assert.match(rendererDocsSource, /lease\.release/);
+  assert.doesNotMatch(
+    rendererDocsSource,
+    /bitmap-media|halftone|per-pixel|max text length|max media size/i,
+  );
+  assert.match(corePerformanceDocsSource, /exact normalized development pressure `0\.8`/i);
+  assert.match(corePerformanceDocsSource, /otherwise development is unavailable/i);
+  assert.match(corePerformanceDocsSource, /workloadBoundary/);
+  assert.match(corePerformanceDocsSource, /maximum-workload boundar/i);
+  assert.match(corePerformanceDocsSource, /numerically downward/i);
+  assert.match(corePerformanceDocsSource, /exhaustive-discrete/i);
+  assert.match(performanceDocsSource, /match(?:es)? every option one-to-one/i);
+  assert.match(corePerformanceDocsSource, /toolcraftDiscreteCombinationBudget/);
+  assert.match(corePerformanceDocsSource, /toolcraftDiscreteDimensionBudget/);
+  assert.match(
+    corePerformanceDocsSource,
+    /bypasses search budgets because no (?:combination )?search runs/i,
+  );
+  assert.match(corePerformanceDocsSource, /planning error/i);
+  assert.match(corePerformanceDocsSource, /TOOLCRAFT_PERFORMANCE_VERIFICATION_LIFECYCLE/);
+  assert.match(corePerformanceDocsSource, /renderScaleCoverage/);
+  assert.match(corePerformanceDocsSource, /canvas-render-scale-backing/);
+  assert.match(
+    corePerformanceDocsSource,
+    /functional failure[\s\S]*without measured performance/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, /Use bare `npm run verify:delivery` once/i);
+  assert.match(
+    workflowDocsSource,
+    /immediate previous and current semantic functional proof models/i,
+  );
+  assert.match(
+    workflowDocsSource,
+    /unchanged `sourceHash` fast path does not collect the catalog, dependency graph, or functional proof model/i,
+  );
+  assert.match(
+    workflowDocsSource,
+    /do not rerun the aggregate, export, or performance matrix after every edit/i,
+  );
+  assert.match(
+    performanceDocsSource,
+    /ordinary changes and performance metadata cannot authorize measured performance/i,
+  );
+  assert.match(
+    performanceDocsSource,
+    /Demand-only performance lifecycle/i,
+  );
+  assert.doesNotMatch(performanceDocsSource, /verify:(?:quick|ui|final)/i);
+  assert.doesNotMatch(
+    corePerformanceDocsSource,
+    /browserCheckPolicy|loadProfile|smoothTargetRatio|stressFixture|workloadTargets/i,
+  );
+  assert.doesNotMatch(corePerformanceDocsSource, /without exceeding development pressure/i);
+  assert.doesNotMatch(corePerformanceDocsSource, /\breachableValues\b/);
+  for (const [docPath, source] of [
+    ["README.md", readmeDocsSource],
+    ["assembly-workflow.md", assemblyDocsSource],
+    ["acceptance-testing.md", acceptanceDocsSource],
+    ["renderer-technique.md", rendererDocsSource],
+    ["workflow.md", workflowDocsSource],
+    ["performance.md", performanceDocsSource],
+    ["core/performance.md", corePerformanceDocsSource],
+  ]) {
+    assert.doesNotMatch(
+      source,
+      /first stable[^\n]*(?:full checkpoint|full performance|performance baseline)/i,
+      `docs/toolcraft/${docPath} must not map first stable delivery to full performance`,
+    );
+    assert.doesNotMatch(
+      source,
+      /first[^\n]*working product[^\n]*(?:full checkpoint|full performance|performance baseline)/i,
+      `docs/toolcraft/${docPath} must not map first working delivery to full performance`,
+    );
+  }
+  assert.match(
+    worklogDocsSource,
+    /Performance intent:\s*performance-iteration[\s\S]*Performance request evidence:\s*"<verbatim exact Request quote>"[\s\S]*Performance paths:\s*\["performance-path:/i,
+  );
+  assert.match(
+    worklogDocsSource,
+    /One bare `npm run verify:delivery` will derive and run the protected proof/i,
+  );
+  assert.match(worklogDocsSource, /renderScaleCoverage/);
+  assert.doesNotMatch(
+    worklogDocsSource,
+    /--reason=|--performance-test|Files changed:|Run:|Skipped checks:|Receipt:/i,
+  );
+  assert.doesNotMatch(worklogDocsSource, /explicit-performance-work/);
 }

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

@@ -0,0 +1,43 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import {
+  collectGeneratedAgentFacingDocs,
+  getStaleAgentPerformanceWorkflowFailures,
+} from "./generate-test-doc-assertions.mjs";
+
+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 }));
+
+  await fs.mkdir(path.join(targetDir, "docs/toolcraft/core"), { recursive: true });
+  await Promise.all([
+    fs.writeFile(
+      path.join(targetDir, "AGENTS.md"),
+      "# Agent contract\nRun --reason=explicit-performance-work for a full matrix.\n",
+    ),
+    fs.writeFile(path.join(targetDir, "docs/toolcraft/workflow.md"), "# Workflow\n"),
+    fs.writeFile(
+      path.join(targetDir, "docs/toolcraft/core/performance.md"),
+      "Run pnpm verify:perf:refresh after a complaint.\n",
+    ),
+  ]);
+
+  const sources = await collectGeneratedAgentFacingDocs(targetDir);
+
+  assert.deepEqual(
+    sources.map(({ docPath }) => docPath),
+    [
+      "AGENTS.md",
+      "docs/toolcraft/core/performance.md",
+      "docs/toolcraft/workflow.md",
+    ],
+  );
+  assert.deepEqual(getStaleAgentPerformanceWorkflowFailures(sources), [
+    "AGENTS.md contains removed performance workflow guidance",
+    "docs/toolcraft/core/performance.md contains removed performance workflow guidance",
+  ]);
+});