@tea-agent/loop-agent 0.39.0-next.9 → 0.39.1

package/dist/shared/update/console-notifier.js

@@ -0,0 +1,100 @@
+import { createInterface } from "node:readline/promises";
+import semver from "semver";
+import { acquireUpdateLock, readUpdateState, updateLockPath, updateStatePath, writeUpdateState, } from "./state.js";
+export async function runConsoleDailyUpdateCheck(options) {
+    void options.writeStdout;
+    void options.packageRoot;
+    void options.cwd;
+    const writeStderr = options.writeStderr ?? ((chunk) => process.stderr.write(chunk));
+    const now = options.now ?? (() => new Date());
+    try {
+        if (!canPromptInteractively(options))
+            return;
+        const statePath = updateStatePath(options.homeDir);
+        const today = formatLocalDate(now());
+        const existing = await readUpdateState(statePath);
+        if (existing.lastPromptedLocalDate === today)
+            return;
+        const release = await acquireUpdateLock(updateLockPath(options.homeDir), {
+            now,
+        });
+        if (!release)
+            return;
+        try {
+            const state = await readUpdateState(statePath);
+            if (state.lastPromptedLocalDate === today)
+                return;
+            const check = await options.client.latestVersionCheck();
+            if (!check.ok)
+                return;
+            if (!semver.gt(check.version, options.currentVersion))
+                return;
+            const parsedLatest = semver.parse(check.version);
+            if (!parsedLatest || parsedLatest.prerelease.length > 0)
+                return;
+            await markPromptedToday(statePath, state, today);
+            const answer = await ask(options, `loop-agent 有新版本：${options.currentVersion} → ${check.version}\n现在更新到 ${check.version}？[y/N] `);
+            if (!isYes(answer))
+                return;
+            const proof = await options.client.canAutoInstall();
+            if (!proof.ok) {
+                writeStderr(`当前 loop-agent 不是由此 npm 的正式全局安装管理，无法自动升级。\n请运行：npm install -g @tea-agent/loop-agent@${check.version}\n`);
+                return;
+            }
+            const install = await options.client.installExact(check.version);
+            if (!install.ok) {
+                writeStderr(`loop-agent 更新失败：${install.reason}\n`);
+                return;
+            }
+            const verified = await options.client.verifyInstalled(check.version);
+            if (!verified.ok) {
+                writeStderr(`loop-agent 已尝试安装，但验证失败：${verified.reason}\n`);
+                return;
+            }
+            writeStderr(`loop-agent 已更新到 ${check.version}；新版本将在下一次命令调用时完全生效。\n`);
+        }
+        finally {
+            await release().catch(() => undefined);
+        }
+    }
+    catch (error) {
+        writeStderr(`loop-agent 更新检查已跳过：${error instanceof Error ? error.message : String(error)}\n`);
+    }
+}
+function canPromptInteractively(options) {
+    if (!options.stdinIsTTY || !options.stderrIsTTY)
+        return false;
+    if (options.env.CI)
+        return false;
+    if (options.env.LOOP_AGENT_DISABLE_UPDATE_CHECK === "1")
+        return false;
+    return true;
+}
+function formatLocalDate(date) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, "0");
+    const day = String(date.getDate()).padStart(2, "0");
+    return `${year}-${month}-${day}`;
+}
+async function markPromptedToday(statePath, state, today) {
+    await writeUpdateState(statePath, {
+        ...state,
+        lastPromptedLocalDate: today,
+    });
+}
+async function ask(options, prompt) {
+    if (options.readLine) {
+        options.writeStderr?.(prompt);
+        return options.readLine(prompt);
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return await rl.question(prompt);
+    }
+    finally {
+        rl.close();
+    }
+}
+function isYes(answer) {
+    return /^(y|yes)$/i.test(answer.trim());
+}

package/dist/{cli → shared}/update/npm-client.js

