@tea-agent/loop-agent 0.42.0-next.2 → 0.42.0-next.4

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

@@ -3,13 +3,13 @@
  * Strong evidence only: package.json deps, config files, source imports.
  * Lockfile-only or directory-name-only must NOT activate adapters.
  */
-import { readFile, readdir, stat } from "node:fs/promises";
+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, isOpenspecSpecFilePath, } 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) => isOpenspecSpecFilePath(candidate), "classified path must be a repo-relative supported spec file under openspec/schemas/, openspec/project-specs/, or ai_workspace/");
+    .refine((candidate) => OPENSPEC_SPEC_EXT_RE.test(candidate), "classified path must be a repo-relative supported spec file");
 /**
  * Stable semantic partition of `designEvidence.normativePaths`. Keys are a
  * generic directory convention (not project-specific file names); the same
@@ -81,6 +81,105 @@ 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
+ * `ai_doc/rules.md` resolve to the stable repo-local path `ai_workspace/rules.md`.
+ */
+export async function resolveFrontendSpecRootAliases(repoRoot, specRoots) {
+    const candidates = [];
+    for (const logicalRoot of specRoots) {
+        const full = path.join(repoRoot, logicalRoot);
+        try {
+            if (!(await lstat(full)).isSymbolicLink())
+                continue;
+            const alias = path.basename(await realpath(full));
+            if (alias && alias !== path.basename(logicalRoot)) {
+                candidates.push({ alias, logicalRoot });
+            }
+        }
+        catch {
+            // Missing/broken links are handled by normal candidate discovery drift.
+        }
+    }
+    const counts = new Map();
+    for (const item of candidates)
+        counts.set(item.alias, (counts.get(item.alias) ?? 0) + 1);
+    return candidates
+        .filter((item) => counts.get(item.alias) === 1)
+        .sort((a, b) => a.alias.localeCompare(b.alias));
+}
 /**
  * Resolve the governance subtree root from harness.json.governanceRoot.
  * Falls back to DEFAULT_OPENSPEC_GOVERNANCE_ROOT when the manifest is missing,
@@ -105,28 +204,54 @@ export async function listOpenspecDiscovery(repoRoot, options = {}) {
         .filter(Boolean);
     const collected = [];
     let excludedGovernanceCount = 0;
+    let scannedFiles = 0;
+    let maxFilesHit = false;
+    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)
+    // with files no component selection should cite. A task that genuinely
+    // needs one can still reference it explicitly — the prewrite gate
+    // candidates come from this discovery, but explicit task-source citations
+    // flow through openspecMandatoryPaths independently.
+    const DEFAULT_EXCLUDED_SPEC_PREFIXES = [
+        "openspec/changes",
+        "openspec/project-specs/changes",
+        "openspec/project-specs/changelog",
+        "openspec/project-specs/history",
+        "openspec/project-specs/archive",
+        "openspec/project-specs/decisions",
+        "openspec/project-specs/proposals",
+    ];
     const isExcluded = (rel) => {
         if (isGovernanceSubtreePath(rel, governanceRoot))
             return true;
+        if (DEFAULT_EXCLUDED_SPEC_PREFIXES.some((prefix) => rel === prefix || rel.startsWith(prefix + "/"))) {
+            return true;
+        }
         return extraExcludedPrefixes.some((prefix) => rel === prefix || rel.startsWith(prefix + "/"));
     };
-    for (const specDir of OPENSPEC_SPEC_DIRS) {
+    for (const specDir of options.specRoots ?? [...OPENSPEC_SPEC_DIRS]) {
         const root = path.join(repoRoot, specDir);
         if (!(await exists(root)))
             continue;
         await walk(root, 0);
     }
-    // openspec/schemas/** and openspec/project-specs/** sort first; remaining
-    // ai_workspace/** business files follow. Dedupe preserves discovery order.
+    // Keep the established default-root priority for deterministic compatibility;
+    // configured extra roots are appended in lexical order.
     const unique = [...new Set(collected)];
-    const openspecPaths = unique
-        .filter((candidate) => candidate.startsWith("openspec/"))
-        .sort();
-    const aiWorkspacePaths = unique
-        .filter((candidate) => candidate.startsWith("ai_workspace/"))
+    const defaultPaths = OPENSPEC_SPEC_DIRS.flatMap((root) => unique.filter((candidate) => candidate.startsWith(root + "/")).sort());
+    const customPaths = unique
+        .filter((candidate) => !defaultPaths.includes(candidate))
         .sort();
-    const deduped = [...openspecPaths, ...aiWorkspacePaths];
-    const truncated = deduped.length > MAX_OPENSPEC_CANDIDATE_PATHS;
+    const deduped = [...defaultPaths, ...customPaths];
+    const truncated = maxFilesHit || deduped.length > MAX_OPENSPEC_CANDIDATE_PATHS;
     const paths = truncated
         ? deduped.slice(0, MAX_OPENSPEC_CANDIDATE_PATHS)
         : deduped;
@@ -136,10 +261,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();
@@ -148,12 +282,31 @@ 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");
+                maxFilesHit = true;
+                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++;
@@ -241,6 +394,14 @@ function emptyClassified() {
  * project-specific file names. Basename stems use word-boundary matching so
  * e.g. `*api*` (case-insensitive) maps to `rule.api` without hardcoding names.
  */
