@structor-dev/cli 0.1.0

package/scripts/smoke-template.mjs

@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+
+import { mkdtemp, mkdir, readFile, 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";
+
+const cases = [
+  {
+    name: "openai-only",
+    models: { openai: true, anthropic: false },
+    consumers: [{ name: "product-app", purpose: "Application repository" }],
+  },
+  {
+    name: "anthropic-only",
+    models: { openai: false, anthropic: true },
+    consumers: [{ name: "product-app", purpose: "Application repository" }],
+  },
+  {
+    name: "both-models",
+    models: { openai: true, anthropic: true },
+    consumers: [
+      { name: "product-frontend", purpose: "Frontend application repository" },
+      { name: "product-backend", purpose: "Backend API repository" },
+    ],
+  },
+];
+const smokePrefix = "smoke-";
+const tempRootPrefix = "structor-";
+const harnessConfigFileName = "harness.config.json";
+const harnessSchemaPath = "schemas/harness-config.schema.json";
+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" });
+}
+
+function runResult(command, args, cwd) {
+  return spawnSync(command, args, { cwd, encoding: "utf8" });
+}
+
+function assertFails(command, args, cwd, label, expectedMessage) {
+  const result = runResult(command, args, cwd);
+  if (result.status === 0) {
+    throw new Error(`${label} should have failed.`);
+  }
+  const output = `${result.stdout}\n${result.stderr}`;
+  if (expectedMessage && !output.includes(expectedMessage)) {
+    throw new Error(`${label} failed without expected message ${JSON.stringify(expectedMessage)}. Output: ${output}`);
+  }
+}
+
+function assertExists(filePath, label) {
+  if (!existsSync(filePath)) {
+    throw new Error(`${label} was not generated: ${filePath}`);
+  }
+}
+
+function assertMissing(filePath, label) {
+  if (existsSync(filePath)) {
+    throw new Error(`${label} should not have been generated: ${filePath}`);
+  }
+}
+
+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`);
+  }
+
+  const config = {
+    $schema: path.relative(workspaceRoot, path.join(repoRoot, harnessSchemaPath)),
+    project: {
+      name: `Smoke ${smokeCase.name}`,
+      slug: `smoke-${smokeCase.name}`,
+      harnessRepoName: `smoke-${smokeCase.name}-structor`,
+    },
+    output: overrides.output ?? {
+      path: `./smoke-${smokeCase.name}-structor`,
+    },
+    models: overrides.models ?? smokeCase.models,
+    clientSupport: {
+      codex: { hooks: smokeCase.models.openai },
+      claude: { rules: smokeCase.models.anthropic, hooks: false, skills: false },
+    },
+    consumers: overrides.consumers ?? smokeCase.consumers.map((consumer) => ({
+      name: consumer.name,
+      path: `./${consumer.name}`,
+      purpose: consumer.purpose,
+      validation: {
+        lint: lintCommand,
+        test: testCommand,
+      },
+    })),
+  };
+  if (overrides.removeProject) delete config.project;
+
+  const configPath = path.join(workspaceRoot, harnessConfigFileName);
+  await writeFile(configPath, overrides.rawJson ?? `${JSON.stringify(config, null, 2)}\n`);
+  return configPath;
+}
+
+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`);
+
+  run(nodeCommand, [path.join(repoRoot, initHarnessScript), "--config", configPath, "--dry-run"], repoRoot);
+  run(
+    nodeCommand,
+    [path.join(repoRoot, initHarnessScript), "--config", configPath, "--install-consumer-entrypoints"],
+    repoRoot,
+  );
+  run(nodeCommand, ["scripts/validate-governance.mjs"], harnessRoot);
+  assertExists(path.join(harnessRoot, "ai/views/index.html"), `${smokeCase.name} generated HTML view`);
+  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`);
+    }
+  }
+
+  const readme = await readFile(path.join(harnessRoot, "README.md"), "utf8");
+  if (!readme.includes("workspace")) {
+    throw new Error(`${smokeCase.name} generated README does not include workspace bootstrap guidance.`);
+  }
+
+  const firstConsumerRoot = path.join(workspaceRoot, smokeCase.consumers[0].name);
+  if (smokeCase.models.openai) {
+    const agentsPath = path.join(firstConsumerRoot, openaiRootEntrypoint);
+    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);
+    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`);
+    assertFails(nodeCommand, ["scripts/check-workspace.mjs"], harnessRoot, `${smokeCase.name} stale Claude pointer`, "instead of");
+    await writeFile(
+      claudePath,
+      `Read ${path.join(harnessRoot, "CLAUDE.md")} before editing.\nRead ${path.join(harnessRoot, "ai/AGENTS.md")} before editing.\nRead ${path.join(harnessRoot, "ai/HUB.md")} before editing.\nRead ${path.join(harnessRoot, "ai/context.md")} before editing.\n`,
+    );
+    await writeFile(claudeMemoryPath, `@../CLAUDE.md\nRead ${path.join(harnessRoot, "AGENTS.md")} before editing.\n`);
+    assertFails(
+      nodeCommand,
+      ["scripts/check-workspace.mjs"],
+      harnessRoot,
+      `${smokeCase.name} Claude memory stale ref`,
+    );
+  }
+}
+
+for (const smokeCase of cases) {
+  await validateCase(smokeCase);
+}
+
+async function validateNegativeConfigCase({ name, overrides, args = [], expectedMessage }) {
+  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);
+  assertFails(
+    nodeCommand,
+    [path.join(repoRoot, initHarnessScript), "--config", configPath, "--dry-run", ...args],
+    repoRoot,
+    name,
+    expectedMessage,
+  );
+}
+
+await validateNegativeConfigCase({
+  name: "no-models",
+  overrides: { models: { openai: false, anthropic: false } },
+  expectedMessage: "Invalid harness config: at least one model provider must be enabled.",
+});
+await validateNegativeConfigCase({
+  name: "malformed-json",
+  overrides: { rawJson: "{not json" },
+});
+await validateNegativeConfigCase({
+  name: "missing-project",
+  overrides: { removeProject: true },
+  expectedMessage: "project is required",
+});
+await validateNegativeConfigCase({
+  name: "absolute-output",
+  overrides: { output: { path: path.join(os.tmpdir(), "absolute-harness-output") } },
+  expectedMessage: "absolute output paths require --allow-absolute-output",
+});
+await validateNegativeConfigCase({
+  name: "template-root-output",
+  overrides: { output: { path: repoRoot } },
+  args: ["--allow-absolute-output"],
+  expectedMessage: "template repo",
+});
+await validateNegativeConfigCase({
+  name: "inside-template-output",
+  overrides: { output: { path: path.join(repoRoot, "generated-harness") } },
+  args: ["--allow-absolute-output"],
+  expectedMessage: "template repo",
+});
+await validateNegativeConfigCase({
+  name: "consumer-root-output",
+  overrides: { output: { path: "./product-app" } },
+  expectedMessage: "configured consumer repo",
+});
+await validateNegativeConfigCase({
+  name: "inside-consumer-output",
+  overrides: { output: { path: "./product-app/generated-harness" } },
+  expectedMessage: "configured consumer repo",
+});
+await validateNegativeConfigCase({
+  name: "workspace-root-output",
+  overrides: { output: { path: "." } },
+  expectedMessage: "workspace root",
+});
+await validateNegativeConfigCase({
+  name: "git-segment-output",
+  overrides: { output: { path: "./generated/.git/harness" } },
+  expectedMessage: ".git path segment",
+});
+
+{
+  const workspaceRoot = await mkdtemp(path.join(os.tmpdir(), `${tempRootPrefix}check-config-`));
+  const smokeCase = { name: "check-config", models: { openai: true, anthropic: false }, consumers: [{ name: "product-app", purpose: "Application repository" }] };
+  const configPath = await writeConfig(workspaceRoot, smokeCase, { output: { path: "." } });
+  assertFails(
+    nodeCommand,
+    [path.join(repoRoot, "scripts/check-config.mjs"), "--config", configPath],
+    repoRoot,
+    "check-config workspace-root-output",
+    "workspace root",
+  );
+}
+
+console.log("Template smoke check passed.");

