coding-agent-harness 1.0.8 → 1.1.0

package/dist/check-lite-forbidden-surfaces.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const defaultRepoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+function parseArgs(argv) {
+    let repoRoot = defaultRepoRoot;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--repo-root") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new Error("--repo-root requires a value");
+            repoRoot = path.resolve(value);
+            index += 1;
+            continue;
+        }
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+    return { repoRoot };
+}
+export function checkLiteForbiddenSurfaces(repoRoot = defaultRepoRoot) {
+    const forbiddenPath = path.join(repoRoot, "docs-release/architecture/document-contract-kernel/products/lite-forbidden-surfaces.txt");
+    const patterns = readForbiddenPatterns(forbiddenPath);
+    const scannedFiles = collectLiteProductFiles(repoRoot);
+    const violations = [];
+    for (const relativeFile of scannedFiles) {
+        const absoluteFile = path.join(repoRoot, relativeFile);
+        const lines = fs.readFileSync(absoluteFile, "utf8").split(/\r?\n/);
+        for (const [lineIndex, line] of lines.entries()) {
+            for (const pattern of patterns) {
+                pattern.pattern.lastIndex = 0;
+                if (pattern.pattern.test(line)) {
+                    violations.push({
+                        file: relativeFile,
+                        line: lineIndex + 1,
+                        pattern: pattern.source,
+                        text: line.trim(),
+                    });
+                }
+            }
+        }
+    }
+    return { ok: violations.length === 0, violations, scannedFiles };
+}
+function readForbiddenPatterns(forbiddenPath) {
+    if (!fs.existsSync(forbiddenPath)) {
+        throw new Error(`Missing Lite forbidden-surface list: ${path.relative(process.cwd(), forbiddenPath)}`);
+    }
+    const lines = fs.readFileSync(forbiddenPath, "utf8").split(/\r?\n/);
+    return lines
+        .map((line) => line.trim())
+        .filter((line) => line && !line.startsWith("#"))
+        .map((line) => {
+        if (line.startsWith("literal:")) {
+            const literal = line.slice("literal:".length);
+            return { source: line, pattern: new RegExp(escapeRegExp(literal), "i") };
+        }
+        if (line.startsWith("regex:")) {
+            const source = line.slice("regex:".length);
+            return { source: line, pattern: new RegExp(source, "i") };
+        }
+        return { source: line, pattern: new RegExp(escapeRegExp(line), "i") };
+    });
+}
+function collectLiteProductFiles(repoRoot) {
+    const files = new Set();
+    const explicitFiles = [
+        "docs-release/architecture/document-contract-kernel/products/lite-skill-overlay.md",
+        "skills/coding-agent-harness-lite/SKILL.md",
+    ];
+    for (const relativeFile of explicitFiles) {
+        if (fs.existsSync(path.join(repoRoot, relativeFile)))
+            files.add(relativeFile);
+    }
+    for (const relativeDir of ["skill-sources/products/lite", "skill-sources/document-kernel/products/lite"]) {
+        const absoluteDir = path.join(repoRoot, relativeDir);
+        if (!fs.existsSync(absoluteDir))
+            continue;
+        for (const relativeFile of walkTextFiles(absoluteDir, repoRoot))
+            files.add(relativeFile);
+    }
+    return [...files].sort();
+}
+function walkTextFiles(current, repoRoot) {
+    const stat = fs.lstatSync(current);
+    if (stat.isSymbolicLink())
+        return [];
+    if (stat.isFile()) {
+        return /\.(md|txt|template)$/.test(current) ? [toPosix(path.relative(repoRoot, current))] : [];
+    }
+    const files = [];
+    for (const entry of fs.readdirSync(current)) {
+        files.push(...walkTextFiles(path.join(current, entry), repoRoot));
+    }
+    return files;
+}
+function toPosix(value) {
+    return value.split(path.sep).join("/");
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    try {
+        const { repoRoot } = parseArgs(process.argv.slice(2));
+        const result = checkLiteForbiddenSurfaces(repoRoot);
+        if (!result.ok) {
+            console.error([
+                "Lite forbidden-surface check failed:",
+                ...result.violations.map((violation) => `${violation.file}:${violation.line}: ${violation.pattern}: ${violation.text}`),
+            ].join("\n"));
+            process.exit(1);
+        }
+        console.log(`Lite forbidden-surface check passed (${result.scannedFiles.length} files scanned)`);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+}

package/dist/check-no-ts-nocheck.mjs

@@ -4,9 +4,9 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 const defaultRepoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const sourceRoots = ["scripts", "tests"];
-const tsNocheckPattern = /^\s*\/\/\s*@ts-nocheck\b/;
+const tsNocheckPattern = new RegExp(String.raw `^\s*//\s*` + "@ts" + String.raw `-nocheck\b`);
 export function checkNoTsNocheck({ repoRoot = defaultRepoRoot, allowlistPath = path.join(repoRoot, "scripts/ts-nocheck-allowlist.json"), } = {}) {
-    const files = collectMtsFiles(repoRoot);
+    const files = collectTypeScriptFiles(repoRoot);
     const allowlist = readAllowlist(allowlistPath);
     const violations = [];
     const observed = new Set();
@@ -22,7 +22,7 @@ export function checkNoTsNocheck({ repoRoot = defaultRepoRoot, allowlistPath = p
                 code: "unlisted-ts-nocheck",
                 file,
                 line: lineIndex + 1,
-                message: `${file}:${lineIndex + 1} has @ts-nocheck but is not in scripts/ts-nocheck-allowlist.json`,
+                message: `${file}:${lineIndex + 1} has ${"@ts"}-nocheck but is not in scripts/ts-nocheck-allowlist.json`,
             });
         }
     }
