coding-agent-harness 1.0.4 → 1.0.6

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

@@ -0,0 +1,161 @@
+// @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 },
+    { key: "closeout-ssot", pathFor: (target) => target.harness.closeoutIndexPath, allowed: "closeout-index-review-route-summary", evaluate: evaluateCloseoutRow },
+    { key: "regression-ssot", pathFor: (target) => path.join(target.harness.regressionRoot, "Regression-SSoT.md"), allowed: "gate-index-current-state", evaluate: evaluateRegressionRow },
+    { key: "cadence-ledger", pathFor: (target) => path.join(target.harness.regressionRoot, "Cadence-Ledger.md"), allowed: "trigger-rule-and-batch-summary", evaluate: evaluateCadenceRow },
+];
+export function validateGovernanceTableBoundaries(target) {
+    const failures = [];
+    const warnings = [];
+    for (const spec of globalTableSpecs) {
+        const file = spec.pathFor(target);
+        if (!fs.existsSync(file))
+            continue;
+        const relative = toPosix(path.relative(target.projectRoot, file));
+        for (const table of parseAllMarkdownTables(readFileSafe(file), relative, spec.key)) {
+            for (const row of table.rows) {
+                if (isPlaceholderRow(row))
+                    continue;
+                for (const finding of spec.evaluate(row)) {
+                    const rowKey = governanceRowKey(row);
+                    const message = [
+                        "governance-table-entropy",
+                        `${relative}:${table.line}`,
+                        `${spec.key} row ${rowKey}`,
+                        finding.reason,
+                        `allowed=${spec.allowed}`,
+                        `route=${finding.route}`,
+                    ].join(": ");
+                    if (isLegacyRow(rowUpdatedDate(row)))
+                        warnings.push(`${message}: legacy-report-only`);
+                    else
+                        failures.push(message);
+                }
+            }
+        }
+    }
+    return { failures, warnings };
+}
+function evaluateFeatureRow(row) {
+    const cells = row.cells || {};
+    const text = rowText(row);
+    const taskPlan = getCell(cells, ["Task Plan", "Task", "任务计划", "路径"], "");
+    const evidence = getCell(cells, ["Acceptance Evidence", "Evidence", "验收证据"], "");
+    const findings = [];
+    if (/(?:09-PLANNING\/MODULES|planning\/modules)\//i.test(taskPlan) && !isModuleAggregateRow(row) && localDetailPattern().test(text)) {
+        findings.push({
+            reason: "module-local detail belongs in module_plan.md or task files, not Feature SSoT",
+            route: "module-plan-or-task-detail",
+        });
+    }
+    if (longEvidencePattern().test(evidence) || temporaryPromptPattern().test(text)) {
+        findings.push({
+            reason: "long evidence or temporary repair prompt belongs in task evidence, not Feature SSoT",
+            route: "task-artifacts-or-progress",
+        });
+    }
+    return findings;
+}
+function isModuleAggregateRow(row) {
+    const cells = row.cells || {};
+    const id = getCell(cells, ["ID"], "");
+    const taskPlan = getCell(cells, ["Task Plan", "Task", "任务计划", "路径"], "");
+    return /^F-MODULE-/i.test(id) && /(?:09-PLANNING\/MODULES|planning\/modules)\/[^/]+\/module_plan\.md/i.test(taskPlan);
+}
+function evaluateLedgerRow(row) {
+    const text = rowText(row);
+    const evidence = ledgerEvidenceText(row);
+    if (executionLogPattern().test(evidence) || temporaryPromptPattern().test(text) || rawTranscriptPattern().test(evidence)) {
+        return [{
+                reason: "execution logs, long evidence, and temporary repair prompts belong in task progress/review/artifacts",
+                route: "task-progress-review-artifacts",
+            }];
+    }
+    return [];
+}
+function ledgerEvidenceText(row) {
+    const cells = row.cells || {};
+    return [
+        "Evidence Summary",
+        "Evidence",
+        "Regression Evidence",
+        "Review Evidence",
+        "Regression",
+        "Review",
+        "证据摘要",
+        "证据",
+        "回归",
+        "审查",
+    ].map((column) => getCell(cells, [column], "")).filter(Boolean).join(" ");
+}
+function evaluateCloseoutRow(row) {
+    const text = rowText(row);
+    if (executionLogPattern().test(text) || rawTranscriptPattern().test(text)) {
+        return [{
+                reason: "closeout rows should route to walkthrough/evidence instead of carrying execution detail",
+                route: "walkthrough-or-task-evidence",
+            }];
+    }
+    return [];
+}
+function evaluateRegressionRow(row) {
+    const text = rowText(row);
+    if (executionLogPattern().test(text) || temporaryPromptPattern().test(text)) {
+        return [{
+                reason: "regression global tables should keep gate state and route detailed failure analysis elsewhere",
+                route: "regression-detail-or-task-review",
+            }];
+    }
+    return [];
+}
+function evaluateCadenceRow(row) {
+    const text = rowText(row);
+    if (rawTranscriptPattern().test(text) || temporaryPromptPattern().test(text)) {
+        return [{
+                reason: "cadence rows should summarize batch outcomes and route raw run detail elsewhere",
+                route: "regression-batch-artifacts",
+            }];
+    }
+    return [];
+}
+function governanceRowKey(row) {
+    return getCell(row.cells || {}, ["ID", "Lesson", "Lesson ID", "Feature", "Work Item", "Gate ID", "Batch ID"], "") || row.id || "unknown-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);
+}
+function localDetailPattern() {
+    return /\b(module|local|implementation detail|parser branch|button label|copy every|工作项|局部|实现细节)\b/i;
+}
+function longEvidencePattern() {
+    return /\b(long evidence|full local evidence|raw evidence|stack trace|reviewer transcript|copied raw)\b/i;
+}
+function executionLogPattern() {
+    return /\b(execution log|command failed|stack trace|raw output|step one|step two|执行流水|命令输出)\b/i;
+}
+function temporaryPromptPattern() {
+    return /\b(temporary repair prompt|repair prompt|copyable prompt|paste back|临时修复提示)\b/i;
+}
+function rawTranscriptPattern() {
+    return /\b(raw transcript|reviewer transcript|full transcript|完整记录|原始记录)\b/i;
+}