package/scripts/validate-governance.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import "./validate-template.mjs";

package/scripts/validate-template.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+for (const command of [["npm", ["run", "check:ci"]], ["npm", ["run", "check:smoke"]]]) {
+  execFileSync(command[0], command[1], {
+    cwd: repoRoot,
+    stdio: "inherit",
+  });
+}
+
+console.log("Template validation passed.");

package/template/.claude/CLAUDE.md.tpl

@@ -0,0 +1,12 @@
+# {{PROJECT_NAME}} Claude Project Memory
+
+Use this alongside the root `CLAUDE.md` entrypoint.
+
+@../CLAUDE.md
+
+- Canonical policy lives in `../ai/*`.
+- Canonical harness policy lives in `../ai/*`.
+- Keep Claude-specific guidance thin and route back into shared docs.
+- Use `.claude/settings.json` only for local tool permission settings.
+- Use `.claude/rules/**` for concise project-surface rules, not copied policy.
+- Claude hooks are disabled by default; add them only with a validator.

package/template/.claude/rules/harness-client-surfaces.md.tpl

@@ -0,0 +1,20 @@
+---
+paths:
+  - "AGENTS.md"
+  - "CLAUDE.md"
+  - ".claude/**"
+  - ".codex/**"
+  - "ai/model-overlays/**"
+  - "scripts/check-*-compatibility.mjs"
+  - "scripts/check-overlay-drift.mjs"
+---
+
+# Harness Client Surface Rules
+
+- Keep `ai/*` as the canonical governance source of truth.
+- Keep `AGENTS.md` and `.codex/**` Codex-native.
+- Keep `CLAUDE.md` and `.claude/**` Claude Code-native.
+- Do not make Codex depend on `CLAUDE.md`.
+- Do not make Claude Code depend on `AGENTS.md`.
+- Do not copy broad canonical docs into `.claude/`; route back to `ai/*`.
+- Do not add Claude Code hooks until a fixture-backed validator is added.

