@tea-agent/loop-agent 0.39.0-beta.7 → 0.39.0-beta.9

package/dist/executors/shell-executor.js

@@ -16,6 +16,7 @@ import { materializeBackendTestAnalysisContract } from "../workflows/dag/backend
 import { extractBackendTestContractEnvelope } from "../workflows/dag/backend-test-contract-envelope.js";
 import { materializeFrontendImplementationContract } from "../workflows/dag/frontend-implementation-contract.js";
 import { assertFrontendSourceBindingFresh, buildContractFromCommittedFacts, deterministicSha256, frontendImplementationContractSchema, serializeDeterministicJson, sha256Hex, writeFrontendImplementationContractArtifact, } from "../workflows/dag/frontend-implementation-contract.js";
+import { checkFrontendSourceFidelityLedger } from "../workflows/dag/frontend-source-fidelity-ledger.js";
 import { materializeFrontendTestResult, validateFrontendCaseEvidence, } from "../workflows/dag/frontend-test-result-contract.js";
 import { copyFrontendTestStandardScenarios } from "../workflows/dag/frontend-test-standard-scenarios.js";
 import { probeFrontendTestEnvironment } from "../workflows/dag/frontend-test-environment-probe.js";
@@ -27,7 +28,7 @@ import { formatFrontendVerificationTraceStdout, runFrontendVerificationTraceGate
 import { captureFrontendWorktreeBaseline, formatFrontendWorktreeDiffStdout, runFrontendWorktreeDiffGate, } from "../workflows/dag/frontend-worktree-diff.js";
 import { readTypedEventStoreFromJsonl } from "../workflows/dag/frontend-typed-event-store.js";
 import { classifyFrontendFailure, } from "../workflows/dag/frontend-repair.js";
-import { FRONTEND_CONTRACT_MAX_BYTES, formatFrontendPrewriteGateStdout, runFrontendPrewriteGate, } from "../workflows/dag/frontend-prewrite-gate.js";
+const FRONTEND_CONTRACT_MAX_BYTES = 65536;
 import { evaluateFrontendDesignPolicy, } from "../workflows/dag/frontend-design-policy.js";
 import { deriveFrontendWriterAdmissionShell, FRONTEND_WRITER_ADMISSION_RESULT_ARTIFACT, frontendWriterAdmissionResultV1Schema, } from "../workflows/dag/frontend-writer-admission.js";
 import { deriveFrontendIntegrationFacts, buildFrontendTestHandoff, frontendCloseoutFactsSchema, renderFrontendCloseout, } from "../workflows/dag/frontend-closeout.js";
@@ -2413,6 +2414,29 @@ async function executeFrontendDesignPolicy(input, meta) {
                 binding: meta.spec.sourceBinding,
             });
         }