@@ -31,13 +31,13 @@ export function checkNoTsNocheck({ repoRoot = defaultRepoRoot, allowlistPath = p
             violations.push({
                 code: "stale-ts-nocheck-allowlist",
                 file,
-                message: `${file} is listed in scripts/ts-nocheck-allowlist.json but no longer has @ts-nocheck`,
+                message: `${file} is listed in scripts/ts-nocheck-allowlist.json but no longer has ${"@ts"}-nocheck`,
             });
         }
     }
     return { ok: violations.length === 0, violations };
 }
-function collectMtsFiles(repoRoot) {
+function collectTypeScriptFiles(repoRoot) {
     const files = [];
     for (const root of sourceRoots) {
         const absoluteRoot = path.join(repoRoot, root);
@@ -59,7 +59,7 @@ function walk(current, files, repoRoot) {
             walk(path.join(current, entry), files, repoRoot);
         return;
     }
-    if (stat.isFile() && current.endsWith(".mts")) {
+    if (stat.isFile() && /\.(mts|ts)$/.test(current)) {
         files.push(path.relative(repoRoot, current).split(path.sep).join("/"));
     }
 }
@@ -84,5 +84,5 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
         console.error(result.violations.map((violation) => violation.message).join("\n"));
         process.exit(1);
     }
-    console.log("No @ts-nocheck gate passed");
+    console.log(`No ${"@ts"}-nocheck gate passed`);
 }

package/dist/check-runtime-emit.mjs

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-// @ts-nocheck
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -75,11 +74,19 @@ export function checkRuntimeEmitContract({ projectRoot = defaultRepoRoot, config
     };
 }
 function runTypeScriptEmit({ projectRoot, configPath, outDir }) {
-    return spawnSync("npm", ["exec", "--yes", "--package", `typescript@${typescriptVersion}`, "--", "tsc", "-p", configPath, "--outDir", outDir, "--noCheck"], {
+    const npmArgs = ["exec", "--yes", "--package", `typescript@${typescriptVersion}`, "--", "tsc", "-p", configPath, "--outDir", outDir, "--noCheck"];
+    const npmCommand = resolveNpmCommand(npmArgs);
+    return spawnSync(npmCommand.command, npmCommand.args, {
         cwd: projectRoot,
         encoding: "utf8",
     });
 }
+function resolveNpmCommand(npmArgs) {
+    const npmExecPath = process.env.npm_execpath;
+    if (npmExecPath)
+        return { command: process.execPath, args: [npmExecPath, ...npmArgs] };
+    return { command: process.platform === "win32" ? "npm.cmd" : "npm", args: npmArgs };
+}
 function compareDirectories({ expectedDir, actualDir, violations }) {
     const expectedFiles = collectFiles(expectedDir).filter((file) => file.endsWith(".mjs")).sort();
     const actualFiles = collectFiles(actualDir).filter((file) => file.endsWith(".mjs")).sort();
@@ -129,7 +136,7 @@ function collectFiles(directory) {
         walk(directory, files, () => true);
     return files.sort();
 }
-function walk(current, files, predicate, sourceRoot) {
+function walk(current, files, predicate, sourceRoot = "") {
     const stat = fs.lstatSync(current);
     if (stat.isSymbolicLink())
         return;

package/dist/check-type-boundaries.mjs

@@ -1,16 +1,17 @@
 #!/usr/bin/env node
-// @ts-nocheck
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 const defaultRepoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const sourceRoots = ["scripts", "tests"];
 const importPattern = /\b(import|export)\s+(type\s+)?(?:[^'"]*?\s+from\s+)?["']([^"']+)["']|\bimport\s*\(\s*["']([^"']+)["']\s*\)/g;
-const tsEscapePattern = /@(ts-ignore|ts-expect-error)\b|\bas\s+unknown\s+as\b|\bRecord\s*<\s*string\s*,\s*any\s*>|(?:^|[^A-Za-z0-9_$])(?:as\s+any|:\s*any\b)/;
+const tsEscapePattern = /@(ts-ignore|ts-expect-error|ts-nocheck)\b|\bas\s+unknown\s+as\b|<[^>\n]*\bany\b[^>\n]*>|(?:^|[^A-Za-z0-9_$])(?:as\s+any|:\s*any\b)/;
+const crossLineUnknownCastPattern = /\bas\s+unknown\s+as\b/;
 export function checkTypeBoundaries({ repoRoot = defaultRepoRoot, escapeAllowlistPath = path.join(repoRoot, "scripts/type-escape-allowlist.json"), } = {}) {
     const files = collectSourceFiles(repoRoot);
     const violations = [];
     const escapeAllowlist = readEscapeAllowlist(escapeAllowlistPath);
+    const observedEscapes = new Set();
     for (const file of files) {
         const absolutePath = path.join(repoRoot, file);
         const content = fs.readFileSync(absolutePath, "utf8");
@@ -25,10 +26,23 @@ export function checkTypeBoundaries({ repoRoot = defaultRepoRoot, escapeAllowlis
                         line: index + 1,
                         message: `${file}:${index + 1} uses a TypeScript escape hatch that requires review`,
                     };
+                    observedEscapes.add(escapeKey(violation));
                     if (!isEscapeAllowed(escapeAllowlist, violation))
                         violations.push(violation);
                 }
             }
+            if (crossLineUnknownCastPattern.test(content) && !lines.some((line) => /\bas\s+unknown\s+as\b/.test(line))) {
+                const line = lineForOffset(content, content.search(crossLineUnknownCastPattern));
+                const violation = {
+                    code: "ts-escape-hatch",
+                    file,
+                    line,
+                    message: `${file}:${line} uses a cross-line TypeScript escape hatch that requires review`,
+                };
+                observedEscapes.add(escapeKey(violation));
+                if (!isEscapeAllowed(escapeAllowlist, violation))
+                    violations.push(violation);
+            }
         }
         for (const imported of imports) {
             if (!isLocalSpecifier(imported.specifier))
@@ -52,6 +66,16 @@ export function checkTypeBoundaries({ repoRoot = defaultRepoRoot, escapeAllowlis
             }
         }
     }
+    for (const allowed of escapeAllowlist.values()) {
+        if (observedEscapes.has(allowed.key))
+            continue;
+        violations.push({
+            code: "stale-ts-escape-allowlist",
+            file: allowed.file,
+            line: allowed.line,
+            message: `${allowed.file}:${allowed.line} is listed in ${path.relative(repoRoot, escapeAllowlistPath)} but no matching TypeScript escape hatch was found`,
+        });
+    }
     return { ok: violations.length === 0, violations };
 }
 function collectSourceFiles(repoRoot) {
@@ -86,7 +110,7 @@ function parseImports(content) {
         imports.push({
             kind: match[1] || "import",
             typeOnly: match[2] === "type ",
-            specifier: match[3] || match[4],
+            specifier: match[3] || match[4] || "",
         });
     }
     return imports;
@@ -134,17 +158,35 @@ function isTypeOnlyTypeScriptImport(file, imported) {
 }
 function readEscapeAllowlist(allowlistPath) {
     if (!allowlistPath || !fs.existsSync(allowlistPath))
-        return new Set();
+        return new Map();
     const parsed = JSON.parse(fs.readFileSync(allowlistPath, "utf8"));
     const entries = Array.isArray(parsed) ? parsed : parsed.escapes || [];
-    return new Set(entries.map((entry) => {
-        if (typeof entry === "string")
-            return entry;
-        return `${entry.file}:${entry.line}:${entry.code || "ts-escape-hatch"}`;
+    return new Map(entries.map((entry) => {
+        if (typeof entry === "string") {
+            return [
+                entry,
+                {
+                    key: entry,
+                    file: entry.split(":")[0] || entry,
+                    line: Number.parseInt(entry.split(":")[1] || "", 10) || undefined,
+                    code: entry.split(":")[2] || "ts-escape-hatch",
+                },
+            ];
+        }
+        const key = `${entry.file}:${entry.line}:${entry.code || "ts-escape-hatch"}`;
+        return [key, { key, file: entry.file, line: entry.line, code: entry.code || "ts-escape-hatch" }];
     }));
 }
 function isEscapeAllowed(allowlist, violation) {
-    return allowlist.has(`${violation.file}:${violation.line}:${violation.code}`) || allowlist.has(`${violation.file}:${violation.line}`);
+    return allowlist.has(escapeKey(violation)) || allowlist.has(`${violation.file}:${violation.line}`);
+}
+function escapeKey(violation) {
+    return `${violation.file}:${violation.line}:${violation.code}`;
+}
+function lineForOffset(content, offset) {
+    if (offset < 0)
+        return 1;
+    return content.slice(0, offset).split(/\r?\n/).length;
 }
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
     const result = checkTypeBoundaries();

package/dist/commands/dashboard-command.mjs

@@ -1,9 +1,31 @@
-// @ts-nocheck
 // Dashboard command parsing stays behavior-first until command handler types are modeled.
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { normalizeTarget, serveDashboardWorkbench, writeDashboardFolder, writeDashboardSingleFile, } from "../lib/harness-core.mjs";
 import { dashboardWatchRoots } from "../lib/harness-paths.mjs";
+export async function runDevDashboardCommand({ takeFlag, takeOption, targetArg }) {
+    const open = !takeFlag("--no-open");
+    const outDir = takeOption("--out-dir", "");
+    const host = takeOption("--host", "127.0.0.1");
+    const port = Number(takeOption("--port", "0"));
+    const localeOverride = takeOption("--locale", "");
+    const target = targetArg();
+    const usesDefaultOutDir = !outDir;
+    const dashboardOutDir = outDir || defaultDevOutDir(target);
+    const opts = {
+        ...(localeOverride ? { localeOverride } : {}),
+        recoverGeneratedDashboard: usesDefaultOutDir,
+        replaceExistingDashboardOutput: usesDefaultOutDir,
+    };
+    try {
+        await serveDashboardWorkbench(dashboardOutDir, target, { ...opts, host, port, autoRefresh: true, open, label: "harness dev" });
+    }
+    catch (error) {
+        console.error(errorMessage(error));
+        process.exit(1);
+    }
+}
 export async function runDashboardCommand({ takeFlag, takeOption, targetArg }) {
     const watch = takeFlag("--watch");
     const workbench = takeFlag("--workbench");
@@ -19,11 +41,11 @@ export async function runDashboardCommand({ takeFlag, takeOption, targetArg }) {
             process.exit(2);
         }
         try {
-            assertV2DashboardTarget(targetArg());
-            await serveDashboardWorkbench(outDir, targetArg(), { ...opts, host, port });
+            requireV2DashboardTarget(targetArg());
+            await serveDashboardWorkbench(outDir, targetArg(), { ...opts, host, port: Number(port) });
         }
         catch (error) {
-            console.error(error.message);
+            console.error(errorMessage(error));
             process.exit(1);
         }
     }
@@ -33,28 +55,29 @@ export async function runDashboardCommand({ takeFlag, takeOption, targetArg }) {
             process.exit(2);
         }
         const target = targetArg();
-        assertV2DashboardTarget(target);
-        const normalizedTarget = normalizeTarget(target);
-        const watchRoots = dashboardWatchRoots(normalizedTarget.harness);
+        const harnessPaths = requireV2DashboardTarget(target);
+        const watchRoots = dashboardWatchRoots(harnessPaths);
         const regenerate = () => {
             try {
                 console.log(writeDashboardFolder(outDir, target, opts));
                 console.log(`dashboard regenerated: ${new Date().toISOString()}`);
             }
             catch (error) {
-                console.error(`dashboard regeneration failed: ${error.message}`);
+                console.error(`dashboard regeneration failed: ${errorMessage(error)}`);
             }
         };
         regenerate();
         let timer = null;
         const watchers = watchRoots.map((watchRoot) => fs.watch(watchRoot, { recursive: true }, () => {
-            clearTimeout(timer);
+            if (timer)
+                clearTimeout(timer);
             timer = setTimeout(regenerate, 300);
         }));
         const close = () => {
             for (const watcher of watchers)
                 watcher.close();
-            clearTimeout(timer);
+            if (timer)
+                clearTimeout(timer);
             process.exit(0);
         };
         process.on("SIGINT", close);
@@ -62,7 +85,7 @@ export async function runDashboardCommand({ takeFlag, takeOption, targetArg }) {
         console.log(`watching ${watchRoots.join(", ")}`);
         await new Promise(() => { });
     }
-    assertV2DashboardTarget(targetArg());
+    requireV2DashboardTarget(targetArg());
     if (outDir) {
         console.log(writeDashboardFolder(outDir, targetArg(), opts));
     }
@@ -71,10 +94,25 @@ export async function runDashboardCommand({ takeFlag, takeOption, targetArg }) {
     }
     process.exit(0);
 }
-function assertV2DashboardTarget(target) {
+function requireV2DashboardTarget(target) {
     const normalizedTarget = normalizeTarget(target);
-    if (normalizedTarget.harness?.version === 2)
-        return;
+    const harnessPaths = readV2HarnessPaths(normalizedTarget);
+    if (harnessPaths)
+        return harnessPaths;
     console.error("dashboard requires v2 harness structure; run `harness migrate-structure --plan` then `harness migrate-structure --apply`");
     process.exit(1);
 }
+function defaultDevOutDir(targetInput) {
+    const target = path.resolve(targetInput || ".");
+    return path.join(os.tmpdir(), "coding-agent-harness-dev", `${path.basename(target) || "project"}-${Buffer.from(target).toString("hex").slice(0, 16)}`);
+}
+function readV2HarnessPaths(target) {
+    const harness = target.harness;
+    return isRecord(harness) && harness.version === 2 ? harness : null;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/commands/migration-command.mjs

@@ -1,4 +1,3 @@
-// @ts-nocheck
 import { applyStructureMigration, buildMigrationPlan, planStructureMigration, runMigration, verifyMigrationSession, } from "../lib/harness-core.mjs";
 import { applyTaskAuditIndexMigration, planTaskAuditIndexMigration, } from "../lib/task-audit-migration.mjs";
 export function runMigrationCommand(command, { args, takeFlag, takeOption, targetArg }) {
@@ -8,6 +7,7 @@ export function runMigrationCommand(command, { args, takeFlag, takeOption, targe
         const planOnly = takeFlag("--plan");
         const force = takeFlag("--force");
         try {
+            const shouldApply = apply && !planOnly;
             const result = apply && !planOnly
                 ? applyStructureMigration(targetArg(), { force })
                 : planStructureMigration(targetArg());
@@ -15,7 +15,7 @@ export function runMigrationCommand(command, { args, takeFlag, takeOption, targe
                 console.log(JSON.stringify(result, null, 2));
             }
             else {
-                console.log(`Structure migration ${result.applied ? "applied" : "plan"}: ${result.target}`);
+                console.log(`Structure migration ${shouldApply ? "applied" : "plan"}: ${result.target}`);
                 console.log(`manifest: ${result.manifest}`);
                 console.log(`actions: ${result.summary.actions}`);
                 for (const action of result.actions || [])
@@ -23,7 +23,7 @@ export function runMigrationCommand(command, { args, takeFlag, takeOption, targe
             }
         }
         catch (error) {
-            console.error(error.message);
+            console.error(errorMessage(error));
             process.exit(1);
         }
         return;
@@ -52,10 +52,11 @@ export function runMigrationCommand(command, { args, takeFlag, takeOption, targe
             process.exit(result.failures?.length ? 1 : 0);
         }
         catch (error) {
-            if (json && error.plan)
-                console.error(JSON.stringify(error.plan, null, 2));
+            const plan = readProperty(error, "plan");
+            if (json && plan)
+                console.error(JSON.stringify(plan, null, 2));
             else
-                console.error(error.message);
+                console.error(errorMessage(error));
             process.exit(1);
         }
     }
@@ -99,7 +100,7 @@ export function runMigrationCommand(command, { args, takeFlag, takeOption, targe
             }
         }
         catch (error) {
-            console.error(error.message);
+            console.error(errorMessage(error));
             process.exit(1);
         }
         return;
@@ -122,7 +123,7 @@ export function runMigrationCommand(command, { args, takeFlag, takeOption, targe
             }), null, 2));
         }
         catch (error) {
-            console.error(error.message);
+            console.error(errorMessage(error));
             process.exit(1);
         }
         return;
@@ -150,3 +151,12 @@ export function runMigrationCommand(command, { args, takeFlag, takeOption, targe
     }
     throw new Error(`Unsupported migration command: ${command}`);
 }
+function readProperty(value, key) {
+    return isRecord(value) ? value[key] : undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/commands/module-command.mjs

@@ -0,0 +1,142 @@
+import { normalizeTarget, prepareModuleRegistration, prepareModuleScaffold, prepareModuleUnregister, readHarnessModules, } from "../lib/harness-core.mjs";
+import { takeRepeatedOptionsFromArgs } from "../lib/command-registry.mjs";
+import { beginGovernanceSync, commitGovernanceSync, governanceRelativePaths, releaseGovernanceSync } from "../lib/governance-sync.mjs";
+export function runModuleCommand({ args, takeFlag, takeOption, targetArg }) {
+    const subcommand = args.shift() || "list";
+    const json = takeFlag("--json");
+    if (subcommand === "list") {
+        const modules = readHarnessModules(targetArg());
+        const items = Object.entries(modules.items || {}).map(([key, module]) => ({ key, ...module }));
+        if (json)
+            console.log(JSON.stringify({ schema: modules.schema, generatedView: modules.generatedView, modules: items }, null, 2));
+        else
+            for (const item of items)
+                console.log(`${item.key}\t${item.status || "planned"}\t${item.title || item.key}`);
+        return;
+    }
+    if (subcommand === "inspect") {
+        const moduleKey = args.shift();
+        if (!moduleKey) {
+            console.error("Missing module key");
+            process.exit(2);
+        }
+        const modules = readHarnessModules(targetArg());
+        const module = modules.items[moduleKey];
+        if (!module) {
+            console.error(`Module is not registered: ${moduleKey}`);
+            process.exit(1);
+        }
+        console.log(JSON.stringify({ key: moduleKey, ...module }, null, 2));
+        return;
+    }
+    if (subcommand === "register") {
+        const dryRun = takeFlag("--dry-run");
+        const moduleKey = args.shift();
+        if (!moduleKey) {
+            console.error("Missing module key");
+            process.exit(2);
+        }
+        const input = {
+            title: takeOption("--title", ""),
+            prefix: takeOption("--prefix", ""),
+            status: takeOption("--status", "planned"),
+            branch: takeOption("--branch", ""),
+            owner: takeOption("--owner", "coordinator"),
+            currentStep: takeOption("--current-step", ""),
+            locale: takeOption("--locale", ""),
+            scope: takeRepeatedOptionsFromArgs(args, "--scope"),
+            shared: takeRepeatedOptionsFromArgs(args, "--shared"),
+            dependsOn: takeRepeatedOptionsFromArgs(args, "--depends-on"),
+        };
+        const target = normalizeTarget(targetArg());
+        const planned = prepareModuleRegistration(target, moduleKey, input, { dryRun: true });
+        const context = beginGovernanceSync(target, {
+            operation: `module register ${moduleKey}`,
+            dryRun,
+            allowDirtyWorktree: true,
+            allowedRelativePaths: governanceRelativePaths(planned.changes),
+        });
+        try {
+            const result = prepareModuleRegistration(target, moduleKey, input, { dryRun });
+            const commit = commitGovernanceSync(context, governanceRelativePaths(result.changes), { message: `chore(harness): register module ${result.moduleKey}` });
+            console.log(JSON.stringify({ ...result, governance: { commit } }, null, 2));
+        }
+        catch (error) {
+            console.error(errorMessage(error));
+            process.exit(1);
+        }
+        finally {
+            releaseGovernanceSync(context);
+        }
+        return;
+    }
+    if (subcommand === "unregister") {
+        const dryRun = takeFlag("--dry-run");
+        const moduleKey = args.shift();
+        if (!moduleKey) {
+            console.error("Missing module key");
+            process.exit(2);
+        }
+        const target = normalizeTarget(targetArg());
+        const planned = prepareModuleUnregister(target, moduleKey, { dryRun: true });
+        const context = beginGovernanceSync(target, {
+            operation: `module unregister ${moduleKey}`,
+            dryRun,
+            allowDirtyWorktree: true,
+            allowedRelativePaths: governanceRelativePaths(planned.changes),
+        });
+        try {
+            const result = prepareModuleUnregister(target, moduleKey, { dryRun });
+            const commit = commitGovernanceSync(context, governanceRelativePaths(result.changes), { message: `chore(harness): unregister module ${result.moduleKey}` });
+            console.log(JSON.stringify({ ...result, governance: { commit } }, null, 2));
+        }
+        catch (error) {
+            console.error(errorMessage(error));
+            process.exit(1);
+        }
+        finally {
+            releaseGovernanceSync(context);
+        }
+        return;
+    }
+    if (subcommand === "scaffold") {
+        const dryRun = takeFlag("--dry-run");
+        const all = takeFlag("--all");
+        const locale = takeOption("--locale", "");
+        const moduleKey = all ? "" : args.shift();
+        if (!all && !moduleKey) {
+            console.error("Missing module key");
+            process.exit(2);
+        }
+        const target = normalizeTarget(targetArg());
+        const modules = readHarnessModules(target);
+        const keys = all ? Object.keys(modules.items || {}).sort() : [moduleKey || ""];
+        const plannedChanges = keys.flatMap((key) => prepareModuleScaffold(target, key, { dryRun: true, locale }).changes);
+        const context = beginGovernanceSync(target, {
+            operation: all ? "module scaffold --all" : `module scaffold ${moduleKey}`,
+            dryRun,
+            allowDirtyWorktree: true,
+            allowedRelativePaths: governanceRelativePaths(plannedChanges),
+            allowDirtyWriteScope: true,
+        });
+        try {
+            const results = keys.map((key) => prepareModuleScaffold(target, key, { dryRun, locale }));
+            const changes = results.flatMap((result) => result.changes);
+            const commit = commitGovernanceSync(context, governanceRelativePaths(changes), { message: all ? "chore(harness): scaffold registered modules" : `chore(harness): scaffold module ${moduleKey}` });
+            console.log(JSON.stringify({ modules: results, changes, governance: { commit } }, null, 2));
+        }
+        catch (error) {
+            console.error(errorMessage(error));
+            process.exit(1);
+        }
+        finally {
+            releaseGovernanceSync(context);
+        }
+        return;
+    }
+    console.error(`Unknown module subcommand: ${subcommand}`);
+    process.exit(2);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}