package/template/.claude/settings.json.tpl

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "deny": [
+      "Read(./.agent.env)",
+      "Read(./.env)",
+      "Read(./.env.*)",
+      "Read(./secrets/**)"
+    ]
+  }
+}

package/template/.codex/hooks.json.tpl

@@ -0,0 +1,77 @@
+{
+  "version": 1,
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "timeoutMs": 2000,
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node scripts/hooks/codex-hook.mjs SessionStart --json"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "timeoutMs": 2000,
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node scripts/hooks/codex-hook.mjs UserPromptSubmit --json"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "timeoutMs": 2000,
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node scripts/hooks/codex-hook.mjs PreToolUse --json"
+          }
+        ]
+      }
+    ],
+    "PermissionRequest": [
+      {
+        "matcher": "*",
+        "timeoutMs": 2000,
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node scripts/hooks/codex-hook.mjs PermissionRequest --json"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "timeoutMs": 2000,
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node scripts/hooks/codex-hook.mjs PostToolUse --json"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "timeoutMs": 2000,
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node scripts/hooks/codex-hook.mjs Stop --json"
+          }
+        ]
+      }
+    ]
+  }
+}

package/template/AGENTS.md.tpl

@@ -0,0 +1,22 @@
+# {{PROJECT_NAME}} Engineering Harness Repo Guide
+
+This repository is the canonical AI engineering harness for {{PROJECT_NAME}}.
+
+## Read Order
+
+1. `./README.md`
+2. `./ai/AGENTS.md`
+3. `./ai/HUB.md`
+4. `./ai/context.md`
+5. Topical docs selected by `./ai/HUB.md`
+
+## Rules
+
+- 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.
+- 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/CLAUDE.md.tpl

@@ -0,0 +1,16 @@
+# {{PROJECT_NAME}} Engineering Harness
+
+This is the Claude-compatible entrypoint for the {{PROJECT_NAME}} engineering
+harness.
+
+Canonical policy lives in `ai/*`. Read:
+
+1. `./ai/AGENTS.md`
+2. `./ai/HUB.md`
+3. `./ai/context.md`
+
+@ai/context.md
+
+Claude-specific notes must stay thin and route back into canonical policy.
+Use `.claude/CLAUDE.md` for Claude Code project memory and keep it aligned with
+this file.

package/template/README.md.tpl