@@ -3,43 +3,77 @@ import { lstat, readFile, realpath } from "node:fs/promises";
 import path from "node:path";
 import semver from "semver";
 const PACKAGE_NAME = "@tea-agent/loop-agent";
+export const DEFAULT_NPM_QUERY_TIMEOUT_MS = 15_000;
 export function createNpmUpdateClient(options) {
     const npmCommand = options.npmCommand ?? "npm";
     const loopAgentCommand = options.loopAgentCommand ?? "loop-agent";
     const runner = options.runner ?? runCommand;
-    const timeoutMs = options.timeoutMs ?? 1500;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_NPM_QUERY_TIMEOUT_MS;
+    const cwd = options.cwd;
     const env = options.env;
+    const distTagVersionCheck = async (channel) => {
+        let result;
+        try {
+            result = await runner(npmCommand, ["view", PACKAGE_NAME, `dist-tags.${channel}`, "--json"], { timeoutMs, cwd, env });
+        }
+        catch {
+            return { ok: false, reason: "spawn-failure" };
+        }
+        if (result.timedOut)
+            return { ok: false, reason: "timeout" };
+        if (result.exitCode === null) {
+            return { ok: false, reason: "spawn-failure" };
+        }
+        if (result.exitCode !== 0) {
+            return { ok: false, reason: "command-failed" };
+        }
+        const version = parseNpmViewDistTag(result.stdout, channel);
+        return version
+            ? { ok: true, version }
+            : { ok: false, reason: "invalid-response" };
+    };
+    const latestVersionCheck = () => distTagVersionCheck("latest");
     return {
         async latestVersion() {
-            const result = await runner(npmCommand, ["view", PACKAGE_NAME, "dist-tags.latest", "--json"], { timeoutMs, env });
-            if (result.exitCode !== 0 || result.timedOut)
-                return undefined;
-            return parseNpmViewLatest(result.stdout);
+            const result = await latestVersionCheck();
+            return result.ok ? result.version : undefined;
         },
+        latestVersionCheck,
+        distTagVersionCheck,
         async canAutoInstall() {
             return proveGlobalNpmInstall({
                 currentVersion: options.currentVersion,
                 packageRoot: options.packageRoot,
                 npmCommand,
                 runner,
+                cwd,
                 env,
                 timeoutMs,
             });
         },
-        async installExact(version) {
-            if (!isStrictRelease(version))
+        async installExact(version, channel = "latest") {
+            if (!isAllowedChannelVersion(version, channel)) {
                 return { ok: false, reason: "invalid-version" };
-            const result = await runner(npmCommand, buildExactInstallArgs(version), { timeoutMs: Math.max(timeoutMs, 120000), env });
+            }
+            const result = await runner(npmCommand, buildExactInstallArgs(version, channel), {
+                timeoutMs: Math.max(timeoutMs, 120000),
+                cwd,
+                env,
+            });
             if (result.exitCode !== 0 || result.timedOut)
                 return { ok: false, reason: "install-failed" };
             return { ok: true };
         },
         async verifyInstalled(version) {
-            const list = await runner(npmCommand, ["list", "-g", PACKAGE_NAME, "--depth=0", "--json"], { timeoutMs, env });
+            const list = await runner(npmCommand, ["list", "-g", PACKAGE_NAME, "--depth=0", "--json"], { timeoutMs, cwd, env });
             if (list.exitCode !== 0 || !verifyNpmListVersion(list.stdout, version)) {
                 return { ok: false, reason: "npm-list-version-mismatch" };
             }
-            const pathVersion = await runner(loopAgentCommand, ["--version"], { timeoutMs, env });
+            const pathVersion = await runner(loopAgentCommand, ["--version"], {
+                timeoutMs,
+                cwd,
+                env,
+            });
             if (pathVersion.exitCode !== 0 || !verifyPathVersion(pathVersion.stdout, version)) {
                 return { ok: false, reason: "path-version-mismatch" };
             }
@@ -48,6 +82,13 @@ export function createNpmUpdateClient(options) {
     };
 }
 export function parseNpmViewLatest(stdout) {
+    return parseNpmViewDistTag(stdout, "latest");
+}
+/**
+ * `latest` stays stable-only. `next` is explicitly selected by a human and
+ * may legitimately be a SemVer prerelease, but remains an exact version.
+ */
+export function parseNpmViewDistTag(stdout, channel) {
     const trimmed = stdout.trim();
     let value = trimmed;
     try {
@@ -58,11 +99,12 @@ export function parseNpmViewLatest(stdout) {
     }
     if (typeof value !== "string")
         return undefined;
-    return isStrictRelease(value) ? value : undefined;
+    return isAllowedChannelVersion(value, channel) ? value : undefined;
 }
-export function buildExactInstallArgs(version) {
-    if (!isStrictRelease(version))
-        throw new Error(`invalid release version: ${version}`);
+export function buildExactInstallArgs(version, channel = "latest") {
+    if (!isAllowedChannelVersion(version, channel)) {
+        throw new Error(`invalid ${channel} version: ${version}`);
+    }
     return ["install", "-g", `${PACKAGE_NAME}@${version}`, "--no-fund", "--no-audit"];
 }
 export function verifyNpmListVersion(stdout, expectedVersion) {
@@ -75,11 +117,18 @@ export function verifyNpmListVersion(stdout, expectedVersion) {
     }
 }
 export function verifyPathVersion(stdout, expectedVersion) {
-    return stdout.trim() === expectedVersion;
+    // `loop-agent --version` may append a build provenance marker. The release
+    // version itself must still match exactly; accepting no other trailing form
+    // keeps PATH verification bound to the requested stable package.
+    return new RegExp(`^${escapeRegExp(expectedVersion)}(?: \\(build [^)]+\\))?$`).test(stdout.trim());
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 async function proveGlobalNpmInstall(options) {
     const root = await options.runner(options.npmCommand, ["root", "-g"], {
         timeoutMs: options.timeoutMs,
+        cwd: options.cwd,
         env: options.env,
     });
     if (root.exitCode !== 0 || root.timedOut)
@@ -110,9 +159,15 @@ function isStrictRelease(version) {
     const parsed = semver.parse(version);
     return Boolean(parsed && parsed.prerelease.length === 0);
 }
+function isAllowedChannelVersion(version, channel) {
+    if (channel === "latest")
+        return isStrictRelease(version);
+    return Boolean(semver.valid(version));
+}
 async function runCommand(command, args, options) {
     return new Promise((resolve) => {
         const child = spawn(command, [...args], {
+            cwd: options.cwd,
             env: options.env ? { ...process.env, ...options.env } : process.env,
             stdio: ["ignore", "pipe", "pipe"],
             shell: false,

package/dist/{cli → shared}/update/state.js

@@ -1,4 +1,4 @@
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 export function updateStatePath(homeDir) {
     return path.join(homeDir, ".loop-agent", "update-state.json");
@@ -18,6 +18,7 @@ export async function readUpdateState(statePath) {
             latestVersion: stringOrUndefined(parsed.latestVersion),
             dismissedVersion: stringOrUndefined(parsed.dismissedVersion),
             retryAfter: stringOrUndefined(parsed.retryAfter),
+            lastPromptedLocalDate: stringOrUndefined(parsed.lastPromptedLocalDate),
         };
     }
     catch {
@@ -36,28 +37,55 @@ export async function acquireUpdateLock(lockPath, options = {}) {
     await mkdir(path.dirname(lockPath), { recursive: true });
     try {
         await mkdir(lockPath);
+        return await claimLock(lockPath, now);
+    }
+    catch {
+        if (await isFreshLock(lockPath, now, staleMs))
+            return undefined;
+        try {
+            await rm(lockPath, { recursive: true, force: true });
+            await mkdir(lockPath);
+            return await claimLock(lockPath, now);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+async function claimLock(lockPath, now) {
+    try {
         await writeFile(path.join(lockPath, "owner.json"), JSON.stringify({ pid: process.pid, at: now().toISOString() }), "utf-8");
         return async () => {
             await rm(lockPath, { recursive: true, force: true });
         };
     }
+    catch {
+        await rm(lockPath, { recursive: true, force: true }).catch(() => undefined);
+        return undefined;
+    }
+}
+async function isFreshLock(lockPath, now, staleMs) {
+    try {
+        const ownerRaw = await readFile(path.join(lockPath, "owner.json"), "utf-8");
+        const owner = JSON.parse(ownerRaw);
+        if (typeof owner.at !== "string")
+            return false;
+        const at = Date.parse(owner.at);
+        if (!Number.isFinite(at))
+            return false;
+        return now().getTime() - at <= staleMs;
+    }
     catch {
         try {
-            const ownerRaw = await readFile(path.join(lockPath, "owner.json"), "utf-8");
-            const owner = JSON.parse(ownerRaw);
-            if (owner.at && now().getTime() - Date.parse(owner.at) > staleMs) {
-                await rm(lockPath, { recursive: true, force: true });
-                await mkdir(lockPath);
-                await writeFile(path.join(lockPath, "owner.json"), JSON.stringify({ pid: process.pid, at: now().toISOString() }), "utf-8");
-                return async () => {
-                    await rm(lockPath, { recursive: true, force: true });
-                };
-            }
+            const info = await stat(lockPath);
+            const mtime = Number.isFinite(info.mtimeMs)
+                ? info.mtimeMs
+                : info.mtime.getTime();
+            return now().getTime() - mtime <= staleMs;
         }
         catch {
-            return undefined;
+            return false;
         }
-        return undefined;
     }
 }
 function emptyState() {

package/dist/task/config-types.js

@@ -87,6 +87,12 @@ export const frontendOpenspecConfigSchema = z.object({
 /** Batch limits and gate profile for the browser-driven frontend test DAG.
  * Token fields are post-case stop thresholds, not model-provider hard caps. */
 export const frontendTestConfigSchema = z.object({
+    /**
+     * Repository-relative frontend-test artifact root.
+     * Default "testcase/frontend". Semantic validation lives in
+     * resolveFrontendTestLayout (fail-closed), not in this schema.
+     */
+    testRoot: z.string().min(1).optional(),
     maxCasesPerBatch: z.number().int().min(1).max(50).optional(),
     maxTokensPerCase: z.number().int().positive().optional(),
     maxTotalTokens: z.number().int().positive().optional(),
@@ -124,6 +130,26 @@ export const frontendTestConfigSchema = z.object({
         .strict()
         .optional(),
 });
+/** Backend-test artifact layout and pipeline mode configuration (plan A/B/D). */
+export const backendTestConfigSchema = z
+    .object({
+    /** Repository-relative test root. Default "testcase". */
+    testRoot: z.string().min(1).optional(),
+    /** Markdown subdirectory relative to testRoot. Default "md". */
+    markdownRel: z.string().min(1).optional(),
+    /** Pytest script subdirectory relative to testRoot. Default "." (testRoot itself). */
+    scriptRel: z.string().min(1).optional(),
+    /** User-provided shared setup document (plan B). Read-only bound source. */
+    sharedSetupDoc: z.string().min(1).optional(),
+    /** Pipeline mode: full 16-node chain (default) or gap-fill incremental DAG (plan D). */
+    mode: z.enum(["full", "gap-fill"]).optional(),
+    /** Required for mode=gap-fill: user missing-scenario document path. */
+    gapDoc: z.string().min(1).optional(),
+    /** gap-fill pytest execution scope: only affected items (default) or all eligible. */
+    executeScope: z.enum(["affected", "all"]).optional(),
+})
+    .strict()
+    .optional();
 export const convergenceConfigSchema = z.object({
     enabled: z.boolean().optional().default(false),
     maxPasses: z.number().int().positive().optional().default(3),
@@ -196,6 +222,8 @@ const taskConfigObjectSchema = z.object({
     frontendTest: frontendTestConfigSchema.optional(),
     /** Frontend OpenSpec gate policy and contract-declared required read paths. */
     frontendOpenspec: frontendOpenspecConfigSchema.optional(),
+    /** Backend-test layout / shared-setup / gap-fill configuration. */
+    backendTest: backendTestConfigSchema,
     notes: z.string().optional().default(""),
 });
 export const taskConfigSchema = z.preprocess((raw) => {

package/dist/task/contract/apply.js

@@ -232,8 +232,11 @@ export async function applyTaskContract(input) {
         // Re-parse through schema to ensure full TaskConfig shape for hash stability
         const fullConfig = parseTaskConfigForRuntime(mergedConfig);
         const taskConfigContent = serializeTaskConfigForDisk(fullConfig);
-        const requirementContent = projectRequirementMarkdown(input.draft);
+        const requirementContent = projectRequirementMarkdown(input.draft, input.requirementLedger);
         const constraintsContent = projectConstraintsMarkdown(input.draft);
+        const requirementLedgerContent = input.requirementLedger !== undefined
+            ? `${JSON.stringify(input.requirementLedger, null, 2)}\n`
+            : undefined;
         // Validate references manifest hash if present (do not modify)
         const paths = getTaskPaths(input.repoRoot, input.taskId);
         const manifestText = await readFile(getSourceManifestPath(paths.sourceDir), "utf-8").catch(() => null);
@@ -241,6 +244,7 @@ export async function applyTaskContract(input) {
             requirementBytes: requirementContent,
             constraintsBytes: constraintsContent,
             referenceManifestBytes: manifestText,
+            requirementLedgerBytes: requirementLedgerContent,
         });
         const taskConfigSha256 = computeTaskConfigSha256(fullConfig);
         const canonicalHash = computeCanonicalHash({
@@ -277,6 +281,9 @@ export async function applyTaskContract(input) {
                 constraintsContent,
                 taskConfigContent,
                 contractRef: nextRef,
+                ...(requirementLedgerContent !== undefined
+                    ? { requirementLedgerContent }
+                    : {}),
             },
         });
         await appendRequestLedgerEntry({
@@ -312,6 +319,9 @@ export async function applyTaskContract(input) {
             changedFiles: [
                 "source/需求.md",
                 "source/执行约束.md",
+                ...(requirementLedgerContent !== undefined
+                    ? ["source/requirement-ledger.json"]
+                    : []),
                 "task.json",
                 "contract.json",
             ],

package/dist/task/contract/constants.js

@@ -17,6 +17,7 @@ export const MANAGED_TASK_CONFIG_FIELDS = [
     "forbiddenPaths",
     "hardConstraints",
     "verifyCommands",
+    "backendTest",
 ];
 export const CONTRACT_FILE_NAME = "contract.json";
 export const TRANSACTIONS_DIR_NAME = ".transactions";
@@ -28,3 +29,5 @@ export const TRANSACTIONS_DIRNAME = TRANSACTIONS_DIR_NAME;
 export const REQUEST_LEDGER_BASENAME = REQUEST_LEDGER_FILE_NAME;
 export const REQUIREMENT_FILE_NAME = "需求.md";
 export const CONSTRAINTS_FILE_NAME = "执行约束.md";
+/** Source fidelity ledger (20260824-frontend-source-fidelity-ledger-v1). */
+export const REQUIREMENT_LEDGER_FILE_NAME = "requirement-ledger.json";

package/dist/task/contract/diff.js

@@ -1,3 +1,4 @@
+import { canonicalizeJsonValue } from "./canonicalize.js";
 import { MANAGED_TASK_CONFIG_FIELDS } from "./constants.js";
 function maxRisk(a, b) {
     const order = ["routine", "elevated", "blocking"];
@@ -139,6 +140,31 @@ export function diffDraftAgainstCurrent(input) {
                 path: "task.json#featureId",
             });
         }
+        // backendTest is managed whole-object: an absent draft value means
+        // "keep existing" and never diffs; declared values compare canonically.
+        if (input.draft.backendTest !== undefined) {
+            const before = cfg.backendTest ?? {};
+            const after = input.draft.backendTest;
+            if (canonicalizeJsonValue(before) !== canonicalizeJsonValue(after)) {
+                changedManagedFields.push("backendTest");
+                risks.push({
+                    code: "BACKEND_TEST_CONFIG_CHANGED",
+                    level: "routine",
+                    message: "backendTest configuration changed",
+                    path: "task.json#backendTest",
+                });
+                const afterKeys = new Set(Object.keys(after));
+                const droppedKeys = Object.keys(before).filter((key) => !afterKeys.has(key));
+                if (droppedKeys.length > 0) {
+                    risks.push({
+                        code: "BACKEND_TEST_CONFIG_WEAKENED",
+                        level: "elevated",
+                        message: `drop backendTest keys: ${droppedKeys.sort().join(", ")}`,
+                        path: "task.json#backendTest",
+                    });
+                }
+            }
+        }
     }
     else {
         for (const field of MANAGED_TASK_CONFIG_FIELDS) {

package/dist/task/contract/hash.js

@@ -35,6 +35,9 @@ export function computeSourceHashes(input) {
     if (input.referenceManifestBytes) {
         sourceHashes.referenceManifestSha256 = sha256Utf8(input.referenceManifestBytes);
     }
+    if (input.requirementLedgerBytes) {
+        sourceHashes.requirementLedgerSha256 = sha256Utf8(input.requirementLedgerBytes);
+    }
     return sourceHashes;
 }
 export function refMatchesObserved(ref, observedCanonicalHash) {

package/dist/task/contract/observe.js

@@ -1,6 +1,6 @@
 import { access, readdir, readFile } from "node:fs/promises";
 import path from "node:path";
-import { CONSTRAINTS_FILE_NAME, CONTRACT_FILE_NAME, REQUIREMENT_FILE_NAME, TRANSACTIONS_DIR_NAME, } from "./constants.js";
+import { CONSTRAINTS_FILE_NAME, CONTRACT_FILE_NAME, REQUIREMENT_FILE_NAME, REQUIREMENT_LEDGER_FILE_NAME, TRANSACTIONS_DIR_NAME, } from "./constants.js";
 import { computeCanonicalHash, computeSourceHashes, computeTaskConfigSha256, } from "./hash.js";
 import { parseTaskContractRef } from "./schema.js";
 import { getTaskPaths } from "../runtime.js";
@@ -33,11 +33,13 @@ export async function loadObservedTaskBytes(repoRoot, taskId) {
     const paths = getTaskPaths(repoRoot, taskId);
     const requirementPath = path.join(paths.sourceDir, REQUIREMENT_FILE_NAME);
     const constraintsPath = path.join(paths.sourceDir, CONSTRAINTS_FILE_NAME);
-    const [requirementBytes, constraintsBytes, taskConfigText, manifestText] = await Promise.all([
+    const requirementLedgerPath = path.join(paths.sourceDir, REQUIREMENT_LEDGER_FILE_NAME);
+    const [requirementBytes, constraintsBytes, taskConfigText, manifestText, requirementLedgerBytes] = await Promise.all([
         readTextIfExists(requirementPath),
         readTextIfExists(constraintsPath),
         readTextIfExists(paths.taskConfigPath),
         readTextIfExists(getSourceManifestPath(paths.sourceDir)),
+        readTextIfExists(requirementLedgerPath),
     ]);
     let taskConfigRaw = null;
     let taskConfigSha256 = null;
@@ -52,6 +54,7 @@ export async function loadObservedTaskBytes(repoRoot, taskId) {
         taskConfigRaw,
         taskConfigSha256,
         referenceManifestBytes: manifestText,
+        requirementLedgerBytes,
         requirementPath,
         constraintsPath,
         taskConfigPath: paths.taskConfigPath,
@@ -164,7 +167,9 @@ export async function observeTaskContractState(repoRoot, taskId) {
             message: error instanceof Error ? error.message : String(error),
         });
     }
-    const observed = await computeObservedCanonicalHashSafe(repoRoot, taskId);
+    const observed = await computeObservedCanonicalHashSafe(repoRoot, taskId, {
+        ref: ref ?? undefined,
+    });
     errors.push(...(observed.errors ?? []));
     if (!ref) {
         return {
@@ -226,7 +231,7 @@ export async function observeTaskContractState(repoRoot, taskId) {
         observationErrors: errors,
     };
 }
-async function computeObservedCanonicalHashSafe(repoRoot, taskId) {
+async function computeObservedCanonicalHashSafe(repoRoot, taskId, options) {
     const errors = [];
     try {
         const bytes = await loadObservedTaskBytes(repoRoot, taskId);
@@ -256,10 +261,26 @@ async function computeObservedCanonicalHashSafe(repoRoot, taskId) {
             }
             return { hash: null, errors };
         }
+        // Legacy compatibility (AC-FIDELITY-004): only include the ledger bytes
+        // when the stored ref actually declares requirementLedgerSha256. A ref
+        // without the ledger field keeps the existing semantics and never
+        // misreports drift for tasks that predate the ledger.
+        const refLedgerHash = options?.ref?.sourceHashes.requirementLedgerSha256 ?? null;
+        if (refLedgerHash && bytes.requirementLedgerBytes === null) {
+            errors.push({
+                code: "MISSING_REQUIREMENT_LEDGER",
+                path: "source/requirement-ledger.json",
+                message: `contract records requirementLedgerSha256 but ${REQUIREMENT_LEDGER_FILE_NAME} is missing`,
+            });
+            return { hash: null, errors };
+        }
         const sourceHashes = computeSourceHashes({
             requirementBytes: bytes.requirementBytes,
             constraintsBytes: bytes.constraintsBytes,
             referenceManifestBytes: bytes.referenceManifestBytes,
+            ...(refLedgerHash
+                ? { requirementLedgerBytes: bytes.requirementLedgerBytes }
+                : {}),
         });
         const hash = computeCanonicalHash({
             sourceHashes,

package/dist/task/contract/paths.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { getTaskPaths } from "../runtime.js";
-import { CONTRACT_JSON_BASENAME, REQUEST_LEDGER_BASENAME, TRANSACTIONS_DIRNAME, } from "./constants.js";
+import { CONTRACT_JSON_BASENAME, REQUIREMENT_LEDGER_FILE_NAME, REQUEST_LEDGER_BASENAME, TRANSACTIONS_DIRNAME, } from "./constants.js";
 export function getTaskContractPaths(repoRoot, taskId) {
     const base = getTaskPaths(repoRoot, taskId);
     return {
@@ -15,5 +15,6 @@ export function getTaskContractPaths(repoRoot, taskId) {
         transactionsDir: path.join(base.taskDir, TRANSACTIONS_DIRNAME),
         requestLedgerPath: path.join(base.taskDir, REQUEST_LEDGER_BASENAME),
         lockPath: path.join(base.taskDir, ".contract.lock"),
+        requirementLedgerPath: path.join(base.sourceDir, REQUIREMENT_LEDGER_FILE_NAME),
     };
 }

package/dist/task/contract/project.js

@@ -1,8 +1,10 @@
 import { canonicalizePathArray, canonicalizeTextProjection, } from "./canonicalize.js";
 /**
  * Project Draft → source/需求.md (deterministic template, projectionVersion=1).
+ * 当携带 ledger 时追加 `## Source ledger` 区块：明确 需求.md 是派生导航视图，
+ * 语义权威为原始 requirement/acceptance 文档与受管 requirement-ledger.json。
  */
-export function projectRequirementMarkdown(draft) {
+export function projectRequirementMarkdown(draft, ledger) {
     const lines = [
         `# 需求：${draft.title}`,
         "",
@@ -62,6 +64,18 @@ export function projectRequirementMarkdown(draft) {
             lines.push(`- [${ref.role}] ${ref.ref}`);
         }
     }
+    if (ledger) {
+        const gateStatus = ledger.stats.unresolvedCount > 0 ||
+            ledger.stats.conflictCount > 0 ||
+            ledger.stats.highRiskUncoveredCount > 0
+            ? "blocked"
+            : "pass";
+        const ledgerLine = ledger.sourcePaths.length > 0
+            ? `source/requirement-ledger.json (${ledger.sourcePaths.length} source document(s))`
+            : "source/requirement-ledger.json";
+        lines.push("", "## Source ledger", "", "> 本文件是派生导航视图，不替代原始 requirement/acceptance 文档。" +
+            " 语义权威为原始文档与 `source/requirement-ledger.json`（确定性切分账本）。", "", `- ledger: ${ledgerLine.length > 160 ? `${ledgerLine.slice(0, 160)}…` : ledgerLine}`, `- inputDigest: ${ledger.inputDigest}`, `- fragments: ${ledger.stats.fragmentCount}`, `- canonical requirements: ${ledger.stats.canonicalRequirementCount}`, `- status: ${gateStatus}`);
+    }
     lines.push("");
     return canonicalizeTextProjection(lines.join("\n"));
 }
@@ -174,6 +188,11 @@ export function mergeManagedTaskConfigFields(existing, draft) {
     if (draft.featureId !== undefined) {
         next.featureId = draft.featureId;
     }
+    // backendTest is whole-object replace when the draft declares it (`{}` is a
+    // legal explicit clear back to the default layout); absent keeps existing.
+    if (draft.backendTest !== undefined) {
+        next.backendTest = draft.backendTest;
+    }
     return next;
 }
 /**

package/dist/task/contract/schema.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { taskKindSchema, taskVerifyCommandSchema } from "../config-types.js";
+import { backendTestConfigSchema, taskKindSchema, taskVerifyCommandSchema, } from "../config-types.js";
 import { TASK_CONFIG_SCHEMA_VERSION, TASK_CONTRACT_CANONICALIZER_VERSION, TASK_CONTRACT_DRAFT_SCHEMA_VERSION, TASK_CONTRACT_PROJECTION_VERSION, TASK_CONTRACT_REF_SCHEMA_VERSION, } from "./constants.js";
 const sha256Schema = z
     .string()
@@ -62,6 +62,11 @@ export const taskContractDraftSchema = z
     requirement: taskContractDraftRequirementSchema,
     constraints: taskContractDraftConstraintsSchema,
     verification: taskContractDraftVerificationSchema,
+    /**
+     * Managed backend-test layout / pipeline configuration projected into
+     * task.json#backendTest. Optional: absent means "keep existing".
+     */
+    backendTest: backendTestConfigSchema,
     references: z.array(taskContractDraftReferenceSchema).optional(),
     sourceResolutions: z
         .array(taskContractDraftSourceResolutionSchema)
@@ -102,6 +107,8 @@ export const taskContractSourceHashesSchema = z
     requirementSha256: sha256Schema,
     constraintsSha256: sha256Schema,
     referenceManifestSha256: sha256Schema.optional(),
+    /** Source fidelity ledger hash; present only when the task binds a ledger. */
+    requirementLedgerSha256: sha256Schema.optional(),
 })
     .strict();
 export const taskContractRefSchema = z