coding-agent-harness 1.0.7 → 1.1.0

package/dist/lib/governance-sync.mjs

@@ -1,15 +1,18 @@
-// @ts-nocheck
 // Governance sync spans dynamic target metadata and Git porcelain until the governance domain model PR.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import crypto from "node:crypto";
 import { spawnSync } from "node:child_process";
-import { readBundledTemplate, readFileSafe, readJsonSafe, repoRoot, todayDate, toPosix, visualMapFile } from "./core-shared.mjs";
+import { readBundledTemplate, readFileSafe, readJsonSafe, repoRoot, todayDate, toPosix } from "./core-shared.mjs";
 import { collectTasks } from "./task-scanner.mjs";
 import { appendMarkdownTableRow, firstColumn, fitMarkdownTableRow, splitMarkdownRow, upsertMarkdownTableRow } from "./markdown-utils.mjs";
 import { resolveHarnessPaths } from "./harness-paths.mjs";
+import { moduleRegistryViewPath, renderModuleRegistryView } from "./module-registry.mjs";
 export class GovernanceSyncError extends Error {
+    code;
+    details;
+    recovery;
     constructor(message, { code = "governance-sync-failed", details = {}, recovery = [] } = {}) {
         super(message);
         this.name = "GovernanceSyncError";
@@ -18,7 +21,7 @@ export class GovernanceSyncError extends Error {
         this.recovery = recovery;
     }
 }
-export function beginGovernanceSync(target, { operation = "governance-sync", dryRun = false, allowDirtyWorktree = false, allowedRelativePaths = [] } = {}) {
+export function beginGovernanceSync(target, { operation = "governance-sync", dryRun = false, allowDirtyWorktree = false, allowedRelativePaths = [], allowDirtyWriteScope = false } = {}) {
     if (dryRun)
         return { target, dryRun, operation, git: inspectGit(target.projectRoot), lockPath: "", active: false };
     const lockPath = path.join(target.projectRoot, ".harness/locks/governance-sync.lock");
@@ -45,7 +48,7 @@ export function beginGovernanceSync(target, { operation = "governance-sync", dry
         }
         if (gitState.entries.length > 0 && allowDirtyWorktree) {
             try {
-                assertDirtyCompatibleWithWriteScope(gitState.entries, allowed);
+                assertDirtyCompatibleWithWriteScope(gitState.entries, allowed, { allowDirtyWriteScope });
             }
             catch (error) {
                 releaseGovernanceSync({ lockPath, active: true });
@@ -79,7 +82,7 @@ function acquireGovernanceSyncLock(lockPath, target, { operation }) {
         catch (error) {
             if (fd !== null)
                 fs.closeSync(fd);
-            if (error?.code === "EEXIST" && attempt === 0 && removeStaleGovernanceSyncLock(lockPath))
+            if (isNodeError(error) && error.code === "EEXIST" && attempt === 0 && removeStaleGovernanceSyncLock(lockPath))
                 continue;
             throw governanceLockExistsError(lockPath, error);
         }
@@ -92,14 +95,15 @@ function removeStaleGovernanceSyncLock(lockPath) {
         return false;
     if (lock.host !== governanceLockHost())
         return false;
-    if (!Number.isInteger(lock?.pid) || lock.pid <= 0)
+    const pid = lock.pid;
+    if (!Number.isInteger(pid) || !pid || pid <= 0)
         return false;
     try {
-        process.kill(lock.pid, 0);
+        process.kill(pid, 0);
         return false;
     }
     catch (error) {
-        if (error?.code !== "ESRCH")
+        if (!isNodeError(error) || error.code !== "ESRCH")
             return false;
     }
     if (readFileSafe(lockPath) !== lockContent)
@@ -113,7 +117,7 @@ function governanceLockHost() {
 function governanceLockExistsError(lockPath, error) {
     return new GovernanceSyncError("Governance sync lock already exists; refusing concurrent registry writes.", {
         code: "governance-lock-exists",
-        details: { lockPath, error: error?.message || String(error) },
+        details: { lockPath, error: errorMessage(error) },
         recovery: [
             `Inspect ${lockPath}.`,
             "If no process owns the lock, remove it manually and retry.",
@@ -149,7 +153,7 @@ export function commitGovernanceSync(context, allowedRelativePaths, { message =
             assertNoUnexpectedOutsideChanges(context.target.projectRoot, allowed, context.initialDirtyEntries || []);
         }
         catch (error) {
-            outsideChanges = error.details || null;
+            outsideChanges = error instanceof GovernanceSyncError ? error.details : null;
         }
         throw new GovernanceSyncError("Governance sync wrote files but Git commit failed.", {
             code: "governance-git-commit-failed",
@@ -172,15 +176,17 @@ export function syncTaskGovernance(target, task, { event = "new-task", state = "
     const ledger = syncLedgerRow(target, task, { event, state, message, planPath, reviewPath, dryRun });
     if (ledger)
         changes.push(ledger);
-    if (task.module) {
-        const moduleRegistry = syncModuleRegistryRow(target, task, { state, planPath, dryRun });
+    const moduleKey = task.module;
+    if (moduleKey) {
+        const taskWithModule = { ...task, module: moduleKey };
+        const moduleRegistry = syncModuleRegistryView(target, { dryRun });
         if (moduleRegistry)
             changes.push(moduleRegistry);
-        changes.push(...syncModuleGeneratedIndexes(target, task.module, { task, dryRun }).changes);
+        changes.push(...syncModuleGeneratedIndexes(target, moduleKey, { task: taskWithModule, dryRun }).changes);
     }
     return { changes };
 }
-export function syncModuleStepGovernance(target, { moduleKey, stepId, state, dryRun = false } = {}) {
+export function syncModuleStepGovernance(target, { moduleKey, stepId, state, dryRun = false }) {
     const changes = [];
     const harnessPaths = activeHarnessPaths(target);
     const ledgerPath = harnessPaths.ledgerPath;
@@ -235,31 +241,12 @@ function syncLedgerRow(target, task, { event, state, message, planPath, reviewPa
     }
     return { destination: relative, action: dryRun ? "would-sync-governance" : "sync-governance", surface: "harness-ledger" };
 }
-function syncModuleRegistryRow(target, task, { state, planPath, dryRun }) {
-    const harnessPaths = activeHarnessPaths(target);
-    const registryPath = path.join(harnessPaths.modulesRoot, "Module-Registry.md");
-    ensureFileFromTemplate(registryPath, "templates/ssot/Module-Registry.md", { dryRun });
+function syncModuleRegistryView(target, { dryRun }) {
+    const registryPath = moduleRegistryViewPath(target);
     const relative = toPosix(path.relative(target.projectRoot, registryPath));
     if (!dryRun) {
-        const content = readFileSafe(registryPath);
-        const moduleKey = task.module;
-        const moduleDirRelative = toPosix(path.relative(target.projectRoot, path.join(harnessPaths.modulesRoot, moduleKey)));
-        const modulePlan = `${moduleDirRelative}/module_plan.md`;
-        const row = [
-            `M-${moduleKey.toUpperCase().replace(/[^A-Z0-9]+/g, "-")}`,
-            moduleKey,
-            `${moduleDirRelative}/**`,
-            "coordinator",
-            state === "planned" ? "reserved" : mapModuleState(state),
-            `codex/${moduleKey}`,
-            modulePlan,
-            "none",
-            "none",
-            planPath,
-            "none",
-            todayDate(),
-        ];
-        fs.writeFileSync(registryPath, upsertMarkdownTableRow(content, /^ID$/i, (header, existing) => rowMatchesModule(header, existing, moduleKey, modulePlan), row));
+        fs.mkdirSync(path.dirname(registryPath), { recursive: true });
+        fs.writeFileSync(registryPath, renderModuleRegistryView(target));
     }
     return { destination: relative, action: dryRun ? "would-sync-governance" : "sync-governance", surface: "module-registry" };
 }
@@ -282,7 +269,7 @@ function syncModuleGeneratedIndexes(target, moduleKey, { task = null, dryRun = f
 }
 export function moduleGeneratedIndexSurfaces(target, tasks = collectTasks(target)) {
     const harnessPaths = activeHarnessPaths(target);
-    const modules = [...new Set((tasks || []).map((task) => task.module).filter(Boolean))].sort();
+    const modules = [...new Set((tasks || []).map((task) => task.module).filter(isNonEmptyString))].sort();
     const surfaces = [];
     for (const moduleKey of modules) {
         const moduleTasks = (tasks || [])
@@ -290,11 +277,11 @@ export function moduleGeneratedIndexSurfaces(target, tasks = collectTasks(target
             .sort((a, b) => String(stripDatePrefix(a.shortId || a.id)).localeCompare(String(stripDatePrefix(b.shortId || b.id))));
         const moduleDir = path.join(harnessPaths.modulesRoot, moduleKey);
         const modulePlanPath = path.join(moduleDir, "module_plan.md");
-        const moduleVisualPath = path.join(moduleDir, visualMapFile);
         const stepRows = moduleTasks.map((task, index) => {
             const stepId = moduleStepId(task);
-            const previous = index === 0 ? "none" : moduleStepId(moduleTasks[index - 1]);
-            return [stepId, task.title || task.shortId || task.id, mapModuleState(task.state), stripTargetPrefix(task.taskPlanPath || `${stripTargetPrefix(task.path)}/task_plan.md`), previous];
+            const previousTask = moduleTasks[index - 1];
+            const previous = index === 0 || !previousTask ? "none" : moduleStepId(previousTask);
+            return [stepId, task.title || task.shortId || task.id || "task", mapModuleState(task.state), stripTargetPrefix(task.taskPlanPath || `${stripTargetPrefix(task.path)}/task_plan.md`), previous];
         });
         surfaces.push({
             surface: "module-plan-index",
@@ -303,20 +290,14 @@ export function moduleGeneratedIndexSurfaces(target, tasks = collectTasks(target
             rows: stepRows,
             content: replaceTableRows(existingOrTemplate(modulePlanPath, "templates/planning/module_plan.md"), /^Step ID$/i, stepRows),
         });
-        surfaces.push({
-            surface: "module-visual-index",
-            absolute: moduleVisualPath,
-            relative: toPosix(path.relative(target.projectRoot, moduleVisualPath)),
-            rows: stepRows,
-            content: renderModuleVisualMap(moduleKey, moduleTasks),
-        });
     }
     return surfaces;
 }
 function collectModuleTasks(target, moduleKey, task) {
-    const tasks = collectTasks(target).filter((candidate) => candidate.module === moduleKey);
-    if (task && !tasks.some((candidate) => stripTargetPrefix(candidate.taskPlanPath) === `${stripTargetPrefix(task.path)}/task_plan.md`)) {
-        tasks.push({
+    const tasks = collectTasks(target);
+    const moduleTasks = tasks.filter((candidate) => candidate.module === moduleKey);
+    if (task && !moduleTasks.some((candidate) => stripTargetPrefix(candidate.taskPlanPath) === `${stripTargetPrefix(task.path)}/task_plan.md`)) {
+        moduleTasks.push({
             ...task,
             module: moduleKey,
             state: task.state || "planned",
@@ -324,61 +305,7 @@ function collectModuleTasks(target, moduleKey, task) {
             completion: 0,
         });
     }
-    return tasks;
-}
-function renderModuleVisualMap(moduleKey, tasks) {
-    const rows = tasks.map((task, index) => {
-        const stepId = moduleStepId(task);
-        const previous = index === 0 ? "none" : moduleStepId(tasks[index - 1]);
-        const state = mapPhaseState(task.state);
-        const completion = Number.isInteger(task.completion) ? task.completion : state === "done" ? 100 : 0;
-        return [
-            stepId,
-            previous,
-            state,
-            completion,
-            task.title || task.shortId || task.id,
-            stripTargetPrefix(task.taskPlanPath || `${stripTargetPrefix(task.path)}/task_plan.md`),
-            task.materialsReady ? "present" : "missing",
-            previous === "none" ? "none" : `depends on ${previous}`,
-            "coordinator",
-        ];
-    });
-    const graphLines = tasks.map((task, index) => {
-        const stepId = moduleStepId(task);
-        const label = fitMarkdownTableRow([task.title || task.shortId || task.id], 1)[0].replace(/"/g, "'");
-        if (index === 0)
-            return `  ${stepId}["${label}"]`;
-        const previous = moduleStepId(tasks[index - 1]);
-        return `  ${previous} --> ${stepId}["${label}"]`;
-    });
-    return `# ${moduleKey} - Visual Map
-
-Visual Map Contract: v1.0
-
-Generated by \`harness new-task --module\` and \`harness governance rebuild\`.
-
-## Map Index
-
-| ID | Type | Purpose | Required For Understanding | Source Evidence | Promotion Candidate |
-| --- | --- | --- | --- | --- | --- |
-| MAP-01 | topology | Show module task sequence generated from task files | yes | task scan | no |
-
-## Phase Graph
-
-\`\`\`mermaid
-flowchart LR
-${graphLines.length ? graphLines.join("\n") : "  EMPTY[\"No module tasks\"]"}
-\`\`\`
-
-## Phase Table
-
-| Phase ID | Depends On | State | Completion | Output | Required Evidence | Evidence Status | Blocking Risk | Owner / Handoff |
-| --- | --- | --- | ---: | --- | --- | --- | --- | --- |
-${rows.map((row) => `| ${fitMarkdownTableRow(row, 9).join(" | ")} |`).join("\n")}
-
-Allowed Evidence Status: missing, partial, present, waived.
-`;
+    return moduleTasks;
 }
 function replaceTableRows(content, headerPattern, rows) {
     const lines = String(content || "").split(/\r?\n/);
@@ -408,17 +335,6 @@ function moduleStepId(task) {
 function stripDatePrefix(value) {
     return String(value || "").replace(/^(?:TASKS\/|MODULES\/[^/]+\/)?\d{4}-\d{2}-\d{2}-/, "");
 }
-function mapPhaseState(state) {
-    if (state === "in_progress")
-        return "in_progress";
-    if (state === "review")
-        return "review";
-    if (state === "done")
-        return "done";
-    if (state === "blocked")
-        return "blocked";
-    return "planned";
-}
 function ensureFileFromTemplate(destinationPath, templateSource, { dryRun = false } = {}) {
     if (fs.existsSync(destinationPath) || dryRun)
         return;
@@ -487,10 +403,10 @@ function assertCommitIdentity(root) {
         });
     }
 }
-function assertDirtyCompatibleWithWriteScope(entries, allowedPaths) {
+function assertDirtyCompatibleWithWriteScope(entries, allowedPaths, { allowDirtyWriteScope = false } = {}) {
     const allowed = new Set(allowedPaths);
     const overlapping = entries.filter((entry) => allowed.has(entry.path));
-    if (overlapping.length > 0) {
+    if (overlapping.length > 0 && !allowDirtyWriteScope) {
         throw new GovernanceSyncError("Governance sync write scope overlaps existing dirty files; refusing to overwrite user-owned changes.", {
             code: "governance-write-scope-dirty",
             details: { overlapping, allowedPaths },
@@ -575,7 +491,7 @@ function fingerprintEntry(root, entry) {
         if (stat.isSymbolicLink())
             return `symlink:${fs.readlinkSync(absolute)}`;
         if (stat.isFile()) {
-            return `file:${stat.size}:${crypto.createHash("sha256").update(fs.readFileSync(absolute)).digest("hex")}`;
+            return `file:${stat.size}:${crypto.createHash("sha256").update(new Uint8Array(fs.readFileSync(absolute))).digest("hex")}`;
         }
         if (stat.isDirectory())
             return "directory";
@@ -599,7 +515,7 @@ function statusEntries(root) {
 }
 function parseStatusPath(value) {
     const unquoted = value.replace(/^"|"$/g, "");
-    return unquoted.includes(" -> ") ? unquoted.split(" -> ").pop() : unquoted;
+    return unquoted.includes(" -> ") ? unquoted.split(" -> ").pop() ?? unquoted : unquoted;
 }
 function git(cwd, args, { allowFailure = false } = {}) {
     const result = spawnSync("git", args, { cwd, encoding: "utf8" });
@@ -615,3 +531,12 @@ function git(cwd, args, { allowFailure = false } = {}) {
 function real(filePath) {
     return fs.realpathSync(filePath);
 }
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}

package/dist/lib/governance-table-boundary.mjs

@@ -1,10 +1,8 @@
-// @ts-nocheck
 // Governance table parsing remains behavior-first until target/table domain types are modeled.
 import fs from "node:fs";
 import path from "node:path";
 import { readFileSafe, toPosix } from "./core-shared.mjs";
 import { getCell, parseAllMarkdownTables } from "./markdown-utils.mjs";
-const newRuleCutoff = "2026-05-24";
 const globalTableSpecs = [
     { key: "feature-ssot", pathFor: (target) => path.join(target.harness.planningRoot, "Feature-SSoT.md"), allowed: "index-state-route-summary", evaluate: evaluateFeatureRow },
     { key: "harness-ledger", pathFor: (target) => target.harness.ledgerPath, allowed: "task-audit-summary-route", evaluate: evaluateLedgerRow },
@@ -34,10 +32,7 @@ export function validateGovernanceTableBoundaries(target) {
                         `allowed=${spec.allowed}`,
                         `route=${finding.route}`,
                     ].join(": ");
-                    if (isLegacyRow(rowUpdatedDate(row)))
-                        warnings.push(`${message}: legacy-report-only`);
-                    else
-                        failures.push(message);
+                    failures.push(message);
                 }
             }
         }
@@ -132,14 +127,6 @@ function governanceRowKey(row) {
 function rowText(row) {
     return Object.values(row.cells || {}).join(" ");
 }
-function rowUpdatedDate(row) {
-    const value = getCell(row.cells || {}, ["Updated", "Date", "日期", "Last Verified", "最近验证"], "");
-    const match = String(value).match(/\d{4}-\d{2}-\d{2}/);
-    return match ? match[0] : "";
-}
-function isLegacyRow(updated) {
-    return updated && updated < newRuleCutoff;
-}
 function isPlaceholderRow(row) {
     const text = rowText(row);
     return /\b(?:YYYY|MM|DD|NNN)\b|L-YYYY|HL-YYYY|\[[^\]]+\]|\.\.\.md|\bowner\b|\bShort lesson title\b/i.test(text);

package/dist/lib/harness-core.mjs

@@ -1,8 +1,8 @@
-// @ts-nocheck
 export * from "./core-shared.mjs";
 export * from "./markdown-utils.mjs";
 export * from "./capability-registry.mjs";
 export * from "./task-scanner.mjs";
+export * from "./task-discovery-contract.mjs";
 export * from "./status-builder.mjs";
 export * from "./check-profiles.mjs";
 export * from "./dashboard-data.mjs";
@@ -10,9 +10,13 @@ export * from "./dashboard-workbench.mjs";
 export * from "./migration-planner.mjs";
 export * from "./structure-migration.mjs";
 export * from "./preset-registry.mjs";
+export * from "./preset-runner.mjs";
 export * from "./governance-index-generator.mjs";
 export * from "./task-lifecycle.mjs";
+export * from "./module-registry.mjs";
 export * from "./task-lesson-sedimentation.mjs";
 export * from "./lesson-maintenance.mjs";
 export * from "./task-index.mjs";
 export * from "./task-tombstone-commands.mjs";
+export * from "./task-archive-eligibility.mjs";
+export * from "./impact-classifier.mjs";

package/dist/lib/harness-paths.mjs

@@ -48,7 +48,7 @@ export function resolveHarnessPaths(targetInput = ".") {
             planningRoot: resolved.planningRoot,
             tasksRoot: resolved.tasksRoot,
             modulesRoot: resolved.modulesRoot,
-            taskRoots: [resolved.tasksRoot, resolved.modulesRoot],
+            taskRoots: [resolved.tasksRoot, resolved.modulesRoot, resolved.externalRoot].filter(Boolean),
             externalRoot: resolved.externalRoot,
             governanceRoot: resolved.governanceRoot,
             generatedRoot: resolved.generatedRoot,
@@ -281,6 +281,9 @@ function readHarnessManifest(manifestPath) {
         return null;
     const manifest = { version: 2, locale: "en-US", capabilities: [], structure: {} };
     let section = "";
+    let inModuleItems = false;
+    let currentModuleKey = "";
+    let currentModuleListField = "";
     for (const rawLine of fs.readFileSync(manifestPath, "utf8").split(/\r?\n/)) {
         const line = rawLine.replace(/\s+#.*$/, "");
         if (!line.trim())
@@ -288,10 +291,15 @@ function readHarnessManifest(manifestPath) {
         const top = line.match(/^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/);
         if (top) {
             section = top[1];
+            inModuleItems = false;
+            currentModuleKey = "";
+            currentModuleListField = "";
             if (section === "version")
                 manifest.version = Number(top[2]) || 2;
             else if (section === "locale")
                 manifest.locale = top[2] || "en-US";
+            else if (section === "modules")
+                manifest.modules = { items: {} };
             else if (section !== "structure" && section !== "capabilities")
                 manifest[section] = top[2];
             continue;
@@ -304,6 +312,54 @@ function readHarnessManifest(manifestPath) {
         const nested = line.match(/^\s+([A-Za-z][A-Za-z0-9_-]*):\s*(.+)$/);
         if (section === "structure" && nested)
             manifest.structure[nested[1]] = nested[2].trim();
+        if (section === "modules") {
+            if (!manifest.modules)
+                manifest.modules = { items: {} };
+            const moduleTop = line.match(/^  ([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/);
+            if (moduleTop) {
+                currentModuleKey = "";
+                currentModuleListField = "";
+                if (moduleTop[1] === "items")
+                    inModuleItems = true;
+                else if (moduleTop[1] === "schema")
+                    manifest.modules.schema = moduleTop[2].trim();
+                else if (moduleTop[1] === "generatedView")
+                    manifest.modules.generatedView = moduleTop[2].trim();
+                else
+                    manifest.modules[moduleTop[1]] = moduleTop[2].trim();
+                continue;
+            }
+            const moduleItem = line.match(/^    ([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/);
+            if (inModuleItems && moduleItem) {
+                currentModuleKey = moduleItem[1];
+                currentModuleListField = "";
+                if (!manifest.modules.items[currentModuleKey])
+                    manifest.modules.items[currentModuleKey] = {};
+                continue;
+            }
+            const moduleField = line.match(/^      ([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/);
+            if (inModuleItems && currentModuleKey && moduleField) {
+                const field = moduleField[1];
+                const raw = moduleField[2].trim();
+                if (["scope", "shared", "dependsOn"].includes(field)) {
+                    manifest.modules.items[currentModuleKey][field] = raw === "[]" ? [] : raw ? [raw] : [];
+                    currentModuleListField = field;
+                }
+                else {
+                    manifest.modules.items[currentModuleKey][field] = raw;
+                    currentModuleListField = "";
+                }
+                continue;
+            }
+            const moduleListItem = line.match(/^        -\s*(.+)$/);
+            if (inModuleItems && currentModuleKey && currentModuleListField && moduleListItem) {
+                const existing = manifest.modules.items[currentModuleKey][currentModuleListField];
+                manifest.modules.items[currentModuleKey][currentModuleListField] = [
+                    ...(Array.isArray(existing) ? existing : []),
+                    moduleListItem[1].trim(),
+                ];
+            }
+        }
     }
     if (!manifest.structure.harnessRoot && manifest.harnessRoot)
         manifest.structure.harnessRoot = manifest.harnessRoot;
@@ -311,6 +367,64 @@ function readHarnessManifest(manifestPath) {
         manifest.structure.planningRoot = `${manifest.harnessRoot}/planning`;
     return manifest;
 }
+export function renderHarnessManifest({ locale, capabilities, structure = null, modules = null }) {
+    const manifestStructure = structure || {
+        harnessRoot: v2HarnessRoot,
+        planningRoot: `${v2HarnessRoot}/planning`,
+        tasksRoot: `${v2HarnessRoot}/planning/tasks`,
+        modulesRoot: `${v2HarnessRoot}/planning/modules`,
+        externalRoot: `${v2HarnessRoot}/planning/external`,
+        governanceRoot: `${v2HarnessRoot}/governance`,
+        generatedRoot: `${v2HarnessRoot}/governance/generated`,
+    };
+    const lines = [
+        "version: 2",
+        `locale: ${locale}`,
+        "capabilities:",
+        ...capabilities.map((capability) => `  - ${capability}`),
+        "structure:",
+        ...Object.entries(manifestStructure).map(([key, value]) => `  ${key}: ${value}`),
+    ];
+    if (modules && (modules.schema || modules.generatedView || Object.keys(modules.items || {}).length > 0)) {
+        lines.push("modules:");
+        if (modules.schema)
+            lines.push(`  schema: ${yamlScalar(modules.schema)}`);
+        if (modules.generatedView)
+            lines.push(`  generatedView: ${yamlScalar(modules.generatedView)}`);
+        lines.push("  items:");
+        for (const [key, module] of Object.entries(modules.items || {}).sort(([left], [right]) => left.localeCompare(right))) {
+            lines.push(`    ${key}:`);
+            for (const field of ["title", "prefix", "status", "branch", "owner", "currentStep", "scope", "shared", "dependsOn", "plan", "brief", "updated"]) {
+                const value = module[field];
+                if (Array.isArray(value)) {
+                    lines.push(`      ${field}:${value.length ? "" : " []"}`);
+                    for (const item of value)
+                        lines.push(`        - ${yamlScalar(String(item))}`);
+                }
+                else if (value !== undefined && value !== null && String(value) !== "") {
+                    lines.push(`      ${field}: ${yamlScalar(String(value))}`);
+                }
+            }
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function assertRenderableHarnessManifest(manifest) {
+    if (!manifest)
+        return;
+    const allowed = new Set(["version", "locale", "capabilities", "structure", "modules", "harnessRoot"]);
+    const unknown = Object.keys(manifest).filter((key) => !allowed.has(key));
+    if (unknown.length > 0)
+        throw new Error(`Cannot rewrite harness.yaml with unknown top-level fields: ${unknown.join(", ")}`);
+}
+function yamlScalar(value) {
+    const raw = String(value || "");
+    if (!raw)
+        return "''";
+    if (/[:#\n\r]|^\s|\s$|^(?:true|false|null|\d+(?:\.\d+)?)$/i.test(raw))
+        return JSON.stringify(raw);
+    return raw;
+}
 function resolveManifestStructurePath(projectRoot, fieldName, relativePath) {
     const raw = String(relativePath || "").trim();
     if (!raw)