+/** True when any path segment (other than the file itself) carries a
+ * component/theme kind marker. Directory-organized libraries such as
+ * `ui/ucp-components-md/AdvancedSearch.md` rely on this; templates/ and
+ * rules/ are handled by their own branches before this fallback runs. */
+function segmentMatchesComponentKind(segments) {
+    const dirSegments = segments.slice(0, -1);
+    return dirSegments.some((segment) => /\bcomponents?\b/.test(segment.toLowerCase()));
+}
 function classifyOpenspecPaths(paths) {
     const classified = emptyClassified();
     const ruleStem = (basename) => {
@@ -260,7 +421,7 @@ function classifyOpenspecPaths(paths) {
         return "other";
     };
     for (const candidate of paths) {
-        if (!isOpenspecSpecFilePath(candidate))
+        if (!OPENSPEC_SPEC_EXT_RE.test(candidate))
             continue;
         const segments = candidate.split("/");
         const basename = segments[segments.length - 1] ?? "";
@@ -279,8 +440,17 @@ function classifyOpenspecPaths(paths) {
                 classified.theme.push(candidate);
             else if (/\bcomponents?\b/.test(lower))
                 classified.component.push(candidate);
-            else
+            else if (segmentMatchesComponentKind(segments)) {
+                // Directory-organized component libraries (e.g.
+                // ui/ucp-components-md/AdvancedSearch.md) carry the kind in the
+                // parent directory name, not the file name. The parent-dir rule
+                // is a fallback so such layouts still land in the component
+                // bucket instead of being dropped into uiOther.
+                classified.component.push(candidate);
+            }
+            else {
                 classified.uiOther.push(candidate);
+            }
         }
         else {
             classified.advisoryOther.push(candidate);
@@ -325,6 +495,7 @@ function toOpenspecDiscovery(discovery, designEvidence) {
         excludedGovernanceCount: discovery.excludedGovernanceCount,
         truncated: discovery.truncated,
         maxCandidates: discovery.maxCandidates,
+        warnings: discovery.warnings,
     };
 }
 export function buildAdapterGuidance(capability) {
@@ -344,7 +515,7 @@ export function buildAdapterGuidance(capability) {
         lines.push("Vue adapter: prefer Composition API if project already uses it; reuse Pinia/Vue Router/Vue Query only when evidenced; Vitest + Vue Test Utils when present.");
     }
     else {
-        lines.push("Unknown framework: use generic frontend-implementation skill only; do not assume React/Vue/Next APIs.");
+        lines.push("Unknown framework: use only the node-scoped generic frontend guidance; do not assume React/Vue/Next APIs.");
     }
     if (capability.a11y.status === "present") {
         lines.push(`A11y tools present: ${capability.a11y.tools.join(", ")}. Report static/component-level evidence only; Browser a11y remains not-run.`);
@@ -361,13 +532,25 @@ export function buildAdapterGuidance(capability) {
  * Discover frontend project capability from repo root.
  * Strong evidence: package.json direct deps + config/bootstrap files.
  */
-export async function discoverFrontendProjectCapability(repoRoot) {
+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);
+        const discovery = await listOpenspecDiscovery(repoRoot, discoveryOptions);
         const designEvidence = buildDesignEvidence(discovery.paths);
         const base = {
             schemaVersion: 1,
@@ -540,7 +723,7 @@ export async function discoverFrontendProjectCapability(repoRoot) {
         router = router ?? "next-router";
     if (hasDep(deps, "vue-router"))
         router = "vue-router";
-    const discovery = await listOpenspecDiscovery(repoRoot);
+    const discovery = await listOpenspecDiscovery(repoRoot, discoveryOptions);
     const designEvidence = buildDesignEvidence(discovery.paths);
     if (discovery.paths.length)
         evidencePaths.push(...discovery.paths.slice(0, 5));

package/dist/task/runtime.js

@@ -72,7 +72,7 @@ export function getTaskPaths(repoRoot, taskId) {
         dagDraftPath: path.join(taskDir, 'dag.json'),
     };
 }
-export async function createTask(repoRoot, taskId, title) {
+export async function createTask(repoRoot, taskId, title, options) {
     const validation = validateNewTaskId(taskId);
     for (const warning of validation.warnings) {
         console.warn(`[new-task] warning: ${warning}`);
@@ -97,7 +97,10 @@ export async function createTask(repoRoot, taskId, title) {
         taskId,
         title: title ?? taskId,
         sourceFiles: [],
-        taskKind: 'standard',
+        taskKind: options?.taskKind ?? 'standard',
+        ...(options?.taskKindExplicit !== undefined
+            ? { taskKindExplicit: options.taskKindExplicit }
+            : {}),
         referenceRepos: [],
         referenceDocs: [],
         allowedPaths: [],

package/dist/task/source-prepare/build-draft.js

@@ -17,10 +17,10 @@ function resolveTaskKind(flags, baseDraft, existing) {
     const parsed = taskKindSchema.safeParse(candidate);
     return parsed.success ? parsed.data : String(candidate);
 }
-function resolveTaskKindExplicit(flags, baseDraft) {
+function resolveTaskKindExplicit(flags, baseDraft, existing) {
     if (flags.taskKindExplicit !== undefined)
         return flags.taskKindExplicit;
-    return baseDraft?.taskKindExplicit ?? false;
+    return (baseDraft?.taskKindExplicit ?? existing?.taskKindExplicit ?? false);
 }
 /**
  * Resolve managed backend-test layout config.
@@ -122,7 +122,7 @@ export function buildPrepareDraft(input) {
     const { taskId, existingTaskConfig, baseDraft, facts, flags, references } = input;
     const title = resolveTitle(taskId, flags, facts, baseDraft, existingTaskConfig);
     const taskKind = resolveTaskKind(flags, baseDraft, existingTaskConfig);
-    const taskKindExplicit = resolveTaskKindExplicit(flags, baseDraft);
+    const taskKindExplicit = resolveTaskKindExplicit(flags, baseDraft, existingTaskConfig);
     const featureId = trimNonEmpty(flags.featureId) ??
         trimNonEmpty(baseDraft?.featureId) ??
         trimNonEmpty(existingTaskConfig?.featureId) ??

package/dist/task/source-prepare/fragment-inventory.js

@@ -175,8 +175,11 @@ export function splitDocumentIntoFragments(doc) {
         const explicitSectionAc = matchExplicitAcHeading(lastHeadingSegment);
         const sectionKind = classifySectionHeading(section.headingPath);
         const effectiveKind = explicitSectionAc ? "acceptance" : sectionKind;
+        // V4 显式 AC 标题行已在下方入口 emit（explicitSectionAc 分支）；正文循环
+        // 必须从标题行的下一行开始，否则同一标题行会被正文循环的 heading 分支
+        // 再次 emit，产生结构性 duplicate（每个 AC 标题式片段出现两次）。
         const bodyStart = section.headingPath
-            ? section.startLine + (explicitSectionAc ? 0 : 1)
+            ? section.startLine + 1
             : section.startLine;
         const bodyEnd = section.endLine;
         const bodyLines = lines.slice(Math.max(0, bodyStart - 1), Math.min(bodyEnd, lines.length));
@@ -438,14 +441,17 @@ export function buildFragmentInventory(input) {
             disposition = "non-goal";
         }
         else {
-            const executable = EXECUTABLE_HINT_RE.test(text);
-            disposition = executable ? "unresolved" : "context-only";
-            if (disposition === "unresolved") {
-                reason = "executable fragment outside recognized requirement/acceptance section";
-            }
-            else {
-                reason = "context-only fragment; excluded from canonical requirement coverage";
-            }
+            // Non-goal/constraint/acceptance/objective sections are classified
+            // above. An "other" section (背景 / 概述 / 说明 …) is contextual
+            // description, not an executable requirement: even when it mentions
+            // implementation verbs ("需要", "渲染", "组件"), it must not be
+            // promoted to a high-risk unresolved executable fragment — that
+            // blocks PRDs whose 背景 prose happens to use such words (merge
+            // regression: "需要一个小组件" was flagged executable via 需要).
+            // Explicit AC ids are already handled by the branches above, so
+            // this branch is always contextual.
+            disposition = "context-only";
+            reason = "context-only fragment; excluded from canonical requirement coverage";
         }
         const priorId = seenText.get(text);
         if (priorId) {

package/dist/task/source-prepare/prepare.js

@@ -5,6 +5,9 @@ import { ContractMutationError, applyTaskContract, logicalRevisionForState, obse
 import { TASK_CONTRACT_DRAFT_SCHEMA_VERSION } from "../contract/constants.js";
 import { getTaskContractPaths } from "../contract/paths.js";
 import { loadTaskConfig } from "../runtime.js";
+import { discoverFrontendProjectCapability, resolveFrontendSpecRootAliases, } from "../frontend-project-capability.js";
+import { classifyTaskDemand } from "../task-demand-routing.js";
+import { DEFAULT_FRONTEND_SPEC_ROOTS, extractDeclaredFrontendSpecRoots, } from "../../shared/openspec-spec.js";
 import { buildPrepareDraft } from "./build-draft.js";
 import { hasBlockingGaps, hasBlockingRisks, isFreshLegacyUnversioned, listPrepareGaps, appendLedgerGaps, } from "./completeness.js";
 import { detectProductArtifactMeta, isIntakeSoftGapCode, } from "./artifact-meta.js";
@@ -681,7 +684,7 @@ export async function prepareTaskSource(input) {
             facts = importedFacts ?? mergedSupplemental;
         }
     }
-    const built = buildPrepareDraft({
+    let built = buildPrepareDraft({
         taskId,
         existingTaskConfig,
         baseDraft,
@@ -689,6 +692,91 @@ export async function prepareTaskSource(input) {
         flags: input.flags,
         references,
     });
+    // Resolve an implicit frontend workflow before the first managed contract is
+    // projected. Explicit taskKind (including explicit standard) remains a hard
+    // contract; only a standard task with strong source/path/project evidence may
+    // be promoted here. This keeps task.json, contract.json, and the first DAG
+    // generation on the same workflow without a later hash-changing re-projection.
+    if (built.draft.taskKind === "standard" &&
+        !built.draft.taskKindExplicit) {
+        const routingRequirement = [
+            ...(sourceIntegrity?.documents ?? [])
+                .map((document) => document.content)
+                .filter((content) => Boolean(content?.trim())),
+            ...(input.intent.kind === "facts" && input.intent.text
+                ? [input.intent.text]
+                : []),
+            built.draft.requirement.objective,
+            ...built.draft.requirement.scope,
+            ...built.draft.requirement.acceptanceCriteria.map((item) => item.text),
+        ].join("\n");
+        let frontendProject;
+        try {
+            frontendProject = await discoverFrontendProjectCapability(repoRoot);
+        }
+        catch {
+            // Capability discovery is advisory for routing. A failed probe must not
+            // turn an otherwise valid standard contract preparation into an error.
+        }
+        const classification = classifyTaskDemand({
+            title: built.draft.title,
+            requirementMarkdown: routingRequirement,
+            allowedPaths: built.draft.constraints.allowedPaths,
+            frontendProject: frontendProject
+                ? {
+                    framework: frontendProject.framework,
+                    evidencePaths: frontendProject.evidencePaths,
+                }
+                : undefined,
+        });
+        if (classification.kind === "frontend") {
+            built = buildPrepareDraft({
+                taskId,
+                existingTaskConfig,
+                baseDraft,
+                facts,
+                flags: {
+                    ...input.flags,
+                    taskKind: "frontend-implementation",
+                },
+                references,
+            });
+        }
+    }
+    // A user can explicitly name a non-default normative directory in the task
+    // prompt (for example “规范目录 `design-system`”). Freeze that root into
+    // the managed task config before the DAG exists; normal DAG selection consumes
+    // the already-resolved task kind instead of mutating task.json later.
+    if (built.draft.taskKind === "frontend-implementation") {
+        // An imported PRD is materialized under sourceIntegrity rather than copied
+        // into intent.text. Use both inputs so a `--prd` invocation can declare a
+        // task-owned spec root just like supplemental free-form text can.
+        const sourceText = [
+            ...(sourceIntegrity?.documents ?? []).flatMap((document) => document.content ? [document.content] : []),
+            ...(input.intent.kind === "facts" && input.intent.text
+                ? [input.intent.text]
+                : []),
+        ].join("\n");
+        const inferredRoots = extractDeclaredFrontendSpecRoots(sourceText);
+        if (inferredRoots.length > 0) {
+            const current = existingTaskConfig?.frontendOpenspec;
+            const configuredRoots = current?.specRoots ?? [...DEFAULT_FRONTEND_SPEC_ROOTS];
+            // Include roots declared by this source before resolving physical-target
+            // aliases. A newly declared root may itself be a symlink (for example
+            // `project-specs -> .../ai_doc`), so resolving aliases against only the
+            // previous config cannot map `ai_doc/rules.md` back to project-specs.
+            const provisionalRoots = [
+                ...new Set([...configuredRoots, ...inferredRoots]),
+            ].sort();
+            const aliases = await resolveFrontendSpecRootAliases(repoRoot, provisionalRoots);
+            const aliasMap = new Map(aliases.map(({ alias, logicalRoot }) => [alias, logicalRoot]));
+            built.draft.frontendOpenspec = {
+                policy: current?.policy ?? "cited",
+                specRoots: [...new Set([...configuredRoots, ...inferredRoots.map((root) => aliasMap.get(root) ?? root)])].sort(),
+                requiredReadPaths: current?.requiredReadPaths ?? [],
+            };
+        }
+    }
     const { gaps, risks } = listPrepareGaps({
         draft: built.draft,
         state,

package/dist/task/source-prepare/semantic-intake.js

@@ -457,8 +457,12 @@ async function buildPrompt(input) {
         "Do NOT invent product behavior that is not supported by the documents.",
         "You MAY recommend an optional engineering block when the repo layout hint supports it:",
         "- allowedPaths / forbiddenPaths as minimal precise globs (e.g. source/packages/**/*.test.ts)",
-        "- verifyCommands as real package scripts (e.g. pnpm -C source test)",
-        "- taskKind when clearly implied (backend-test / frontend-test / standard / …)",
+        "- verifyCommands as real package scripts (e.g. pnpm -C source test); when acceptance criteria name a specific test file to run (e.g. 定向 vitest（test/.../xxx.test.ts）), emit the corresponding targeted command as its own entry (e.g. npx vitest run test/.../xxx.test.ts) instead of only the full-suite script — targeted commands are what a frontend implementation plan maps to behavior verification targets",
+        "- taskKind when clearly implied, choosing from {standard / frontend-implementation / frontend-test / backend-test / knowledge-sync}:",
+        "  - frontend-implementation: the deliverable is a frontend component/page/UI feature (even when it ships with its own tests)",
+        "  - frontend-test: the deliverable is a browser/UI automation test suite for EXISTING functionality (no implementation work)",
+        "  - backend-test: pytest/backend test suite; standard: general repo implementation",
+        "  A task that IMPLEMENTS a component and adds tests for it is frontend-implementation, never frontend-test.",
         "Prefer smallest correct write boundary; do not invent product paths that are not in the layout hint.",
         "Do NOT rewrite or suggest editing the original PRD files.",
         "Prefer explicit text; use provenance derived for rephrasing; use inferred only when clearly implied — if you must invent ACs, leave acceptanceCriteria empty so the system can stop for clarification.",

package/dist/task/source-references.js

@@ -22,6 +22,18 @@ function slugifyName(value) {
         .replace(/-{2,}/g, "-");
     return slug || "requirement";
 }
+/** Stable identity of a manifest document for change detection. Timestamps and
+ * byte sizes are excluded: identical content re-imported later must not appear
+ * "changed" (the canonical hash includes manifest bytes). */
+function documentIdentity(doc) {
+    return `${doc.role}|${doc.name}|${doc.materializedPath}|${doc.sha256}`;
+}
+function sameDocumentSet(left, right) {
+    if (left.length !== right.length)
+        return false;
+    const rightIds = new Set(right.map(documentIdentity));
+    return left.every((doc) => rightIds.has(documentIdentity(doc)));
+}
 function ensureUniqueReferenceName(existing, baseName, extension) {
     const used = new Set(existing);
     const candidate = `${baseName}${extension}`;
@@ -149,10 +161,19 @@ export async function importPrdDocument(input) {
     const documents = [...(existingManifest?.documents ?? [])].filter((entry) => entry.materializedPath !== materializedRelativePath);
     documents.push(document);
     documents.sort((left, right) => left.materializedPath.localeCompare(right.materializedPath));
+    // Keep `updatedAt` stable across re-imports of the same content: the
+    // canonical contract hash includes the manifest bytes, so a fresh
+    // timestamp on every identical re-import would make the observed
+    // canonical hash drift and fail task verification. Only bump it when the
+    // document set actually changed (a new/changed materialized file).
+    const documentSetChanged = !existingManifest ||
+        !sameDocumentSet(existingManifest.documents, documents);
     const manifest = {
         schemaVersion: 1,
         taskId: input.taskId,
-        updatedAt: importedAt,
+        updatedAt: documentSetChanged
+            ? importedAt
+            : (existingManifest?.updatedAt ?? importedAt),
         documents,
     };
     await writeSourceManifest(paths.sourceDir, manifest);

package/dist/worker/console/chat/chat-ui-policy.js

@@ -19,7 +19,9 @@ export function shouldPlayCompletionSound(input) {
 export function copyTextForMessage(input) {
     return input.code ?? input.text;
 }
-/** Empty sandbox means scripts, same-origin access, navigation and popups are denied. */
+/** Project HTML may run its own UI scripts, but remains an opaque origin with
+ * forms, popups and top-level navigation denied by omission. */
+export const HTML_PREVIEW_SANDBOX = "allow-scripts";
 export function previewSandbox() {
-    return { sandbox: "" };
+    return { sandbox: HTML_PREVIEW_SANDBOX };
 }