@structor-dev/cli 0.1.0 → 0.2.0

package/scripts/setup-contributor.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  generateHarness,
+  installConsumerEntrypoints,
+} from "./init-harness.mjs";
+import {
+  assertSafeWriteTarget,
+  exists,
+} from "./lib.mjs";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const workspaceRoot = path.dirname(repoRoot);
+const presetRoot = path.join(repoRoot, "contrib/self-harness");
+const presetConfigPath = path.join(presetRoot, "harness.config.json");
+const overlayRoot = path.join(presetRoot, "files");
+
+function parseArgs(argv) {
+  return {
+    dryRun: argv.includes("--dry-run"),
+    force: argv.includes("--force"),
+  };
+}
+
+async function collectOverlayFiles() {
+  const files = [];
+
+  async function walk(currentPath) {
+    const entries = await readdir(currentPath, { withFileTypes: true });
+    for (const entry of entries) {
+      const absolutePath = path.join(currentPath, entry.name);
+      if (entry.isDirectory()) {
+        await walk(absolutePath);
+      } else if (entry.isFile()) {
+        files.push(path.relative(overlayRoot, absolutePath).replaceAll(path.sep, "/"));
+      }
+    }
+  }
+
+  await walk(overlayRoot);
+  return files.sort();
+}
+
+async function overlaySelfHarnessFiles(outputRoot, options) {
+  for (const relativePath of await collectOverlayFiles()) {
+    const sourcePath = path.join(overlayRoot, relativePath);
+    const targetPath = path.join(outputRoot, relativePath);
+    const existed = await exists(targetPath);
+
+    if (options.dryRun) {
+      console.log(`would ${existed ? "overwrite" : "create"} self-harness overlay ${targetPath}`);
+      continue;
+    }
+
+    await assertSafeWriteTarget({
+      targetPath,
+      rootPath: outputRoot,
+      label: `Self-harness overlay ${relativePath}`,
+    });
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    await writeFile(targetPath, await readFile(sourcePath, "utf8"));
+    console.log(`${existed ? "wrote" : "created"} self-harness overlay ${targetPath}`);
+  }
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const config = JSON.parse(await readFile(presetConfigPath, "utf8"));
+
+  console.log("Structor contributor setup");
+  console.log(`Workspace: ${workspaceRoot}`);
+  console.log(`Preset: ${presetConfigPath}`);
+
+  const resolvedConfig = await generateHarness(config, {
+    configPath: presetConfigPath,
+    configDir: workspaceRoot,
+    dryRun: options.dryRun,
+    force: true,
+    allowTemplateRepoConsumer: true,
+  });
+
+  await overlaySelfHarnessFiles(resolvedConfig.outputRoot, options);
+
+  const bootstrapArgs = ["scripts/bootstrap-workspace.mjs"];
+  if (options.force) bootstrapArgs.push("--force");
+
+  if (options.dryRun) {
+    console.log(`would refresh self-harness HTML views in ${resolvedConfig.outputRoot}`);
+    console.log(`would run workspace bootstrap dry-run in ${resolvedConfig.outputRoot}: ${process.execPath} ${bootstrapArgs.join(" ")}`);
+  } else {
+    execFileSync(process.execPath, ["scripts/generate-html-views.mjs"], {
+      cwd: resolvedConfig.outputRoot,
+      stdio: "inherit",
+    });
+    execFileSync(process.execPath, bootstrapArgs, {
+      cwd: resolvedConfig.outputRoot,
+      stdio: "inherit",
+    });
+  }
+
+  console.log("Source entrypoint preview");
+  await installConsumerEntrypoints(resolvedConfig, {
+    dryRun: true,
+    force: options.force,
+    config: presetConfigPath,
+  });
+
+  if (!options.dryRun) {
+    console.log("Source entrypoint apply");
+    await installConsumerEntrypoints(resolvedConfig, {
+      dryRun: false,
+      force: options.force,
+      config: presetConfigPath,
+    });
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/scripts/smoke-template.mjs

@@ -1,11 +1,20 @@
 #!/usr/bin/env node
 
-import { mkdtemp, mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdtemp, mkdir, readFile, symlink, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { execFileSync, spawnSync } from "node:child_process";
 import os from "node:os";
 import path from "node:path";
 import { repoRoot } from "./lib.mjs";
+import {
+  artifactEnabled,
+  artifactTargetPath,
+  consumerEntrypointsForSettings,
+  generatedHarnessArtifacts,
+  requiredHarnessRepoFilesForWorkspaceCheck,
+  requiredWorkspaceFilesForWorkspaceCheck,
+  validationPlanForSettings,
+} from "./generated-harness-contract.mjs";
 
 const cases = [
   {
@@ -35,11 +44,6 @@ const initHarnessScript = "scripts/init-harness.mjs";
 const nodeCommand = "node";
 const lintCommand = "npm run lint";
 const testCommand = "npm test";
-const openaiRootEntrypoint = "AGENTS.md";
-const openaiCodexConfig = ".codex/hooks.json";
-const claudeRootEntrypoint = "CLAUDE.md";
-const claudeMemoryEntrypoint = ".claude/CLAUDE.md";
-const claudeRulesEntrypoint = ".claude/rules/harness-client-surfaces.md";
 
 function run(command, args, cwd) {
   execFileSync(command, args, { cwd, stdio: "pipe" });
@@ -76,6 +80,7 @@ async function writeConfig(workspaceRoot, smokeCase, overrides = {}) {
   for (const consumer of smokeCase.consumers) {
     await mkdir(path.join(workspaceRoot, consumer.name), { recursive: true });
     await writeFile(path.join(workspaceRoot, consumer.name, "README.md"), `# ${consumer.name}\n`);
+    await writeFile(path.join(workspaceRoot, consumer.name, "package.json"), `${JSON.stringify({ name: consumer.name })}\n`);
   }
 
   const config = {
@@ -110,10 +115,59 @@ async function writeConfig(workspaceRoot, smokeCase, overrides = {}) {
   return configPath;
 }
 
+function settingsForSmokeCase(smokeCase) {
+  return {
+    models: smokeCase.models,
+    clientSupport: {
+      codexHooks: smokeCase.models.openai,
+      claudeRules: smokeCase.models.anthropic,
+      claudeHooks: false,
+      claudeSkills: false,
+    },
+  };
+}
+
+function findEntrypoint(entrypoints, predicate, label) {
+  const entrypoint = entrypoints.find(predicate);
+  if (!entrypoint) throw new Error(`Generated harness contract is missing ${label}.`);
+  return entrypoint;
+}
+
+function assertContractSurfaces({ smokeCase, workspaceRoot, harnessRoot }) {
+  const settings = settingsForSmokeCase(smokeCase);
+  for (const relativePath of requiredHarnessRepoFilesForWorkspaceCheck(settings)) {
+    assertExists(path.join(harnessRoot, relativePath), `${smokeCase.name} contract repo file ${relativePath}`);
+  }
+  for (const relativePath of requiredWorkspaceFilesForWorkspaceCheck(settings)) {
+    assertExists(path.join(workspaceRoot, relativePath), `${smokeCase.name} contract workspace file ${relativePath}`);
+  }
+  for (const artifact of generatedHarnessArtifacts.filter((item) => item.generated && !artifactEnabled(item, settings))) {
+    assertMissing(path.join(harnessRoot, artifactTargetPath(artifact)), `${smokeCase.name} disabled contract artifact ${artifactTargetPath(artifact)}`);
+  }
+  for (const consumer of smokeCase.consumers) {
+    const consumerRoot = path.join(workspaceRoot, consumer.name);
+    for (const entrypoint of consumerEntrypointsForSettings(settings)) {
+      assertExists(path.join(consumerRoot, entrypoint.path), `${consumer.name} contract entrypoint ${entrypoint.path}`);
+    }
+  }
+
+  const plan = validationPlanForSettings(settings);
+  if (settings.clientSupport.codexHooks) {
+    const codexDependencies = plan.checkDependencies["scripts/check-codex-hooks.mjs"] ?? [];
+    for (const dependency of ["scripts/hooks/codex-hook.mjs", "scripts/hooks/lib/codex-hooks-core.mjs"]) {
+      if (!codexDependencies.includes(dependency)) {
+        throw new Error(`Codex hook validation must trust generated dependency ${dependency}.`);
+      }
+    }
+  }
+}
+
 async function validateCase(smokeCase) {
   const workspaceRoot = await mkdtemp(path.join(os.tmpdir(), `${tempRootPrefix}${smokeCase.name}-`));
   const configPath = await writeConfig(workspaceRoot, smokeCase);
   const harnessRoot = path.join(workspaceRoot, `${smokePrefix}${smokeCase.name}-structor`);
+  const settings = settingsForSmokeCase(smokeCase);
+  const consumerEntrypoints = consumerEntrypointsForSettings(settings);
 
   run(nodeCommand, [path.join(repoRoot, initHarnessScript), "--config", configPath, "--dry-run"], repoRoot);
   run(
@@ -126,69 +180,7 @@ async function validateCase(smokeCase) {
   run(nodeCommand, ["scripts/bootstrap-workspace.mjs", "--dry-run"], harnessRoot);
   run(nodeCommand, ["scripts/bootstrap-workspace.mjs"], harnessRoot);
   run(nodeCommand, ["scripts/check-workspace.mjs"], harnessRoot);
-
-  if (smokeCase.models.openai) {
-    assertExists(path.join(harnessRoot, "workspace/AGENTS.md"), `${smokeCase.name} generated workspace AGENTS`);
-    assertExists(path.join(workspaceRoot, "AGENTS.md"), `${smokeCase.name} workspace AGENTS`);
-  } else {
-    assertMissing(path.join(harnessRoot, "workspace/AGENTS.md"), `${smokeCase.name} generated workspace AGENTS`);
-    assertMissing(path.join(workspaceRoot, "AGENTS.md"), `${smokeCase.name} workspace AGENTS`);
-  }
-  if (smokeCase.models.anthropic) {
-    assertExists(path.join(harnessRoot, "workspace/CLAUDE.md"), `${smokeCase.name} generated workspace CLAUDE`);
-    assertExists(path.join(harnessRoot, "workspace/.claude/CLAUDE.md"), `${smokeCase.name} generated workspace Claude memory`);
-    assertExists(path.join(harnessRoot, "workspace/.claude/settings.json"), `${smokeCase.name} generated workspace Claude settings`);
-    assertExists(path.join(workspaceRoot, "CLAUDE.md"), `${smokeCase.name} workspace CLAUDE`);
-    assertExists(path.join(workspaceRoot, ".claude/CLAUDE.md"), `${smokeCase.name} workspace Claude memory`);
-    assertExists(path.join(workspaceRoot, ".claude/settings.json"), `${smokeCase.name} workspace Claude settings`);
-  } else {
-    assertMissing(path.join(harnessRoot, "workspace/CLAUDE.md"), `${smokeCase.name} generated workspace CLAUDE`);
-    assertMissing(path.join(harnessRoot, "workspace/.claude/CLAUDE.md"), `${smokeCase.name} generated workspace Claude memory`);
-    assertMissing(path.join(harnessRoot, "workspace/.claude/settings.json"), `${smokeCase.name} generated workspace Claude settings`);
-    assertMissing(path.join(workspaceRoot, "CLAUDE.md"), `${smokeCase.name} workspace CLAUDE`);
-    assertMissing(path.join(workspaceRoot, ".claude/CLAUDE.md"), `${smokeCase.name} workspace Claude memory`);
-    assertMissing(path.join(workspaceRoot, ".claude/settings.json"), `${smokeCase.name} workspace Claude settings`);
-  }
-
-  if (smokeCase.models.openai) {
-    assertExists(path.join(harnessRoot, openaiRootEntrypoint), `${smokeCase.name} OpenAI root entrypoint`);
-    assertExists(path.join(harnessRoot, openaiCodexConfig), `${smokeCase.name} Codex hook config`);
-    assertExists(path.join(harnessRoot, "scripts/check-codex-hooks.mjs"), `${smokeCase.name} Codex hook validator`);
-    assertExists(path.join(harnessRoot, "scripts/hooks/codex-hook.mjs"), `${smokeCase.name} Codex hook script`);
-    assertExists(
-      path.join(harnessRoot, "ai/model-overlays/openai/AGENTS.md"),
-      `${smokeCase.name} OpenAI overlay`,
-    );
-  } else {
-    assertMissing(path.join(harnessRoot, openaiRootEntrypoint), `${smokeCase.name} OpenAI root entrypoint`);
-    assertMissing(path.join(harnessRoot, ".codex/hooks.json"), `${smokeCase.name} Codex hook config`);
-  }
-
-  if (smokeCase.models.anthropic) {
-    assertExists(path.join(harnessRoot, claudeRootEntrypoint), `${smokeCase.name} Claude root entrypoint`);
-    assertExists(path.join(harnessRoot, claudeMemoryEntrypoint), `${smokeCase.name} Claude memory`);
-    assertExists(path.join(harnessRoot, claudeRulesEntrypoint), `${smokeCase.name} Claude rule`);
-    assertExists(
-      path.join(harnessRoot, "scripts/check-claude-compatibility.mjs"),
-      `${smokeCase.name} Claude compatibility validator`,
-    );
-    assertExists(
-      path.join(harnessRoot, "ai/model-overlays/anthropic/CLAUDE.md"),
-      `${smokeCase.name} Claude overlay`,
-    );
-  } else {
-    assertMissing(path.join(harnessRoot, claudeRootEntrypoint), `${smokeCase.name} Claude root entrypoint`);
-    assertMissing(path.join(harnessRoot, claudeRulesEntrypoint), `${smokeCase.name} Claude rule`);
-  }
-
-  for (const consumer of smokeCase.consumers) {
-    const consumerRoot = path.join(workspaceRoot, consumer.name);
-    if (smokeCase.models.openai) assertExists(path.join(consumerRoot, "AGENTS.md"), `${consumer.name} AGENTS.md`);
-    if (smokeCase.models.anthropic) {
-      assertExists(path.join(consumerRoot, claudeRootEntrypoint), `${consumer.name} CLAUDE.md`);
-      assertExists(path.join(consumerRoot, claudeMemoryEntrypoint), `${consumer.name} .claude/CLAUDE.md`);
-    }
-  }
+  assertContractSurfaces({ smokeCase, workspaceRoot, harnessRoot });
 
   const readme = await readFile(path.join(harnessRoot, "README.md"), "utf8");
   if (!readme.includes("workspace")) {
@@ -197,15 +189,32 @@ async function validateCase(smokeCase) {
 
   const firstConsumerRoot = path.join(workspaceRoot, smokeCase.consumers[0].name);
   if (smokeCase.models.openai) {
-    const agentsPath = path.join(firstConsumerRoot, openaiRootEntrypoint);
+    const agentsPath = path.join(
+      firstConsumerRoot,
+      findEntrypoint(consumerEntrypoints, (entrypoint) => entrypoint.model === "openai", "OpenAI consumer entrypoint").path,
+    );
     await writeFile(agentsPath, `This mentions ${path.basename(harnessRoot)} but has no usable path.\n`);
     assertFails(nodeCommand, ["scripts/check-workspace.mjs"], harnessRoot, `${smokeCase.name} substring-only pointer`, "does not contain a resolvable");
     await writeFile(agentsPath, `Read /tmp/${path.basename(harnessRoot)}/AGENTS.md before editing.\n`);
     assertFails(nodeCommand, ["scripts/check-workspace.mjs"], harnessRoot, `${smokeCase.name} stale pointer`, "instead of");
   }
   if (smokeCase.models.anthropic && !smokeCase.models.openai) {
-    const claudePath = path.join(firstConsumerRoot, claudeRootEntrypoint);
-    const claudeMemoryPath = path.join(firstConsumerRoot, claudeMemoryEntrypoint);
+    const claudePath = path.join(
+      firstConsumerRoot,
+      findEntrypoint(
+        consumerEntrypoints,
+        (entrypoint) => entrypoint.model === "anthropic" && entrypoint.routing === "harness",
+        "Claude consumer entrypoint",
+      ).path,
+    );
+    const claudeMemoryPath = path.join(
+      firstConsumerRoot,
+      findEntrypoint(
+        consumerEntrypoints,
+        (entrypoint) => entrypoint.model === "anthropic" && entrypoint.routing === "claude-memory",
+        "Claude memory consumer entrypoint",
+      ).path,
+    );
     await writeFile(claudePath, `This mentions ${path.basename(harnessRoot)} but has no usable path.\n`);
     assertFails(nodeCommand, ["scripts/check-workspace.mjs"], harnessRoot, `${smokeCase.name} substring-only Claude pointer`, "does not contain a resolvable");
     await writeFile(claudePath, `Read /tmp/${path.basename(harnessRoot)}/CLAUDE.md before editing.\n`);
@@ -228,10 +237,11 @@ for (const smokeCase of cases) {
   await validateCase(smokeCase);
 }
 
-async function validateNegativeConfigCase({ name, overrides, args = [], expectedMessage }) {
+async function validateNegativeConfigCase({ name, overrides, args = [], expectedMessage, setup }) {
   const workspaceRoot = await mkdtemp(path.join(os.tmpdir(), `${tempRootPrefix}${name}-`));
   const smokeCase = { name, models: { openai: true, anthropic: false }, consumers: [{ name: "product-app", purpose: "Application repository" }] };
   const configPath = await writeConfig(workspaceRoot, smokeCase, overrides);
+  if (setup) await setup(workspaceRoot);
   assertFails(
     nodeCommand,
     [path.join(repoRoot, initHarnessScript), "--config", configPath, "--dry-run", ...args],
@@ -260,6 +270,19 @@ await validateNegativeConfigCase({
   overrides: { output: { path: path.join(os.tmpdir(), "absolute-harness-output") } },
   expectedMessage: "absolute output paths require --allow-absolute-output",
 });
+await validateNegativeConfigCase({
+  name: "relative-traversal-output",
+  overrides: { output: { path: "../outside-harness-output" } },
+  expectedMessage: "workspace boundary",
+});
+await validateNegativeConfigCase({
+  name: "symlink-output",
+  overrides: { output: { path: "./linked-harness-output" } },
+  expectedMessage: "symlinked output directories",
+  setup: async (workspaceRoot) => {
+    await symlink(path.join(workspaceRoot, "product-app"), path.join(workspaceRoot, "linked-harness-output"), "dir");
+  },
+});
 await validateNegativeConfigCase({
   name: "template-root-output",
   overrides: { output: { path: repoRoot } },
@@ -292,6 +315,170 @@ await validateNegativeConfigCase({
   overrides: { output: { path: "./generated/.git/harness" } },
   expectedMessage: ".git path segment",
 });
+await validateNegativeConfigCase({
+  name: "absolute-consumer",
+  overrides: {
+    consumers: [{
+      name: "outside-app",
+      path: path.join(os.tmpdir(), "outside-app"),
+      purpose: "Application repository",
+      validation: {},
+    }],
+  },
+  expectedMessage: "absolute paths are not allowed",
+});
+await validateNegativeConfigCase({
+  name: "traversal-consumer",
+  overrides: {
+    consumers: [{
+      name: "outside-app",
+      path: "../outside-app",
+      purpose: "Application repository",
+      validation: {},
+    }],
+  },
+  expectedMessage: "relative traversal",
+});
+await validateNegativeConfigCase({
+  name: "force-traversal-consumer",
+  overrides: {
+    consumers: [{
+      name: "outside-app",
+      path: "../outside-app",
+      purpose: "Application repository",
+      validation: {},
+    }],
+  },
+  args: ["--install-consumer-entrypoints", "--force"],
+  expectedMessage: "relative traversal",
+});
+await validateNegativeConfigCase({
+  name: "unconfirmed-consumer",
+  overrides: {
+    consumers: [{
+      name: "not-repo",
+      path: "./not-repo",
+      purpose: "Existing directory without repo signals",
+      validation: {},
+    }],
+  },
+  args: ["--install-consumer-entrypoints"],
+  expectedMessage: "not a confirmed consumer repository",
+  setup: async (workspaceRoot) => {
+    await mkdir(path.join(workspaceRoot, "not-repo"), { recursive: true });
+  },
+});
+await validateNegativeConfigCase({
+  name: "symlinked-consumer",
+  overrides: {
+    consumers: [{
+      name: "linked-app",
+      path: "./linked-app",
+      purpose: "Symlinked application repository",
+      validation: {},
+    }],
+  },
+  args: ["--install-consumer-entrypoints"],
+  expectedMessage: "symlinked consumer paths",
+  setup: async (workspaceRoot) => {
+    const outsideRoot = await mkdtemp(path.join(os.tmpdir(), `${tempRootPrefix}outside-consumer-`));
+    await writeFile(path.join(outsideRoot, "package.json"), `${JSON.stringify({ name: "outside-app" })}\n`);
+    await symlink(outsideRoot, path.join(workspaceRoot, "linked-app"), "dir");
+  },
+});
+
+{
+  const workspaceRoot = await mkdtemp(path.join(os.tmpdir(), `${tempRootPrefix}workspace-claude-symlink-`));
+  const smokeCase = {
+    name: "workspace-claude-symlink",
+    models: { openai: false, anthropic: true },
+    consumers: [{ name: "product-app", purpose: "Application repository" }],
+  };
+  const configPath = await writeConfig(workspaceRoot, smokeCase);
+  const harnessRoot = path.join(workspaceRoot, "smoke-workspace-claude-symlink-structor");
+  const outsideRoot = path.join(workspaceRoot, "outside-claude");
+  await mkdir(outsideRoot);
+
+  run(nodeCommand, [path.join(repoRoot, initHarnessScript), "--config", configPath], repoRoot);
+  await symlink(outsideRoot, path.join(workspaceRoot, ".claude"), "dir");
+
+  assertFails(
+    nodeCommand,
+    ["scripts/bootstrap-workspace.mjs"],
+    harnessRoot,
+    "workspace .claude symlink",
+    "symlinked write targets",
+  );
+  assertMissing(path.join(outsideRoot, "CLAUDE.md"), "workspace bootstrap should not write through symlinked .claude");
+}
+
+{
+  const workspaceRoot = await mkdtemp(path.join(os.tmpdir(), `${tempRootPrefix}worktree-pointer-symlink-`));
+  const smokeCase = {
+    name: "worktree-pointer-symlink",
+    models: { openai: true, anthropic: false },
+    consumers: [{ name: "product-app", purpose: "Application repository" }],
+  };
+  const configPath = await writeConfig(workspaceRoot, smokeCase);
+  const harnessRoot = path.join(workspaceRoot, "smoke-worktree-pointer-symlink-structor");
+  const consumerRoot = path.join(workspaceRoot, "product-app");
+  const outsideRoot = path.join(workspaceRoot, "outside-pointer");
+  const openaiEntrypoint = findEntrypoint(
+    consumerEntrypointsForSettings(settingsForSmokeCase(smokeCase)),
+    (entrypoint) => entrypoint.model === "openai",
+    "OpenAI consumer entrypoint",
+  );
+  const outsidePointer = path.join(outsideRoot, openaiEntrypoint.path);
+  await mkdir(outsideRoot);
+  await writeFile(outsidePointer, "Read /tmp/other-structor/AGENTS.md before editing.\n");
+
+  run(nodeCommand, [path.join(repoRoot, initHarnessScript), "--config", configPath], repoRoot);
+  run("git", ["init"], consumerRoot);
+  await symlink(outsidePointer, path.join(consumerRoot, openaiEntrypoint.path));
+
+  assertFails(
+    nodeCommand,
+    ["scripts/bootstrap-codex-worktree.mjs", consumerRoot],
+    harnessRoot,
+    "worktree pointer symlink",
+    "symlinked write targets",
+  );
+  if ((await readFile(outsidePointer, "utf8")) !== "Read /tmp/other-structor/AGENTS.md before editing.\n") {
+    throw new Error("worktree repair should not write through a symlinked pointer file.");
+  }
+}
+
+{
+  const workspaceRoot = await mkdtemp(path.join(os.tmpdir(), `${tempRootPrefix}force-consumer-entrypoints-`));
+  const smokeCase = {
+    name: "force-consumer-entrypoints",
+    models: { openai: true, anthropic: false },
+    consumers: [{ name: "product-app", purpose: "Application repository" }],
+  };
+  const configPath = await writeConfig(workspaceRoot, smokeCase);
+  const openaiEntrypoint = findEntrypoint(
+    consumerEntrypointsForSettings(settingsForSmokeCase(smokeCase)),
+    (entrypoint) => entrypoint.model === "openai",
+    "OpenAI consumer entrypoint",
+  );
+  const agentsPath = path.join(workspaceRoot, "product-app", openaiEntrypoint.path);
+  await writeFile(agentsPath, "OLD");
+
+  run(nodeCommand, [path.join(repoRoot, initHarnessScript), "--config", configPath, "--install-consumer-entrypoints"], repoRoot);
+  if (await readFile(agentsPath, "utf8") !== "OLD") {
+    throw new Error("consumer entrypoint should be skipped without --force.");
+  }
+
+  run(
+    nodeCommand,
+    [path.join(repoRoot, initHarnessScript), "--config", configPath, "--install-consumer-entrypoints", "--force"],
+    repoRoot,
+  );
+  const forcedContent = await readFile(agentsPath, "utf8");
+  if (forcedContent === "OLD" || !forcedContent.includes("This consumer repository is governed by")) {
+    throw new Error("consumer entrypoint should be overwritten with --force.");
+  }
+}
 
 {
   const workspaceRoot = await mkdtemp(path.join(os.tmpdir(), `${tempRootPrefix}check-config-`));

package/template/AGENTS.md.tpl

@@ -15,8 +15,10 @@ This repository is the canonical AI engineering harness for {{PROJECT_NAME}}.
 - Treat `ai/*` as canonical harness policy.
 - Keep model-specific files thin.
 - Keep consumer repo implementation details in consumer repos.
-- Do not add runner, polling, PR automation, dashboards, or external writes to
-  this harness.
+- Do not add runner, polling, PR automation, live dashboards, orchestration UI,
+  or external writes to this harness.
+- Read-only generated Harness Cockpit views under `ai/views/*` are review
+  artifacts, not workflow control surfaces.
 - Validate harness changes with `node scripts/validate-governance.mjs`.
 - Use `node scripts/bootstrap-workspace.mjs --dry-run` before installing or
   refreshing workspace-level or consumer repo entrypoints.

package/template/README.md.tpl

@@ -55,6 +55,11 @@ Validate the harness:
 node scripts/validate-governance.mjs
 ```
 
+Generated artifact, entrypoint, and check participation lives in
+`scripts/generated-harness-contract.mjs`. The validator uses that contract to
+resolve required files, trusted check dependencies, and enabled client-support
+surfaces.
+
 `validate-governance.mjs` also runs client-support checks when the matching
 surfaces are enabled:
 

package/template/ai/CODEX-HOOKS.md.tpl

@@ -1,6 +1,6 @@
 # Codex Hooks
 
-Codex hooks provide lightweight local guardrails for `{{PROJECT_NAME}}`.
+Codex hooks provide lightweight local guardrails for {{PROJECT_NAME_CODE}}.
 
 ## Scope
 

package/template/ai/HARNESS-ENGINEERING.md.tpl

@@ -13,8 +13,11 @@ instead of chat history or human memory.
 - The harness defines what must be true.
 - A runner decides when and how work executes.
 - The harness owns policy, contracts, templates, quality, and validation.
-- Runtime state, polling, PR automation, dashboards, auto-merge, and repair
-  loops belong outside the canonical docs layer unless explicitly authorized.
+- Runtime state, polling, PR automation, live dashboards, auto-merge, repair
+  loops, and orchestration UI belong outside the canonical docs layer unless
+  explicitly authorized.
+- Read-only generated Harness Cockpit views are allowed when they are derived
+  from canonical local files and do not execute validation or workflows.
 
 ## System Of Record
 

package/template/ai/HARNESS.md.tpl

@@ -24,13 +24,16 @@ It does not implement product behavior and it is not a runner.
 - long-running polling
 - agent session lifecycle
 - PR lifecycle automation
-- dashboards
+- live dashboards or orchestration UI
 - auto-merge
 - production autonomous execution
 - runtime state stores
 - repair-loop daemons
 - external client automation that is not validated as a local harness guardrail
 
+Read-only generated Harness Cockpit views under `ai/views/*` are allowed when
+they summarize canonical local files and do not execute workflows.
+
 ## Harness vs Runner
 
 The harness answers what must be true. A runner answers when and how work is

package/template/ai/contracts/codex-hooks.contract.json.tpl

@@ -10,6 +10,63 @@
     "scripts/hooks/lib/codex-hooks-core.mjs",
     "ai/contracts/codex-hooks.md"
   ],
-  "forbiddenTokens": ["fetch(", "writeFile(", "appendFile("],
+  "forbiddenTokens": [
+    "fetch(",
+    "writeFile(",
+    "appendFile(",
+    "chmod(",
+    "chown(",
+    "copyFile(",
+    "cp(",
+    "fchmod(",
+    "fchown(",
+    "fdatasync(",
+    "fsync(",
+    "ftruncate(",
+    "futimes(",
+    "lchmod(",
+    "lchown(",
+    "link(",
+    "lutimes(",
+    "mkdir(",
+    "mkdtemp(",
+    "rename(",
+    "rm(",
+    "rmdir(",
+    "symlink(",
+    "truncate(",
+    "unlink(",
+    "utimes(",
+    "writev(",
+    "writeFileSync",
+    "appendFileSync",
+    "chmodSync",
+    "chownSync",
+    "copyFileSync",
+    "cpSync",
+    "fchmodSync",
+    "fchownSync",
+    "fdatasyncSync",
+    "fsyncSync",
+    "ftruncateSync",
+    "futimesSync",
+    "lchmodSync",
+    "lchownSync",
+    "linkSync",
+    "lutimesSync",
+    "mkdirSync",
+    "mkdtempSync",
+    "renameSync",
+    "rmSync",
+    "rmdirSync",
+    "symlinkSync",
+    "truncateSync",
+    "unlinkSync",
+    "utimesSync",
+    "writeSync",
+    "writevSync",
+    "createWriteStream",
+    "openSync(write flags)"
+  ],
   "validation": ["node scripts/check-codex-hooks.mjs"]
 }