@structor-dev/cli 0.1.0

package/template/scripts/check-template-governance.mjs.tpl

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+
+import { access, readFile } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const models = {
+  openai: {{MODEL_OPENAI_ENABLED}},
+  anthropic: {{MODEL_ANTHROPIC_ENABLED}},
+};
+const clientSupport = {
+  codexHooks: {{CLIENT_CODEX_HOOKS_ENABLED}},
+  claudeRules: {{CLIENT_CLAUDE_RULES_ENABLED}},
+  claudeHooks: {{CLIENT_CLAUDE_HOOKS_ENABLED}},
+  claudeSkills: {{CLIENT_CLAUDE_SKILLS_ENABLED}},
+};
+const openaiRequiredFiles = ["AGENTS.md", "ai/model-overlays/openai/AGENTS.md", "workspace/AGENTS.md"];
+const claudeRequiredFiles = [
+  "CLAUDE.md",
+  ".claude/CLAUDE.md",
+  ".claude/settings.json",
+  "ai/model-overlays/anthropic/CLAUDE.md",
+  "workspace/CLAUDE.md",
+  "workspace/.claude/CLAUDE.md",
+  "workspace/.claude/settings.json",
+  "scripts/check-claude-compatibility.mjs",
+];
+const codexRequiredFiles = [
+  ".codex/hooks.json",
+  "ai/contracts/codex-hooks.contract.json",
+  "scripts/check-codex-hooks.mjs",
+  "scripts/hooks/codex-hook.mjs",
+  "scripts/hooks/lib/codex-hooks-core.mjs",
+];
+const claudeRulesRequiredFiles = [".claude/rules/harness-client-surfaces.md", "workspace/.claude/rules/harness-client-surfaces.md"];
+const driftFile = "scripts/check-overlay-drift.mjs";
+const requiredFiles = [
+  "README.md",
+  "ai/AGENTS.md",
+  "ai/HUB.md",
+  "ai/context.md",
+  "ai/HARNESS.md",
+  "ai/HARNESS-ENGINEERING.md",
+  "ai/READINESS.md",
+  "ai/QUALITY.md",
+  "ai/DECISIONS.md",
+  "ai/PRODUCT-SUMMARY.md",
+  "ai/PRODUCT.md",
+  "ai/ARCHITECTURE.md",
+  "ai/DESIGN.md",
+  "ai/WORKFLOW.md",
+  "ai/VERSIONING.md",
+  "ai/CODEX-HOOKS.md",
+  "ai/RUNNER-SAFETY.md",
+  "ai/RUNNER-READINESS.md",
+  "ai/AGENT-GARBAGE-COLLECTION.md",
+  "ai/knowledge-manifest.json",
+  "ai/workspace/REPOS.md",
+  "ai/workspace/SYSTEM-MAP.md",
+  "ai/workspace/SESSION-BOOTSTRAP.md",
+  "ai/workspace/LOCAL-STACK.md",
+  "ai/workspace/TEST-STRATEGY.md",
+  "ai/contracts/README.md",
+  "ai/contracts/repo-boundaries.md",
+  "ai/contracts/repo-boundaries.contract.json",
+  "ai/contracts/app-legibility.md",
+  "ai/contracts/app-legibility.contract.json",
+  "ai/contracts/api-boundary.md",
+  "ai/contracts/api-boundary.contract.json",
+  "ai/contracts/security-boundary.md",
+  "ai/contracts/security-boundary.contract.json",
+  "ai/contracts/codex-hooks.md",
+  "ai/contracts/release-flow.md",
+  "ai/contracts/release-flow.contract.json",
+  "ai/contracts/github-safety.md",
+  "ai/contracts/github-safety.contract.json",
+  "ai/templates/README.md",
+  "ai/templates/task-brief-template.md",
+  "ai/templates/issue-template.md",
+  "ai/templates/fixtures/issues/valid-ready.md",
+  "ai/templates/fixtures/issues/invalid-placeholder.md",
+  "ai/templates/fixtures/issues/invalid-protected-surface.md",
+  "ai/skills/README.md",
+  "ai/skills/review-architecture.md",
+  "ai/skills/review-security.md",
+  "ai/skills/review-contract-drift.md",
+  "ai/skills/review-governance-drift.md",
+  "ai/plans/README.md",
+  "ai/plans/tech-debt.md",
+  "ai/specs/README.md",
+  "scripts/bootstrap-workspace.mjs",
+  "scripts/check-workspace.mjs",
+  "scripts/validate-governance.mjs",
+  "scripts/check-template-governance.mjs",
+  "scripts/check-readiness.mjs",
+  "scripts/check-task-template.mjs",
+  "scripts/check-issue-template.mjs",
+  "scripts/check-knowledge-manifest.mjs",
+  "scripts/check-plans.mjs",
+  "scripts/check-review-skills.mjs",
+  "scripts/check-garbage-collection.mjs",
+  "scripts/check-contract-manifests.mjs",
+  "scripts/generate-html-views.mjs",
+  "scripts/check-html-views.mjs",
+  "scripts/bootstrap-codex-worktree.mjs",
+  "scripts/check-worktrees.mjs",
+  "scripts/check-worktree-bootstrap-fixtures.mjs",
+  "scripts/lib/worktree-bootstrap.mjs",
+  "scripts/fixtures/worktrees/README.md",
+];
+
+if (models.openai) {
+  requiredFiles.push(...openaiRequiredFiles);
+}
+
+if (models.anthropic) {
+  requiredFiles.push(...claudeRequiredFiles);
+}
+
+if (clientSupport.codexHooks) {
+  requiredFiles.push(...codexRequiredFiles);
+}
+
+if (clientSupport.claudeRules) {
+  requiredFiles.push(...claudeRulesRequiredFiles);
+}
+
+if (models.openai || models.anthropic) {
+  requiredFiles.push(driftFile);
+}
+
+async function exists(relativePath) {
+  try {
+    await access(path.join(repoRoot, relativePath), fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const errors = [];
+for (const relativePath of requiredFiles) {
+  if (!(await exists(relativePath))) errors.push(`missing ${relativePath}`);
+}
+
+for (const relativePath of requiredFiles.filter((item) => item.endsWith(".md"))) {
+  const content = await readFile(path.join(repoRoot, relativePath), "utf8");
+  if (/\{\{[A-Z0-9_]+\}\}/.test(content)) {
+    errors.push(`${relativePath} contains an unresolved template placeholder.`);
+  }
+}
+
+if (errors.length > 0) {
+  console.error("Generated harness governance check failed.");
+  for (const error of errors) console.error(`- ${error}`);
+  process.exit(1);
+}
+
+console.log("Generated harness governance check passed.");

package/template/scripts/check-workspace.mjs.tpl

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+
+import { access, readFile } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { assertReferencesHarnessRoot } from "./lib/worktree-bootstrap.mjs";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const workspaceRoot = path.resolve(repoRoot, "..");
+const harnessRepoName = "{{HARNESS_REPO_NAME}}";
+const consumers = {{CONSUMER_CONFIG_JSON}};
+const models = {
+  openai: {{MODEL_OPENAI_ENABLED}},
+  anthropic: {{MODEL_ANTHROPIC_ENABLED}},
+};
+const clientSupport = {
+  codexHooks: {{CLIENT_CODEX_HOOKS_ENABLED}},
+  claudeRules: {{CLIENT_CLAUDE_RULES_ENABLED}},
+};
+const harnessRepoNameError = "repo folder name: expected";
+const missingEntryPrefix = "missing ";
+const repoBaseFiles = [
+  "README.md",
+  "ai/AGENTS.md",
+  "ai/HUB.md",
+  "ai/context.md",
+  "ai/HARNESS.md",
+  "ai/HARNESS-ENGINEERING.md",
+  "ai/READINESS.md",
+  "ai/QUALITY.md",
+  "ai/DECISIONS.md",
+  "ai/PRODUCT-SUMMARY.md",
+  "ai/PRODUCT.md",
+  "ai/ARCHITECTURE.md",
+  "ai/DESIGN.md",
+  "ai/WORKFLOW.md",
+  "ai/VERSIONING.md",
+  "ai/CODEX-HOOKS.md",
+  "ai/RUNNER-SAFETY.md",
+  "ai/RUNNER-READINESS.md",
+  "ai/AGENT-GARBAGE-COLLECTION.md",
+  "ai/knowledge-manifest.json",
+  "ai/workspace/REPOS.md",
+  "ai/workspace/SYSTEM-MAP.md",
+  "ai/workspace/SESSION-BOOTSTRAP.md",
+  "ai/workspace/LOCAL-STACK.md",
+  "ai/workspace/TEST-STRATEGY.md",
+  "ai/contracts/README.md",
+  "ai/templates/README.md",
+  "ai/skills/README.md",
+  "ai/specs/README.md",
+  "scripts/bootstrap-workspace.mjs",
+  "scripts/check-workspace.mjs",
+  "scripts/validate-governance.mjs",
+  "scripts/check-readiness.mjs",
+  "scripts/check-task-template.mjs",
+  "scripts/check-issue-template.mjs",
+  "scripts/check-knowledge-manifest.mjs",
+  "scripts/check-plans.mjs",
+  "scripts/check-review-skills.mjs",
+  "scripts/check-garbage-collection.mjs",
+  "scripts/check-contract-manifests.mjs",
+  "scripts/generate-html-views.mjs",
+  "scripts/check-html-views.mjs",
+  "scripts/bootstrap-codex-worktree.mjs",
+  "scripts/check-worktrees.mjs",
+  "scripts/check-worktree-bootstrap-fixtures.mjs",
+];
+const openaiRepoFiles = ["AGENTS.md", "ai/model-overlays/openai/AGENTS.md", "scripts/check-overlay-drift.mjs"];
+const anthopicRepoFiles = [
+  "CLAUDE.md",
+  ".claude/CLAUDE.md",
+  ".claude/settings.json",
+  "ai/model-overlays/anthropic/CLAUDE.md",
+  "scripts/check-claude-compatibility.mjs",
+  "scripts/check-overlay-drift.mjs",
+];
+const codexRepoFiles = [".codex/hooks.json", "scripts/check-codex-hooks.mjs", "scripts/hooks/codex-hook.mjs"];
+const claudeRulesRepoFiles = [".claude/rules/harness-client-surfaces.md"];
+const workspaceOpenaiFiles = ["AGENTS.md"];
+const workspaceAnthropicFiles = ["CLAUDE.md", ".claude/CLAUDE.md", ".claude/settings.json"];
+const workspaceClaudeRulesFiles = [".claude/rules/harness-client-surfaces.md"];
+const CLAUDE_MD = "CLAUDE.md";
+
+const repoRequiredFiles = [...repoBaseFiles];
+
+if (models.openai) {
+  repoRequiredFiles.push(...openaiRepoFiles);
+}
+
+if (models.anthropic) {
+  repoRequiredFiles.push(...anthopicRepoFiles);
+}
+
+if (clientSupport.codexHooks) {
+  repoRequiredFiles.push(...codexRepoFiles);
+}
+
+if (clientSupport.claudeRules) {
+  repoRequiredFiles.push(...claudeRulesRepoFiles);
+}
+
+const workspaceRequiredFiles = [];
+if (models.openai) workspaceRequiredFiles.push(...workspaceOpenaiFiles);
+if (models.anthropic) workspaceRequiredFiles.push(...workspaceAnthropicFiles);
+if (clientSupport.claudeRules) workspaceRequiredFiles.push(...workspaceClaudeRulesFiles);
+
+async function exists(filePath) {
+  try {
+    await access(filePath, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function collectMissing(basePath, relativePaths, prefix) {
+  const missing = [];
+  for (const relativePath of relativePaths) {
+    if (!(await exists(path.join(basePath, relativePath)))) {
+      missing.push(`${prefix}:${relativePath}`);
+    }
+  }
+  return missing;
+}
+
+async function readIfExists(filePath) {
+  if (!(await exists(filePath))) return null;
+  return readFile(filePath, "utf8");
+}
+
+async function collectHarnessRoutingIssue({ basePath, relativePath, expectedHarnessRoot }) {
+  const pointerPath = path.join(basePath, relativePath);
+  const pointerContent = await readIfExists(pointerPath);
+  if (pointerContent === null) return `${relativePath} missing.`;
+  return assertReferencesHarnessRoot({
+    pointerPath: relativePath,
+    pointerContent,
+    consumerRoot: basePath,
+    expectedHarnessRoot,
+    models,
+  });
+}
+
+async function collectClaudeMemoryRoutingIssue({ basePath, relativePath }) {
+  const pointerPath = path.join(basePath, relativePath);
+  const pointerContent = await readIfExists(pointerPath);
+  if (pointerContent === null) return `${relativePath} missing.`;
+  if (!pointerContent.includes("../CLAUDE.md")) {
+    return `${relativePath} must route through ../CLAUDE.md.`;
+  }
+  return assertReferencesHarnessRoot({
+    pointerPath: relativePath,
+    pointerContent,
+    consumerRoot: basePath,
+    expectedHarnessRoot: repoRoot,
+    models,
+    requireHarnessReference: false,
+  });
+}
+
+async function main() {
+  const missing = [];
+  if (path.basename(repoRoot) !== harnessRepoName) {
+    missing.push(`${harnessRepoNameError} ${harnessRepoName}, found ${path.basename(repoRoot)}`);
+  }
+
+  missing.push(...(await collectMissing(repoRoot, repoRequiredFiles, "repo")));
+  missing.push(...(await collectMissing(workspaceRoot, workspaceRequiredFiles, "workspace")));
+
+  for (const consumer of consumers) {
+    const consumerRoot = path.resolve(workspaceRoot, consumer.workspacePath);
+    if (!(await exists(consumerRoot))) {
+      missing.push(`consumer:${consumer.name}:missing repo at ${consumerRoot}`);
+      continue;
+    }
+    if (models.openai) {
+      const issue = await collectHarnessRoutingIssue({ basePath: workspaceRoot, relativePath: "AGENTS.md", expectedHarnessRoot: repoRoot });
+      if (issue) missing.push(`workspace:${issue}`);
+    }
+    if (models.anthropic) {
+      const issue = await collectHarnessRoutingIssue({ basePath: workspaceRoot, relativePath: CLAUDE_MD, expectedHarnessRoot: repoRoot });
+      if (issue) missing.push(`workspace:${issue}`);
+      const memoryIssue = await collectClaudeMemoryRoutingIssue({ basePath: workspaceRoot, relativePath: ".claude/CLAUDE.md" });
+      if (memoryIssue) missing.push(`workspace:${memoryIssue}`);
+    }
+    if (models.openai) {
+      const issue = await collectHarnessRoutingIssue({ basePath: consumerRoot, relativePath: "AGENTS.md", expectedHarnessRoot: repoRoot });
+      if (issue) missing.push(`consumer:${consumer.name}:${issue}`);
+    }
+    if (models.anthropic) {
+      const issue = await collectHarnessRoutingIssue({ basePath: consumerRoot, relativePath: CLAUDE_MD, expectedHarnessRoot: repoRoot });
+      if (issue) missing.push(`consumer:${consumer.name}:${issue}`);
+      const memoryIssue = await collectClaudeMemoryRoutingIssue({ basePath: consumerRoot, relativePath: ".claude/CLAUDE.md" });
+      if (memoryIssue) missing.push(`consumer:${consumer.name}:${memoryIssue}`);
+    }
+  }
+
+  if (missing.length > 0) {
+    console.error("Workspace bootstrap check failed.");
+    for (const item of missing) console.error(`- ${item}`);
+    process.exit(1);
+  }
+
+  console.log("Workspace layout check passed.");
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/template/scripts/check-worktree-bootstrap-fixtures.mjs.tpl

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+
+import assert from "node:assert/strict";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  buildRepairPlan,
+  classifyWorktreeBootstrap,
+  models,
+  parseWorktreeListPorcelain,
+  requiredPointerFiles,
+  renderPointerFile,
+} from "./lib/worktree-bootstrap.mjs";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const harnessRoot = "/workspace/{{HARNESS_REPO_NAME}}";
+const consumerRoot = "/workspace/{{PRIMARY_CONSUMER_NAME}}";
+const workspaceAgentsPath = "AGENTS.md";
+const workspaceClaudePath = "CLAUDE.md";
+const workspaceCodexPath = ".codex/hooks.json";
+const stateValid = "valid";
+const stateMissing = "missing";
+const stateStaleRelative = "stale_relative";
+const stateWrongHarnessRoot = "wrong_harness_root";
+const stateUnsupportedRepo = "unsupported_repo";
+const stateMissingPath = "missing_path";
+const stateDetached = "detached";
+const statePrunable = "prunable";
+const fixturePathPrefix = "scripts/fixtures/worktrees";
+const fixturesMissingPathSuffix = "missing-path";
+const tempConsumerRoot = "/tmp/{{PRIMARY_CONSUMER_NAME}}";
+const testCaseTemplateConsumer = "{{PRIMARY_CONSUMER_NAME}}";
+const invalidHarnessRoot = "Read ../{{HARNESS_REPO_NAME}}/AGENTS.md before editing.";
+const wrongHarnessRootPointer = `Read /other/{{HARNESS_REPO_NAME}}/AGENTS.md before editing.`;
+const harnessFiles = new Set([
+  ...(models.openai ? ["AGENTS.md"] : []),
+  ...(models.anthropic ? ["CLAUDE.md"] : []),
+  "ai/AGENTS.md",
+  "ai/HUB.md",
+  "ai/context.md",
+]);
+
+function files(entries) {
+  return [...requiredPointerFiles, workspaceCodexPath].map((relativePath) => ({
+    relativePath,
+    exists: Object.hasOwn(entries, relativePath),
+    content: entries[relativePath] ?? "",
+  }));
+}
+
+async function fileIsFile(filePath) {
+  const relativePath = path.relative(harnessRoot, filePath).replaceAll(path.sep, "/");
+  return harnessFiles.has(relativePath);
+}
+
+const validAgentPointer = `Read ${harnessRoot}/AGENTS.md before editing.`;
+const validClaudePointer = `Read ${harnessRoot}/CLAUDE.md before editing.`;
+const mixedAgentPointer = models.openai
+  ? `Read ${harnessRoot}/AGENTS.md and ${harnessRoot}/ai/MISSING.md before editing.`
+  : `Read ${harnessRoot}/CLAUDE.md and ${harnessRoot}/ai/MISSING.md before editing.`;
+const staleAgentPointer = invalidHarnessRoot;
+const validPointers = {
+  ...(models.openai ? { [workspaceAgentsPath]: validAgentPointer } : {}),
+  ...(models.anthropic ? { [workspaceClaudePath]: validClaudePointer } : {}),
+};
+const mixedPointers = models.openai
+  ? {
+      [workspaceAgentsPath]: mixedAgentPointer,
+      ...(models.anthropic ? { [workspaceClaudePath]: validClaudePointer } : {}),
+    }
+  : {
+      [workspaceClaudePath]: mixedAgentPointer,
+    };
+const stalePointers = Object.fromEntries(requiredPointerFiles.map((relativePath) => [relativePath, staleAgentPointer]));
+const wrongRootPointers = Object.fromEntries(requiredPointerFiles.map((relativePath) => [relativePath, wrongHarnessRootPointer]));
+
+const cases = [
+  { name: "valid", targetPath: consumerRoot, repoName: testCaseTemplateConsumer, targetExists: true, files: files(validPointers), expectedState: stateValid, expectedValid: true, expectedRepairable: false },
+  { name: "missing", targetPath: consumerRoot, repoName: testCaseTemplateConsumer, targetExists: true, files: files({}), expectedState: stateMissing, expectedValid: false, expectedRepairable: true },
+  { name: "stale_relative", targetPath: tempConsumerRoot, repoName: testCaseTemplateConsumer, targetExists: true, files: files(stalePointers), expectedState: stateStaleRelative, expectedValid: false, expectedRepairable: true },
+  { name: "wrong_harness_root", targetPath: consumerRoot, repoName: testCaseTemplateConsumer, targetExists: true, files: files(wrongRootPointers), expectedState: stateWrongHarnessRoot, expectedValid: false, expectedRepairable: true },
+  { name: "unsupported_repo", targetPath: "/workspace/random-app", repoName: null, targetExists: true, files: files({ [workspaceAgentsPath]: validAgentPointer }), expectedState: stateUnsupportedRepo, expectedValid: false, expectedRepairable: false },
+  { name: "missing_path", targetPath: path.join(repoRoot, `${fixturePathPrefix}/${fixturesMissingPathSuffix}`), repoName: testCaseTemplateConsumer, targetExists: false, files: files({}), expectedState: stateMissingPath, expectedValid: false, expectedRepairable: false },
+  { name: "detached", targetPath: tempConsumerRoot, repoName: testCaseTemplateConsumer, targetExists: true, files: files(validPointers), worktreeRecord: { detached: true }, expectedState: stateDetached, expectedValid: true, expectedRepairable: false },
+  { name: "prunable", targetPath: tempConsumerRoot, repoName: testCaseTemplateConsumer, targetExists: true, files: files({ [workspaceAgentsPath]: validAgentPointer }), worktreeRecord: { prunable: true }, expectedState: statePrunable, expectedValid: false, expectedRepairable: false },
+];
+
+for (const testCase of cases) {
+  const result = await classifyWorktreeBootstrap({
+    targetPath: testCase.targetPath,
+    targetExists: testCase.targetExists,
+    harnessRoot,
+    repoName: testCase.repoName,
+    files: testCase.files,
+    worktreeRecord: testCase.worktreeRecord ?? {},
+    fileIsFile,
+  });
+  assert.equal(result.state, testCase.expectedState, testCase.name);
+  assert.equal(result.valid, testCase.expectedValid, testCase.name);
+  assert.equal(result.repairable, testCase.expectedRepairable, testCase.name);
+  if (result.repairable) assert.equal(buildRepairPlan({ inspection: result, harnessRoot }).writes.length > 0, true, testCase.name);
+}
+
+const mixedResult = await classifyWorktreeBootstrap({
+  targetPath: consumerRoot,
+  targetExists: true,
+  harnessRoot,
+  repoName: testCaseTemplateConsumer,
+  files: files(mixedPointers),
+  fileIsFile,
+});
+assert.equal(mixedResult.valid, false, "mixed_references");
+assert.equal(mixedResult.repairable, true, "mixed_references");
+assert.equal(mixedResult.state, stateMissing, "mixed_references");
+
+const pointerPattern = new RegExp(`{{HARNESS_REPO_NAME}}/${models.openai ? "AGENTS" : "CLAUDE"}\\.md`);
+const worktreePorcelainOutput = "worktree /repo/main\nHEAD abc\nbranch refs/heads/main\n\nworktree /repo/detached\nHEAD def\ndetached\n";
+
+assert.match(renderPointerFile({ relativePath: requiredPointerFiles[0], harnessRoot, repoName: testCaseTemplateConsumer }), pointerPattern);
+assert.equal(parseWorktreeListPorcelain(worktreePorcelainOutput).length, 2);
+
+console.log("Worktree bootstrap fixture check passed.");

package/template/scripts/check-worktrees.mjs.tpl

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  canonicalRepos,
+  exists,
+  formatInspection,
+  inspectCheckout,
+  listGitWorktrees,
+} from "./lib/worktree-bootstrap.mjs";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const workspaceRoot = path.resolve(repoRoot, "..");
+const includeCanonicalArg = "--include-canonical";
+const includeNoWorktreeListArg = "--no-worktree-list";
+const strictArg = "--strict";
+const canonicalInspectionSource = "canonical";
+const worktreeInspectionSource = "worktree";
+const noTargetsMessage = "No worktree bootstrap targets selected. Use --include-canonical or allow git worktree discovery.";
+
+const args = new Set(process.argv.slice(2));
+const includeCanonical = args.has(includeCanonicalArg);
+const includeWorktreeList = !args.has(includeNoWorktreeListArg);
+const strict = args.has(strictArg);
+
+const inspections = [];
+if (includeCanonical) {
+  for (const repoName of canonicalRepos) {
+    const inspection = await inspectCheckout({ targetPath: path.join(workspaceRoot, repoName), harnessRoot: repoRoot });
+    inspection.source = canonicalInspectionSource;
+    inspections.push(inspection);
+  }
+}
+
+if (includeWorktreeList) {
+  for (const repoName of canonicalRepos) {
+    const canonicalPath = path.join(workspaceRoot, repoName);
+    if (!(await exists(canonicalPath))) continue;
+    let records = [];
+    try {
+      records = await listGitWorktrees(canonicalPath);
+    } catch {
+      continue;
+    }
+    for (const record of records) {
+      if (includeCanonical && path.resolve(record.path) === path.resolve(canonicalPath)) continue;
+      const inspection = await inspectCheckout({ targetPath: record.path, harnessRoot: repoRoot, worktreeRecord: record });
+      inspection.source = worktreeInspectionSource;
+      inspections.push(inspection);
+    }
+  }
+}
+
+if (inspections.length === 0) {
+  console.log(noTargetsMessage);
+  process.exit(0);
+}
+
+console.log("Worktree bootstrap check:");
+for (const inspection of inspections) {
+  console.log(`- ${formatInspection(inspection, { harnessRoot: repoRoot }).replaceAll("\n", "\n  ")}`);
+}
+
+const blocking = strict ? inspections.filter((inspection) => !inspection.valid) : inspections.filter((inspection) => inspection.source === canonicalInspectionSource && !inspection.valid);
+if (blocking.length > 0) {
+  console.error(`Worktree bootstrap check found ${blocking.length} blocking issue(s).`);
+  process.exit(1);
+}

package/template/scripts/fixtures/worktrees/README.md.tpl

@@ -0,0 +1,4 @@
+# Worktree Fixtures
+
+This directory documents fixture intent for `check-worktree-bootstrap-fixtures.mjs`.
+The checker uses in-memory fixtures so it can run without creating worktrees.