@tea-agent/loop-agent 0.42.0-next.1 → 0.42.0-next.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,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

@@ -16,17 +16,15 @@ const NON_GOAL_HEADING_RE = /(?:^|\s)(?:非目标|out of scope|non-goals|non goa
 const OBJECTIVE_HEADING_RE = /(?:^|\s)(?:目标|objective|问题与目标|业务目标|需求概述)(?:\s|$)/iu;
 /** 可执行片段启发式（AC 风格/祈使语气）：命中则不可按 context-only 降级。 */
 const EXECUTABLE_HINT_RE = /(?:必须|应当|应支持|需要|需|不得|should|must|shall|will|require|support|implement|provide|ensure|verify|当.*?时|when.*?then)/iu;
-/** 显式 AC 式 ID 前缀：AC-001 / AC-FE-001 / AC-FE-INS-001 等（允许 bullet 标记后空格
- * 与 checklist 勾选框）。收紧解析（AC-001 / AC-HARD-001）：AC 后必须跟分隔符
- * （-/_）+ 大写字母/数字 id 形态（含可选 FE/BE/UI/API 作用域前缀与 V4 `#### AC-*`
- * 标题归属）；`## Acceptance Criteria` / `## Acceptance` / Ac 开头普通单词永不产生
- * 伪造 id（ACCEPTANCE 类 id 全量消失）。捕获组 1 = AC id，捕获组 2 = 余下文本。 */
-const EXPLICIT_AC_ID_RE = /^\s*(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s+)?(AC(?:[-_](?:FE|BE|UI|API))?[-_][A-Z0-9]+(?:[-_][A-Z0-9]+)*)\s*[:：]?\s*(.*)$/iu;
-/** 显式 AC 标题式：`#### AC-FE-001 Save nickname` / `### AC-001：正文`。
- * AC 后必须跟分隔符（-/_）+ id 形态；普通单词（Acceptance Criteria / Acceptance）
- * 永不匹配，按 ACCEPTANCE_HEADING_RE 章节分类生成稳定 REQ-SRC-* 片段。
- * 捕获组 1 = AC id，捕获组 2 = 标题余下文本。 */
-const EXPLICIT_AC_HEADING_RE = /^\s*(AC(?:[-_](?:FE|BE|UI|API))?[-_][A-Z0-9]+(?:[-_][A-Z0-9]+)*)\s*[:：]?\s*(.*)$/iu;
+/** 显式 requirement ID：AC-001 / BR-001 / REQ-SRC-001 等（允许 bullet 标记后空格
+ * 与 checklist 勾选框）。AC/BR/REQ 都是 DAG 的合法 canonical requirement 身份；
+ * 之前这里只识别 AC，导致已进入 canonicalRequirements 的 BR 片段无法绑定来源。
+ * 捕获组 1 = requirement id，捕获组 2 = 余下文本。 */
+const EXPLICIT_REQUIREMENT_ID_RE = /^\s*(?:(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s+)?)?((?:REQ|BR|AC)(?:[-_][A-Z0-9]+)+)\s*[:：]?\s*(.*)$/iu;
+/** 显式 requirement 标题式：`#### AC-FE-001 Save nickname` / `### BR-001：正文`。
+ * 普通单词（Acceptance Criteria / Acceptance）永不匹配，按章节分类生成稳定
+ * REQ-SRC-* 片段。捕获组 1 = requirement id，捕获组 2 = 标题余下文本。 */
+const EXPLICIT_REQUIREMENT_HEADING_RE = /^\s*((?:REQ|BR|AC)(?:[-_][A-Z0-9]+)+)\s*[:：]?\s*(.*)$/iu;
 /** Markdown 表格数据行（非分隔行）。 */
 const TABLE_DATA_ROW_RE = /^\s*\|.*\|\s*$/;
 const TABLE_SEPARATOR_ROW_RE = /^\s*\|[\s:|-]+\|\s*$/;
@@ -35,11 +33,11 @@ function isTableHeaderRow(line, nextLine) {
     return isTableDataRow(line) && TABLE_SEPARATOR_ROW_RE.test(nextLine.trim());
 }
 /** 表格行首格显式 AC ID：`| AC-001 | 订单列表加载完成 |` → id=AC-001, rest=订单列表加载完成。 */
-function matchTableRowAcId(line) {
+function matchTableRowRequirementId(line) {
     const trimmed = line.trim().replace(/^\|/, "");
     const cells = trimmed.split("|");
     const first = cells[0]?.trim() ?? "";
-    const idMatch = EXPLICIT_AC_HEADING_RE.exec(first);
+    const idMatch = EXPLICIT_REQUIREMENT_HEADING_RE.exec(first);
     if (!idMatch)
         return null;
     const id = (idMatch[1] ?? "").trim().toUpperCase().replace(/_/g, "-");
@@ -52,6 +50,14 @@ function matchTableRowAcId(line) {
         .trim();
     return { id, rest: rest || id };
 }
+/** The splitter may use only AC ids as fragment identities; BR/REQ ids are
+ * mapped later while keeping the generated REQ-SRC fragment identity. */
+function matchTableRowAcId(line) {
+    const match = matchTableRowRequirementId(line);
+    if (!match || !/^AC(?:-[A-Z0-9]+)+$/iu.test(match.id))
+        return null;
+    return match;
+}
 export function sha256Text(text) {
     return createHash("sha256").update(text, "utf8").digest("hex");
 }
@@ -66,7 +72,20 @@ export function normalizeFragmentText(text) {
         .trim();
 }
 export function matchExplicitAcId(line) {
-    const match = EXPLICIT_AC_ID_RE.exec(line.trim());
+    const match = EXPLICIT_REQUIREMENT_ID_RE.exec(line.trim());
+    if (!match)
+        return null;
+    const rawId = match[1] ?? "";
+    if (!/^AC(?:[-_][A-Z0-9]+)+$/iu.test(rawId))
+        return null;
+    const id = rawId.trim().toUpperCase().replace(/_/g, "-");
+    if (!id)
+        return null;
+    return { id, rest: (match[2] ?? "").trim() };
+}
+/** Match an explicit AC/BR/REQ id in a list item or a paragraph fragment. */
+export function matchExplicitRequirementId(line) {
+    const match = EXPLICIT_REQUIREMENT_ID_RE.exec(line.trim());
     if (!match)
         return null;
     const rawId = match[1] ?? "";
@@ -77,7 +96,20 @@ export function matchExplicitAcId(line) {
 }
 /** V4 显式 AC 标题式匹配：`#### AC-FE-001 Save nickname` → id=AC-FE-001, rest=Save nickname。 */
 export function matchExplicitAcHeading(headingText) {
-    const match = EXPLICIT_AC_HEADING_RE.exec(headingText.trim());
+    const match = EXPLICIT_REQUIREMENT_HEADING_RE.exec(headingText.trim());
+    if (!match)
+        return null;
+    const rawId = match[1] ?? "";
+    if (!/^AC(?:[-_][A-Z0-9]+)+$/iu.test(rawId))
+        return null;
+    const id = rawId.trim().toUpperCase().replace(/_/g, "-");
+    if (!id)
+        return null;
+    return { id, rest: (match[2] ?? "").trim() };
+}
+/** Match an explicit AC/BR/REQ id in a heading. */
+export function matchExplicitRequirementHeading(headingText) {
+    const match = EXPLICIT_REQUIREMENT_HEADING_RE.exec(headingText.trim());
     if (!match)
         return null;
     const rawId = match[1] ?? "";
@@ -175,8 +207,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));
@@ -386,7 +421,8 @@ export function buildFragmentInventory(input) {
             : null;
         const explicit = explicitIdFromId
             ? { id: explicitIdFromId, rest: fragment.text }
-            : matchExplicitAcId(fragment.text);
+            : matchExplicitRequirementId(fragment.text) ??
+                matchTableRowRequirementId(fragment.text);
         // V4 标题/条目下正文继承的显式 AC ID（不生成取代它的 REQ-SRC-*）。
         const inherited = !explicit && fragment.explicitAcId
             ? { id: fragment.explicitAcId, rest: fragment.text }
@@ -438,14 +474,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) {