@tea-agent/loop-agent 0.39.0-beta.1 → 0.39.0-beta.11

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,27 +204,52 @@ 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)
+    // 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 deduped = [...defaultPaths, ...customPaths];
     const truncated = deduped.length > MAX_OPENSPEC_CANDIDATE_PATHS;
     const paths = truncated
         ? deduped.slice(0, MAX_OPENSPEC_CANDIDATE_PATHS)
@@ -136,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();
@@ -148,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++;
@@ -241,6 +392,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 +419,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 +438,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 +493,7 @@ function toOpenspecDiscovery(discovery, designEvidence) {
         excludedGovernanceCount: discovery.excludedGovernanceCount,
         truncated: discovery.truncated,
         maxCandidates: discovery.maxCandidates,
+        warnings: discovery.warnings,
     };
 }
 export function buildAdapterGuidance(capability) {
@@ -361,13 +530,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 +721,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/source-prepare/completeness.js

@@ -55,6 +55,25 @@ export function observationBlocksPrepare(state) {
     }
     return null;
 }
+/**
+ * 精确 identity 绑定的人类 resolution 判定（AC-001 / AC-005）：decidedBy==='human'、
+ * decision trim 后非空、sourceRef 与冲突 id 精确匹配三者同时成立才算有效；model/
+ * system 伪造判定、stale sourceRef（不匹配当前冲突 identity）或空/空白 decision 一律
+ * 不解锁。resolution 信息取自 draft 层（不重排流水线，listPrepareGaps 仍先于 ledger
+ * 构建执行）。
+ */
+export function hasValidHumanConflictResolution(draft, conflictId) {
+    for (const resolution of draft.sourceResolutions ?? []) {
+        if (resolution.sourceRef !== conflictId)
+            continue;
+        if (resolution.decidedBy !== "human")
+            continue;
+        if (!resolution.decision?.trim())
+            continue;
+        return true;
+    }
+    return false;
+}
 export function listPrepareGaps(input) {
     const gaps = [];
     const risks = [];
@@ -108,6 +127,12 @@ export function listPrepareGaps(input) {
     }
     if (input.acceptanceConflicts && input.acceptanceConflicts.length > 0) {
         for (const conflict of input.acceptanceConflicts) {
+            // AC-001：有效 human resolution（human + 非空 decision + sourceRef 与冲突 id
+            // 精确匹配）解除该 id 的 legacy blocking gap；无 resolution 或 resolution 不
+            // 满足三条件（AC-005：伪造判定 / stale sourceRef / 空 decision）仍发射阻断。
+            if (hasValidHumanConflictResolution(input.draft, conflict.id)) {
+                continue;
+            }
             gaps.push({
                 code: "ACCEPTANCE_ID_CONFLICT",
                 level: "blocking",
@@ -246,3 +271,166 @@ export function hasBlockingGaps(gaps) {
 export function hasBlockingRisks(risks) {
     return risks.some((risk) => risk.level === "blocking");
 }
+/**
+ * Source fidelity ledger 分级 fail-closed 阻断（AC-003 / AC-FIDELITY-003）：
+ * 高风险未映射/排除、unresolved、冲突返回稳定错误并阻断；低风险 context-only 仅当
+ * 理由完整且独立 reviewer pass 后继续；duplicate 保留全部来源（warning 可见）。
+ * 仅 taskKind 为 frontend-implementation 时全量阻断，其他 taskKind 保持 warning。
+ */
+export function appendLedgerGaps(input) {
+    const { gaps, risks } = input;
+    if (!input.ledgerSummary?.present)
+        return;
+    const blocking = input.taskKind === "frontend-implementation";
+    const level = blocking ? "blocking" : "warning";
+    const summary = input.ledgerSummary;
+    if (summary.unresolvedCount > 0) {
+        const gap = {
+            code: "SOURCE_FIDELITY_UNRESOLVED",
+            level,
+            message: `ledger 有 ${summary.unresolvedCount} 个 unresolved fragment（需人工 sourceResolutions 确认后才可继续）`,
+            details: {
+                fragmentIds: summary.exclusions
+                    .filter((e) => /^REQ-SRC-/.test(e.fragmentId) || e.fragmentId.startsWith("AC-"))
+                    .slice(0, 10)
+                    .map((e) => e.fragmentId),
+            },
+            selfHealing: blocking
+                ? {
+                    action: "reimport-prd",
+                    steps: [
+                        "检查原始 PRD 中无法映射到 canonical AC 的可执行片段（unresolved）",
+                        "补齐/修正 PRD 使每个可执行片段都能绑定 AC，或由人工在 sourceResolutions 中确认排除理由",
+                        "重新 importPrd（同 taskId）后 task advance 重建 ledger",
+                    ],
+                }
+                : undefined,
+        };
+        gaps.push(gap);
+        risks.push({
+            code: "SOURCE_FIDELITY_UNRESOLVED",
+            level: blocking ? "blocking" : "elevated",
+            message: gap.message,
+        });
+    }
+    if (summary.conflictCount > 0) {
+        const gap = {
+            code: "SOURCE_FIDELITY_CONFLICT",
+            level,
+            message: `ledger 检测到 ${summary.conflictCount} 个 AC 文本冲突（同一 ID 不同文本）`,
+            selfHealing: blocking
+                ? {
+                    action: "reimport-prd",
+                    steps: [
+                        "统一同一 AC ID 的文本后重新 importPrd（同 taskId）",
+                        "或由人工在 sourceResolutions 中声明冲突取舍（conflict → decision）",
+                    ],
+                }
+                : undefined,
+        };
+        gaps.push(gap);
+        risks.push({
+            code: "SOURCE_FIDELITY_CONFLICT",
+            level: blocking ? "blocking" : "elevated",
+            message: gap.message,
+        });
+    }
+    if (summary.failureCode === "SOURCE_FIDELITY_HIGH_RISK_UNCOVERED") {
+        const gap = {
+            code: "SOURCE_FIDELITY_HIGH_RISK_UNCOVERED",
+            level,
+            message: "ledger 存在高风险 acceptance 片段未映射到 canonical requirement",
+            selfHealing: blocking
+                ? {
+                    action: "reimport-prd",
+                    steps: [
+                        "为每个未覆盖的高风险片段补齐 canonical AC（或人工 sourceResolutions 确认）",
+                        "重新 importPrd（同 taskId）后 task advance 重建 ledger",
+                    ],
+                }
+                : undefined,
+        };
+        gaps.push(gap);
+        risks.push({
+            code: "SOURCE_FIDELITY_HIGH_RISK_UNCOVERED",
+            level: blocking ? "blocking" : "elevated",
+            message: gap.message,
+        });
+    }
+    for (const error of input.ledgerErrors ?? []) {
+        if (error.code === "SOURCE_FIDELITY_LEDGER_MISSING") {
+            const gap = {
+                code: "SOURCE_FIDELITY_LEDGER_MISSING",
+                level,
+                message: error.message,
+            };
+            gaps.push(gap);
+        }
+        // AC-BLOCK-001：canonical requirement 缺少 fragment/sourceRef 证据、来源引用
+        // 无效、fragment 无效均为 blocking gap（frontend task），保证 prepare/apply
+        // 以稳定码 fail closed（appendLedgerGaps 是 prepare 补洞的唯一入口）。
+        if (error.code === "SOURCE_FIDELITY_REQUIREMENT_NOT_COVERED" ||
+            error.code === "SOURCE_FIDELITY_SOURCE_REF_INVALID" ||
+            error.code === "SOURCE_FIDELITY_FRAGMENT_INVALID") {
+            const gap = {
+                code: error.code,
+                level,
+                message: error.message,
+                selfHealing: blocking
+                    ? {
+                        action: "reimport-prd",
+                        steps: [
+                            "检查 PRD 中每个 canonical requirement 是否都有可审计的 fragment/sourceRef 证据",
+                            "补齐缺失的验收标准映射或修正引用后重新 importPrd（同 taskId）",
+                            "重新 importPrd（同 taskId）后 task advance 重建 ledger",
+                        ],
+                    }
+                    : undefined,
+            };
+            gaps.push(gap);
+            risks.push({
+                code: error.code,
+                level: blocking ? "blocking" : "elevated",
+                message: error.message,
+            });
+        }
+        if (error.code === "SOURCE_FIDELITY_CONTEXT_ONLY_UNREVIEWED" &&
+            blocking) {
+            // 低风险 context-only 仅独立 reviewer pass 放行；未通过则 frontend 任务阻断。
+            const gap = {
+                code: "SOURCE_FIDELITY_CONTEXT_ONLY_UNREVIEWED",
+                level: "blocking",
+                message: error.message,
+                selfHealing: {
+                    action: "reimport-prd",
+                    steps: [
+                        "检查 context-only 片段是否缺少完整排除理由，或由人工在 sourceResolutions 中确认",
+                        "重新 importPrd（同 taskId）后 task advance 重建 ledger 并复核 reviewer 判定",
+                    ],
+                },
+            };
+            gaps.push(gap);
+        }
+    }
+    // 低风险 context-only：记录并提示排除理由/独立 reviewer 要求（不阻断普通任务）。
+    if (summary.contextOnlyCount > 0) {
+        gaps.push({
+            code: "SOURCE_FIDELITY_CONTEXT_ONLY_UNREVIEWED",
+            level: "warning",
+            message: `ledger 有 ${summary.contextOnlyCount} 个 context-only fragment（低风险排除；frontend 任务需完整理由且独立 reviewer pass）`,
+            details: {
+                fragmentIds: summary.exclusions
+                    .filter((e) => e.fragmentId.startsWith("REQ-SRC-"))
+                    .slice(0, 10)
+                    .map((e) => e.fragmentId),
+            },
+        });
+    }
+    if (summary.duplicateCount > 0) {
+        gaps.push({
+            code: "SOURCE_FIDELITY_DUPLICATE_PRESERVED",
+            level: "warning",
+            message: `ledger 保留 ${summary.duplicateCount} 个 duplicate fragment（duplicate 保留全部来源）`,
+        });
+    }
+}