+        // Byte freshness is necessary but not sufficient: require the same ledger
+        // semantic checks as the shadow prewrite gate before production writer
+        // admission can be materialized.
+        if (meta.spec.sourceBinding) {
+            const ledgerCheck = await checkFrontendSourceFidelityLedger({
+                workspaceRoot: input.cwd,
+                binding: meta.spec.sourceBinding,
+                contractRequirements: contract.requirements.map((requirement) => ({
+                    id: requirement.id,
+                    sourceFragmentIds: requirement.sourceFragmentIds,
+                    sourceRefs: requirement.sourceRefs,
+                })),
+            });
+            if (!ledgerCheck.ok) {
+                return {
+                    ok: false,
+                    stdout: "",
+                    stderr: `frontend design policy blocked: ${ledgerCheck.failureReason ?? "source fidelity ledger validation failed"}`,
+                    failureCategory: "invalid-output",
+                    durationMs: Date.now() - started,
+                };
+            }
+        }
         const sourceFreshness = await collectFrontendSourceFreshness({
             workspaceRoot: input.cwd,
             sourceBinding: meta.spec.sourceBinding,
@@ -2455,7 +2479,7 @@ async function executeFrontendDesignPolicy(input, meta) {
         }
         return {
             ok: true,
-            stdout: `Frontend design policy: approved findings=0\nContract: ${path.posix.join(config.outputDir, config.artifactName)}`,
+            stdout: `Frontend design policy: approved findings=0\nContract: ${path.resolve(meta.runDir, config.outputDir, config.artifactName)}`,
             stderr: "",
             failureCategory: "success",
             durationMs: Date.now() - started,
@@ -3377,34 +3401,6 @@ async function executeDagShellNodeInner(input, meta) {
     if (shell?.frontendWriterAdmission) {
         return executeFrontendWriterAdmission(input, meta);
     }
-    if (shell?.frontendPrewriteGate) {
-        const started = Date.now();
-        try {
-            const result = await runFrontendPrewriteGate({
-                runDir: meta.runDir,
-                config: shell.frontendPrewriteGate,
-                sourceBinding: meta.spec.sourceBinding,
-                workspaceRoot: input.cwd,
-                repoRoot: input.cwd,
-            });
-            return {
-                ok: true,
-                stdout: formatFrontendPrewriteGateStdout(result),
-                stderr: "",
-                failureCategory: "success",
-                durationMs: Date.now() - started,
-            };
-        }
-        catch (error) {
-            return {
-                ok: false,
-                stdout: "",
-                stderr: error instanceof Error ? error.message : String(error),
-                failureCategory: "invalid-output",
-                durationMs: Date.now() - started,
-            };
-        }
-    }
     if (shell?.frontendVerificationBundle) {
         return executeFrontendVerificationBundle(input, meta);
     }

package/dist/shared/dag-prompt-override.js

@@ -1,15 +1,14 @@
 /**
  * Internal switch for the experimental "rerun failed node with an edited
- * prompt" capability. Default is OFF; nothing may depend on it being enabled.
- * The switch is deliberately env-based (no harness.json surface) while the
- * feature is internal.
+ * prompt" capability. The feature is enabled by default; the environment
+ * variable remains as an emergency kill switch while the feature is internal.
  */
 export const DAG_RERUN_PROMPT_OVERRIDE_ENV = "HARNESS_DAG_RERUN_PROMPT_OVERRIDE";
 /** Upper bound for an override input body (characters). */
 export const MAX_DAG_RERUN_PROMPT_OVERRIDE_CHARS = 65_536;
 export function isDagRerunPromptOverrideEnabled(env = process.env) {
-    const value = env[DAG_RERUN_PROMPT_OVERRIDE_ENV];
-    return value === "1" || value === "true";
+    const value = env[DAG_RERUN_PROMPT_OVERRIDE_ENV]?.trim().toLowerCase();
+    return value !== "0" && value !== "false" && value !== "off";
 }
 export const DAG_RERUN_PROMPT_ADDENDUM_TAG = "operator_addendum";
 /**

package/dist/shared/update/npm-client.js

@@ -11,10 +11,10 @@ export function createNpmUpdateClient(options) {
     const timeoutMs = options.timeoutMs ?? DEFAULT_NPM_QUERY_TIMEOUT_MS;
     const cwd = options.cwd;
     const env = options.env;
-    const latestVersionCheck = async () => {
+    const distTagVersionCheck = async (channel) => {
         let result;
         try {
-            result = await runner(npmCommand, ["view", PACKAGE_NAME, "dist-tags.latest", "--json"], { timeoutMs, cwd, env });
+            result = await runner(npmCommand, ["view", PACKAGE_NAME, `dist-tags.${channel}`, "--json"], { timeoutMs, cwd, env });
         }
         catch {
             return { ok: false, reason: "spawn-failure" };
@@ -27,17 +27,19 @@ export function createNpmUpdateClient(options) {
         if (result.exitCode !== 0) {
             return { ok: false, reason: "command-failed" };
         }
-        const version = parseNpmViewLatest(result.stdout);
+        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 latestVersionCheck();
             return result.ok ? result.version : undefined;
         },
         latestVersionCheck,
+        distTagVersionCheck,
         async canAutoInstall() {
             return proveGlobalNpmInstall({
                 currentVersion: options.currentVersion,
@@ -49,10 +51,11 @@ export function createNpmUpdateClient(options) {
                 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), {
+            }
+            const result = await runner(npmCommand, buildExactInstallArgs(version, channel), {
                 timeoutMs: Math.max(timeoutMs, 120000),
                 cwd,
                 env,
@@ -79,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 {
@@ -89,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) {
@@ -106,7 +117,13 @@ 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"], {
@@ -142,6 +159,11 @@ 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], {

package/dist/task/config-types.js

@@ -219,6 +219,21 @@ const taskConfigObjectSchema = z.object({
     maxFixLoops: z.number().int().min(0).optional().default(2),
     /** Supervised DAG convergence is opt-in until runtime smoke evidence is stronger. */
     convergence: convergenceConfigSchema.optional().default({ enabled: false }),
+    /** Frontend recovery continuation quota. Bounds how many times a failed
+     * frontend run may auto-recover via M6 recovery operations (1 = current
+     * default; raise to 2-3 for more tolerance of transient verify failures). */
+    frontendRecovery: z
+        .object({
+        maxContinuations: z
+            .number()
+            .int()
+            .min(1)
+            .max(5)
+            .optional()
+            .default(1),
+    })
+        .strict()
+        .optional(),
     /** Outer loop auto mode never writes by default; DAG execute requires this policy plus path/writeSet gates. */
     loopAutoExecutionPolicy: loopAutoExecutionPolicySchema
         .optional()

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

@@ -29,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/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"));
 }

package/dist/task/contract/schema.js

@@ -108,6 +108,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

package/dist/task/contract/transaction.js

@@ -21,6 +21,7 @@ export async function runJournaledContractCommit(input) {
     const constraintsRel = `source/${CONSTRAINTS_FILE_NAME}`;
     const taskConfigRel = "task.json";
     const contractRel = CONTRACT_FILE_NAME;
+    const requirementLedgerRel = `source/requirement-ledger.json`;
     const targetSpecs = [
         {
             kind: "requirement",
@@ -46,6 +47,17 @@ export async function runJournaledContractCommit(input) {
             content: input.targets.contractRef,
             isJson: true,
         },
+        ...(input.targets.requirementLedgerContent !== undefined
+            ? [
+                {
+                    kind: "requirement-ledger",
+                    relativePath: requirementLedgerRel,
+                    // Content is already serialized JSON text; stageText avoids double-encoding.
+                    content: input.targets.requirementLedgerContent,
+                    isJson: false,
+                },
+            ]
+            : []),
     ];
     const targetRecords = [];
     for (const spec of targetSpecs) {

package/dist/task/frontend-project-capability.js

@@ -6,7 +6,7 @@
 import { lstat, readFile, readdir, realpath, stat } from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
-import { DEFAULT_OPENSPEC_GOVERNANCE_ROOT, MAX_OPENSPEC_CANDIDATE_PATHS, OPENSPEC_SPEC_DIRS, OPENSPEC_SPEC_EXT_RE, isGovernanceSubtreePath, } from "../shared/openspec-spec.js";
+import { DEFAULT_OPENSPEC_GOVERNANCE_ROOT, MAX_OPENSPEC_CANDIDATE_PATHS, OPENSPEC_SPEC_DIRS, OPENSPEC_SPEC_EXT_RE, isGovernanceSubtreePath, isValidFrontendSpecRoot, } from "../shared/openspec-spec.js";
 const classifiedPathSchema = z
     .string()
     .refine((candidate) => OPENSPEC_SPEC_EXT_RE.test(candidate), "classified path must be a repo-relative supported spec file");
@@ -81,6 +81,77 @@ async function exists(filePath) {
         return false;
     }
 }
+export const FRONTEND_SPEC_REGISTRY_PATH = "ai_workspace/loop-agent/spec-registry.json";
+const SPEC_SIGNAL_RE = /(?:规范|规约|标准|约定|guideline|standard|convention|design[- ]?system|rule|token|component|style|theme)/i;
+const SPEC_EXCLUDE_RE = /(?:^|\/)(?:archive|history|changelog|changes|proposals?|release[-_ ]notes?)(?:\/|$)/i;
+/** Stable, bounded heuristic used only for candidate ordering/classification. */
+export function scoreFrontendSpecCandidate(filePath, contentPreview = "", options = {}) {
+    const normalized = filePath.replaceAll("\\", "/");
+    const lower = normalized.toLowerCase();
+    const reasons = [];
+    let score = 0;
+    if (options.registryMode === "normative") {
+        score += 100;
+        reasons.push("registry-normative");
+    }
+    else if (options.registryMode === "advisory") {
+        score += 30;
+        reasons.push("registry-advisory");
+    }
+    if (options.taskRelated) {
+        score += 25;
+        reasons.push("task-related");
+    }
+    if (/(?:design-system|guidelines?|standards?|conventions?|rules?|specs?)(?:\/|$)/i.test(lower)) {
+        score += 20;
+        reasons.push("spec-directory");
+    }
+    if (/(?:guidelines?|standards?|conventions?|rules?|tokens?|components?|theme|style)/i.test(path.basename(lower))) {
+        score += 15;
+        reasons.push("spec-filename");
+    }
+    if (SPEC_SIGNAL_RE.test(contentPreview)) {
+        score += 20;
+        reasons.push("spec-content");
+    }
+    if (/(?:^|\n)\s*(?:#{1,6}\s*)?(?:rules?|do|don't|必须|禁止|约定|规范)\b/im.test(contentPreview)) {
+        score += 15;
+        reasons.push("normative-structure");
+    }
+    if (SPEC_EXCLUDE_RE.test(lower)) {
+        score -= 80;
+        reasons.push("excluded-history-path");
+    }
+    const kind = options.registryMode === "normative" || score >= 80
+        ? "normative"
+        : score >= 35
+            ? "advisory"
+            : "unknown";
+    return { path: normalized, kind, score, reasons, source: options.registryMode ? "registry" : "auto-discovered" };
+}
+/** Read the optional project-level registry without making it mandatory. */
+export async function readFrontendSpecRegistry(repoRoot) {
+    const raw = await readJson(path.join(repoRoot, FRONTEND_SPEC_REGISTRY_PATH));
+    if (!raw || typeof raw !== "object")
+        return null;
+    const value = raw;
+    if (value.version !== 1 || !Array.isArray(value.roots))
+        return null;
+    const roots = value.roots
+        .filter((item) => Boolean(item) && typeof item === "object")
+        .map((item) => ({
+        path: typeof item.path === "string" ? item.path.replaceAll("\\", "/").replace(/\/+$/, "") : "",
+        scope: Array.isArray(item.scope) ? item.scope.filter((v) => typeof v === "string") : undefined,
+        mode: (item.mode === "normative" || item.mode === "advisory" ? item.mode : undefined),
+        description: typeof item.description === "string" ? item.description : undefined,
+    }))
+        .filter((item) => isValidFrontendSpecRoot(item.path));
+    return {
+        version: 1,
+        roots,
+        discovery: value.discovery && typeof value.discovery === "object" ? value.discovery : undefined,
+    };
+}
 /**
  * Resolve only unambiguous symlink-root aliases. The physical target is never
  * emitted as a candidate path: it merely lets task-source wording such as
@@ -133,6 +204,14 @@ export async function listOpenspecDiscovery(repoRoot, options = {}) {
         .filter(Boolean);
     const collected = [];
     let excludedGovernanceCount = 0;
+    let scannedFiles = 0;
+    let scannedBytes = 0;
+    const warnings = [];
+    const maxDepth = options.maxDepth ?? 4;
+    const maxFiles = options.maxFiles ?? MAX_OPENSPEC_CANDIDATE_PATHS;
+    const maxBytes = options.maxBytes ?? 1024 * 1024;
+    const timeoutMs = options.timeoutMs ?? 2000;
+    const startedAt = Date.now();
     // Metadata / bookkeeping directories that are not normative design specs:
     // changelogs, ADR/history archives, proposals under review, and scratch
     // state. Reading them inflates the candidate list (and the plan prompt)
@@ -181,10 +260,19 @@ export async function listOpenspecDiscovery(repoRoot, options = {}) {
         excludedGovernanceCount,
         truncated,
         maxCandidates: MAX_OPENSPEC_CANDIDATE_PATHS,
+        warnings,
     };
     async function walk(dir, depth) {
-        if (depth > 4)
+        if (Date.now() - startedAt >= timeoutMs) {
+            if (!warnings.includes("timeout-exceeded"))
+                warnings.push("timeout-exceeded");
             return;
+        }
+        if (depth > maxDepth) {
+            if (!warnings.includes("max-depth-exceeded"))
+                warnings.push("max-depth-exceeded");
+            return;
+        }
         let entries = [];
         try {
             entries = (await readdir(dir)).sort();
@@ -193,12 +281,30 @@ export async function listOpenspecDiscovery(repoRoot, options = {}) {
             return;
         }
         for (const name of entries) {
+            if (Date.now() - startedAt >= timeoutMs) {
+                if (!warnings.includes("timeout-exceeded"))
+                    warnings.push("timeout-exceeded");
+                return;
+            }
+            if (scannedFiles >= maxFiles) {
+                if (!warnings.includes("max-files-exceeded"))
+                    warnings.push("max-files-exceeded");
+                return;
+            }
             const full = path.join(dir, name);
             try {
                 const info = await stat(full);
                 if (info.isDirectory())
                     await walk(full, depth + 1);
                 else if (OPENSPEC_SPEC_EXT_RE.test(name)) {
+                    const size = info.size;
+                    if (scannedBytes + size > maxBytes) {
+                        if (!warnings.includes("max-bytes-exceeded"))
+                            warnings.push("max-bytes-exceeded");
+                        return;
+                    }
+                    scannedFiles++;
+                    scannedBytes += size;
                     const rel = path.relative(repoRoot, full).replace(/\\/g, "/");
                     if (isExcluded(rel)) {
                         excludedGovernanceCount++;
@@ -387,6 +493,7 @@ function toOpenspecDiscovery(discovery, designEvidence) {
         excludedGovernanceCount: discovery.excludedGovernanceCount,
         truncated: discovery.truncated,
         maxCandidates: discovery.maxCandidates,
+        warnings: discovery.warnings,
     };
 }
 export function buildAdapterGuidance(capability) {
@@ -424,12 +531,24 @@ export function buildAdapterGuidance(capability) {
  * Strong evidence: package.json direct deps + config/bootstrap files.
  */
 export async function discoverFrontendProjectCapability(repoRoot, options = {}) {
+    const registry = await readFrontendSpecRegistry(repoRoot);
+    const registryRoots = registry?.roots
+        .filter((root) => !root.scope || root.scope.includes("frontend"))
+        .map((root) => root.path) ?? [];
+    const discoveryOptions = {
+        ...options,
+        specRoots: [...new Set([...OPENSPEC_SPEC_DIRS, ...(options.specRoots ?? []), ...registryRoots])],
+        maxDepth: registry?.discovery?.maxDepth ?? options.maxDepth,
+        maxFiles: registry?.discovery?.maxFiles ?? options.maxFiles,
+        maxBytes: registry?.discovery?.maxBytes ?? options.maxBytes,
+        timeoutMs: registry?.discovery?.timeoutMs ?? options.timeoutMs,
+    };
     const evidencePaths = [];
     const reasons = [];
     const pkgPath = path.join(repoRoot, "package.json");
     const pkgRaw = await readJson(pkgPath);
     if (!pkgRaw || typeof pkgRaw !== "object") {
-        const discovery = await listOpenspecDiscovery(repoRoot, options);
+        const discovery = await listOpenspecDiscovery(repoRoot, discoveryOptions);
         const designEvidence = buildDesignEvidence(discovery.paths);
         const base = {
             schemaVersion: 1,
@@ -602,7 +721,7 @@ export async function discoverFrontendProjectCapability(repoRoot, options = {})
         router = router ?? "next-router";
     if (hasDep(deps, "vue-router"))
         router = "vue-router";
-    const discovery = await listOpenspecDiscovery(repoRoot, options);
+    const discovery = await listOpenspecDiscovery(repoRoot, discoveryOptions);
     const designEvidence = buildDesignEvidence(discovery.paths);
     if (discovery.paths.length)
         evidencePaths.push(...discovery.paths.slice(0, 5));