@tea-agent/loop-agent 0.16.4 → 0.16.6-beta.0

package/CHANGELOG.md

@@ -9,12 +9,21 @@
 
 ### 修复
 
+- 前端实现计划/修订节点会注入当前包内权威 `frontend-implementation-contract-v1` Schema 与固定 source binding，避免模型猜测字段导致契约门禁失败。
+- 前端 Mock 策略节点的 canonical 输出会把首条 `MOCK_STRATEGY:` 协议行提升为第一行，避免解释性前言触发 `first-non-empty` 门禁误判。
+- 前端规范回退目录统一为本地 `openspec/`，DAG 能力发现、提示词、Skill 与验证证据检查不再查找大小写不一致的旧目录名。
 - 后端测试复合 Shell pipeline 现在与普通 Shell 节点共享 Git write guard；即使命令退出成功，只要越过 `read-only`、`allowedPaths` 或 `forbiddenPaths` 边界，节点仍会 fail-closed。
 - Observe 现使用实际的 repair safety 节点，并只在修复节点真正开始执行后计入一次 attempt；条件跳过不再误报已修复，安全门禁失败会显示为 `rejected`。
 - Pi SDK 对缺少响应 ID 的累计 Token 生命周期事件改为取本次执行最大快照，避免同一响应的匿名 usage 被重复累加。
 - Pi SDK 执行长推理或大段结构化输出时不再把高频流式增量事件无界累积到内存；同一响应在多个生命周期事件中重复出现的 Token 用量只统计一次，避免 `Invalid string length` 和成本数据虚高。
 - 后端测试复合执行节点继续保持 clean environment、失败分类和 fail-closed outcome，并为 initial/final Result、repair eligibility、traceability 与 Observe 投影保留结构化运行证据。
 
+## [0.16.5] - 2026-07-20
+
+### 修复
+
+- 后端测试分析/执行合同物化支持 free-form 环境侦察与 GWT/嵌套 endpoint 形状的严格 schema 归一化，避免 BE-TEST 在 contracts 门被模型字段漂移误拦。
+
 ## [0.16.4] - 2026-07-19
 
 ### 修复

package/dist/executors/dag-pi-executor.js

@@ -272,7 +272,7 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep) {
         persona,
         step,
     });
-    const mapped = mapPiResultToDagNodeResult(result);
+    const mapped = mapPiResultToDagNodeResult(result, input.task.firstProtocolLine);
     if (!isWriteTask) {
         return mapped;
     }
@@ -315,17 +315,57 @@ export async function executeDagPiNode(input, meta, piStepFn = executePiStep) {
         durationMs: mapped.durationMs || Date.now() - started,
     };
 }
-export function mapPiResultToDagNodeResult(result) {
+export function mapPiResultToDagNodeResult(result, firstProtocolLine) {
+    const assistantText = canonicalizeProtocolFirstLine(result.assistantText, firstProtocolLine);
     return {
         ok: result.ok,
-        stdout: result.assistantText || result.stdout,
+        stdout: assistantText || result.stdout,
         stderr: result.stderr,
         failureCategory: result.failureCategory,
         durationMs: result.durationMs,
-        assistantText: result.assistantText,
+        assistantText,
         backend: result.backend,
         sdkAttempted: result.sdkAttempted,
         tokensUsed: result.tokensUsed,
         parsedEvents: result.parsedEvents,
     };
 }
+function canonicalizeProtocolFirstLine(assistantText, firstProtocolLine) {
+    if (!assistantText || !firstProtocolLine)
+        return assistantText;
+    const lines = assistantText.split(/\r?\n/);
+    let protocolIndex = -1;
+    let protocolLine = "";
+    for (const [index, line] of lines.entries()) {
+        const normalized = normalizeProtocolLine(line);
+        if (normalized.startsWith(firstProtocolLine)) {
+            protocolIndex = index;
+            protocolLine = normalized;
+            break;
+        }
+    }
+    if (protocolIndex < 0)
+        return assistantText;
+    if (protocolIndex === 0) {
+        return [protocolLine, ...lines.slice(1)].join("\n");
+    }
+    const before = lines.slice(0, protocolIndex);
+    const after = lines.slice(protocolIndex + 1);
+    while (before.at(-1)?.trim() === "" &&
+        after.at(0)?.trim() === "") {
+        after.shift();
+    }
+    const bodyLines = [...before, ...after];
+    while (bodyLines.at(0)?.trim() === "")
+        bodyLines.shift();
+    while (bodyLines.at(-1)?.trim() === "")
+        bodyLines.pop();
+    return bodyLines.length > 0
+        ? `${protocolLine}\n\n${bodyLines.join("\n")}`
+        : protocolLine;
+}
+function normalizeProtocolLine(line) {
+    const trimmed = line.trim();
+    const emphasized = trimmed.match(/^(\*{1,3})\s*(.*?)\s*\1$/);
+    return (emphasized?.[2] ?? trimmed).trim();
+}

package/dist/executors/pi-sdk-executor.js

@@ -308,9 +308,7 @@ export async function executeSingleSdkAttempt(options) {
                 return;
             const line = serializeSessionEvent(event);
             stdoutLines.push(line);
-            if (sessionEventAppender) {
-                sessionEventAppender.append(line, event);
-            }
+            sessionEventAppender?.append(line, event);
         });
         const filePrefix = options.attachedFiles.map((file) => `@${file}`).join(' ');
         const promptMessage = filePrefix

package/dist/worker/observe/spec-evidence.js