package/{scripts → dist}/lib/harness-core.mjs

@@ -1,11 +1,14 @@
+// @ts-nocheck
 export * from "./core-shared.mjs";
 export * from "./markdown-utils.mjs";
 export * from "./capability-registry.mjs";
 export * from "./task-scanner.mjs";
+export * from "./status-builder.mjs";
 export * from "./check-profiles.mjs";
 export * from "./dashboard-data.mjs";
 export * from "./dashboard-workbench.mjs";
 export * from "./migration-planner.mjs";
+export * from "./structure-migration.mjs";
 export * from "./preset-registry.mjs";
 export * from "./governance-index-generator.mjs";
 export * from "./task-lifecycle.mjs";

package/dist/lib/harness-paths.mjs

@@ -0,0 +1,338 @@
+import fs from "node:fs";
+import path from "node:path";
+export const v2HarnessRoot = "coding-agent-harness";
+export const legacyPlanningRoot = ["docs", "09-PLANNING"];
+export const legacyTaskRoot = [...legacyPlanningRoot, "TASKS"];
+export const legacyModuleRoot = [...legacyPlanningRoot, "MODULES"];
+export const legacyWalkthroughRoot = ["docs", "10-WALKTHROUGH"];
+export const legacyLedgerFile = ["docs", "Harness-Ledger.md"];
+export const legacyCloseoutFile = [...legacyWalkthroughRoot, "Closeout-SSoT.md"];
+export const legacyCompatMode = "legacy-compat";
+export const safeAdoptionCapability = "safe-adoption";
+export function legacyPath(...segments) {
+    return segments.flat().join("/");
+}
+export function resolveHarnessPaths(targetInput = ".") {
+    const target = normalizeTargetShape(targetInput);
+    const manifestPath = path.join(target.harnessRootCandidate, "harness.yaml");
+    const manifest = readHarnessManifest(manifestPath);
+    if (manifest) {
+        const structure = manifest.structure || {};
+        const harnessRoot = structure.harnessRoot || v2HarnessRoot;
+        const planningRoot = structure.planningRoot || `${harnessRoot}/planning`;
+        const tasksRoot = structure.tasksRoot || `${planningRoot}/tasks`;
+        const modulesRoot = structure.modulesRoot || `${planningRoot}/modules`;
+        const externalRoot = structure.externalRoot || `${planningRoot}/external`;
+        const governanceRoot = structure.governanceRoot || `${harnessRoot}/governance`;
+        const generatedRoot = structure.generatedRoot || `${governanceRoot}/generated`;
+        const regressionRoot = structure.regressionRoot || `${governanceRoot}/regression`;
+        const resolved = Object.fromEntries(Object.entries({
+            harnessRoot,
+            planningRoot,
+            tasksRoot,
+            modulesRoot,
+            externalRoot,
+            governanceRoot,
+            generatedRoot,
+            regressionRoot,
+        }).map(([key, value]) => [key, resolveManifestStructurePath(target.projectRoot, key, value)]));
+        return {
+            version: 2,
+            manifest,
+            manifestPath,
+            input: target.input,
+            projectRoot: target.projectRoot,
+            docsRoot: target.docsRoot,
+            docsOnly: target.docsOnly,
+            harnessRoot: resolved.harnessRoot,
+            planningRoot: resolved.planningRoot,
+            tasksRoot: resolved.tasksRoot,
+            modulesRoot: resolved.modulesRoot,
+            taskRoots: [resolved.tasksRoot, resolved.modulesRoot],
+            externalRoot: resolved.externalRoot,
+            governanceRoot: resolved.governanceRoot,
+            generatedRoot: resolved.generatedRoot,
+            regressionRoot: resolved.regressionRoot,
+            ledgerPath: path.join(resolved.generatedRoot, "Harness-Ledger.md"),
+            closeoutIndexPath: path.join(resolved.generatedRoot, "Closeout-Index.md"),
+            legacy: legacyPaths(target.projectRoot),
+        };
+    }
+    const legacy = legacyPaths(target.projectRoot);
+    return {
+        version: 1,
+        manifest: null,
+        manifestPath,
+        input: target.input,
+        projectRoot: target.projectRoot,
+        docsRoot: target.docsRoot,
+        docsOnly: target.docsOnly,
+        harnessRoot: target.docsRoot,
+        planningRoot: legacy.planningRoot,
+        tasksRoot: legacy.tasksRoot,
+        modulesRoot: legacy.modulesRoot,
+        taskRoots: [legacy.tasksRoot, legacy.modulesRoot],
+        externalRoot: "",
+        governanceRoot: target.docsRoot,
+        generatedRoot: path.join(legacy.planningRoot, "generated"),
+        regressionRoot: path.join(target.docsRoot, "05-TEST-QA"),
+        ledgerPath: legacy.ledgerPath,
+        closeoutIndexPath: legacy.closeoutPath,
+        legacy,
+    };
+}
+export function taskIdFromDirectory(paths, taskDir) {
+    const normalized = path.resolve(taskDir);
+    const tasksRoot = path.resolve(paths.tasksRoot);
+    const modulesRoot = path.resolve(paths.modulesRoot);
+    const externalRoot = paths.externalRoot ? path.resolve(paths.externalRoot) : "";
+    if (isPathInside(normalized, tasksRoot))
+        return `TASKS/${toPosix(path.relative(tasksRoot, normalized))}`;
+    if (isPathInside(normalized, modulesRoot)) {
+        const relative = toPosix(path.relative(modulesRoot, normalized));
+        const match = relative.match(/^([^/]+)\/tasks\/(.+)$/);
+        return match ? `MODULES/${match[1]}/${match[2]}` : `MODULES/${relative}`;
+    }
+    if (externalRoot && isPathInside(normalized, externalRoot))
+        return `EXTERNAL/${toPosix(path.relative(externalRoot, normalized))}`;
+    if (paths.version === 1)
+        return toPosix(path.relative(paths.planningRoot, normalized));
+    return toPosix(path.relative(paths.projectRoot, normalized));
+}
+export function taskRefPath(paths, raw) {
+    if (/^TASKS\//.test(raw))
+        return path.join(paths.tasksRoot, raw.replace(/^TASKS\//, ""));
+    if (/^MODULES\//.test(raw))
+        return moduleRefPath(paths, raw.replace(/^MODULES\//, ""));
+    if (/^EXTERNAL\//.test(raw) && paths.externalRoot)
+        return path.join(paths.externalRoot, raw.replace(/^EXTERNAL\//, ""));
+    if (/^(tasks|modules|external)\//.test(raw))
+        return path.join(paths.planningRoot, raw);
+    return "";
+}
+export function taskLocalWalkthrough(paths, taskDir) {
+    if (paths.version !== 2)
+        return "";
+    const walkthrough = path.join(taskDir, "walkthrough.md");
+    if (!fs.existsSync(walkthrough))
+        return "";
+    let stat;
+    try {
+        stat = fs.lstatSync(walkthrough);
+    }
+    catch {
+        return "";
+    }
+    if (!stat.isFile() || stat.isSymbolicLink())
+        return "";
+    return toPosix(path.relative(paths.projectRoot, walkthrough));
+}
+export function dashboardWatchRoots(paths) {
+    const roots = paths.version === 2
+        ? [
+            paths.harnessRoot,
+            paths.planningRoot,
+            paths.tasksRoot,
+            paths.modulesRoot,
+            paths.externalRoot,
+            paths.governanceRoot,
+            paths.generatedRoot,
+            paths.regressionRoot,
+        ]
+        : [paths.docsRoot];
+    return dedupeAncestorRoots(roots.filter(Boolean).map((root) => path.resolve(root)).filter((root) => fs.existsSync(root)));
+}
+export function discoverImplicitHarnessTarget(input = ".") {
+    const root = path.resolve(input || ".");
+    const nearest = findNearestHarnessRoot(root);
+    if (nearest)
+        return projectRootForHarnessRoot(nearest);
+    const discovered = findProjectHarnessRoot(root, { requireDeclaredProjectRoot: false });
+    return discovered ? projectRootForHarnessRoot(discovered) : "";
+}
+function moduleRefPath(paths, relative) {
+    if (paths.version !== 2)
+        return path.join(paths.modulesRoot, relative);
+    const [moduleKey = "", ...taskSegments] = relative.split("/");
+    return taskSegments.length ? path.join(paths.modulesRoot, moduleKey, "tasks", ...taskSegments) : path.join(paths.modulesRoot, moduleKey);
+}
+export function toPosix(value) {
+    return String(value).split(path.sep).join("/");
+}
+function normalizeTargetShape(input = ".") {
+    if (input && typeof input === "object" && input.projectRoot) {
+        const requestedProjectRoot = path.resolve(input.projectRoot);
+        const inputPath = path.resolve(input.input || requestedProjectRoot);
+        const directHarnessRoot = findNearestHarnessRoot(inputPath);
+        const discoveredHarnessRoot = directHarnessRoot || findProjectHarnessRoot(requestedProjectRoot);
+        const projectRoot = directHarnessRoot
+            ? projectRootForHarnessRoot(directHarnessRoot)
+            : requestedProjectRoot;
+        return {
+            ...input,
+            projectRoot,
+            docsRoot: input.docsRoot || path.join(projectRoot, "docs"),
+            harnessRootCandidate: input.harnessRootCandidate || discoveredHarnessRoot || path.join(projectRoot, v2HarnessRoot),
+        };
+    }
+    const target = path.resolve(typeof input === "string" ? input || "." : ".");
+    const docsProjectRoot = path.dirname(target);
+    const siblingHarnessRoot = findProjectHarnessRoot(docsProjectRoot);
+    const siblingV2Manifest = siblingHarnessRoot
+        ? path.join(siblingHarnessRoot, "harness.yaml")
+        : path.join(docsProjectRoot, v2HarnessRoot, "harness.yaml");
+    const isDocsRoot = path.basename(target) === "docs" &&
+        (fs.existsSync(path.join(target, "09-PLANNING")) || fs.existsSync(path.join(target, "11-REFERENCE")) || fs.existsSync(siblingV2Manifest));
+    const directHarnessRoot = !isDocsRoot ? findNearestHarnessRoot(target) : "";
+    const discoveredHarnessRoot = directHarnessRoot || (!isDocsRoot ? findProjectHarnessRoot(target) : siblingHarnessRoot);
+    const projectRoot = isDocsRoot ? docsProjectRoot : directHarnessRoot ? projectRootForHarnessRoot(directHarnessRoot) : target;
+    return {
+        input: target,
+        projectRoot,
+        docsRoot: isDocsRoot ? target : path.join(target, "docs"),
+        docsOnly: isDocsRoot,
+        harnessRootCandidate: discoveredHarnessRoot || path.join(projectRoot, v2HarnessRoot),
+    };
+}
+function findNearestHarnessRoot(target) {
+    let current = target;
+    for (let depth = 0; depth < 5; depth += 1) {
+        if (fs.existsSync(path.join(current, "harness.yaml")))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return "";
+}
+function findProjectHarnessRoot(projectRoot, { requireDeclaredProjectRoot = true } = {}) {
+    const defaultRoot = path.join(projectRoot, v2HarnessRoot);
+    if (fs.existsSync(path.join(defaultRoot, "harness.yaml")))
+        return defaultRoot;
+    const candidates = [];
+    const ignored = new Set([".git", "node_modules", "tmp", "dist", "build", ".next", "coverage"]);
+    function visit(dir, depth) {
+        if (depth > 5 || !fs.existsSync(dir))
+            return;
+        if (fs.existsSync(path.join(dir, "harness.yaml")) && (!requireDeclaredProjectRoot || projectRootForHarnessRoot(dir) === projectRoot)) {
+            candidates.push(dir);
+            return;
+        }
+        for (const entry of fs.readdirSync(dir)) {
+            if (ignored.has(entry))
+                continue;
+            const full = path.join(dir, entry);
+            let stat;
+            try {
+                stat = fs.lstatSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (stat.isDirectory() && !stat.isSymbolicLink())
+                visit(full, depth + 1);
+        }
+    }
+    visit(projectRoot, 0);
+    const unique = [...new Set(candidates)].sort((left, right) => {
+        const leftDepth = path.relative(projectRoot, left).split(path.sep).filter(Boolean).length;
+        const rightDepth = path.relative(projectRoot, right).split(path.sep).filter(Boolean).length;
+        return leftDepth - rightDepth || left.localeCompare(right);
+    });
+    if (unique.length > 1) {
+        const shallowestDepth = path.relative(projectRoot, unique[0]).split(path.sep).filter(Boolean).length;
+        const shallowest = unique.filter((item) => path.relative(projectRoot, item).split(path.sep).filter(Boolean).length === shallowestDepth);
+        if (shallowest.length === 1)
+            return shallowest[0];
+        throw new Error(`Multiple v2 harness manifests found at the same nearest depth; pass the intended harness root explicitly: ${shallowest.map((item) => toPosix(path.relative(projectRoot, item))).join(", ")}`);
+    }
+    return unique[0] || "";
+}
+function projectRootForHarnessRoot(harnessRoot) {
+    const manifest = readHarnessManifest(path.join(harnessRoot, "harness.yaml"));
+    const declaredHarnessRoot = manifest?.structure?.harnessRoot || v2HarnessRoot;
+    let current = harnessRoot;
+    for (let depth = 0; depth < 10; depth += 1) {
+        if (path.resolve(current, declaredHarnessRoot) === path.resolve(harnessRoot))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return path.dirname(harnessRoot);
+}
+function legacyPaths(projectRoot) {
+    const docsRoot = path.join(projectRoot, "docs");
+    const planningRoot = path.join(docsRoot, ...legacyPlanningRoot.slice(1));
+    return {
+        docsRoot,
+        planningRoot,
+        tasksRoot: path.join(docsRoot, ...legacyTaskRoot.slice(1)),
+        modulesRoot: path.join(docsRoot, ...legacyModuleRoot.slice(1)),
+        walkthroughRoot: path.join(docsRoot, ...legacyWalkthroughRoot.slice(1)),
+        ledgerPath: path.join(projectRoot, ...legacyLedgerFile),
+        closeoutPath: path.join(projectRoot, ...legacyCloseoutFile),
+    };
+}
+function readHarnessManifest(manifestPath) {
+    if (!fs.existsSync(manifestPath))
+        return null;
+    const manifest = { version: 2, locale: "en-US", capabilities: [], structure: {} };
+    let section = "";
+    for (const rawLine of fs.readFileSync(manifestPath, "utf8").split(/\r?\n/)) {
+        const line = rawLine.replace(/\s+#.*$/, "");
+        if (!line.trim())
+            continue;
+        const top = line.match(/^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/);
+        if (top) {
+            section = top[1];
+            if (section === "version")
+                manifest.version = Number(top[2]) || 2;
+            else if (section === "locale")
+                manifest.locale = top[2] || "en-US";
+            else if (section !== "structure" && section !== "capabilities")
+                manifest[section] = top[2];
+            continue;
+        }
+        const listItem = line.match(/^\s*-\s*(.+)$/);
+        if (section === "capabilities" && listItem) {
+            manifest.capabilities.push(listItem[1].trim());
+            continue;
+        }
+        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 (!manifest.structure.harnessRoot && manifest.harnessRoot)
+        manifest.structure.harnessRoot = manifest.harnessRoot;
+    if (!manifest.structure.planningRoot && manifest.harnessRoot)
+        manifest.structure.planningRoot = `${manifest.harnessRoot}/planning`;
+    return manifest;
+}
+function resolveManifestStructurePath(projectRoot, fieldName, relativePath) {
+    const raw = String(relativePath || "").trim();
+    if (!raw)
+        throw new Error(`Invalid v2 harness manifest: structure.${fieldName} is empty`);
+    if (path.isAbsolute(raw))
+        throw new Error(`Invalid v2 harness manifest: structure.${fieldName} escapes project root: ${raw}`);
+    const resolved = path.resolve(projectRoot, raw);
+    if (!isPathInside(resolved, projectRoot)) {
+        throw new Error(`Invalid v2 harness manifest: structure.${fieldName} escapes project root: ${raw}`);
+    }
+    return resolved;
+}
+function isPathInside(child, parent) {
+    const relative = path.relative(parent, child);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function dedupeAncestorRoots(roots) {
+    const result = [];
+    for (const root of [...new Set(roots)].sort((a, b) => a.length - b.length)) {
+        if (result.some((parent) => isPathInside(root, parent)))
+            continue;
+        result.push(root);
+    }
+    return result;
+}

package/dist/lib/lesson-maintenance.mjs

@@ -0,0 +1,139 @@
+// @ts-nocheck
+import fs from "node:fs";
+import path from "node:path";
+import { datePrefix, lessonCandidatesFile, normalizeTarget, readFileSafe, slug, toPosix, } from "./core-shared.mjs";
+import { collectTasks, parseLessonCandidateStatus, } from "./task-scanner.mjs";
+import { beginGovernanceSync, commitGovernanceSync, releaseGovernanceSync, } from "./governance-sync.mjs";
+export function promoteLessonCandidate(targetInput, taskId, candidateId, { dryRun = false, apply = false } = {}) {
+    const target = normalizeTarget(targetInput);
+    const normalizedRef = slug(taskId);
+    const matchesBareSlug = (item) => {
+        if (!datePrefix.test(normalizedRef)) {
+            const shortBase = datePrefix.test(item.shortId) ? item.shortId.replace(datePrefix, "") : item.shortId;
+            if (shortBase === normalizedRef)
+                return true;
+        }
+        return false;
+    };
+    const candidates = collectTasks(target).filter((item) => item.id === taskId || item.shortId === taskId || item.id.endsWith(`/${taskId}`) || matchesBareSlug(item));
+    if (candidates.length > 1) {
+        const options = candidates.map((item) => `- ${item.id}`).join("\n");
+        throw new Error(`Ambiguous task reference: ${taskId}\n${options}`);
+    }
+    const task = candidates[0];
+    if (!task)
+        throw new Error(`Task not found: ${taskId}`);
+    if (!candidateId)
+        throw new Error("Missing lesson candidate id");
+    const taskDir = path.join(target.projectRoot, task.path.replace(/^TARGET:/, ""));
+    const candidatePath = path.join(taskDir, lessonCandidatesFile);
+    const candidateContent = readFileSafe(candidatePath);
+    const parsed = parseLessonCandidateStatus(candidateContent);
+    const row = parsed.rows.find((item) => item.id.toLowerCase() === candidateId.toLowerCase());
+    if (!row)
+        throw new Error(`Lesson candidate not found: ${candidateId}`);
+    if (!["needs-promotion", "promoted"].includes(row.status)) {
+        throw new Error(`Lesson candidate must be needs-promotion before promotion; current status is ${row.status}`);
+    }
+    const lessonId = lessonIdFromCandidate(row.id);
+    const title = row.title || lessonId;
+    const detailRoot = target.harness.version === 2
+        ? toPosix(path.relative(target.projectRoot, path.join(target.harness.governanceRoot, "lessons")))
+        : "docs/01-GOVERNANCE/lessons";
+    const detailRelative = `${detailRoot}/${lessonId}-${slug(title)}.md`;
+    const detailPath = path.join(target.projectRoot, detailRelative);
+    const changes = [];
+    if (!fs.existsSync(detailPath))
+        changes.push({ action: dryRun ? "would-create" : "create", path: `TARGET:${detailRelative}` });
+    if (row.status !== "promoted" || parsed.status !== "promoted")
+        changes.push({ action: dryRun ? "would-update" : "update", path: task.lessonCandidatePath || `TARGET:${toPosix(path.relative(target.projectRoot, candidatePath))}` });
+    const effectiveDryRun = dryRun || !apply;
+    if (effectiveDryRun) {
+        return {
+            dryRun: true,
+            applyRequired: true,
+            taskId: task.id,
+            candidateId: row.id,
+            lessonId,
+            detailDoc: `TARGET:${detailRelative}`,
+            changes: changes.map((change) => ({ ...change, action: change.action.replace(/^(create|append|update)$/, "would-$1") })),
+            nextCommand: `harness lesson-promote ${task.shortId} ${row.id} --apply`,
+        };
+    }
+    const governanceContext = beginGovernanceSync(target, { operation: `lesson-promote ${task.id} ${row.id}` });
+    try {
+        fs.mkdirSync(path.dirname(detailPath), { recursive: true });
+        if (!fs.existsSync(detailPath))
+            fs.writeFileSync(detailPath, renderLessonDetail({ lessonId, candidate: row, task, detailRelative }));
+        fs.writeFileSync(candidatePath, markCandidatePromoted(candidateContent, row.id, lessonId));
+        const commit = commitGovernanceSync(governanceContext, [
+            detailRelative,
+            toPosix(path.relative(target.projectRoot, candidatePath)),
+        ], { message: `chore(harness): promote lesson ${row.id}` });
+        return { dryRun: false, taskId: task.id, candidateId: row.id, lessonId, detailDoc: `TARGET:${detailRelative}`, changes, governance: { commit } };
+    }
+    finally {
+        releaseGovernanceSync(governanceContext);
+    }
+}
+function lessonIdFromCandidate(candidateId) {
+    const match = String(candidateId || "").match(/^LC-(\d{4})(\d{2})(\d{2})-(\d+)$/i);
+    if (!match)
+        return `L-${slug(candidateId)}`;
+    return `L-${match[1]}-${match[2]}-${match[3]}-${match[4].padStart(3, "0")}`;
+}
+function renderLessonDetail({ lessonId, candidate, task }) {
+    return [
+        `# ${lessonId} - ${candidate.title || "Lesson Candidate"}`,
+        "",
+        "## Source",
+        "",
+        `- Task: ${task.id}`,
+        `- Candidate: ${candidate.id}`,
+        `- Promotion target: ${candidate.promotionTarget || "not specified"}`,
+        "",
+        "## Summary",
+        "",
+        candidate.title || "Promoted lesson candidate.",
+        "",
+        "## Why It Matters",
+        "",
+        candidate.reviewDecision || "Human review marked this candidate for governance promotion.",
+        "",
+        "## Status",
+        "",
+        "- State: pending governance integration",
+        "",
+    ].join("\n");
+}
+function markCandidatePromoted(content, candidateId, lessonId) {
+    const lines = String(content || "").split(/\r?\n/);
+    const headerIndex = lines.findIndex((line) => /^\|\s*ID\s*\|/.test(line));
+    if (headerIndex >= 0) {
+        const header = splitSimpleRow(lines[headerIndex]);
+        const statusIndex = header.findIndex((cell) => /^(Row Status|行状态|Status|状态)$/i.test(cell));
+        const decisionIndex = header.findIndex((cell) => /^(Review Decision|审查决定)$/i.test(cell));
+        for (let index = headerIndex + 2; index < lines.length && lines[index].trim().startsWith("|"); index += 1) {
+            const cells = splitSimpleRow(lines[index]);
+            if ((cells[0] || "").toLowerCase() !== candidateId.toLowerCase())
+                continue;
+            if (statusIndex >= 0)
+                cells[statusIndex] = "promoted";
+            if (decisionIndex >= 0 && !cells[decisionIndex].includes(lessonId))
+                cells[decisionIndex] = `${cells[decisionIndex]} promoted:${lessonId}`.trim();
+            lines[index] = `| ${cells.map(escapeCell).join(" | ")} |`;
+        }
+    }
+    return `${lines.join("\n")
+        .replace("| Task-level status | needs-promotion |", "| Task-level status | promoted |")
+        .replace("| Promotion state | not-promoted |", "| Promotion state | promoted |")
+        .replace("| Closeout token | pending |", `| Closeout token | checked-created:${lessonId} |`)
+        .replace(/\| Closeout token \| queued-promotion:[^|]+ \|/, `| Closeout token | checked-created:${lessonId} |`)
+        .trimEnd()}\n`;
+}
+function splitSimpleRow(line) {
+    return String(line || "").replace(/^\s*\|/, "").replace(/\|\s*$/, "").split("|").map((cell) => cell.trim());
+}
+function escapeCell(value) {
+    return String(value || "").replace(/\r?\n/g, " ").replaceAll("|", "\\|").trim();
+}