@tea-agent/loop-agent 0.41.0-next.3 → 0.41.1-beta.0

package/dist/executors/shell-write-guard.js

@@ -124,6 +124,13 @@ export function isEphemeralToolCachePath(filePath) {
     if (normalized === ".coverage" || normalized.startsWith(".coverage.")) {
         return true;
     }
+    // vite/vitest runtime caches live under node_modules/.vite (e.g.
+    // node_modules/.vite/vitest/results.json). node_modules is the gitignored
+    // dependency tree — tool cache writes there are never a writer's product
+    // change and must not trip the write guard.
+    if (normalized.startsWith("node_modules/.vite/")) {
+        return true;
+    }
     if (/(?:^|\/)__pycache__(?:\/|$)/.test(normalized))
         return true;
     if (/\.(?:pyc|pyo)$/.test(normalized))

package/dist/shared/dag-failure-category.js

@@ -47,10 +47,22 @@ const RAW_TO_NORMALIZED = {
     "verify-failure": "validation",
     "test-failure": "validation",
     "verification-plan-stale": "validation",
+    "read-burst": "validation",
+    // Writer persisted real file changes but the final provider call hit a
+    // context overflow; verification never ran. Distinct from empty-output so
+    // the report shows partial success instead of a spec issue.
+    "partial-success-with-context-overflow": "validation",
+    // Writer burned an excessive token budget (unconverged read-edit-test loop)
+    // and still failed; distinct from empty-output for accurate reporting.
+    "writer-budget-exhausted": "validation",
     network: "executor",
     quota: "executor",
     "rate-limit": "executor",
     unavailable: "executor",
+    // Context window overflow (400 request-too-large): the session needs
+    // compaction / fresh context before retrying — an executor-side
+    // environment condition, not a plan-quality defect.
+    "context-overflow": "executor",
     // Deterministic capability/policy refusal: missing verified launcher JS
     // entry, capability allowlist rejection, or missing bounded write tool
     // profile. These are environment/config defects the operator repairs

package/dist/shared/openspec-spec.js

@@ -12,6 +12,19 @@ export const OPENSPEC_SPEC_DIRS = [
     "openspec/project-specs",
     "ai_workspace",
 ];
+/** Default roots used when a frontend task does not declare specRoots. */
+export const DEFAULT_FRONTEND_SPEC_ROOTS = OPENSPEC_SPEC_DIRS;
+/** A task-owned spec root must be a normalized, repo-relative POSIX directory. */
+export function isValidFrontendSpecRoot(value) {
+    return (Boolean(value) &&
+        !value.includes("\\") &&
+        !value.startsWith("/") &&
+        !value.includes("//") &&
+        !value.split("/").some((segment) => !segment ||
+            segment === "." ||
+            segment === ".." ||
+            /\s/.test(segment)));
+}
 /** Allowed spec file extensions (case-insensitive). */
 export const OPENSPEC_SPEC_EXT_RE = /\.(md|mdx|json|yaml|yml)$/i;
 /**
@@ -43,14 +56,17 @@ export function isGovernanceSubtreePath(filePath, governanceRoot) {
  * directories.  `filePath` must be a repo-relative POSIX path (backslashes are
  * normalised internally).  Directory names are case-sensitive.
  */
-export function isOpenspecSpecPath(filePath) {
+export function isFrontendSpecPath(filePath, specRoots = DEFAULT_FRONTEND_SPEC_ROOTS) {
     const normalized = filePath.replaceAll("\\", "/");
-    for (const dir of OPENSPEC_SPEC_DIRS) {
+    for (const dir of specRoots) {
         if (normalized === dir || normalized.startsWith(dir + "/"))
             return true;
     }
     return false;
 }
+export function isOpenspecSpecPath(filePath) {
+    return isFrontendSpecPath(filePath);
+}
 /**
  * Returns `true` when `filename` (the basename only, not a full path) has an
  * allowed frontend specification extension.
@@ -59,10 +75,13 @@ export function isValidOpenspecExtension(filename) {
     return OPENSPEC_SPEC_EXT_RE.test(filename);
 }
 /** Returns `true` for a supported file inside a canonical openspec spec dir. */
-export function isOpenspecSpecFilePath(filePath) {
-    return (isOpenspecSpecPath(filePath) &&
+export function isFrontendSpecFilePath(filePath, specRoots = DEFAULT_FRONTEND_SPEC_ROOTS) {
+    return (isFrontendSpecPath(filePath, specRoots) &&
         isValidOpenspecExtension(filePath.replaceAll("\\", "/")));
 }
+export function isOpenspecSpecFilePath(filePath) {
+    return isFrontendSpecFilePath(filePath);
+}
 /**
  * Returns `true` when free-form search input references a canonical frontend
  * specification directory with exact lowercase directory names.
@@ -123,3 +142,50 @@ export function extractTaskSourceOpenspecPaths(markdown, governanceRoot = DEFAUL
         !isGovernanceSubtreePath(token, governanceRoot))
         .sort();
 }
+/**
+ * Extract explicit specification-file citations for a task's frozen spec roots.
+ * This is intentionally path-only: source preparation decides which roots are
+ * normative, while DAG execution only consumes that frozen configuration.
+ */
+export function extractTaskSourceFrontendSpecPaths(markdown, specRoots, governanceRoot = DEFAULT_OPENSPEC_GOVERNANCE_ROOT) {
+    if (!markdown)
+        return [];
+    const raw = new Set();
+    const collect = (token) => {
+        const normalized = normalizeCitationToken(token);
+        if (normalized)
+            raw.add(normalized);
+    };
+    for (const match of markdown.matchAll(/`([^`\n]+)`/g))
+        collect(match[1] ?? "");
+    for (const match of markdown.matchAll(/\[[^\]]*\]\(([^)\s]+)\)/g))
+        collect(match[1] ?? "");
+    for (const root of specRoots) {
+        const escaped = root.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        for (const match of markdown.matchAll(new RegExp(`(?:^|[\\s\"'([>])(${escaped}/[A-Za-z0-9._/-]+)`, "g"))) {
+            collect(match[1] ?? "");
+        }
+    }
+    return [...raw]
+        .filter((token) => isFrontendSpecFilePath(token, specRoots) && !isGovernanceSubtreePath(token, governanceRoot))
+        .sort();
+}
+/**
+ * Source-preparation helper for explicitly named normative directories. A root
+ * is inferred only on a line that declares a spec/规范/design-system intent;
+ * arbitrary Markdown links never silently broaden task configuration.
+ */
+export function extractDeclaredFrontendSpecRoots(markdown) {
+    const roots = new Set();
+    for (const line of markdown.split(/\r?\n/)) {
+        if (!/(?:规范|规约|标准|设计系统|\bspec(?:ification)?\b|\bdesign[ -]?system\b|\bguidelines?\b|\brules?\b)/i.test(line))
+            continue;
+        for (const match of line.matchAll(/`([^`]+)`|\[[^\]]+\]\(([^)\s]+)\)/g)) {
+            const raw = (match[1] ?? match[2] ?? "").replaceAll("\\", "/").replace(/\/+$/, "");
+            if (!raw || !isValidFrontendSpecRoot(raw))
+                continue;
+            roots.add(isValidOpenspecExtension(raw) ? raw.split("/").slice(0, -1).join("/") : raw);
+        }
+    }
+    return [...roots].filter(isValidFrontendSpecRoot).sort();
+}

package/dist/shared/operator/capabilities.js

@@ -2240,6 +2240,13 @@ export const OPERATOR_COMMAND_COVERAGE = Object.freeze([
         source: "loop-agent",
         note: "server-side read-only run-facts check (ineligible plan / explicit rerun-task recommendation) replaces the browser Human Gate (2026-08-11).",
     },
+    {
+        command: "loop-agent dag follow-up",
+        coverage: "excluded",
+        action: null,
+        source: "loop-agent",
+        exclusionReason: "Frontend review recovery helper is a direct advanced CLI composition (create/import task and optional advance), not an Operator action endpoint.",
+    },
     {
         command: "loop-agent dag reconcile-tasks",
         coverage: "human-gated-required",

package/dist/task/config-types.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { isOpenspecSpecFilePath } from "../shared/openspec-spec.js";
+import { DEFAULT_FRONTEND_SPEC_ROOTS, isFrontendSpecFilePath, isValidFrontendSpecRoot, } from "../shared/openspec-spec.js";
 export const taskFlowSchema = z.enum([
     "auto",
     "micro",
@@ -76,13 +76,27 @@ export const frontendOpenspecPolicySchema = z.enum(["cited", "scan-strict"]);
  */
 export const frontendOpenspecConfigSchema = z.object({
     policy: frontendOpenspecPolicySchema.optional().default("cited"),
+    /**
+     * Repo-relative directories containing frontend normative files. These are
+     * frozen in task.json during contract preparation, before DAG generation.
+     */
+    specRoots: z
+        .array(z.string().refine((candidate) => isValidFrontendSpecRoot(candidate), "frontendOpenspec.specRoots entries must be normalized repo-relative directories"))
+        .optional(),
     requiredReadPaths: z
-        .array(z
-        .string()
-        .refine((candidate) => !candidate.includes("\\") &&
-        isOpenspecSpecFilePath(candidate), "frontendOpenspec.requiredReadPaths entries must be repo-relative supported files under openspec/schemas/, openspec/project-specs/, or ai_workspace/"))
+        .array(z.string())
         .optional()
         .default([]),
+}).superRefine((value, ctx) => {
+    const roots = value.specRoots ?? DEFAULT_FRONTEND_SPEC_ROOTS;
+    if (new Set(roots).size !== roots.length) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "frontendOpenspec.specRoots must not contain duplicates", path: ["specRoots"] });
+    }
+    for (const required of value.requiredReadPaths) {
+        if (!isFrontendSpecFilePath(required, roots)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: "frontendOpenspec.requiredReadPaths entries must be repo-relative supported files under frontendOpenspec.specRoots", path: ["requiredReadPaths"] });
+        }
+    }
 });
 /** Batch limits and gate profile for the browser-driven frontend test DAG.
  * Token fields are post-case stop thresholds, not model-provider hard caps. */
@@ -149,8 +163,6 @@ export const backendTestConfigSchema = z
     executeScope: z.enum(["affected", "all"]).optional(),
     /** Backend-test-only workspace mutation control; omitted means Git guard. */
     workspaceControl: z.enum(["git", "filesystem-only"]).optional(),
-    /** Per-command timeout for the readiness-authorized pytest/HTML execution node. */
-    executeTimeoutMs: z.number().int().min(60_000).max(7_200_000).optional(),
 })
     .strict()
     .optional();
@@ -209,6 +221,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/adopt.js

@@ -90,6 +90,10 @@ export async function adoptTaskContract(input) {
             requirementBytes: bytes.requirementBytes,
             constraintsBytes: bytes.constraintsBytes,
             referenceManifestBytes: bytes.referenceManifestBytes,
+            ...(state.ref?.sourceHashes.requirementLedgerSha256 &&
+                bytes.requirementLedgerBytes !== null
+                ? { requirementLedgerBytes: bytes.requirementLedgerBytes }
+                : {}),
         });
         const taskConfigSha256 = computeTaskConfigSha256(fullConfig);
         const canonicalHash = computeCanonicalHash({

package/dist/task/contract/import-revision.js

@@ -45,6 +45,10 @@ export async function refreshManagedContractAfterImport(input) {
             requirementBytes: bytes.requirementBytes,
             constraintsBytes: bytes.constraintsBytes,
             referenceManifestBytes: bytes.referenceManifestBytes,
+            ...(state2.ref.sourceHashes.requirementLedgerSha256 &&
+                bytes.requirementLedgerBytes !== null
+                ? { requirementLedgerBytes: bytes.requirementLedgerBytes }
+                : {}),
         });
         const taskConfigSha256 = computeTaskConfigSha256(fullConfig);
         const canonicalHash = computeCanonicalHash({

package/dist/task/contract/project.js

@@ -184,6 +184,9 @@ export function mergeManagedTaskConfigFields(existing, draft) {
             command: cmd.command,
             ...(cmd.timeoutMs !== undefined ? { timeoutMs: cmd.timeoutMs } : {}),
         })),
+        ...(draft.frontendOpenspec !== undefined
+            ? { frontendOpenspec: draft.frontendOpenspec }
+            : {}),
     };
     if (draft.featureId !== undefined) {
         next.featureId = draft.featureId;

package/dist/task/contract/schema.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { backendTestConfigSchema, taskKindSchema, taskVerifyCommandSchema, } from "../config-types.js";
+import { backendTestConfigSchema, frontendOpenspecConfigSchema, taskKindSchema, taskVerifyCommandSchema, } from "../config-types.js";
 import { TASK_CONFIG_SCHEMA_VERSION, TASK_CONTRACT_CANONICALIZER_VERSION, TASK_CONTRACT_DRAFT_SCHEMA_VERSION, TASK_CONTRACT_PROJECTION_VERSION, TASK_CONTRACT_REF_SCHEMA_VERSION, } from "./constants.js";
 const sha256Schema = z
     .string()
@@ -74,6 +74,7 @@ export const taskContractDraftSchema = z
     openQuestions: z.array(z.string()).optional(),
     assumptions: z.array(z.string()).optional(),
     hardConstraints: z.array(z.string()).optional(),
+    frontendOpenspec: frontendOpenspecConfigSchema.optional(),
     interviewAssessmentRef: z
         .object({
         draftSha256: z.string().min(1),

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) ??