@@ -0,0 +1,109 @@
+# {{PROJECT_NAME}} Engineering Harness
+
+This repository contains the AI engineering harness for {{PROJECT_NAME}}.
+
+The harness defines policy, contracts, context routing, task templates, review
+rules, quality tracking, and validation. It does not implement product behavior
+and it is not a runner or orchestration runtime.
+
+## Client Support
+
+This harness includes the client support selected during generation:
+
+- OpenAI/Codex enabled: `{{MODEL_OPENAI_ENABLED}}`
+- Anthropic/Claude Code enabled: `{{MODEL_ANTHROPIC_ENABLED}}`
+- Codex hooks enabled: `{{CLIENT_CODEX_HOOKS_ENABLED}}`
+- Claude project rules enabled: `{{CLIENT_CLAUDE_RULES_ENABLED}}`
+- Claude hooks enabled: `{{CLIENT_CLAUDE_HOOKS_ENABLED}}`
+- Claude skills enabled: `{{CLIENT_CLAUDE_SKILLS_ENABLED}}`
+
+Canonical policy lives in `ai/*`. Client-specific files are thin startup,
+project-rule, or local guardrail surfaces that route back to that canonical
+policy. They should not become independent policy sources.
+
+Codex hook support, when enabled, is intentionally conservative: deterministic,
+local, bounded by short timeouts, and validated to avoid network calls, external
+writes, and runtime-state mutation. It is a harness guardrail, not a runner or a
+complete security boundary. Hooks catch common high-risk operations and provide
+contextual reminders, but they do not replace sandboxing, permission controls,
+code review, CI policy, or secret management.
+
+## Expected Workspace Layout
+
+This harness is intended to live as a sibling of the consumer repositories it
+governs:
+
+```text
+workspace/
+  {{HARNESS_REPO_NAME}}/
+  <consumer-repo>/
+  <optional-second-consumer-repo>/
+```
+
+The workspace bootstrap and check scripts resolve consumer repositories from
+that shared parent folder.
+
+## Consumer Repositories
+
+{{CONSUMER_REPOS_LIST}}
+
+## First Run
+
+Validate the harness:
+
+```sh
+node scripts/validate-governance.mjs
+```
+
+`validate-governance.mjs` also runs client-support checks when the matching
+surfaces are enabled:
+
+- `scripts/check-codex-hooks.mjs`
+- `scripts/check-claude-compatibility.mjs`
+- `scripts/check-overlay-drift.mjs`
+
+Preview workspace-level pointer files:
+
+```sh
+node scripts/bootstrap-workspace.mjs --dry-run
+```
+
+If the preview is safe, install or refresh workspace-level pointers and verify
+the full layout:
+
+```sh
+node scripts/bootstrap-workspace.mjs
+node scripts/check-workspace.mjs
+```
+
+`bootstrap-workspace.mjs` installs workspace-level `AGENTS.md`, `CLAUDE.md`,
+and `.claude/*` files when the selected model support requires them. It skips
+existing files unless `--force` is passed.
+
+## Daily Use
+
+Agents should start from the workspace, this harness repo, or a bootstrapped
+consumer repo, then follow the local `AGENTS.md` or `CLAUDE.md` entrypoint into
+`ai/HUB.md`.
+
+Consumer repos own implementation, runtime behavior, local validation, and
+deployment checks. The harness owns shared policy, contracts, task templates,
+review guidance, and validation evidence expectations.
+
+## Validation
+
+```sh
+node scripts/validate-governance.mjs
+node scripts/check-workspace.mjs
+```
+
+If workspace entrypoints are missing or stale:
+
+```sh
+node scripts/bootstrap-workspace.mjs --dry-run
+node scripts/bootstrap-workspace.mjs
+```
+
+Consumer repos should expose local install, lint, test, build, and health
+commands. The harness documents expected contracts and validation evidence, but
+consumer repos own implementation and runtime checks.

package/template/ai/AGENT-GARBAGE-COLLECTION.md.tpl

@@ -0,0 +1,18 @@
+# Agent Garbage Collection
+
+Use this file to convert repeated agent mistakes into durable fixes.
+
+Archive stale instructions instead of letting them compete with active policy.
+Generated files should be regenerated or validated before being treated as
+evidence.
+
+## Entry Format
+
+- Pattern:
+- Impact:
+- Durable fix:
+- Validation:
+
+## Entries
+
+No repeated patterns recorded yet.

package/template/ai/AGENTS.md.tpl

@@ -0,0 +1,36 @@
+# {{PROJECT_NAME}} Shared AI Guide
+
+This folder holds canonical shared guidance for the {{PROJECT_NAME}} engineering
+harness.
+
+## Scope
+
+- shared policy for AI-assisted development
+- context routing and task shape
+- product, architecture, and design context ready to fill from consumer repos
+- contracts and boundary rules
+- review skills and validation policy
+- quality tracking and repeated-mistake capture
+
+## Rules
+
+- Keep shared docs model-neutral.
+- Keep model overlays thin and synchronized.
+- Keep consumer implementation details out of this layer.
+- Use `ai/HUB.md` to route tasks before loading topical docs.
+- Use `node scripts/validate-governance.mjs` for harness validation.
+- Use `node scripts/check-workspace.mjs` when changing workspace bootstrap or
+  consumer entrypoint behavior.
+
+## Coding Conventions
+
+- Prefer deep modules that hide decisions behind clear APIs.
+- Keep coordination logic close to the module that owns the decision.
+- Use precise names that make the domain model obvious.
+- Reuse existing types, helpers, and abstractions before adding new ones.
+- Keep diffs minimal and avoid unrelated rewrites.
+- Comments should explain non-obvious intent, invariants, constraints, and
+  trade-offs; do not narrate syntax.
+- In UI or structured modules, use section markers when they improve scanning:
+  `// PROPS`, `// STATE`, `// RQ`, `// RHF`, `// HOOKS`, `// EFFECTS`,
+  `// METHODS`, `// VARS`, `// ARGS`, and `// PARAMS`.