coding-agent-harness 1.0.2 → 1.0.4

package/scripts/lib/dashboard-data.mjs

@@ -56,7 +56,6 @@ function collectDashboardDocumentPaths(target) {
     "09-PLANNING/Module-Registry.md",
     "05-TEST-QA/Regression-SSoT.md",
     "05-TEST-QA/Cadence-Ledger.md",
-    "01-GOVERNANCE/Lessons-SSoT.md",
     "10-WALKTHROUGH/Closeout-SSoT.md",
   ]) {
     addDocsPath(relativePath);
@@ -104,7 +103,7 @@ function documentKind(source) {
   if (lower.includes("module-registry.md")) return "module-registry";
   if (lower.includes("regression-ssot.md")) return "regression-ssot";
   if (lower.includes("cadence-ledger.md")) return "cadence-ledger";
-  if (lower.includes("lessons-ssot.md")) return "lessons-ssot";
+  if (/\/01-governance\/lessons\/[^/]+\.md$/i.test(lower)) return "lesson-detail";
   if (lower.endsWith("/progress.md")) return "task-progress";
   if (lower.endsWith("/brief.md")) return "task-brief";
   if (lower.endsWith("/review.md")) return "task-review";
@@ -200,6 +199,7 @@ export function collectGraph(status, tables = { tables: [] }) {
 }
 
 export function categorizeWarning(message) {
+  if (/governance-table-entropy/i.test(message)) return "Governance Table Boundary";
   if (/missing execution_strategy\.md|missing visual_(?:map|roadmap)\.md|Visual (?:Map|Roadmap)/i.test(message)) return "Plan Contract Missing";
   if (/legacy-compat|adoption-needed|legacy check/i.test(message)) return "Adoption Advice";
   if (/Evidence|evidence/i.test(message)) return "Missing Evidence";
@@ -213,6 +213,7 @@ function warningType(message) {
   if (/missing visual_map\.md|Visual Map/i.test(message)) return "missing-visual-map";
   if (/missing visual_roadmap\.md|Visual Roadmap/i.test(message)) return "missing-visual-roadmap";
   if (/Reviewer Identity|Confidence Challenge|Final Confidence Basis|Evidence Checked/i.test(message)) return "review-schema-gap";
+  if (/governance-table-entropy/i.test(message)) return "governance-table-entropy";
   if (/Evidence|evidence/i.test(message)) return "missing-evidence";
   if (/missing required file/i.test(message)) return "legacy-reference-gap";
   if (/legacy-compat|legacy check|adoption-needed/i.test(message)) return "capability-adoption";
@@ -231,6 +232,7 @@ function warningScope(message) {
 
 function warningPhase(type, scope) {
   if (type === "capability-adoption") return "baseline";
+  if (type === "governance-table-entropy") return "global-table-boundary";
   if (type === "missing-brief" || type === "missing-execution-strategy" || type === "missing-visual-map" || type === "missing-visual-roadmap") return "active-task-contracts";
   if (scope === "module") return "module-classification";
   if (type === "review-schema-gap" || type === "missing-evidence") return "review-evidence";
@@ -240,6 +242,7 @@ function warningPhase(type, scope) {
 
 function warningFixability(type, scope) {
   if (["missing-brief", "missing-execution-strategy", "missing-visual-map", "missing-visual-roadmap"].includes(type)) return "guided";
+  if (type === "governance-table-entropy") return "manual";
   if (type === "legacy-reference-gap" || scope === "reference") return "template";
   if (type === "capability-adoption") return "decision";
   if (type === "review-schema-gap" || type === "missing-evidence") return "human-evidence";
@@ -248,6 +251,7 @@ function warningFixability(type, scope) {
 
 function warningPriority(type, scope, message) {
   if (/fail|invalid|blocked/i.test(message) || type === "schema-drift") return "P1";
+  if (type === "governance-table-entropy") return /legacy-report-only/i.test(message) ? "P3" : "P2";
   if (["missing-brief", "missing-execution-strategy", "missing-visual-map", "missing-visual-roadmap"].includes(type) && scope === "task") return "P2";
   if (type === "review-schema-gap" || type === "missing-evidence") return "P2";
   if (type === "capability-adoption") return "P3";
@@ -284,19 +288,24 @@ function summarizeWarnings(warnings) {
 }
 
 export function collectAdoption(status) {
-  const warnings = status.checkState.details.warnings.flatMap((message) => splitWarningMessage(message)).map((message, index) => {
+  const dashboardMessages = [
+    ...(status.checkState.details.warnings || []),
+    ...(status.checkState.details.failures || []).filter((message) => /governance-table-entropy/i.test(message)),
+  ];
+  const warnings = dashboardMessages.flatMap((message) => splitWarningMessage(message)).map((message, index) => {
     const type = warningType(message);
     const scope = warningScope(message);
     const affectedPaths = warningAffectedPaths(message);
+    const stableSuffix = type === "governance-table-entropy" ? `-${stableWarningIdPart(governanceWarningRowKey(message))}` : "";
     return {
-      id: `AD-${String(index + 1).padStart(3, "0")}`,
+      id: `AD-${String(index + 1).padStart(3, "0")}${stableSuffix}`,
       category: categorizeWarning(message),
       type,
       scope,
       priority: warningPriority(type, scope, message),
       phase: warningPhase(type, scope),
       fixability: warningFixability(type, scope),
-      status: "open",
+      status: /legacy-report-only/i.test(message) ? "legacy-report-only" : "open",
       confidence: warningConfidence(message),
       severity: status.mode === "legacy-compat" ? "advice" : "warning",
       title: warningTitle(message),
@@ -330,6 +339,18 @@ export function collectAdoption(status) {
   };
 }
 
+function governanceWarningRowKey(message) {
+  const match = String(message || "").match(/\brow\s+([^:]+)/i);
+  return match ? match[1].trim() : "global-table";
+}
+
+function stableWarningIdPart(value) {
+  return String(value || "global-table")
+    .replace(/[^A-Za-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80) || "global-table";
+}
+
 export function splitWarningMessage(message) {
   return String(message || "")
     .split(/\n-\s+/)
@@ -338,6 +359,7 @@ export function splitWarningMessage(message) {
 }
 
 function warningTitle(message) {
+  if (/governance-table-entropy/i.test(message)) return "Global table boundary";
   if (/missing execution_strategy\.md/i.test(message)) return "Missing execution strategy";
   if (/missing visual_map\.md|Visual Map/i.test(message)) return "Missing visual map";
   if (/missing visual_roadmap\.md|Visual Roadmap/i.test(message)) return "Missing legacy visual roadmap";
@@ -354,6 +376,7 @@ function warningAffected(message) {
 }
 
 function warningAction(message) {
+  if (/governance-table-entropy/i.test(message)) return "Move local detail to module/task docs; keep the global row to summary, state, route, and audit result.";
   if (/execution_strategy\.md/i.test(message)) return "Add standalone execution strategy file.";
   if (/visual_map\.md|Visual Map/i.test(message)) return "Add standalone visual map file.";
   if (/visual_roadmap\.md|Visual Roadmap/i.test(message)) return "Rewrite legacy visual_roadmap.md into canonical visual_map.md.";
@@ -377,7 +400,7 @@ export function writeDashboardFolder(outDir, targetInput, options = {}) {
   const registry = readCapabilityRegistry(target);
   const locale = options.localeOverride || registry.locale;
   const bundle = buildDashboardBundle(targetInput, options);
-  return writeDashboardDirectory(outDir, bundle, { repoRoot, projectRoot: target.projectRoot, docsRoot: target.docsRoot, locale, workbenchRuntime: options.workbenchRuntime === true });
+  return writeDashboardDirectory(outDir, bundle, { repoRoot, projectRoot: target.projectRoot, docsRoot: target.docsRoot, locale, workbenchRuntime: options.workbenchRuntime === true, recoverGeneratedDashboard: options.recoverGeneratedDashboard === true });
 }
 
 export function writeDashboardSingleFile(outFile, targetInput, options = {}) {

package/scripts/lib/dashboard-workbench.mjs

@@ -5,13 +5,14 @@ import http from "node:http";
 import path from "node:path";
 import { URL } from "node:url";
 import { confirmTaskReview } from "./task-lifecycle.mjs";
+import { createLessonSedimentationTask } from "./task-lesson-sedimentation.mjs";
 import { normalizeTarget } from "./core-shared.mjs";
 import { collectTasks } from "./task-scanner.mjs";
 import { writeDashboardFolder } from "./dashboard-data.mjs";
 
 const jsonHeaders = { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" };
 
-export async function serveDashboardWorkbench(outDir, targetInput, { host = "127.0.0.1", port = 0, localeOverride = "", autoRefresh = false, open = false, label = "dashboard workbench" } = {}) {
+export async function serveDashboardWorkbench(outDir, targetInput, { host = "127.0.0.1", port = 0, localeOverride = "", autoRefresh = false, open = false, label = "dashboard workbench", recoverGeneratedDashboard = false } = {}) {
   if (host !== "127.0.0.1") throw new Error("dashboard workbench only supports --host 127.0.0.1");
   const target = normalizeTarget(targetInput);
   const outputDir = path.resolve(outDir);
@@ -19,7 +20,7 @@ export async function serveDashboardWorkbench(outDir, targetInput, { host = "127
   const options = localeOverride ? { localeOverride } : {};
   let snapshotVersion = Date.now();
   const regenerate = () => {
-    writeDashboardFolder(outputDir, targetInput, { ...options, workbenchRuntime: true });
+    writeDashboardFolder(outputDir, targetInput, { ...options, workbenchRuntime: true, recoverGeneratedDashboard });
     snapshotVersion = Date.now();
   };
   regenerate();
@@ -35,7 +36,7 @@ export async function serveDashboardWorkbench(outDir, targetInput, { host = "127
         writeJson(response, 200, {
           mode: "workbench",
           csrfToken,
-          writableActions: ["review-complete"],
+          writableActions: ["review-complete", "lesson-sedimentation-task"],
           target: target.projectRoot,
           autoRefresh: autoRefresh === true,
           snapshotVersion,
@@ -52,8 +53,8 @@ export async function serveDashboardWorkbench(outDir, targetInput, { host = "127
           writeJson(response, 404, { error: "Task not found" });
           return;
         }
-        if (!isTaskInReviewStage(task)) {
-          writeJson(response, 409, { error: "Review completion is only available while the task is in review." });
+        if (!isTaskInReviewQueue(task)) {
+          writeJson(response, 409, reviewQueueRejectionPayload(task));
           return;
         }
         if (task.reviewStatus === "confirmed") {
@@ -71,14 +72,36 @@ export async function serveDashboardWorkbench(outDir, targetInput, { host = "127
         return;
       }
 
+      if (requestUrl.pathname === "/api/tasks/lesson-sedimentation" && request.method === "POST") {
+        assertTrustedWorkbenchRequest(request, { origin, csrfToken });
+        const body = await readJsonBody(request);
+        const taskId = String(body.taskId || "");
+        const candidateId = String(body.candidateId || "");
+        const task = collectTasks(target).find((item) => item.id === taskId);
+        if (!task) {
+          writeJson(response, 404, { error: "Task not found" });
+          return;
+        }
+        if (!candidateId) {
+          writeJson(response, 400, { error: "Missing lesson candidate id" });
+          return;
+        }
+        const result = createLessonSedimentationTask(target.projectRoot, taskId, candidateId, {
+          title: body.title || "",
+        });
+        regenerate();
+        writeJson(response, 200, result);
+        return;
+      }
+
       if (request.method !== "GET" && request.method !== "HEAD") {
         writeJson(response, 405, { error: "Method not allowed" });
         return;
       }
       serveStaticFile(response, outputDir, requestUrl.pathname, request.method === "HEAD");
     } catch (error) {
-      const status = /CSRF|Origin|Host/.test(error.message) ? 403 : 400;
-      writeJson(response, status, { error: error.message });
+      const status = error.status || (/CSRF|Origin|Host/.test(error.message) ? 403 : 400);
+      writeJson(response, status, errorPayload(error));
     }
   });
 
@@ -103,11 +126,20 @@ export async function serveDashboardWorkbench(outDir, targetInput, { host = "127
   await new Promise(() => {});
 }
 
-function isTaskInReviewStage(task) {
-  const state = task?.state || "";
-  const lifecycle = task?.lifecycleState || "";
-  if (["not_started", "planned", "in_progress"].includes(state)) return false;
-  return state === "review" || ["in_review", "review-blocked"].includes(lifecycle);
+function isTaskInReviewQueue(task) {
+  return task?.reviewQueueState === "ready-to-confirm" && Array.isArray(task?.taskQueues) && task.taskQueues.includes("review");
+}
+
+function reviewQueueRejectionPayload(task) {
+  return {
+    error: "Review completion is only available for tasks in the review queue.",
+    reviewQueueState: task?.reviewQueueState || "unknown",
+    taskQueues: Array.isArray(task?.taskQueues) ? task.taskQueues : [],
+    queueReasons: Array.isArray(task?.queueReasons) ? task.queueReasons : [],
+    repairPrompt: task?.repairPrompt || "",
+    reviewStatus: task?.reviewStatus || "unknown",
+    taskId: task?.id || "",
+  };
 }
 
 function startPollingWatch(root, regenerate) {
@@ -202,6 +234,14 @@ function writeJson(response, status, payload) {
   response.end(`${JSON.stringify(payload)}\n`);
 }
 
+function errorPayload(error) {
+  const payload = { error: error.message };
+  if (error.code) payload.code = error.code;
+  if (Array.isArray(error.recovery) && error.recovery.length > 0) payload.recovery = error.recovery;
+  if (error.details) payload.details = error.details;
+  return payload;
+}
+
 function mimeType(filePath) {
   if (filePath.endsWith(".html")) return "text/html; charset=utf-8";
   if (filePath.endsWith(".js")) return "text/javascript; charset=utf-8";

package/scripts/lib/dashboard-writer.mjs

@@ -18,10 +18,11 @@ export function writeDashboardDirectory(outDir, bundle, options = {}) {
   const target = path.resolve(outDir);
   assertSafeDashboardTarget(target, options);
   if (fs.existsSync(target)) fs.rmSync(target, { recursive: true, force: true });
+  fs.mkdirSync(target, { recursive: true });
+  fs.writeFileSync(path.join(target, dashboardMarker), "generated dashboard directory\n");
   copyDashboardAssets(target, options);
   fs.writeFileSync(path.join(target, "assets/app.js"), readDashboardApp(dashboardTemplateRootForLocale(options.locale)));
   fs.writeFileSync(path.join(target, "index.html"), renderDashboardIndex(options.locale, options));
-  fs.writeFileSync(path.join(target, dashboardMarker), "generated dashboard directory\n");
   writeJsonFile(path.join(target, "data/status.json"), bundle.status);
   writeJsonFile(path.join(target, "data/tables.json"), bundle.tables);
   writeJsonFile(path.join(target, "data/documents.json"), bundle.documents);
@@ -156,12 +157,23 @@ function assertSafeDashboardTarget(target, options) {
   if (fs.existsSync(target)) {
     const entries = fs.readdirSync(target);
     const hasMarker = fs.existsSync(path.join(target, dashboardMarker));
-    if (entries.length > 0 && !hasMarker) {
+    const canRecoverGeneratedDashboard = options.recoverGeneratedDashboard === true && looksLikeGeneratedDashboardDirectory(target);
+    if (entries.length > 0 && !hasMarker && !canRecoverGeneratedDashboard) {
       throw new Error(`Refusing to overwrite non-dashboard directory: ${target}`);
     }
   }
 }
 
+function looksLikeGeneratedDashboardDirectory(target) {
+  return [
+    "index.html",
+    "README.md",
+    "assets/app.js",
+    "assets/dashboard-data.js",
+    "data/status.json",
+  ].every((relativePath) => fs.existsSync(path.join(target, relativePath)));
+}
+
 function dashboardTemplateRootForLocale(locale = "en-US") {
   return dashboardTemplateRoot;
 }

package/scripts/lib/git-status-summary.mjs

@@ -0,0 +1,46 @@
+import fs from "node:fs";
+import path from "node:path";
+import { inspectGit } from "./governance-sync.mjs";
+
+export function summarizeGitState(target) {
+  const state = inspectGit(target.projectRoot);
+  if (!state.inGit) {
+    return {
+      summary: {
+        inGit: false,
+        root: "",
+        dirty: false,
+        entries: [],
+        blocksCliAutoCommit: false,
+      },
+      warnings: [],
+    };
+  }
+  const targetRoot = real(target.projectRoot);
+  const gitRoot = real(state.gitRoot);
+  const rootMatches = gitRoot === targetRoot;
+  const entries = rootMatches ? state.entries.map((entry) => ({
+    path: entry.path,
+    index: entry.index,
+    worktree: entry.worktree,
+  })) : [];
+  const dirty = entries.length > 0;
+  const warnings = [];
+  if (dirty) {
+    warnings.push(`dirty-state: ${entries.length} uncommitted Git path(s) will block CLI-owned auto-commit; commit them or record owner/no-commit reason before lifecycle commands.`);
+  }
+  return {
+    summary: {
+      inGit: true,
+      root: rootMatches ? "TARGET:." : "outside-target",
+      dirty,
+      entries,
+      blocksCliAutoCommit: !rootMatches || dirty,
+    },
+    warnings,
+  };
+}
+
+function real(filePath) {
+  return fs.realpathSync(filePath);
+}

package/scripts/lib/governance-index-generator.mjs

@@ -0,0 +1,174 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  normalizeTarget,
+  readBundledTemplate,
+  todayDate,
+  toPosix,
+} from "./core-shared.mjs";
+import { splitMarkdownRow } from "./markdown-utils.mjs";
+import { collectTasks } from "./task-scanner.mjs";
+import {
+  beginGovernanceSync,
+  commitGovernanceSync,
+  moduleGeneratedIndexSurfaces,
+  releaseGovernanceSync,
+} from "./governance-sync.mjs";
+import { markdownCell } from "./task-lifecycle/text-utils.mjs";
+
+export function rebuildGovernanceIndexes(targetInput, { dryRun = false, archive = false, apply = false } = {}) {
+  const target = normalizeTarget(targetInput);
+  const effectiveApply = Boolean(apply && !dryRun);
+  const context = beginGovernanceSync(target, { operation: "governance rebuild", dryRun: !effectiveApply });
+  try {
+    const tasks = collectTasks(target)
+      .filter((task) => task.deletionState !== "deleted")
+      .sort((a, b) => String(a.id).localeCompare(String(b.id)));
+    const surfaces = [...governanceSurfaces(target, tasks), ...moduleGeneratedIndexSurfaces(target, tasks)];
+    const archiveDir = archive ? uniqueArchiveDir(target) : "";
+    const changes = surfaces.map((surface) => ({
+      surface: surface.surface,
+      destination: surface.relative,
+      action: surface.archiveOnly
+        ? apply ? "archive-legacy-governance-table" : "would-archive-legacy-governance-table"
+        : apply ? "rebuild-governance-index" : "would-rebuild-governance-index",
+      generatedRows: surface.rows.length,
+      archive: archive ? `${archiveDir}/${surface.relative}` : "",
+    }));
+
+    if (!effectiveApply) {
+      return { dryRun: true, archive, applied: false, archiveDir, changes };
+    }
+
+    const allowed = [];
+    for (const surface of surfaces) {
+      if (archive && fs.existsSync(surface.absolute)) {
+        const archivePath = path.join(target.projectRoot, archiveDir, surface.relative);
+        fs.mkdirSync(path.dirname(archivePath), { recursive: true });
+        fs.copyFileSync(surface.absolute, archivePath);
+        allowed.push(toPosix(path.relative(target.projectRoot, archivePath)));
+      }
+      if (surface.archiveOnly) {
+        if (archive && fs.existsSync(surface.absolute)) {
+          fs.rmSync(surface.absolute);
+          allowed.push(surface.relative);
+        }
+        continue;
+      }
+      fs.mkdirSync(path.dirname(surface.absolute), { recursive: true });
+      fs.writeFileSync(surface.absolute, surface.content);
+      allowed.push(surface.relative);
+    }
+
+    const commit = commitGovernanceSync(context, allowed, { message: "chore(harness): rebuild generated governance indexes" });
+    return { dryRun: false, archive, applied: true, archiveDir, changes, commit };
+  } finally {
+    releaseGovernanceSync(context);
+  }
+}
+
+function governanceSurfaces(target, tasks) {
+  return [
+    {
+      surface: "harness-ledger",
+      absolute: path.join(target.docsRoot, "Harness-Ledger.md"),
+      relative: toPosix(path.relative(target.projectRoot, path.join(target.docsRoot, "Harness-Ledger.md"))),
+      rows: tasks.map(ledgerRow),
+      content: replaceTableRows(readBundledTemplate("templates/ledger/Harness-Ledger.md"), /^ID$/i, tasks.map(ledgerRow)),
+    },
+    ...legacyFeatureSurfaces(target),
+  ];
+}
+
+function legacyFeatureSurfaces(target) {
+  return [
+    ["legacy-feature-ssot", path.join(target.docsRoot, "09-PLANNING/Feature-SSoT.md")],
+    ["legacy-private-feature-ssot", path.join(target.docsRoot, "09-PLANNING/Private-Feature-SSoT.md")],
+  ].filter(([, absolute]) => fs.existsSync(absolute)).map(([surface, absolute]) => ({
+    surface,
+    absolute,
+    relative: toPosix(path.relative(target.projectRoot, absolute)),
+    rows: [],
+    content: "",
+    archiveOnly: true,
+  }));
+}
+
+function replaceTableRows(content, headerPattern, rows) {
+  const lines = String(content || "").split(/\r?\n/);
+  for (let index = 0; index < lines.length - 1; index += 1) {
+    if (!lines[index].trim().startsWith("|")) continue;
+    const header = splitMarkdownRow(lines[index]);
+    if (!header.some((cell) => headerPattern.test(cell))) continue;
+    const separator = splitMarkdownRow(lines[index + 1]);
+    if (!separator.every((cell) => /^:?-{3,}:?$/.test(cell))) continue;
+    let end = index + 2;
+    while (end < lines.length && lines[end].trim().startsWith("|")) end += 1;
+    const fitted = rows.map((row) => fitRow(row, header.length));
+    lines.splice(index + 2, end - index - 2, ...fitted.map((row) => `| ${row.join(" | ")} |`));
+    return `${lines.join("\n").trimEnd()}\n`;
+  }
+  return `${String(content || "").trimEnd()}\n\n${rows.map((row) => `| ${row.join(" | ")} |`).join("\n")}\n`;
+}
+
+function fitRow(row, length) {
+  const next = row.map((cell) => markdownCell(cell));
+  while (next.length < length) next.push("");
+  return next.slice(0, length);
+}
+
+function ledgerRow(task) {
+  const plan = stripTarget(task.taskPlanPath || `${stripTarget(task.path)}/task_plan.md`);
+  const scope = task.module ? "module" : "task";
+  const moduleKey = task.module || "none";
+  return [
+    taskLedgerId(task),
+    scope,
+    moduleKey,
+    task.title || task.shortId || task.id,
+    mapLedgerState(task.state),
+    Array.isArray(task.taskQueues) && task.taskQueues.length ? task.taskQueues.join(",") : "none",
+    plan,
+    task.reviewStatus === "confirmed" ? stripTarget(task.reviewPath) : (task.reviewStatus || "pending"),
+    task.lessonCandidateDecisionComplete ? "checked" : (task.lessonCandidateStatus || "pending"),
+    task.walkthroughPath ? stripTarget(task.walkthroughPath) : (task.closeoutStatus || "pending"),
+    residual(task),
+    todayDate(),
+  ];
+}
+
+function residual(task) {
+  if (Array.isArray(task.stateConflicts) && task.stateConflicts.length) return `state-conflicts:${task.stateConflicts.length}`;
+  if (Array.isArray(task.materialIssues) && task.materialIssues.length) return `material-issues:${task.materialIssues.length}`;
+  return "none";
+}
+
+function taskLedgerId(task) {
+  return `HL-${taskSlug(task)}`;
+}
+
+function taskSlug(task) {
+  return String(task.shortId || task.id || "task").replace(/^TASKS\//, "").replace(/^MODULES\//, "").replace(/[^A-Za-z0-9-]+/g, "-").slice(0, 72);
+}
+
+function stripTarget(value) {
+  return String(value || "").replace(/^TARGET:/, "");
+}
+
+function mapLedgerState(state) {
+  if (state === "in_progress") return "active";
+  if (state === "review") return "review";
+  if (state === "done") return "closed";
+  if (state === "blocked") return "blocked";
+  return "planned";
+}
+
+function uniqueArchiveDir(target) {
+  const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(".", "-");
+  const base = `docs/01-GOVERNANCE/archive/generated-governance-tables/${stamp}`;
+  for (let index = 0; index < 100; index += 1) {
+    const candidate = index === 0 ? base : `${base}-${String(index).padStart(2, "0")}`;
+    if (!fs.existsSync(path.join(target.projectRoot, candidate))) return candidate;
+  }
+  throw new Error("Unable to allocate a unique governance table archive directory");
+}