coding-agent-harness 1.0.7 → 1.1.0

package/dist/lib/task-template-materials.mjs

@@ -0,0 +1,131 @@
+import path from "node:path";
+import { lessonCandidatesFile, readFileSafe, toPosix, visualMapFile, } from "./core-shared.mjs";
+export function collectUneditedTemplateMaterialIssues(target, taskDir, materials) {
+    const issues = [];
+    const files = [
+        { label: "brief.md", sourcePath: toPosix(path.relative(target.projectRoot, path.join(taskDir, "brief.md"))), content: materials.briefContent },
+        { label: "task_plan.md", sourcePath: toPosix(path.relative(target.projectRoot, path.join(taskDir, "task_plan.md"))), content: materials.taskPlanContent },
+        { label: "execution_strategy.md", sourcePath: toPosix(path.relative(target.projectRoot, path.join(taskDir, "execution_strategy.md"))), content: materials.executionStrategyContent },
+        { label: visualMapFile, sourcePath: toPosix(path.relative(target.projectRoot, path.join(taskDir, visualMapFile))), content: materials.visualMapContent },
+        { label: "progress.md", sourcePath: toPosix(path.relative(target.projectRoot, path.join(taskDir, "progress.md"))), content: materials.progressContent },
+        { label: "findings.md", sourcePath: toPosix(path.relative(target.projectRoot, path.join(taskDir, "findings.md"))), content: materials.findingsContent },
+        { label: "review.md", sourcePath: toPosix(path.relative(target.projectRoot, path.join(taskDir, "review.md"))), content: materials.reviewContent },
+        { label: lessonCandidatesFile, sourcePath: toPosix(path.relative(target.projectRoot, path.join(taskDir, lessonCandidatesFile))), content: materials.lessonCandidatesContent },
+    ];
+    if (materials.walkthroughPath) {
+        files.push({
+            label: path.basename(materials.walkthroughPath),
+            sourcePath: materials.walkthroughPath,
+            content: readFileSafe(path.join(target.projectRoot, materials.walkthroughPath)),
+        });
+    }
+    for (const file of files) {
+        const markers = uneditedCoreTemplateSlots(file.label, file.content);
+        if (markers.length === 0)
+            continue;
+        issues.push({
+            code: "unedited-template-material",
+            severity: "P2",
+            queue: "missing-materials",
+            sourcePath: `TARGET:${file.sourcePath}`,
+            sourceLine: 0,
+            owner: "agent",
+            message: `[unedited-template-material] Reviewable task material still contains default core content in ${file.label}: ${markers.slice(0, 3).join(", ")}.`,
+            allowedWritePaths: [`${toPosix(path.relative(target.projectRoot, taskDir))}/**`],
+            forbiddenActions: ["human-confirm", "edit-unrelated-task", "fabricate-evidence"],
+            validationCommands: ["node dist/harness.mjs check --profile target-project <target>"],
+            confidence: "high",
+            repairable: true,
+            enforceFailure: materials.humanReviewConfirmed,
+        });
+    }
+    return issues;
+}
+function uneditedCoreTemplateSlots(label, content) {
+    const text = String(content || "");
+    const markers = [];
+    if (label === "brief.md") {
+        if (sectionHasDefault(text, ["Outcome Statement", "一句话结果"], [
+            "One sentence stating the concrete result this task must produce.",
+            "用一句话说明这个任务完成后会产生什么具体结果。",
+            "说明这个任务完成后，用户或项目能直接看到的结果。",
+        ]))
+            markers.push("brief-outcome");
+    }
+    else if (label === "task_plan.md") {
+        if (sectionHasDefault(text, ["Goal", "目标"], [
+            "[State the outcome this task must deliver in one sentence.]",
+            "[用一句话说明本任务完成后应达到的状态。]",
+        ]))
+            markers.push("task-plan-goal");
+    }
+    else if (label === "execution_strategy.md") {
+        if (sectionHasDefault(text, ["Strategy Summary"], ["[Describe the execution approach, including why this operating model fits the risk and scope.]"]) ||
+            /\|\s*L0\s*\|\s*\[静态检查\s*\/\s*小范围自检\]\s*\|\s*`?progress\.md`?\s*\|\s*\[通过标准\]\s*\|/i.test(text)) {
+            markers.push("execution-strategy-core-plan");
+        }
+    }
+    else if (label === visualMapFile) {
+        if (hasDefaultExecutionPhase(text))
+            markers.push("visual-map-execution-phase");
+    }
+    else if (label === "progress.md") {
+        if (/^\|\s*YYYY-MM-DD HH:MM\s*\|\s*coordinator\s*\|\s*\[action taken\]\s*\|/im.test(text) ||
+            /^###\s*\[YYYY-MM-DD HH:MM\]\s*-\s*\[阶段名称\]\s*$/im.test(text) ||
+            /^-\s*做了什么：\[具体操作\]\s*$/im.test(text)) {
+            markers.push("progress-log-entry");
+        }
+    }
+    else if (label === "review.md") {
+        if (/\|\s*Evidence Summary\s*\|\s*\[(?:tests, diff, runtime, and review packet evidence|测试、diff、运行和审查材料证据)\]\s*\|/i.test(text) ||
+            /\|\s*E-001\s*\|[^|\n]*\|[^|\n]*\|\s*\[(?:what was checked and what it showed|检查了什么，结论是什么)\]\s*\|/i.test(text)) {
+            markers.push("review-evidence");
+        }
+    }
+    else if (label === lessonCandidatesFile) {
+        if (/\|\s*Task-level status\s*\|\s*no-candidate-accepted\s*\|/i.test(text) &&
+            /^(?:Not decided yet\. Fill this only when review accepts that the task produced no reusable lesson candidate\.|尚未判定。只有人工审查接受本任务没有可复用候选时，才填写这里。)\s*$/im.test(text)) {
+            markers.push("lesson-no-candidate-reason");
+        }
+    }
+    else if (label === "walkthrough.md") {
+        if (sectionHasDefault(text, ["Summary", "摘要"], ["Pending closeout.", "待收口。"]))
+            markers.push("walkthrough-summary");
+    }
+    return markers;
+}
+function sectionHasDefault(text, headings, defaults) {
+    const body = sectionBody(text, headings);
+    if (!body)
+        return false;
+    return defaults.some((value) => body === value || body.split(/\r?\n/).map((line) => line.trim()).includes(value));
+}
+function sectionBody(text, headings) {
+    const lines = text.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+        const match = lines[index].match(/^(#{2,6})\s+(.+?)\s*$/);
+        if (!match)
+            continue;
+        if (!headings.includes(match[2].trim()))
+            continue;
+        const level = match[1].length;
+        const body = [];
+        for (let bodyIndex = index + 1; bodyIndex < lines.length; bodyIndex += 1) {
+            const nextHeading = lines[bodyIndex].match(/^(#{2,6})\s+/);
+            if (nextHeading && nextHeading[1].length <= level)
+                break;
+            if (lines[bodyIndex].trim())
+                body.push(lines[bodyIndex].trim());
+        }
+        return body.join("\n").trim();
+    }
+    return "";
+}
+function hasDefaultExecutionPhase(text) {
+    const rows = text.split(/\r?\n/).filter((line) => /^\|\s*EXEC-01\s*\|/.test(line));
+    return rows.some((row) => {
+        const cells = row.split("|").map((cell) => cell.trim()).filter(Boolean);
+        return cells.some((cell) => cell === "Scoped implementation, document update, and verification evidence" || cell === "有边界的实现、文档切片和验证证据") &&
+            cells.some((cell) => cell === "diff, commands, worker handoff, or artifact path" || cell === "diff、commands、worker handoff 或 artifact path");
+    });
+}

package/dist/lib/task-tombstone-commands.mjs

@@ -1,22 +1,27 @@
-// @ts-nocheck
 import fs from "node:fs";
 import path from "node:path";
 import { normalizeTarget, nowTimestamp, readFileSafe, toPosix, datePrefix, } from "./core-shared.mjs";
+import { removeHeadingSectionOutsideFences } from "./markdown-utils.mjs";
 import { collectTasks } from "./task-scanner.mjs";
+import { resolveTaskDirectory } from "./task-lifecycle.mjs";
+import { taskIdFromDirectory } from "./harness-paths.mjs";
+import { assessArchiveEligibility, normalizeArchiveActor } from "./task-archive-eligibility.mjs";
+import { normalizeReviewBoolean } from "./task-review-model.mjs";
 import { beginGovernanceSync, commitGovernanceSync, releaseGovernanceSync, } from "./governance-sync.mjs";
-export function supersedeTask(targetInput, oldRef, { by = "", reason = "" } = {}) {
+export function supersedeTask(targetInput, oldRef, { by = "", reason = "", deletedBy = "", confirm = "", allowOpenFindings = false } = {}) {
     if (!by)
         throw new Error("task-supersede requires --by <new-task-id>");
     const target = normalizeTarget(targetInput);
     const oldTask = resolveTask(target, oldRef);
     const newTask = resolveTask(target, by);
+    assertSoftDeleteEligible(oldTask, { reason, deletedBy, confirm, allowOpenFindings, action: "task-supersede" });
     const governanceContext = beginGovernanceSync(target, { operation: `task-supersede ${oldTask.id}` });
     try {
         writeTombstone(target, oldTask, {
             State: "superseded",
             "Superseded By": newTask.id,
             Reason: reason || "superseded",
-            Operator: "coordinator",
+            Operator: normalizeTombstoneActor(deletedBy) || "coordinator",
             Timestamp: nowTimestamp(),
             "Reopen Eligible": "yes",
             "Archive Eligible": "no",
@@ -32,15 +37,43 @@ export function supersedeTask(targetInput, oldRef, { by = "", reason = "" } = {}
         releaseGovernanceSync(governanceContext);
     }
 }
-export function softDeleteTask(targetInput, taskRef, { reason = "" } = {}) {
+export function softDeleteTask(targetInput, taskRef, options = {}) {
+    return deleteTask(targetInput, taskRef, { ...options, hard: false });
+}
+export function deleteTask(targetInput, taskRef, { hard = false, reason = "", deletedBy = "", confirm = "", allowOpenFindings = false } = {}) {
     const target = normalizeTarget(targetInput);
     const task = resolveTask(target, taskRef);
-    return writeDeletionState(target, task, "soft-deleted", reason || "soft-delete", "task-delete --soft");
+    if (!hard) {
+        assertSoftDeleteEligible(task, { reason, deletedBy, confirm, allowOpenFindings, action: "task-delete" });
+        return writeDeletionState(target, task, "soft-deleted", reason || "soft-delete", "task-delete --soft", {
+            Operator: normalizeTombstoneActor(deletedBy) || "coordinator",
+        });
+    }
+    assertHardDeleteEligible(target, task, { reason, deletedBy, confirm });
+    const taskDir = path.join(target.projectRoot, task.path.replace(/^TARGET:/, ""));
+    const allowedPaths = collectTaskDirectoryFiles(taskDir).map((file) => toPosix(path.relative(target.projectRoot, file)));
+    const governanceContext = beginGovernanceSync(target, { operation: `task-delete --hard ${task.id}` });
+    try {
+        fs.rmSync(taskDir, { recursive: true, force: true });
+        const commit = commitGovernanceSync(governanceContext, allowedPaths, {
+            message: `chore(harness): hard delete task ${task.id}`,
+        });
+        return { taskId: task.id, deletionState: "hard-deleted", reason, governance: { commit } };
+    }
+    finally {
+        releaseGovernanceSync(governanceContext);
+    }
 }
-export function archiveTask(targetInput, taskRef, { reason = "" } = {}) {
+export function archiveTask(targetInput, taskRef, { reason = "", archivedBy = "", archiveFields = {} } = {}) {
     const target = normalizeTarget(targetInput);
     const task = resolveTask(target, taskRef);
-    return writeDeletionState(target, task, "archived", reason || "archive", "task-archive");
+    const archiveAudit = assertArchiveEligible(task, { archivedBy });
+    const normalizedArchiveFields = normalizeArchiveFields(archiveFields);
+    assertNoReservedArchiveFields(normalizedArchiveFields);
+    return writeDeletionState(target, task, "archived", reason || "archive", "task-archive", {
+        ...normalizedArchiveFields,
+        ...archiveAudit,
+    });
 }
 export function reopenTask(targetInput, taskRef, { reason = "" } = {}) {
     const target = normalizeTarget(targetInput);
@@ -49,7 +82,7 @@ export function reopenTask(targetInput, taskRef, { reason = "" } = {}) {
     try {
         const taskPlanPath = path.join(target.projectRoot, task.taskPlanPath.replace(/^TARGET:/, ""));
         const content = readFileSafe(taskPlanPath);
-        const next = content.replace(/\n##\s*(?:Task Tombstone|任务墓碑)\s*$[\s\S]*?(?=^##\s+|(?![\s\S]))/im, "");
+        const next = removeHeadingSectionOutsideFences(content, /^##\s*(?:Task Tombstone|任务墓碑)\s*$/i);
         fs.writeFileSync(taskPlanPath, next.endsWith("\n") ? next : `${next}\n`);
         appendProgress(target, task, "task-reopen", reason || "reopened");
         const commit = commitGovernanceSync(governanceContext, taskPaths(target, task), {
@@ -61,7 +94,8 @@ export function reopenTask(targetInput, taskRef, { reason = "" } = {}) {
         releaseGovernanceSync(governanceContext);
     }
 }
-function writeDeletionState(target, task, deletionState, reason, action) {
+function writeDeletionState(target, task, deletionState, reason, action, archiveFields = {}) {
+    const normalizedArchiveFields = normalizeArchiveFields(archiveFields);
     const governanceContext = beginGovernanceSync(target, { operation: `${action} ${task.id}` });
     try {
         writeTombstone(target, task, {
@@ -71,6 +105,7 @@ function writeDeletionState(target, task, deletionState, reason, action) {
             Timestamp: nowTimestamp(),
             "Reopen Eligible": "yes",
             "Archive Eligible": deletionState === "archived" ? "yes" : "no",
+            ...normalizedArchiveFields,
         });
         appendProgress(target, task, action, reason);
         const commit = commitGovernanceSync(governanceContext, taskPaths(target, task), {
@@ -90,22 +125,121 @@ function contextFor(_target, context) {
 }
 function resolveTask(target, ref) {
     const normalized = String(ref || "").trim();
-    const matches = collectTasks(target).filter((task) => {
-        const bare = datePrefix.test(task.shortId) ? task.shortId.replace(datePrefix, "") : task.shortId;
-        return task.id === normalized || task.shortId === normalized || task.id.endsWith(`/${normalized}`) || bare === normalized;
-    });
-    if (matches.length === 1)
-        return matches[0];
-    if (matches.length > 1)
-        throw new Error(`Ambiguous task reference: ${ref}`);
+    const resolvedTarget = target;
+    const taskDir = resolveTaskDirectory(resolvedTarget, normalized);
+    const taskId = taskIdFromDirectory(resolvedTarget.harness, taskDir);
+    const task = collectTasks(target).find((candidate) => candidate.id === taskId);
+    if (task)
+        return task;
     throw new Error(`Task not found: ${ref}`);
 }
+function assertArchiveEligible(task, { archivedBy = "" } = {}) {
+    const result = assessArchiveEligibility(task, { archivedBy, now: nowTimestamp() });
+    if (!result.eligible)
+        throw new Error(result.reason);
+    return result.auditFields;
+}
 function writeTombstone(target, task, fields) {
     const taskPlanPath = path.join(target.projectRoot, task.taskPlanPath.replace(/^TARGET:/, ""));
-    const content = readFileSafe(taskPlanPath).replace(/\n##\s*(?:Task Tombstone|任务墓碑)\s*$[\s\S]*?(?=^##\s+|(?![\s\S]))/im, "");
+    const content = removeHeadingSectionOutsideFences(readFileSafe(taskPlanPath), /^##\s*(?:Task Tombstone|任务墓碑)\s*$/i);
     const block = ["", "## Task Tombstone", "", "| Field | Value |", "| --- | --- |", ...Object.entries(fields).map(([key, value]) => `| ${key} | ${escapeCell(value)} |`), ""].join("\n");
     fs.writeFileSync(taskPlanPath, `${content.trimEnd()}\n${block}`);
 }
+function assertSoftDeleteEligible(task, { reason = "", deletedBy = "", confirm = "", allowOpenFindings = false, action = "task-delete" } = {}) {
+    const risky = isRiskyMutationTask(task);
+    const hasOpenFindings = !isDraftState(task.state) && hasOpenBlockingFindings(task);
+    if (!risky && !hasOpenFindings)
+        return;
+    const missing = [];
+    if (!String(reason || "").trim())
+        missing.push("--reason");
+    if (!normalizeTombstoneActor(deletedBy))
+        missing.push("--deleted-by");
+    if (String(confirm || "").trim() !== task.id)
+        missing.push(`--confirm ${task.id}`);
+    if (hasOpenFindings && !allowOpenFindings)
+        missing.push("--allow-open-findings");
+    if (missing.length) {
+        throw new Error(`${action} would hide a risky task; required: ${missing.join(", ")}`);
+    }
+}
+export function assertHardDeleteEligible(target, task, { reason = "", deletedBy = "", confirm = "" } = {}) {
+    const missing = [];
+    if (!String(reason || "").trim())
+        missing.push("--reason");
+    if (!normalizeTombstoneActor(deletedBy))
+        missing.push("--deleted-by");
+    if (String(confirm || "").trim() !== task.id)
+        missing.push(`--confirm ${task.id}`);
+    if (missing.length)
+        throw new Error(`task-delete --hard requires accountable safe draft confirmation: ${missing.join(", ")}`);
+    const blockers = [];
+    if (!isDraftState(task.state))
+        blockers.push(`state:${task.state}`);
+    if (task.deletionState !== "active")
+        blockers.push(`deletionState:${task.deletionState}`);
+    if (isRiskyMutationTask(task))
+        blockers.push("task has lifecycle, review, evidence, or closeout history");
+    if (!isDraftState(task.state) && hasOpenBlockingFindings(task))
+        blockers.push("task has open blocking findings");
+    const taskDir = path.join(target.projectRoot, task.path.replace(/^TARGET:/, ""));
+    const disallowedFiles = collectTaskDirectoryFiles(taskDir).filter((file) => !isSafeDraftFile(taskDir, file));
+    if (disallowedFiles.length)
+        blockers.push(`non-scaffold files: ${disallowedFiles.map((file) => toPosix(path.relative(taskDir, file))).join(", ")}`);
+    if (blockers.length)
+        throw new Error(`task-delete --hard only supports safe draft tasks; ${blockers.join("; ")}`);
+}
+function isRiskyMutationTask(task) {
+    return !isDraftState(task.state) ||
+        Boolean(task.reviewSubmitted) ||
+        task.reviewStatus === "confirmed" ||
+        Boolean(task.reviewConfirmation?.confirmed) ||
+        task.materialsReady === true && !isDraftState(task.state) ||
+        (task.evidence || []).length > 0 ||
+        (task.taskQueues || []).some((queue) => ["blocked", "review", "confirmed", "finalized", "lessons"].includes(queue));
+}
+function isDraftState(state) {
+    const normalized = String(state || "").trim().toLowerCase().replaceAll("-", "_").replace(/\s+/g, "_");
+    return ["planned", "not_started"].includes(normalized);
+}
+function hasOpenBlockingFindings(task) {
+    return (task.risks || []).some((risk) => normalizeReviewBoolean(risk.open) !== "no" && (normalizeReviewBoolean(risk.blocksRelease) === "yes" || ["P0", "P1", "P2"].includes(String(risk.severity))));
+}
+function normalizeTombstoneActor(value) {
+    return normalizeArchiveActor(value);
+}
+function collectTaskDirectoryFiles(taskDir) {
+    if (!fs.existsSync(taskDir))
+        return [];
+    const files = [];
+    const visit = (dir) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                visit(full);
+            else if (entry.isFile())
+                files.push(full);
+        }
+    };
+    visit(taskDir);
+    return files.sort();
+}
+function isSafeDraftFile(taskDir, file) {
+    const relative = toPosix(path.relative(taskDir, file));
+    return [
+        "INDEX.md",
+        "brief.md",
+        "execution_strategy.md",
+        "findings.md",
+        "lesson_candidates.md",
+        "progress.md",
+        "review.md",
+        "task_plan.md",
+        "visual_map.md",
+        "walkthrough.md",
+        "long-running-task-contract.md",
+    ].includes(relative) || /^artifacts\/INDEX\.md$/.test(relative) || /^references\/INDEX\.md$/.test(relative);
+}
 function appendSupersedes(target, task, oldId) {
     const taskPlanPath = path.join(target.projectRoot, task.taskPlanPath.replace(/^TARGET:/, ""));
     const content = readFileSafe(taskPlanPath);
@@ -123,3 +257,38 @@ function appendProgress(target, task, action, reason) {
 function escapeCell(value) {
     return String(value || "").replace(/\r?\n/g, " ").replaceAll("|", "\\|").trim();
 }
+function normalizeArchiveFields(fields) {
+    const entries = Object.entries(fields || {});
+    const normalized = {};
+    const seen = new Set();
+    for (const [rawKey, rawValue] of entries) {
+        const key = String(rawKey || "").trim();
+        if (!key || /[\r\n|]/.test(key))
+            throw new Error(`Invalid archive field key: ${key || "<empty>"}`);
+        const normalizedKey = key.toLowerCase();
+        if (seen.has(normalizedKey))
+            throw new Error(`Duplicate archive field key: ${key}`);
+        seen.add(normalizedKey);
+        normalized[key] = String(rawValue || "").replace(/\r?\n/g, " ").trim();
+    }
+    return normalized;
+}
+function assertNoReservedArchiveFields(fields) {
+    const reserved = new Set([
+        "state",
+        "reason",
+        "operator",
+        "timestamp",
+        "reopen eligible",
+        "archive eligible",
+        "archived by",
+        "archived at",
+        "review confirmed by",
+        "review confirmed at",
+        "review confirmation id",
+        "review commit sha",
+    ]);
+    const blocked = Object.keys(fields).filter((key) => reserved.has(key.toLowerCase()));
+    if (blocked.length)
+        throw new Error(`Reserved archive field cannot be overridden: ${blocked.join(", ")}`);
+}

package/dist/lib/types/check-profiles.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/types/impact.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/types/preset.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/types/task-lifecycle.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/types/task-scanner.js

@@ -0,0 +1 @@
+export {};

package/dist/postinstall.mjs

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-// @ts-nocheck
 import { seedBundledPresets } from "./lib/harness-core.mjs";
 if (process.env.CODING_AGENT_HARNESS_SKIP_POSTINSTALL === "1")
     process.exit(0);
@@ -10,5 +9,6 @@ try {
     console.log(`coding-agent-harness postinstall: ${summary} at ${result.target}`);
 }
 catch (error) {
-    console.warn(`coding-agent-harness postinstall: preset seed skipped (${error.message})`);
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`coding-agent-harness postinstall: preset seed skipped (${message})`);
 }

package/dist/run-built-tests.mjs

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-// @ts-nocheck
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
@@ -9,7 +8,9 @@ const outDir = path.join(repoRoot, "tmp", `test-runner-emit-${process.pid}`);
 const typescriptVersion = "5.9.3";
 const options = parseArgs(process.argv.slice(2));
 fs.rmSync(outDir, { recursive: true, force: true });
-const emit = spawnSync("npm", ["exec", "--yes", "--package", `typescript@${typescriptVersion}`, "--", "tsc", "-p", "tsconfig.tests.json", "--outDir", outDir, "--noCheck"], {
+const npmArgs = ["exec", "--yes", "--package", `typescript@${typescriptVersion}`, "--", "tsc", "-p", "tsconfig.tests.json", "--outDir", outDir, "--noCheck"];
+const npmCommand = resolveNpmCommand(npmArgs);
+const emit = spawnSync(npmCommand.command, npmCommand.args, {
     cwd: repoRoot,
     encoding: "utf8",
     stdio: "inherit",
@@ -36,7 +37,7 @@ const result = spawnSync(process.execPath, [runner], {
 if (result.status !== 0)
     process.exit(result.status || 1);
 function parseArgs(argv) {
-    const parsed = { test: undefined };
+    const parsed = {};
     for (let index = 0; index < argv.length; index += 1) {
         const arg = argv[index];
         if (arg === "--test") {
@@ -55,6 +56,12 @@ function requireValue(argv, index, option) {
         throw new Error(`${option} requires a value`);
     return value;
 }
+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 linkPackageResources() {
     for (const entry of [
         "package.json",

package/docs-release/README.md

@@ -56,6 +56,7 @@ Not every document is written for the same reader.
 ### Architecture / 架构
 
 - `architecture/overview.md` / `architecture/overview.zh-CN.md` — public architecture overview, including the CLI, dashboard, task lifecycle, migration rails, review gate, and release package surface. 公开架构总览，覆盖 CLI、Dashboard、任务生命周期、迁移轨道、审查门禁和发布包表面。
+- `architecture/document-contract-kernel/README.md` — shared Document Contract Kernel for Full/Lite Skill semantics, compatibility matrix, change classification, Lite forbidden surfaces, and Lite to Full upgrade mapping.
 
 ### Methodology / 方法论
 
@@ -71,7 +72,7 @@ Not every document is written for the same reader.
 - `guides/migration-playbook.md` / `guides/migration-playbook.en-US.md` — smooth migration guide for existing legacy harness projects. 旧 Harness 项目的平滑迁移指南。
 - `guides/legacy-migration-agent-prompt.md` / `guides/legacy-migration-agent-prompt.zh-CN.md` — prompt contract for agents running baseline or full legacy migration. 给迁移 Agent 使用的执行合同。
 - `guides/full-legacy-migration-subagent-strategy.md` / `guides/full-legacy-migration-subagent-strategy.zh-CN.md` — full readable cutover strategy with subagent roles, adversarial review, and dashboard/CLI proof gates. 完整可读迁移的 subagent 分工、对抗审查和 Dashboard/CLI 证据门禁。
-- `guides/typescript-runtime-migration-closeout.md` — public closeout for the TypeScript runtime source-twin migration and the remaining `.mjs` shim policy. TypeScript runtime source twin 迁移收口和剩余 `.mjs` shim 策略。
+- `guides/typescript-runtime-migration-closeout.md` — public closeout for the TypeScript runtime source-twin migration and the documented preset/dashboard JavaScript exceptions. TypeScript runtime source twin 迁移收口和已记录的 preset/dashboard JavaScript 例外。
 
 ## Repository Operating Models / 仓库运行模式
 

package/docs-release/architecture/document-contract-kernel/README.md

@@ -0,0 +1,150 @@
+# Document Contract Kernel
+
+The Document Contract Kernel is the product and Skill contract shared by the
+Full Coding Agent Harness Skill and the future Lite Skill. It defines the stable
+document semantics that both product surfaces must preserve without turning Lite
+into a runtime mode or forcing Full to lower its automation and audit bar.
+
+This contract is public source material. Full and Lite Skill text should be
+generated from this shared source plus product overlays. Until a generator is
+introduced, changes to the concepts or compatibility matrix must update this
+file and the product overlays in the same change.
+
+## Kernel Naming Boundary
+
+| Name | Layer | Responsibility | Must not do |
+| --- | --- | --- | --- |
+| Document Contract Kernel | Product / Skill contract | Shared document semantics, Lite/Full compatibility matrix, change classification, and upgrade mapping | Implement runtime behavior, read or write files, or define git, markdown, or path utilities |
+| Domain Kernel | Runtime domain | Task identity, policy, state transitions, module ownership, and preset model | Describe Skill installation copy, package manager commands, UI text, or git transport |
+| Infrastructure Kernel | Runtime infrastructure | Filesystem, path, template, markdown, git, date, id, and locale helpers | Own business semantics or product distribution semantics |
+
+Always write the full name "Document Contract Kernel" in source and docs. Do not
+shorten it to a generic `kernel/` label; that collides with later runtime
+refactoring work.
+
+## Shared Concepts
+
+| Concept | Kernel semantic | Lite expression | Full expression |
+| --- | --- | --- | --- |
+| Agent entry | The first project protocol an agent reads before acting | `AGENTS.md` | `AGENTS.md` plus optional `CLAUDE.md` shim |
+| Project context | Durable project facts, separate from chat memory | `context/architecture`, `context/development`, `context/integrations` | Same directories, with optional source packs and generated indexes |
+| Task package | The smallest reviewable unit of work for one objective | `tasks/<id>/brief.md`, `task_plan.md`, `progress.md`, `walkthrough.md` | `planning/tasks/<id>/` or module task package |
+| Brief | Purpose, scope, and first-read entry for the task | Required | Required |
+| Task plan | Goal, scope, steps, acceptance criteria, and verification intent | Required | Required |
+| Progress evidence | Execution log with evidence references | Required, hand-maintained | Required, may be updated by lifecycle command |
+| Review | Independent review or human confirmation material | Optional | Required for standard and complex work |
+| Visual map | Phase, state, and structure aid | Optional for simple work | Required in CLI-created task packages |
+| Walkthrough | Closeout summary, validation, residual risks, and lesson decision | Required | Required |
+| Regression | The project's important validation surfaces | Simple checklist | Regression SSoT, cadence, and checks |
+| Lessons | Reusable learning from the work | Optional `lessons.md` | Lesson candidates plus promoted lesson details |
+
+## Compatibility Matrix
+
+Compatibility matrix version: `document-contract-kernel-v0.5`.
+
+| Surface | Lite | Full | Kernel classification |
+| --- | --- | --- | --- |
+| `AGENTS.md` | Required | Required | Shared |
+| `CLAUDE.md` | Optional shim | Optional shim | Shared optional |
+| `context/` | Required | Required | Shared |
+| `brief.md` | Required | Required | Shared |
+| `task_plan.md` | Required | Required | Shared |
+| `progress.md` | Required | Required | Shared |
+| `walkthrough.md` | Required | Required | Shared |
+| `review.md` | Optional | Required for standard and complex work | Shared with profile differences |
+| `visual_map.md` | Optional for simple work | Required in CLI-created task packages | Shared with profile differences |
+| `regression.md` | Simple checklist | Regression SSoT and cadence | Shared with profile differences |
+| `lessons.md` | Optional simple table | Lesson candidates and promoted details | Shared with profile differences |
+| `harness.yaml` | Forbidden | Required | Full-only |
+| Generated ledger | Forbidden | Supported | Full-only |
+| Dashboard / Workbench | Forbidden | Supported | Full-only |
+| Preset | Forbidden | Supported | Full-only |
+| Module Registry | Forbidden | Supported | Full-only |
+| Lifecycle CLI commands | Forbidden | Supported | Full-only |
+| `npm install` / `npx coding-agent-harness` | Forbidden | Allowed with user consent | Full-only |
+| Node.js version requirement | Forbidden | Required by the source package and runtime | Full-only |
+
+## Change Classification
+
+Every PR or task that edits Skill, template, or public product docs must be
+classified before implementation.
+
+| Change type | Definition | Must sync | Must not do |
+| --- | --- | --- | --- |
+| Kernel change | Changes the base semantics of AGENTS, context, task package, progress, walkthrough, review, regression, or lessons | Lite overlay, Full overlay, and this compatibility matrix | Update only the Full Skill |
+| Full-only change | CLI, Dashboard, Preset, module registry, generated ledger, transaction, migration, or runtime automation | Full Skill, runtime docs, and Full overlay | Leak into Lite source |
+| Lite-only change | Document-only scaffold, lower cognitive load wording, and hand-maintained task material | Lite overlay | Weaken Full audit or automation requirements |
+| Migration bridge | Maps Lite project material into a Full Harness project | Full migration docs and Lite upgrade note | Promise that Lite supports Full surfaces in place |
+
+PR checklist:
+
+- [ ] Does this change alter the Document Contract Kernel?
+- [ ] If yes, did Lite and Full overlays both change?
+- [ ] If yes, did the compatibility matrix version or content change?
+- [ ] If Full-only, does the Lite forbidden-surface check still pass?
+- [ ] If Lite-only, did Full retain its review, regression, and automation requirements?
+
+## Lite Forbidden Surfaces
+
+Lite is a document-only Skill surface. It must not contain product or runtime
+surfaces that imply package installation, CLI operation, dashboard operation,
+preset execution, generated governance, module registry ownership, lifecycle
+commands, or a Node.js runtime requirement.
+
+The canonical blocked pattern list is
+`docs-release/architecture/document-contract-kernel/products/lite-forbidden-surfaces.txt`.
+Run the guard with:
+
+```bash
+node scripts/check-lite-forbidden-surfaces.mts
+```
+
+The guard scans Lite product source files only. It intentionally does not scan
+this contract document or the forbidden pattern list, because those files must
+name Full-only surfaces to define the boundary.
+
+## Lite to Full Upgrade Path
+
+A Lite project can be used as migration input for Full Harness adoption. Lite
+does not promise that Full runtime adapters can read or update its files in
+place.
+
+1. Read Lite `AGENTS.md`, `context/`, `tasks/`, `regression.md`, and `lessons.md`.
+2. Create the Full harness manifest and v2 directory structure.
+3. Map `tasks/<id>/` into Full `planning/tasks/<id>/`.
+4. If `review.md` or `visual_map.md` is missing, create adoption-needed follow-up
+   work or fill it within an approved migration budget.
+5. Project Lite `regression.md` into Regression SSoT.
+6. Project Lite `lessons.md` into lesson candidates, not promoted lesson details.
+7. Run Full migration and check evidence before claiming Full adoption.
+
+## Source, Overlay, Generator Path
+
+The maintainable target is shared source plus product overlays:
+
+```text
+docs-release/architecture/document-contract-kernel/
+  README.md
+  products/
+    lite-skill-overlay.md
+    full-skill-overlay.md
+    lite-forbidden-surfaces.txt
+```
+
+Future generator shape:
+
+1. Render this shared Document Contract Kernel source.
+2. Apply the Full or Lite product overlay.
+3. Stamp the compatibility matrix version into the generated Skill.
+4. Run Lite forbidden-surface checks after Lite render.
+5. Run Full concept coverage checks after Full render.
+
+Generated targets should be:
+
+```text
+SKILL.md
+skills/coding-agent-harness-lite/SKILL.md
+```
+
+The Lite target is not created in Phase 0.5. This phase establishes the public
+contract and drift guard that a later Lite implementation must use.