@@ -18,7 +18,7 @@ const KB_CONNECTOR_TOOLS = new Set([
 ]);
 /**
  * Pattern for detecting spec-related files:
- * - openSpec/** files
+ * - openspec/** files
  * - *.spec.md / *.spec.ts / *.spec.tsx
  * - project-specs/**
  * - design-spec.md, code-standards.md, review-checklist.md, etc.
@@ -27,7 +27,6 @@ const KB_CONNECTOR_TOOLS = new Set([
  */
 const SPEC_FILE_PATTERNS = [
     /openspec\//i,
-    /\/openSpec\//i,
     /\/project-specs\//i,
     /\/spec\//i,
     /\.spec\.(md|tsx?|jsx?)$/i,

package/dist/workflows/dag/backend-test-analysis-contract.js

@@ -108,25 +108,317 @@ export function extractStrictJsonObject(text) {
     }
     return JSON.parse(blocks[0][1]);
 }
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function firstSourceRef(value, fallback = "source/需求.md") {
+    const record = asRecord(value);
+    if (!record)
+        return fallback;
+    if (typeof record.sourceRef === "string" && record.sourceRef.trim())
+        return record.sourceRef.trim();
+    const refs = asArray(record.sourceRefs).filter((item) => typeof item === "string" && item.trim().length > 0);
+    return refs[0]?.trim() || fallback;
+}
+function coerceField(value) {
+    const record = asRecord(value);
+    if (!record || typeof record.name !== "string" || !record.name.trim())
+        return null;
+    const sourceRefs = asArray(record.sourceRefs).filter((item) => typeof item === "string" && item.trim().length > 0);
+    const field = {
+        name: record.name.trim(),
+        sourceRefs,
+    };
+    if (typeof record.type === "string" && record.type.trim())
+        field.type = record.type.trim();
+    if (typeof record.required === "boolean")
+        field.required = record.required;
+    if (typeof record.description === "string")
+        field.description = record.description;
+    else if (typeof record.notes === "string")
+        field.description = record.notes;
+    if (typeof record.format === "string" && record.format.trim())
+        field.format = record.format.trim();
+    if (record.comparison === "exact" || record.comparison === "parseable-only" || record.comparison === "semantic") {
+        field.comparison = record.comparison;
+    }
+    if (typeof record.precision === "string" && record.precision.trim())
+        field.precision = record.precision.trim();
+    return field;
+}
+function coerceAcceptanceCriterion(value) {
+    const record = asRecord(value);
+    if (!record || typeof record.id !== "string" || !record.id.trim())
+        return null;
+    const textParts = [];
+    if (typeof record.text === "string" && record.text.trim())
+        textParts.push(record.text.trim());
+    else {
+        if (typeof record.title === "string" && record.title.trim())
+            textParts.push(record.title.trim());
+        const gwt = ["given", "when", "then"]
+            .map((key) => (typeof record[key] === "string" && record[key].trim() ? `${key}: ${String(record[key]).trim()}` : ""))
+            .filter(Boolean);
+        if (gwt.length)
+            textParts.push(gwt.join("; "));
+        else if (typeof record.description === "string" && record.description.trim())
+            textParts.push(record.description.trim());
+    }
+    const text = textParts.join(" — ").trim();
+    if (!text)
+        return null;
+    return { id: record.id.trim(), text, sourceRef: firstSourceRef(record) };
+}
+function coerceEndpoint(value) {
+    const record = asRecord(value);
+    if (!record || typeof record.id !== "string" || !record.id.trim())
+        return null;
+    if (typeof record.method !== "string" || typeof record.path !== "string")
+        return null;
+    const method = record.method.trim().toUpperCase();
+    const pathValue = record.path.trim();
+    if (!pathValue.startsWith("/"))
+        return null;
+    const request = asRecord(record.request);
+    const successResponse = asRecord(record.successResponse);
+    const nestedBody = asRecord(successResponse?.responseBody) ?? asRecord(record.responseBody);
+    const requestFields = [
+        ...asArray(record.requestFields),
+        ...asArray(request?.headers),
+        ...asArray(request?.query),
+        ...asArray(request?.pathParams),
+    ]
+        .map(coerceField)
+        .filter((item) => item !== null);
+    const responseFields = [
+        ...asArray(record.responseFields),
+        ...asArray(successResponse?.fields),
+    ]
+        .map(coerceField)
+        .filter((item) => item !== null);
+    const successStatuses = asArray(record.successStatuses)
+        .map((item) => (typeof item === "number" ? item : Number.NaN))
+        .filter((item) => Number.isInteger(item) && item >= 100 && item <= 399);
+    if (typeof successResponse?.status === "number" && successResponse.status >= 100 && successResponse.status <= 399) {
+        successStatuses.push(successResponse.status);
+    }
+    const uniqueSuccess = [...new Set(successStatuses)];
+    const errorCases = [
+        ...asArray(record.errorCases),
+        ...asArray(record.errorResponses),
+    ]
+        .map((item) => {
+        const err = asRecord(item);
+        if (!err)
+            return null;
+        const description = (typeof err.description === "string" && err.description.trim()) ||
+            (typeof err.message === "string" && err.message.trim()) ||
+            (typeof err.code === "string" && err.code.trim()) ||
+            (typeof err.status === "number" ? `HTTP ${err.status}` : "");
+        if (!description)
+            return null;
+        const out = { description };
+        if (typeof err.status === "number" && err.status >= 400 && err.status <= 599)
+            out.status = err.status;
+        if (typeof err.code === "string" && err.code.trim())
+            out.code = err.code.trim();
+        if (typeof err.messageField === "string" && err.messageField.trim())
+            out.messageField = err.messageField.trim();
+        return out;
+    })
+        .filter((item) => item !== null);
+    const kind = nestedBody && typeof nestedBody.kind === "string" && ["array", "object", "scalar", "empty", "unknown"].includes(nestedBody.kind)
+        ? nestedBody.kind
+        : "unknown";
+    const ordering = nestedBody && typeof nestedBody.ordering === "string" && ["specified", "unspecified", "not-applicable"].includes(nestedBody.ordering)
+        ? nestedBody.ordering
+        : "unspecified";
+    const responseBody = { kind, ordering };
+    if (nestedBody && typeof nestedBody.itemSchemaRef === "string" && nestedBody.itemSchemaRef.trim()) {
+        responseBody.itemSchemaRef = nestedBody.itemSchemaRef.trim();
+    }
+    if (nestedBody && typeof nestedBody.description === "string" && nestedBody.description.trim()) {
+        responseBody.description = nestedBody.description.trim();
+    }
+    else if (nestedBody && typeof nestedBody.schemaRef === "string" && nestedBody.schemaRef.trim()) {
+        responseBody.description = `schemaRef=${nestedBody.schemaRef.trim()}`;
+    }
+    const sourceRefs = [
+        ...asArray(record.sourceRefs),
+        ...asArray(successResponse?.sourceRefs),
+    ].filter((item) => typeof item === "string" && item.trim().length > 0);
+    return {
+        id: record.id.trim(),
+        method,
+        path: pathValue,
+        requestFields,
+        responseFields,
+        responseBody,
+        successStatuses: uniqueSuccess.length ? uniqueSuccess : [200],
+        errorCases,
+        sourceRefs,
+    };
+}
+function coerceEvidencedIdItem(value, textKey) {
+    const record = asRecord(value);
+    if (!record)
+        return null;
+    const id = (typeof record.id === "string" && record.id.trim()) ||
+        (typeof record.name === "string" && record.name.trim()) ||
+        "";
+    if (!id)
+        return null;
+    const text = (typeof record[textKey] === "string" && String(record[textKey]).trim()) ||
+        (typeof record.description === "string" && record.description.trim()) ||
+        (typeof record.text === "string" && record.text.trim()) ||
+        (typeof record.notes === "string" && record.notes.trim()) ||
+        (typeof record.title === "string" && record.title.trim()) ||
+        "";
+    if (!text)
+        return null;
+    return { id, [textKey]: text, sourceRef: firstSourceRef(record) };
+}
+function coerceBoundary(value) {
+    const record = asRecord(value);
+    if (!record)
+        return null;
+    const field = (typeof record.field === "string" && record.field.trim()) ||
+        (typeof record.id === "string" && record.id.trim()) ||
+        (typeof record.name === "string" && record.name.trim()) ||
+        "";
+    const constraint = (typeof record.constraint === "string" && record.constraint.trim()) ||
+        (typeof record.description === "string" && record.description.trim()) ||
+        (typeof record.text === "string" && record.text.trim()) ||
+        "";
+    if (!field || !constraint)
+        return null;
+    return { field, constraint, sourceRef: firstSourceRef(record) };
+}
+const OPTIONAL_EVIDENCE_KNOWN_KEYS = new Set([
+    "name",
+    "id",
+    "description",
+    "notes",
+    "text",
+    "title",
+    "sourceRef",
+    "sourceRefs",
+    "severity",
+    "mitigation",
+    "level",
+    "impact",
+    "kind",
+    "required",
+]);
+function coerceOptionalEvidence(value) {
+    const record = asRecord(value);
+    if (!record)
+        return null;
+    // Fail closed on unknown keys so near-schema payloads cannot strip extras and pass.
+    for (const key of Object.keys(record)) {
+        if (!OPTIONAL_EVIDENCE_KNOWN_KEYS.has(key)) {
+            throw new Error(`optional evidence has unrecognized key: ${key}`);
+        }
+    }
+    const description = (typeof record.description === "string" && record.description.trim()) ||
+        (typeof record.notes === "string" && record.notes.trim()) ||
+        (typeof record.text === "string" && record.text.trim()) ||
+        (typeof record.title === "string" && record.title.trim()) ||
+        "";
+    if (!description)
+        return null;
+    const out = { description };
+    const name = (typeof record.name === "string" && record.name.trim()) ||
+        (typeof record.id === "string" && record.id.trim()) ||
+        "";
+    if (name)
+        out.name = name;
+    const sourceRef = firstSourceRef(record, "");
+    if (sourceRef)
+        out.sourceRef = sourceRef;
+    return out;
+}
+function coerceEvidenceGap(value) {
+    const record = asRecord(value);
+    if (!record)
+        return null;
+    const description = (typeof record.description === "string" && record.description.trim()) ||
+        (typeof record.text === "string" && record.text.trim()) ||
+        "";
+    if (!description)
+        return null;
+    const out = { description };
+    if (typeof record.requirementId === "string" && record.requirementId.trim())
+        out.requirementId = record.requirementId.trim();
+    else if (typeof record.acId === "string" && record.acId.trim())
+        out.requirementId = record.acId.trim();
+    const sourceRef = firstSourceRef(record, "");
+    if (sourceRef)
+        out.sourceRef = sourceRef;
+    return out;
+}
+/** Coerce common free-form model shapes into Backend Test Analysis v2 before strict parse. */
+export function coerceBackendTestAnalysisInput(value) {
+    const record = asRecord(value);
+    if (!record)
+        return value;
+    const next = { ...record, schemaVersion: 2 };
+    next.acceptanceCriteria = asArray(record.acceptanceCriteria)
+        .map(coerceAcceptanceCriterion)
+        .filter((item) => item !== null);
+    next.endpoints = asArray(record.endpoints)
+        .map(coerceEndpoint)
+        .filter((item) => item !== null);
+    next.dataModels = asArray(record.dataModels)
+        .map((item) => coerceEvidencedIdItem(item, "description"))
+        .filter((item) => item !== null);
+    next.businessRules = asArray(record.businessRules)
+        .map((item) => coerceEvidencedIdItem(item, "text"))
+        .filter((item) => item !== null);
+    next.stateTransitions = asArray(record.stateTransitions);
+    next.boundaryConstraints = asArray(record.boundaryConstraints)
+        .map(coerceBoundary)
+        .filter((item) => item !== null);
+    next.externalDependencies = asArray(record.externalDependencies)
+        .map(coerceOptionalEvidence)
+        .filter((item) => item !== null);
+    next.risks = asArray(record.risks)
+        .map(coerceOptionalEvidence)
+        .filter((item) => item !== null);
+    next.evidenceGaps = asArray(record.evidenceGaps)
+        .map(coerceEvidenceGap)
+        .filter((item) => item !== null);
+    return next;
+}
 function normalizeAnalysis(value) {
-    const v2 = backendTestAnalysisContractSchema.safeParse(value);
-    if (v2.success)
-        return v2.data;
-    const v1 = analysisV1Schema.safeParse(value);
-    if (!v1.success) {
-        throw new Error(v2.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; "));
+    const candidates = [value, coerceBackendTestAnalysisInput(value)];
+    let lastError = "invalid analysis contract";
+    for (const candidate of candidates) {
+        const v2 = backendTestAnalysisContractSchema.safeParse(candidate);
+        if (v2.success)
+            return v2.data;
+        lastError = v2.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ");
+        const v1 = analysisV1Schema.safeParse(candidate);
+        if (v1.success) {
+            return backendTestAnalysisContractSchema.parse({
+                ...v1.data,
+                schemaVersion: 2,
+                endpoints: v1.data.endpoints.map((endpoint) => ({
+                    ...endpoint,
+                    requestFields: endpoint.requestFields.map((field) => ({ ...field, sourceRefs: [] })),
+                    responseFields: endpoint.responseFields.map((field) => ({ ...field, sourceRefs: [] })),
+                    responseBody: { kind: "unknown", ordering: "unspecified" },
+                    sourceRefs: [],
+                })),
+            });
+        }
     }
-    return backendTestAnalysisContractSchema.parse({
-        ...v1.data,
-        schemaVersion: 2,
-        endpoints: v1.data.endpoints.map((endpoint) => ({
-            ...endpoint,
-            requestFields: endpoint.requestFields.map((field) => ({ ...field, sourceRefs: [] })),
-            responseFields: endpoint.responseFields.map((field) => ({ ...field, sourceRefs: [] })),
-            responseBody: { kind: "unknown", ordering: "unspecified" },
-            sourceRefs: [],
-        })),
-    });
+    throw new Error(lastError);
 }
 function assertSourceBinding(contract, binding) {
     const requirement = binding.sources.find((source) => source.kind === "requirement");

package/dist/workflows/dag/backend-test-execution-contract.js

@@ -324,6 +324,171 @@ export function assertBackendTestExecutionPreflight(input) {
         workingDirectory,
     };
 }
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+/**
+ * Coerce free-form environment scout JSON into Backend Test Execution Contract v1.
+ * Prefer exact schema payloads; otherwise map common discovery shapes onto the
+ * pytest-centric runtime contract without inventing secrets or managed commands.
+ */
+export function coerceBackendTestExecutionInput(value) {
+    const direct = backendTestExecutionContractSchema.safeParse(value);
+    if (direct.success)
+        return direct.data;
+    const record = asRecord(value);
+    if (!record)
+        return value;
+    // Near-schema payloads (string framework + runner + testRoot) must stay fail-closed.
+    // Only free-form discovery envelopes are rewritten onto the pytest contract.
+    const looksSchemaShaped = typeof record.framework === "string" &&
+        asRecord(record.runner) !== null &&
+        typeof record.testRoot === "string";
+    if (looksSchemaShaped)
+        return value;
+    if (typeof record.framework === "string" && record.framework !== "pytest") {
+        return value;
+    }
+    const frameworkObj = asRecord(record.framework);
+    const discovered = asRecord(record.discoveredFixtures);
+    const verification = asRecord(record.verification);
+    const layout = asRecord(record.repositoryLayout);
+    const environment = asRecord(record.environment);
+    const commandHints = [];
+    if (typeof record.primaryCommand === "string" && record.primaryCommand.trim()) {
+        commandHints.push(record.primaryCommand.trim());
+    }
+    if (frameworkObj && typeof frameworkObj.primaryCommand === "string" && frameworkObj.primaryCommand.trim()) {
+        commandHints.push(frameworkObj.primaryCommand.trim());
+    }
+    for (const item of Array.isArray(verification?.commands) ? verification.commands : []) {
+        if (typeof item === "string" && item.trim())
+            commandHints.push(item.trim());
+    }
+    if (commandHints.length === 0) {
+        commandHints.push(`python -m pytest ${BACKEND_TEST_EXECUTION_DEFAULT_TEST_ROOT}/ -v`);
+    }
+    const existingFixtures = [];
+    for (const item of Array.isArray(record.existingFixtures) ? record.existingFixtures : []) {
+        const fixture = asRecord(item);
+        if (!fixture)
+            continue;
+        if (typeof fixture.name === "string" && typeof fixture.sourcePath === "string" && typeof fixture.kind === "string") {
+            existingFixtures.push({
+                name: fixture.name,
+                sourcePath: fixture.sourcePath,
+                kind: fixture.kind,
+            });
+        }
+    }
+    if (existingFixtures.length === 0 && discovered) {
+        const bootstrap = asRecord(discovered.serverBootstrap);
+        if (bootstrap && typeof bootstrap.module === "string" && bootstrap.module.trim()) {
+            existingFixtures.push({
+                name: typeof bootstrap.symbol === "string" && bootstrap.symbol.trim()
+                    ? bootstrap.symbol.trim()
+                    : "server-bootstrap",
+                sourcePath: bootstrap.module.trim(),
+                kind: "server-bootstrap",
+            });
+        }
+        for (const key of ["auth", "database", "remoteServices"]) {
+            const val = discovered[key];
+            if (typeof val === "string" && val.trim() && val.trim() !== "none") {
+                existingFixtures.push({
+                    name: key,
+                    sourcePath: ".",
+                    kind: val.trim(),
+                });
+            }
+        }
+    }
+    if (existingFixtures.length === 0) {
+        // Fail-closed in-process contract still needs one fixture entry; use default test root as a non-secret anchor.
+        existingFixtures.push({
+            name: "pytest-test-root",
+            sourcePath: BACKEND_TEST_EXECUTION_DEFAULT_TEST_ROOT,
+            kind: "test-root",
+        });
+    }
+    const authenticationMode = (typeof record.authenticationMode === "string" && record.authenticationMode.trim()) ||
+        (typeof discovered?.auth === "string" && discovered.auth.trim()) ||
+        "none";
+    const evidenceRefs = [];
+    for (const item of Array.isArray(record.evidenceRefs) ? record.evidenceRefs : []) {
+        if (typeof item === "string" && item.trim())
+            evidenceRefs.push(item.trim());
+    }
+    if (layout) {
+        for (const key of [
+            "apiContractDoc",
+            "routeImplementation",
+            "serviceImplementation",
+            "serverEntry",
+        ]) {
+            const val = layout[key];
+            if (typeof val === "string" && val.trim())
+                evidenceRefs.push(val.trim());
+        }
+        for (const item of Array.isArray(layout.existingApiTests) ? layout.existingApiTests : []) {
+            if (typeof item === "string" && item.trim())
+                evidenceRefs.push(item.trim());
+        }
+    }
+    const targetMode = record.targetMode === "external-running-service" ||
+        record.targetMode === "managed-command" ||
+        record.targetMode === "in-process"
+        ? record.targetMode
+        : "in-process";
+    const coerced = {
+        schemaVersion: 1,
+        framework: "pytest",
+        runner: {
+            frozenCommandHints: [...new Set(commandHints)],
+        },
+        testRoot: (typeof record.testRoot === "string" && record.testRoot.trim()) ||
+            BACKEND_TEST_EXECUTION_DEFAULT_TEST_ROOT,
+        workingDirectory: (typeof record.workingDirectory === "string" && record.workingDirectory.trim()) ||
+            ".",
+        report: asRecord(record.report) ?? {
+            format: "junit",
+            relativeHint: "reports/backend-test-junit.xml",
+        },
+        targetMode,
+        existingFixtures,
+        authenticationMode,
+        requiredEnvNames: Array.isArray(record.requiredEnvNames)
+            ? record.requiredEnvNames.filter((item) => typeof item === "string" && item.trim().length > 0)
+            : [],
+        dataIsolation: asRecord(record.dataIsolation) ?? {
+            mode: "ephemeral-local",
+            evidence: "coerced from free-form environment scout; no durable shared fixtures",
+        },
+        evidenceGaps: Array.isArray(record.evidenceGaps) ? record.evidenceGaps : [],
+        evidenceRefs: [...new Set(evidenceRefs)],
+    };
+    if (typeof record.baseUrlEnvName === "string" && record.baseUrlEnvName.trim()) {
+        coerced.baseUrlEnvName = record.baseUrlEnvName.trim();
+    }
+    if (Array.isArray(record.readiness))
+        coerced.readiness = record.readiness;
+    if (asRecord(record.managedCommand))
+        coerced.managedCommand = record.managedCommand;
+    // Preserve free-form discovery notes as non-blocking evidence gaps when useful.
+    if (frameworkObj &&
+        typeof frameworkObj.testRunner === "string" &&
+        frameworkObj.testRunner !== "pytest") {
+        const gaps = Array.isArray(coerced.evidenceGaps) ? [...coerced.evidenceGaps] : [];
+        gaps.push({
+            description: `environment scout reported testRunner=${frameworkObj.testRunner}; runtime contract remains pytest with default testRoot=${BACKEND_TEST_EXECUTION_DEFAULT_TEST_ROOT}`,
+            sourceRef: typeof environment?.cwd === "string" ? "package.json" : "source/需求.md",
+        });
+        coerced.evidenceGaps = gaps;
+    }
+    return coerced;
+}
 export async function materializeBackendTestExecutionContract(input) {
     if (!/^[a-z0-9][a-z0-9._-]*\.json$/.test(input.artifactName) ||
         !/^[a-z0-9][a-z0-9._-]*$/.test(input.outputDir)) {
@@ -339,17 +504,29 @@ export async function materializeBackendTestExecutionContract(input) {
     catch (error) {
         throw new Error(`invalid-output: ${error instanceof Error ? error.message : String(error)}`);
     }
-    const secrets = secretIssues(parsed);
-    if (secrets.length) {
-        throw new Error(`invalid-output: ${secrets.join("; ")}`);
-    }
-    const result = backendTestExecutionContractSchema.safeParse(parsed);
-    if (!result.success) {
-        throw new Error(`invalid-output: ${result.error.issues
+    const candidates = [parsed, coerceBackendTestExecutionInput(parsed)];
+    let accepted = null;
+    let lastSchemaError = "invalid execution contract";
+    let lastSecretError = "";
+    for (const candidate of candidates) {
+        const secrets = secretIssues(candidate);
+        if (secrets.length) {
+            lastSecretError = secrets.join("; ");
+            continue;
+        }
+        const result = backendTestExecutionContractSchema.safeParse(candidate);
+        if (result.success) {
+            accepted = result.data;
+            break;
+        }
+        lastSchemaError = result.error.issues
             .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
-            .join("; ")}`);
+            .join("; ");
+    }
+    if (!accepted) {
+        throw new Error(`invalid-output: ${lastSecretError || lastSchemaError}`);
     }
-    const normalized = normalizeContractPaths(result.data);
+    const normalized = normalizeContractPaths(accepted);
     // evidenceGaps may record greenfield/incomplete discovery (no test_*.py yet,
     // missing pytest.ini, projected schema path, etc.). Do not block materialize:
     // generate-functional-cases / generate-pytest are expected to fill automation.

package/dist/workflows/dag/frontend-implementation-contract.js

@@ -1,9 +1,86 @@
 import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { z } from "zod";
 import { writeDagRunJsonArtifact } from "../../infrastructure/harness/artifact-store.js";
+import { findPackageRoot } from "../../shared/package-metadata.js";
 export const FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID = "frontend-implementation-contract-v1";
+/**
+ * Load the canonical frontend-implementation-contract-v1 JSON Schema from the
+ * installed loop-agent package docs/templates/ path. Package-root discovery
+ * works from both the source module and the compiled dist module without
+ * relying on CommonJS globals in the ESM runtime.
+ *
+ * Validation is fail-closed: missing file, malformed JSON, mismatched $id,
+ * missing additionalProperties: false, or incomplete top-level required keys
+ * all throw before any DAG prompt is assembled.
+ */
+export function loadFrontendImplementationContractJsonSchema(startDir = path.dirname(fileURLToPath(import.meta.url))) {
+    const packageRoot = findPackageRoot(startDir);
+    if (!packageRoot) {
+        throw new Error(`cannot locate loop-agent package root from ${path.resolve(startDir)}`);
+    }
+    const schemaPath = path.join(packageRoot, "docs", "templates", "frontend-implementation-contract.schema.json");
+    let content;
+    try {
+        content = readFileSync(schemaPath, "utf-8");
+    }
+    catch (error) {
+        throw new Error(`cannot load frontend-implementation-contract.schema.json from current loop-agent package at ${schemaPath}: ${error.code ?? String(error)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`frontend-implementation-contract.schema.json is not valid JSON: ${error.message}`);
+    }
+    if (parsed === null || typeof parsed !== "object") {
+        throw new Error("frontend-implementation-contract.schema.json root is not a JSON object");
+    }
+    const schema = parsed;
+    if (schema.$id !== FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID) {
+        throw new Error(`schema $id mismatch: expected ${FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID}, got ${String(schema.$id)}`);
+    }
+    if (schema.additionalProperties !== false) {
+        throw new Error("schema must have additionalProperties: false at top level");
+    }
+    const expectedRequired = [
+        "schemaVersion",
+        "sourceBinding",
+        "riskLevel",
+        "targets",
+        "requirements",
+        "uiStates",
+        "interactions",
+        "mockApi",
+        "designEvidence",
+        "verificationTargets",
+        "evidenceGaps",
+    ];
+    const actualRequired = Array.isArray(schema.required) ? schema.required : [];
+    const missing = expectedRequired.filter((key) => !actualRequired.includes(key));
+    if (missing.length > 0) {
+        throw new Error(`schema required fields missing: ${missing.join(", ")}`);
+    }
+    const properties = schema.properties && typeof schema.properties === "object"
+        ? schema.properties
+        : {};
+    const missingProperties = expectedRequired.filter((key) => !Object.hasOwn(properties, key));
+    if (missingProperties.length > 0) {
+        throw new Error(`schema properties missing: ${missingProperties.join(", ")}`);
+    }
+    const schemaVersion = properties.schemaVersion;
+    const mockApi = properties.mockApi;
+    const mockApiProperties = mockApi?.properties;
+    const productionDefaultOff = mockApiProperties?.productionDefaultOff;
+    if (schemaVersion?.const !== 1 || productionDefaultOff?.const !== true) {
+        throw new Error("schema fixed values are incomplete: schemaVersion.const must be 1 and mockApi.productionDefaultOff.const must be true");
+    }
+    return JSON.stringify(parsed);
+}
 const id = z.string().regex(/^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/);
 const safePath = z
     .string()

package/dist/workflows/dag/frontend-project-capability.js

@@ -32,8 +32,8 @@ function allDeps(pkg) {
 function hasDep(deps, name) {
     return Object.hasOwn(deps, name);
 }
-async function listOpenSpec(repoRoot) {
-    const root = path.join(repoRoot, "openSpec");
+async function listOpenspec(repoRoot) {
+    const root = path.join(repoRoot, "openspec");
     if (!(await exists(root)))
         return [];
     const out = [];
@@ -70,7 +70,7 @@ export function buildAdapterGuidance(capability) {
         "## Frontend project capability (generation-time)",
         `Framework: ${capability.framework}${capability.frameworkVersion ? `@${capability.frameworkVersion}` : ""}`,
         `Evidence: ${capability.evidencePaths.join(", ") || "(none)"}`,
-        "Rules: openSpec/** and task sources outrank adapter tips; do not invent APIs for unknown versions; lockfile-only is not enough.",
+        "Rules: openspec/** and task sources outrank adapter tips; do not invent APIs for unknown versions; lockfile-only is not enough.",
     ];
     if (capability.framework === "react") {
         lines.push("React adapter: prefer function components + hooks; reuse existing Testing Library / Vitest patterns; do not introduce new state libs without authorization.");
@@ -276,14 +276,14 @@ export async function discoverFrontendProjectCapability(repoRoot) {
         router = router ?? "next-router";
     if (hasDep(deps, "vue-router"))
         router = "vue-router";
-    const openSpec = await listOpenSpec(repoRoot);
+    const openspec = await listOpenspec(repoRoot);
     const designEvidence = {
-        normativePaths: openSpec,
+        normativePaths: openspec,
         advisoryPaths: [],
         conflicts: [],
     };
-    if (openSpec.length)
-        evidencePaths.push(...openSpec.slice(0, 5));
+    if (openspec.length)
+        evidencePaths.push(...openspec.slice(0, 5));
     const base = {
         schemaVersion: 1,
         framework,

package/dist/workflows/dag/frontend-risk.js

@@ -33,7 +33,7 @@ const HIGH_RISK_PATTERNS = [
     },
     {
         id: "design-conflict",
-        re: /design\s+conflict|规范冲突|openSpec\s+conflict/i,
+        re: /design\s+conflict|规范冲突|openspec\s+conflict/i,
     },
     {
         id: "cross-domain-paths",

package/dist/workflows/dag/init-hybrid.js

@@ -22,6 +22,7 @@ import { buildBackendTestEffectiveResultSelectorShellSnippet, buildBackendTestRe
 import { buildBackendTestOutcomeGateShellSnippet } from "./backend-test-result-contract.js";
 import { classifyFrontendRisk, } from "./frontend-risk.js";
 import { discoverFrontendProjectCapability, } from "./frontend-project-capability.js";
+import { FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID, loadFrontendImplementationContractJsonSchema, } from "./frontend-implementation-contract.js";
 const REQUIREMENT_FILE = "需求.md";
 const CONSTRAINT_FILE = "执行约束.md";
 const REFERENCE_DIRECTORY = "references";
@@ -1355,10 +1356,11 @@ function buildFrontendMockAssessNode(sources, sourceContext, mockContextBlock, f
         allowedPaths: readOnlyPaths,
         forbiddenPaths,
         skills: FRONTEND_IMPLEMENTATION_SKILLS,
-        outputContract: "Plain Markdown whose first non-empty line is MOCK_STRATEGY: native|browser-intercept|request-adapter|not-needed|blocked, followed by Mock Decision, API Contract Evidence, Specification Evidence, Service Evidence, Backend Readiness, Selection Evidence, Endpoint / Fixture Matrix, Activation, Target Files, Production Safety, Verification Plan, Real Integration Gap, and Blocking Issues. No file writes.",
+        firstProtocolLine: "MOCK_STRATEGY:",
+        outputContract: "Plain Markdown whose first line is MOCK_STRATEGY: native|browser-intercept|request-adapter|not-needed|blocked, followed by Mock Decision, API Contract Evidence, Specification Evidence, Service Evidence, Backend Readiness, Selection Evidence, Endpoint / Fixture Matrix, Activation, Target Files, Production Safety, Verification Plan, Real Integration Gap, and Blocking Issues. No file writes.",
         subtask_prompt: [
             "Perform read-only Mock assessment and select one safe frontend data strategy.",
-            "The first non-empty line must be exactly one of: MOCK_STRATEGY: native, MOCK_STRATEGY: browser-intercept, MOCK_STRATEGY: request-adapter, MOCK_STRATEGY: not-needed, or MOCK_STRATEGY: blocked.",
+            "The first line must be exactly one of: MOCK_STRATEGY: native, MOCK_STRATEGY: browser-intercept, MOCK_STRATEGY: request-adapter, MOCK_STRATEGY: not-needed, or MOCK_STRATEGY: blocked. Do not emit blank lines, headings, or explanatory preamble before it.",
             "Prefer an existing native Mock facility. Use browser-intercept only with an existing browser/e2e harness. When no Mock exists but the API layer is writable, use request-adapter by adding a minimal reversible adapter/DI seam within the approved writeSet; the real adapter must remain the production default.",
             autoMaySkipMissingMock
                 ? "Auto mode may skip Mock when no project Mock capability is confirmed. Select not-needed with positive evidence from contract/scout that no project Mock capability is confirmed, continue without adding Mock files or dependencies, run the fixed verification entrypoints, and record any unproved real API behavior in Real Integration Gap. Do not block solely because no project Mock capability, browser interception harness, or request adapter exists."
@@ -1616,7 +1618,7 @@ function resolveFrontendCapabilityContextBlock(sources) {
     if (capability) {
         parts.push("", capability.adapterGuidance);
         if (capability.designEvidence.normativePaths.length > 0) {
-            parts.push(`openSpec normative candidates: ${capability.designEvidence.normativePaths.slice(0, 12).join(", ")}`);
+            parts.push(`openspec normative candidates: ${capability.designEvidence.normativePaths.slice(0, 12).join(", ")}`);
         }
         parts.push(`A11y capability: ${capability.a11y.status}` +
             (capability.a11y.tools.length
@@ -1749,6 +1751,46 @@ function buildFrontendHybridDagFromTask(sources) {
             allowedPaths: taskConfig.allowedPaths,
             complexity: taskConfig.complexity,
         });
+    const frontendSourceBinding = buildDagSourceBinding(sources);
+    const frontendContractSchemaBlock = (() => {
+        const schema = loadFrontendImplementationContractJsonSchema();
+        const requirement = frontendSourceBinding.sources.find((source) => source.kind === "requirement");
+        if (!requirement) {
+            throw new Error("frontend implementation contract context requires a bound requirement source");
+        }
+        const referencePaths = frontendSourceBinding.sources
+            .filter((s) => s.kind === "reference")
+            .map((s) => s.path);
+        const fixedFields = {
+            schemaVersion: 1,
+            sourceBinding: {
+                taskId: frontendSourceBinding.taskId,
+                requirementPath: requirement.path,
+                requirementSha256: requirement.sha256,
+                referencePaths,
+                requirementIds: frontendSourceBinding.requirementIds,
+            },
+            riskLevel: frontendRisk.selectedRisk,
+            targets: { files: implementPaths.writeSet },
+        };
+        return [
+            `## ${FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID} JSON Schema (authoritative; do not guess fields)`,
+            schema,
+            "",
+            "## Fixed contract fields (deterministic; copy exactly and do not modify)",
+            JSON.stringify(fixedFields),
+            "",
+            "## Forbidden fields (these are NOT in the schema; do not emit)",
+            "- schemaId",
+            "- targetFiles",
+            "- requirementCoverage",
+            "",
+            "## Critical rules",
+            "- verificationTargets is a TOP-LEVEL required array",
+            "- uiStates items use name/applicable/expectedBehavior/implementationTargets/verificationTargetIds/notApplicableReason",
+            "- mockApi.productionDefaultOff must always be true (including strategy: not-needed)",
+        ].join("\n");
+    })();
     const sourceContext = [
         buildSourceContextBlock(sources),
         capabilityContextBlock,
@@ -1757,7 +1799,7 @@ function buildFrontendHybridDagFromTask(sources) {
         .join("\n\n");
     const hasMockVerifyCommands = (taskConfig.frontendMock?.verifyCommands.length ?? 0) > 0 ||
         mockCapability.verifyCommands.length > 0;
-    const requirementIds = buildDagSourceBinding(sources).requirementIds;
+    const requirementIds = frontendSourceBinding.requirementIds;
     const requirementCoverageInstruction = requirementIds.length > 0
         ? `Include a Requirement Coverage section that lists every exact source identifier: ${requirementIds.join(", ")}. Preserve each identifier verbatim and map it to concrete implementation and verification steps.`
         : "";
@@ -1916,6 +1958,7 @@ function buildFrontendHybridDagFromTask(sources) {
                     fixedVerificationContext,
                     sourceContext,
                     mockContextBlock,
+                    frontendContractSchemaBlock,
                 ].join("\n\n"),
             },
             {
@@ -1992,6 +2035,7 @@ function buildFrontendHybridDagFromTask(sources) {
                     "Read-only: do not modify code, docs, artifacts, or repository files. This node revises the plan only.",
                     "End the response with exactly one fenced json object conforming to frontend-implementation-contract-v1. Bind it to the supplied task sources; map every requirement and applicable UI state to concrete implementation and verification targets or an explicit blocking evidence gap. Do not include secrets or unsafe paths.",
                     sourceContext,
+                    frontendContractSchemaBlock,
                 ].join("\n\n"),
             },
             ...(requirementIds.length > 0

package/dist/workflows/dag/types.js

@@ -306,6 +306,7 @@ export const dagTaskSchema = z.object({
     shell: dagShellConfigSchema.optional(),
     static: dagStaticConfigSchema.optional(),
     outputContract: z.string().optional(),
+    firstProtocolLine: z.string().min(1).optional(),
     allowedPaths: z.array(z.string()).optional().default([]),
     forbiddenPaths: z.array(z.string()).optional().default([]),
     decisionGate: dagDecisionGateSchema.optional(),

package/docs/templates/agent-dag.schema.json

@@ -389,6 +389,11 @@
           "type": "string",
           "minLength": 1
         },
+        "firstProtocolLine": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Optional protocol prefix whose first matching Pi assistant-output line is promoted to the canonical first line. Missing matches are not synthesized."
+        },
         "allowedPaths": {
           "type": "array",
           "items": { "type": "string", "minLength": 1 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.16.4",
+  "version": "0.16.6-beta.0",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",

package/skills/frontend-design-review/SKILL.md

@@ -12,7 +12,7 @@ references:
 For first/final design review nodes. Read the checklist, then audit contract, scout,
 mock strategy, plan/revision, task constraints/bounds, and traceable design evidence. The knowledge-
 base connector is TODO: never invent results. If absent/failed/unmatched, require
-`<repoRoot>/openSpec/**` search/read evidence before repo conventions.
+`<repoRoot>/openspec/**` search/read evidence before repo conventions.
 
 ## Verdict Contract
 
@@ -27,7 +27,7 @@ remaining, incomplete, or newly introduced gaps.
 
 - Any criterion lacks implementation/verification; UI states lack reasons; a
   dependency lacks permission; confirmed primitives/rules are ignored; design claims
-  lack knowledge-base or required `openSpec/` evidence; paths cross write bounds;
+  lack knowledge-base or required `openspec/` evidence; paths cross write bounds;
   commands are missing/non-deterministic; or interaction, responsive, accessibility,
   data, or failure behavior requires guessing.
 - `MOCK_STRATEGY: blocked`; missing permitted target paths, endpoint/schema-to-fixture
@@ -35,7 +35,7 @@ remaining, incomplete, or newly introduced gaps.
   inline fake data; commented real requests; Mock-on production defaults; test-only
   production imports; or Mock evidence reported as real integration.
 
-Knowledge-base absence is advisory if relevant `openSpec/` rules were searched/read
+Knowledge-base absence is advisory if relevant `openspec/` rules were searched/read
 and applied. Block skipped fallback, unresolved conflict, or unresolved UI decisions.
 
 ## Method And Output
@@ -48,7 +48,7 @@ Advisory, and never edit files.
 Run `grep`/`find`, then explicit `read` calls for applicable specs and checklist.
 Only successful paired reads count as “已读取规范文件”; summaries do not. List each
 read path/section in `Checked Items`. If the connector is unavailable, search/read
-`openSpec/` before accepting repository conventions.
+`openspec/` before accepting repository conventions.
 
 ```markdown
 VERDICT: pass

package/skills/frontend-design-review/references/review-checklist.md

@@ -9,7 +9,7 @@
 ## Project Fit
 
 - Reuse components, hooks, API helpers, mocks, schemas, router patterns, tokens, and theme rules.
-- Cite knowledge-base or `openSpec/`; failed/empty knowledge queries must search `<repoRoot>/openSpec/**`.
+- Cite knowledge-base or `openspec/`; failed/empty knowledge queries must search `<repoRoot>/openspec/**`.
 - Record source status, query terms, paths/headings, conflicts, authorized deps, and allowed paths.
 
 ## Interaction / Quality
@@ -35,6 +35,6 @@
 
 ## Verdict Matrix
 
-- Request revision for coverage gaps, unsafe scope, unauthorized deps, unresolved required interaction, missing required verification, skipped `openSpec/` fallback, unsafe/missing Mock strategy, or Mock evidence presented as real integration.
-- Knowledge-base unavailable but relevant `openSpec/` rules applied is advisory only.
+- Request revision for coverage gaps, unsafe scope, unauthorized deps, unresolved required interaction, missing required verification, skipped `openspec/` fallback, unsafe/missing Mock strategy, or Mock evidence presented as real integration.
+- Knowledge-base unavailable but relevant `openspec/` rules applied is advisory only.
 - Optional cleanup that cannot affect acceptance is advisory.

package/skills/frontend-implementation/SKILL.md

@@ -23,7 +23,7 @@ Read all required references before running any listed frontend node.
 ## Source And Evidence Rules
 
 Use task sources/references, constraints, then `task.json`. Follow `design-spec.md`:
-knowledge base; `<repoRoot>/openSpec/**` after unavailable/failed/empty; then repo
+knowledge base; `<repoRoot>/openspec/**` after unavailable/failed/empty; then repo
 evidence. Cite tight paths/symbols, label gaps/conflicts, and never invent APIs,
 rules, commands, or retrievals. Scout/planners locate and explicitly read applicable
 specs; only successful paired reads count. Lockfile-only, fixture-only, or unread

package/skills/frontend-implementation/references/code-standards.md

@@ -2,7 +2,7 @@
 
 Discover rules from task constraints, `design-spec.md` source order, config, code,
 tests, manifests, and generated types. After knowledge-base failure, applicable
-`<repoRoot>/openSpec/**` rules are normative. Preferences are not rules, and docs do
+`<repoRoot>/openspec/**` rules are normative. Preferences are not rules, and docs do
 not override installed APIs without an explicit compatibility decision.
 
 ## Discover And Cite

package/skills/frontend-implementation/references/design-spec.md

@@ -3,13 +3,13 @@
 ## Required Source Sequence
 
 1. Attempt the configured component/design knowledge-base query first.
-2. If unavailable, failed, timed out, or unmatched, recursively search the project root's exact `openSpec/` directory.
+2. If unavailable, failed, timed out, or unmatched, recursively search the project root's exact `openspec/` directory.
 3. Treat relevant matches as the current project's specification for this run.
 4. Only then use component source, tokens, stories, tests, and pages as non-normative repository fallback.
 
-Never skip `openSpec/` directly to neighboring-code conventions. Report source
+Never skip `openspec/` directly to neighboring-code conventions. Report source
 conflicts instead of combining them. Explicit task requirements remain the contract;
-flag conflicts with knowledge-base or `openSpec/` rules.
+flag conflicts with knowledge-base or `openspec/` rules.
 
 ## Knowledge Base Connection — TODO
 
@@ -17,11 +17,11 @@ Request format is undecided. TODO: define connector/owner, namespaces, secret-fr
 auth, query fields, result identity/version/time, and failure behavior.
 
 Attempt only a connector actually available in the execution environment. Otherwise
-record `not-configured` and run the `openSpec/` fallback; never invent a connection.
+record `not-configured` and run the `openspec/` fallback; never invent a connection.
 
-## `openSpec/` Fallback Procedure
+## `openspec/` Fallback Procedure
 
-- Confirm whether `<repoRoot>/openSpec/` exists and enumerate its files recursively.
+- Confirm whether `<repoRoot>/openspec/` exists and enumerate its files recursively.
 - Read indexes first, then search names/content using task, route, component, interaction, theme, token, and state terms.
 - Read relevant matches in context; do not treat a filename-only hit as a rule.
 - Record search terms, inspected/matched paths, headings or tight line ranges, applied rules, and conflicts.
@@ -29,9 +29,9 @@ record `not-configured` and run the `openSpec/` fallback; never invent a connect
 
 ## Retrieval Evidence
 
-Record source as `knowledge-base`, `openSpec fallback`, `repository fallback`, or
+Record source as `knowledge-base`, `openspec fallback`, `repository fallback`, or
 `unavailable`. Knowledge-base evidence includes query, source ID/version/time, rules,
-and conflicts. `openSpec fallback` includes terms, paths/headings/lines, rules, and conflicts.
+and conflicts. `openspec fallback` includes terms, paths/headings/lines, rules, and conflicts.
 
 ## Rules To Retrieve Or Discover
 
@@ -42,5 +42,5 @@ and conflicts. `openSpec fallback` includes terms, paths/headings/lines, rules,
 
 - Reuse confirmed primitives unless a new pattern is authorized.
 - Define applicable states and responsive behavior before implementation.
-- Cite knowledge-base or `openSpec/` evidence for component/token choices; label weaker repository fallback.
+- Cite knowledge-base or `openspec/` evidence for component/token choices; label weaker repository fallback.
 - Make deviations and unresolved gaps explicit.

package/skills/frontend-implementation/references/node-contracts.md

@@ -5,11 +5,11 @@ Pre-write nodes are read-only. Preserve IDs, labels, commands, language, require
 ## Core nodes
 
 - **`frontend-contract-pi`**: `Scope`, `Non-goals`, `Acceptance Criteria`, `UI States`, `Target Runtime Environment`, `Risks`, `Verification Expectations`. No guessed requirements.
-- **`frontend-scout-pi`**: routes, components, tokens, data/API/Mock, scripts, tests, assets. Fact vs inference vs gap. Knowledge base first; else search+read `<repoRoot>/openSpec/**` before repo fallback. Output stack, routes, components, styling, conventions, state/data, test entry points, reuse, risks.
-- **`frontend-mock-assess-pi` + gate**: first non-empty line
+- **`frontend-scout-pi`**: routes, components, tokens, data/API/Mock, scripts, tests, assets. Fact vs inference vs gap. Knowledge base first; else search+read `<repoRoot>/openspec/**` before repo fallback. Output stack, routes, components, styling, conventions, state/data, test entry points, reuse, risks.
+- **`frontend-mock-assess-pi` + gate**: declares `firstProtocolLine: "MOCK_STRATEGY:"`; canonical output first line
   `MOCK_STRATEGY: native|browser-intercept|request-adapter|not-needed|blocked`
-  Prefer native Mock; browser intercept only with existing e2e; request-adapter only for reversible local preview. Default `auto` may select `not-needed` when contract/scout evidence confirms no project Mock capability, without adding Mock files/deps, while keeping real requests default and recording the Real Integration Gap. Other `not-needed` cases need positive no-remote/stable-backend evidence; invalid when `frontendMock.policy=required`. `blocked` for missing/conflicting contracts, unsafe paths/deps, unread specs, production-default-on, unverifiable entrypoints. Output Mock Decision, API/spec/service evidence, backend readiness, selection evidence, endpoint/fixture matrix, activation, targets, production safety, verification plan, real-integration gap, blocking issues. Never invent fields, store secrets, comment real requests, import test mocks into production, or treat Mock as real integration. Gate uses `first-non-empty` only; never authorizes writes. Unsafe required contracts → no writer.
-- **`frontend-plan-pi` + design loop**: AC → steps, in-bound files, UI states, reuse, deps, activation/rollback, frozen verify entrypoints, real-integration gap. First gate: `VERDICT: pass|request-revision`. Pass may emit `PASS_NO_REVISION_NEEDED`; else full corrected plan without invented evidence. Final review rechecks plan/findings/revision/assessment/Mock safety. Only final `VERDICT: pass` authorizes writes; failure → replan/rerun (not dev-fix).
+  Pi output mapping promotes the first matching protocol line ahead of any preamble without inventing or replacing its value; missing, malformed, or blocked strategies still fail closed. Prefer native Mock; browser intercept only with existing e2e; request-adapter only for reversible local preview. Default `auto` may select `not-needed` when contract/scout evidence confirms no project Mock capability, without adding Mock files/deps, while keeping real requests default and recording the Real Integration Gap. Other `not-needed` cases need positive no-remote/stable-backend evidence; invalid when `frontendMock.policy=required`. `blocked` for missing/conflicting contracts, unsafe paths/deps, unread specs, production-default-on, unverifiable entrypoints. Output Mock Decision, API/spec/service evidence, backend readiness, selection evidence, endpoint/fixture matrix, activation, targets, production safety, verification plan, real-integration gap, blocking issues. Never invent fields, store secrets, comment real requests, import test mocks into production, or treat Mock as real integration. Gate uses `first-non-empty` only; never authorizes writes. Unsafe required contracts → no writer.
+- **`frontend-plan-pi` + design loop**: AC → steps, in-bound files, UI states, reuse, deps, activation/rollback, frozen verify entrypoints, real-integration gap. First gate: `VERDICT: pass|request-revision`. Pass may emit `PASS_NO_REVISION_NEEDED`; else full corrected plan without invented evidence. Final review rechecks plan/findings/revision/assessment/Mock safety. Only final `VERDICT: pass` authorizes writes; failure → replan/rerun (not dev-fix). The plan-pi prompt now includes the complete `frontend-implementation-contract-v1` JSON Schema loaded from the loop-agent package `docs/templates/` path, plus deterministic source binding, risk level, and allowed implementation targets. The model does not need to search or guess contract fields; `schemaId`, `targetFiles`, `requirementCoverage` are explicitly forbidden.
 - **`frontend-implement-pi`**: sole exclusive writer. Stay in `writeSet`; real requests default-on; Mock reversible, dev/test-only, production-off. Atomic handler/intercept/adapter with consumer+tests. Stop on forbidden paths or guesses. Output changed files, behavior, UI states, styling notes, verification attempted, residual risks. Optional mock-verify when frozen; static+behavior always; behavior must prove page consumption. Skipped-Mock `not-needed` keeps real integration pending unless the real backend path has fresh evidence.
 
 ## Contract / trace / stages (M1–M2)
@@ -24,4 +24,4 @@ static/behavior/trace may `nonZeroExitPolicy: record`. Assess → `contracts/fro
 
 ## Risk & capability (M4–M6)
 
-Deterministic risk (no model); high-risk beats small; supervised never small. Small may drop first design gate + plan-revision; contract shell retargets to `frontend-plan-pi`. Capability seed injects adapters; openSpec/task sources outrank. A11y: static/component tools only when present; Browser a11y always not-run.
+Deterministic risk (no model); high-risk beats small; supervised never small. Small may drop first design gate + plan-revision; contract shell retargets to `frontend-plan-pi`. Capability seed injects adapters; openspec/task sources outrank. A11y: static/component tools only when present; Browser a11y always not-run.

package/skills/frontend-review/SKILL.md

@@ -37,7 +37,7 @@ required check, forbidden write, or unmet acceptance criterion forces revision.
   and no false real-integration claim. `not-needed` needs applicable real/no-remote
   evidence, or an explicit default-auto skipped-Mock rationale with the Real
   Integration Gap preserved when no project Mock capability is confirmed.
-- Component/design claims require traceable knowledge-base evidence or, after connection/query failure or no match, relevant `<repoRoot>/openSpec/**` evidence. The connector format is TODO; never claim a query or fallback search without evidence. Execute explicit `grep`/`find` to locate spec files and `read` to load them before referencing their rules. Only successful `read` tool calls are observable as "已读取规范文件" in the spec-evidence inspector.
+- Component/design claims require traceable knowledge-base evidence or, after connection/query failure or no match, relevant `<repoRoot>/openspec/**` evidence. The connector format is TODO; never claim a query or fallback search without evidence. Execute explicit `grep`/`find` to locate spec files and `read` to load them before referencing their rules. Only successful `read` tool calls are observable as "已读取规范文件" in the spec-evidence inspector.
 - Treat shell exit status as authoritative. Do not edit files.
 
 ## Evidence And Output

package/skills/frontend-review/references/review-findings.md

@@ -11,7 +11,7 @@
 - Cite tight file locations, exact commands/results, or named DAG artifacts.
 - Never invent evidence; name the missing check. An implementation summary is not the actual diff.
 - Failed required static/behavior verification is at least Important unless proven unrelated.
-- A knowledge-base claim records connector/query, source ID/version, and retrieval time. If absent, failed, or unmatched, review evidence must show `<repoRoot>/openSpec/**` search terms and matched paths/headings; label `openSpec fallback`, `repository fallback`, or `unavailable` accurately.
+- A knowledge-base claim records connector/query, source ID/version, and retrieval time. If absent, failed, or unmatched, review evidence must show `<repoRoot>/openspec/**` search terms and matched paths/headings; label `openspec fallback`, `repository fallback`, or `unavailable` accurately.
 
 ## Review Sequence
 
@@ -25,7 +25,7 @@
 6. Check component/design evidence, responsive/accessibility behavior, dependencies, and maintenance fit when applicable.
 7. Classify findings and derive the verdict mechanically.
 
-Skipping the required `openSpec/` search after knowledge-base failure is Important
+Skipping the required `openspec/` search after knowledge-base failure is Important
 when component/design compliance affects acceptance or implementation choices.
 
 Use one issue per finding:

package/skills/frontend-verification/SKILL.md

@@ -24,9 +24,9 @@ verdict/findings, and required browser, visual, manual, or knowledge evidence.
 - Mock-backed behavior proves frontend rendering and state transitions only. It never
   proves backend readiness, transport compatibility, or real API integration.
 - Unavailable commands remain gaps.
-- Resolve design evidence via knowledge base, then `<repoRoot>/openSpec/**` after
+- Resolve design evidence via knowledge base, then `<repoRoot>/openspec/**` after
   failure/no match. Its connector format remains TODO; never invent it. An applied
-  `openSpec fallback` is available project evidence.
+  `openspec fallback` is available project evidence.
 - Separate Mock service/handler checks from page consumption and record the
   dev/test-only boundary; handler tests alone do not prove page use.
 

package/skills/frontend-verification/references/verification-checklist.md

@@ -12,9 +12,9 @@
 
 ## Design And Component Evidence
 
-- Claims cite knowledge-base retrieval or `<repoRoot>/openSpec/**` fallback.
+- Claims cite knowledge-base retrieval or `<repoRoot>/openspec/**` fallback.
 - Evidence records query/source/time or fallback search terms, paths, headings, and applied rules.
-- Relevant `openSpec/` matches satisfy source availability; missing both sources blocks explicit compliance or required design decisions.
+- Relevant `openspec/` matches satisfy source availability; missing both sources blocks explicit compliance or required design decisions.
 
 ## Status
 

package/skills/loop-agent/references/hybrid-dag.md

@@ -120,7 +120,7 @@ contract-pi → scout-src ∥ scout-tests → plan-pi → write-set-audit-pi
 | `authority-surface-audit-pi` + `authority-surface-gate-shell` | 可选 permission/state/tool-exposure audit；仅 authority signal 或显式 `authority-surface-audit` marker 时插入；gate 仅接受 `VERDICT: pass` |
 | `review-pi` + `review-verdict-recovery-pi` + `review-gate-shell` | Critical/Important → `request-revision`；recovery 只规范化 VERDICT 协议（不得从自然语言猜 pass）；gate 只认 `review-verdict-recovery-pi` 的 `VERDICT: pass` |
 
-**Verdict gate contract（`shell.verdictGate`）**：声明 `fromNodeId`、`accept[]`、可选 `label`、可选 `lineMode`。runner 展开为一条 shell command，从 injected current run directory 读 `$HARNESS_DAG_RUN_DIR/<fromNodeId>.json`，对 extracted `assistantText ?? stdout` verdict line 与 `accept[]` exact-match。默认 `lineMode` 为 `first-non-empty` 以兼容；supervised gate 用 `first-verdict-line` 选 Pi 在 preamble 或常见整行 Markdown emphasis（如 `**VERDICT: pass**`）后第一条 normalized `VERDICT:` line。勿用 `result.summary.md`、grep VERDICT、latest-active-run discovery 或 multi-command stateful gate。`--strict-governance` 对 anti-pattern fail。supervisor 仍为 `executor: pi` 上的 `role: supervisor`。
+**Verdict gate contract（`shell.verdictGate`）**：声明 `fromNodeId`、`accept[]`、可选 `label`、可选 `lineMode`。runner 展开为一条 shell command，从 injected current run directory 读 `$HARNESS_DAG_RUN_DIR/<fromNodeId>.json`，对 extracted `assistantText ?? stdout` verdict line 与 `accept[]` exact-match。默认 `lineMode` 为 `first-non-empty` 以兼容；需要固定非 `VERDICT:` 协议首行的 Pi 节点可显式声明 `firstProtocolLine`，executor 会把第一条匹配前缀的行提升为 canonical 首行，不匹配时不伪造。`frontend-mock-assess-pi` 用它固定 `MOCK_STRATEGY:`，gate 仍保持 `first-non-empty` exact-match。supervised gate 用 `first-verdict-line` 选 Pi 在 preamble 或常见整行 Markdown emphasis（如 `**VERDICT: pass**`）后第一条 normalized `VERDICT:` line。勿用 `result.summary.md`、grep VERDICT、latest-active-run discovery 或 multi-command stateful gate。`--strict-governance` 对 anti-pattern fail。supervisor 仍为 `executor: pi` 上的 `role: supervisor`。
 
 **Repair artifact gate contract（`shell.repairArtifactGate`）**：声明 `fromNodeId`（supervisor artifact 节点）与 `repairNodeId`（承接修订的 Pi 修复节点）。runner **不再**按节点名（历史 `repair-cursor` / `repair-pi`）猜测 repair 节点：显式 `repairNodeId` 必须存在、直接 `depends_on` gate、且是受治理 Pi writer（`executor: pi`、`toolProfile: write`、`writePolicy: exclusive`、`allowedPaths`+`writeSet` 非空且 `writeSet` 不与 `forbiddenPaths` 冲突）。新生成的 supervised DAG 总是写入 `repairNodeId`；旧 DAG 缺失时只在能唯一、安全地推导出下游 Pi writer 时兼容，零个或多个候选、或候选不满足契约都在执行前 fail closed。validation 覆盖存在性、直接下游、writer 属性与路径边界。