@tea-agent/loop-agent 0.44.0-next.1 → 0.44.0-next.11

package/dist/workflows/dag/hybrid/templates/knowledge-sync.js

@@ -0,0 +1,495 @@
+import { assertValidDagSpec } from "../../validate.js";
+import { DEFAULT_DAG_EXECUTOR_MODELS, DEFAULT_DAG_OUTPUT_LANGUAGE, parseDagSpec } from "../../types.js";
+import { HYBRID_DEFAULTS, STANDARD_GLOBAL_CONSTRAINTS, buildSourceContextBlock, buildVerifyEvidence, extractObjective, extractSuccessCriteria } from "../sources.js";
+import { commonForbiddenPaths, commonReadOnlyPaths, stampGeneratedArtifactBindings, } from "./shared.js";
+export const KNOWLEDGE_SYNC_DEFAULTS = {
+    ...HYBRID_DEFAULTS,
+    writePolicy: "read-only",
+};
+export const KNOWLEDGE_SYNC_SKILLS_BY_ROLE = {
+    planner: ["loop-agent"],
+    scout: [],
+    implementer: ["verification-before-completion"],
+    reviewer: ["requesting-code-review"],
+    verifier: ["verification-before-completion", "systematic-debugging"],
+    closeout: ["loop-agent", "verification-before-completion"],
+};
+export function buildMultiPerspectiveReviewAggregateScript(fromNodeIds, label) {
+    if (fromNodeIds.length === 0) {
+        throw new Error("multi-perspective aggregate requires at least one review node id");
+    }
+    const idsLiteral = JSON.stringify([...fromNodeIds]);
+    const labelLiteral = JSON.stringify(label);
+    return [
+        "node",
+        "-e",
+        JSON.stringify([
+            "const fs=require('fs');",
+            "const path=require('path');",
+            `const ids=${idsLiteral};`,
+            `const label=${labelLiteral};`,
+            "const runDir=process.env.HARNESS_DAG_RUN_DIR;",
+            "if(!runDir){ console.error(label+': missing HARNESS_DAG_RUN_DIR'); process.exit(1); }",
+            "function normalize(line){",
+            "  const t=String(line).trim();",
+            "  const m=t.match(/^\\*{1,3}\\s*(VERDICT:[^*]+?)\\s*\\*{1,3}$/);",
+            "  return (m?m[1]:t).trim();",
+            "}",
+            "function firstVerdict(text){",
+            "  for (const line of String(text||'').split(/\\r?\\n/)) {",
+            "    const n=normalize(line);",
+            "    if(/^VERDICT:/.test(n)) return n;",
+            "  }",
+            "  return '';",
+            "}",
+            "const failures=[];",
+            "for (const id of ids) {",
+            "  const file=path.join(runDir, id+'.json');",
+            "  if(!fs.existsSync(file)){ failures.push(id+': missing JSON '+file); continue; }",
+            "  let raw; try { raw=JSON.parse(fs.readFileSync(file,'utf8')); } catch(e){ failures.push(id+': invalid JSON'); continue; }",
+            "  const verdict=firstVerdict(raw.assistantText ?? raw.stdout ?? '');",
+            "  if(verdict!=='VERDICT: pass') failures.push(id+': '+(verdict||'missing VERDICT line'));",
+            "  else console.log(id+': VERDICT: pass');",
+            "}",
+            "if(failures.length){ console.error(label+' blocked:\\n'+failures.join('\\n')); process.exit(1); }",
+            "console.log(label+': all perspectives VERDICT: pass ('+ids.length+')');",
+        ].join("")),
+    ].join(" ");
+}
+export function buildMultiPerspectiveReviewNodes(input) {
+    const reviewNodes = input.perspectives.map((p) => ({
+        id: `${input.nodePrefix}${p.id}-pi`,
+        depends_on: [...input.dependsOn],
+        role: "reviewer",
+        executor: "pi",
+        complexity: "HIGH",
+        writePolicy: "read-only",
+        allowedPaths: input.allowedPaths,
+        forbiddenPaths: commonForbiddenPaths(input.sources),
+        outputContract: `Plain Markdown; first non-empty line is VERDICT: pass or VERDICT: request-revision. Perspective: ${p.perspective}. No file writes.`,
+        subtask_prompt: [
+            `You are the **${p.perspective}** reviewer in a multi-perspective review panel.`,
+            "Other perspectives run in parallel; do not assume their conclusions. Stay in your role.",
+            "First non-empty line must be exactly VERDICT: pass or VERDICT: request-revision.",
+            "Any Critical or Important finding in your domain must force VERDICT: request-revision.",
+            "Structure: VERDICT line, then Findings (Critical/Important/Minor), then Checked Items, then Residual Risks.",
+            "Cite concrete paths/ids as evidence. Read-only: do not modify files.",
+            ...input.sharedBrief,
+            "Focus for this perspective:",
+            ...p.focus.map((line) => `- ${line}`),
+            buildSourceContextBlock(input.sources),
+        ].join("\n\n"),
+    }));
+    const reviewIds = reviewNodes.map((n) => n.id);
+    if (input.structuredVerdictGate) {
+        const aggregateNodeId = `${input.nodePrefix}aggregate-pi`;
+        const aggregateNode = {
+            id: aggregateNodeId,
+            depends_on: reviewIds,
+            role: "reviewer",
+            executor: "pi",
+            complexity: "HIGH",
+            writePolicy: "read-only",
+            allowedPaths: input.allowedPaths,
+            forbiddenPaths: commonForbiddenPaths(input.sources),
+            outputContract: "Plain Markdown; first non-empty line is exactly VERDICT: pass only when every upstream perspective emitted VERDICT: pass, otherwise VERDICT: request-revision. No file writes.",
+            subtask_prompt: [
+                `Aggregate ${input.gateLabel} without changing any review finding.`,
+                `Inspect every upstream result: ${reviewIds.join(", ")}.`,
+                "First non-empty line must be exactly VERDICT: pass only when every upstream first verdict is VERDICT: pass; otherwise use VERDICT: request-revision.",
+                "List each upstream node and its observed verdict as evidence. Do not invent or override a missing/request-revision verdict.",
+                "Read-only: do not modify files.",
+            ].join("\n\n"),
+        };
+        const gateNode = {
+            id: input.gateId,
+            depends_on: [aggregateNodeId],
+            role: "verifier",
+            executor: "shell",
+            complexity: "LOW",
+            writePolicy: "read-only",
+            allowedPaths: commonReadOnlyPaths(input.sources),
+            forbiddenPaths: commonForbiddenPaths(input.sources),
+            outputContract: `Structured verdict gate: exit 0 only when ${aggregateNodeId} emits VERDICT: pass.`,
+            subtask_prompt: `Structured gate for ${input.gateLabel}: all perspectives must pass before downstream apply/promote.`,
+            shell: {
+                commands: [],
+                verdictGate: {
+                    fromNodeId: aggregateNodeId,
+                    accept: ["pass"],
+                    routingAccept: ["request-revision"],
+                    source: "verdict-line",
+                    lineMode: "first-verdict-line",
+                    label: input.gateLabel,
+                },
+                cwd: ".",
+                timeoutMs: 60000,
+            },
+        };
+        return [...reviewNodes, aggregateNode, gateNode];
+    }
+    const aggregateScript = buildMultiPerspectiveReviewAggregateScript(reviewIds, input.gateLabel);
+    const gateNode = {
+        id: input.gateId,
+        depends_on: reviewIds,
+        role: "verifier",
+        executor: "shell",
+        complexity: "LOW",
+        writePolicy: "read-only",
+        allowedPaths: commonReadOnlyPaths(input.sources),
+        forbiddenPaths: commonForbiddenPaths(input.sources),
+        outputContract: `Deterministic multi-perspective gate: exit 0 only when every review node among ${reviewIds.join(", ")} emits VERDICT: pass.`,
+        subtask_prompt: `Aggregate gate for ${input.gateLabel}: all perspectives must pass before downstream apply/promote.`,
+        shell: {
+            commands: [aggregateScript],
+            verifyEvidence: buildVerifyEvidence({
+                phase: "final",
+                quota: "full",
+                commandSource: "inline",
+                fallbackCommands: [aggregateScript],
+                finalFullRequired: true,
+                commandTimeoutMs: 60_000,
+            }),
+            cwd: ".",
+            timeoutMs: 60000,
+        },
+    };
+    return [...reviewNodes, gateNode];
+}
+export const KNOWLEDGE_SYNC_FEATURE_ID_RE = /^F-[A-Za-z0-9][A-Za-z0-9._-]*$/;
+export function assertSafeKnowledgeSyncFeatureId(featureId) {
+    const trimmed = featureId.trim();
+    if (!KNOWLEDGE_SYNC_FEATURE_ID_RE.test(trimmed)) {
+        throw new Error(`knowledge-sync featureId must match F-<id> (letters/digits/._- only); got ${JSON.stringify(featureId)}`);
+    }
+    if (trimmed.includes("..") ||
+        trimmed.includes("/") ||
+        trimmed.includes("\\")) {
+        throw new Error(`knowledge-sync featureId must not contain path segments: ${featureId}`);
+    }
+    return trimmed;
+}
+export function resolveKnowledgeSyncFeatureId(sources) {
+    const candidates = [];
+    const fromConfig = sources.taskConfig.featureId?.trim();
+    if (fromConfig)
+        candidates.push(fromConfig);
+    for (const line of sources.taskConfig.hardConstraints ?? []) {
+        const match = line.match(/(?:featureId|feature_id)\s*[=:]\s*(F-[A-Za-z0-9][A-Za-z0-9._-]*)/i);
+        if (match?.[1])
+            candidates.push(match[1]);
+    }
+    const fromRequirement = sources.requirementMarkdown?.match(/\b(F-\d{4}-\d{2,})\b/);
+    if (fromRequirement?.[1])
+        candidates.push(fromRequirement[1]);
+    if (KNOWLEDGE_SYNC_FEATURE_ID_RE.test(sources.taskId)) {
+        candidates.push(sources.taskId);
+    }
+    for (const candidate of candidates) {
+        try {
+            return assertSafeKnowledgeSyncFeatureId(candidate);
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    throw new Error([
+        "knowledge-sync requires an explicit featureId bound to features/<featureId>/.",
+        'Set task.json "featureId": "F-YYYY-NNN", or hardConstraints entry featureId=F-…,',
+        "or put F-YYYY-NNN in 需求.md, or use a taskId that is already an F-* id.",
+    ].join(" "));
+}
+export function knowledgeSyncWriteSet(featureId) {
+    const id = assertSafeKnowledgeSyncFeatureId(featureId);
+    return [
+        `features/${id}/testing/**`,
+        `features/${id}/requirement-delta.md`,
+        "docs/test-reports/**",
+    ];
+}
+export function knowledgeSyncPendingWriteSet(featureId) {
+    const id = assertSafeKnowledgeSyncFeatureId(featureId);
+    return [`features/${id}/testing/sync/pending/**`];
+}
+export function knowledgeSyncPointerWriteSet(featureId) {
+    const id = assertSafeKnowledgeSyncFeatureId(featureId);
+    return [
+        `features/${id}/testing/runs/**`,
+        `features/${id}/testing/sync/applied/**`,
+    ];
+}
+export function knowledgeSyncDraftRelPath(featureId) {
+    const id = assertSafeKnowledgeSyncFeatureId(featureId);
+    return `features/${id}/testing/sync/pending/knowledge-sync-draft.json`;
+}
+export function buildKnowledgeSyncCollectNode(sources, featureId) {
+    return {
+        id: "knowledge-sync-collect-pi",
+        depends_on: [],
+        role: "planner",
+        executor: "pi",
+        complexity: "MED",
+        writePolicy: "read-only",
+        allowedPaths: commonReadOnlyPaths(sources),
+        forbiddenPaths: commonForbiddenPaths(sources),
+        outputContract: "Plain Markdown inventory of final-verification evidence, acceptance criteria, cases, defects, and requirement-delta candidates; no file writes.",
+        subtask_prompt: [
+            "Collect inputs for knowledge-sync after final verification.",
+            `Bound featureId for this run: ${featureId} (directory features/${featureId}/).`,
+            `Read task source (需求.md, 执行约束.md, references), features/${featureId}/ testing assets when present, and upstream final verification / pytest / retrospect evidence paths.`,
+            "Produce a concise inventory covering: featureId/taskId/runId/headSha, AC list, reviewed cases, automation bindings, open defects, requirement-delta risk, and missing evidence.",
+            "Do not claim final verification passed without shell evidence. Read-only: do not modify repository files.",
+            buildSourceContextBlock(sources),
+        ].join("\n\n"),
+    };
+}
+export function buildKnowledgeSyncDraftNode(sources, featureId) {
+    const pending = knowledgeSyncPendingWriteSet(featureId);
+    const draftPath = knowledgeSyncDraftRelPath(featureId);
+    return {
+        id: "knowledge-sync-draft-pi",
+        depends_on: ["knowledge-sync-collect-pi"],
+        role: "implementer",
+        executor: "pi",
+        toolProfile: "write",
+        complexity: "HIGH",
+        writePolicy: "exclusive",
+        writeSet: pending,
+        allowedPaths: pending,
+        forbiddenPaths: commonForbiddenPaths(sources),
+        subtask_prompt: [
+            "Using knowledge-sync-collect-pi inventory and final verification evidence, write the pending knowledge-sync draft for this Feature only.",
+            `featureId MUST be exactly ${featureId}. Write only under features/${featureId}/testing/sync/pending/.`,
+            `Create ${draftPath} (schemaVersion 1) and features/${featureId}/testing/sync/pending/knowledge-sync-draft.md human summary.`,
+            "Draft payload must include: acceptanceVerdict, coverageMatrix, caseIndex, automationMap, defects, requirementDelta (or null), retrospectiveRef, evidencePointers, and operations[] with op/target/risk/reason.",
+            `Every operations[].target path must stay under features/${featureId}/ or docs/test-reports/.`,
+            "Mark requirement/acceptance body edits as risk=high. Keep raw shell logs as path pointers only.",
+            "If final verification is not pass, still write draft but set gates.blockIfFinalVerificationNotPass accordingly and do not invent pass results.",
+            "Stay within writeSet. Do not write other features/**, src/**, .harness/**, or knowledge/testing/standards/**.",
+            buildSourceContextBlock(sources),
+        ].join("\n\n"),
+    };
+}
+export function buildKnowledgeSyncValidateNode(sources, featureId) {
+    const draftPath = knowledgeSyncDraftRelPath(featureId);
+    const validateScript = [
+        "node",
+        "-e",
+        JSON.stringify([
+            "const fs=require('fs');",
+            "const path=require('path');",
+            `const featureId=${JSON.stringify(featureId)};`,
+            `const file=${JSON.stringify(draftPath)};`,
+            "if(!fs.existsSync(file)){ console.error('knowledge-sync validate: missing draft at '+file); process.exit(1); }",
+            "let draft; try { draft=JSON.parse(fs.readFileSync(file,'utf8')); } catch(e){ console.error('invalid JSON',file,e.message); process.exit(1); }",
+            "let failed=false;",
+            "if(draft.schemaVersion!==1){ console.error(file+': schemaVersion must be 1'); failed=true; }",
+            "for (const key of ['featureId','taskId','runId','finalVerification','operations','payload','gates']) {",
+            "  if(draft[key]===undefined||draft[key]===null){ console.error(file+': missing '+key); failed=true; }",
+            "}",
+            "if(draft.featureId!==featureId){ console.error(file+': featureId must be '+featureId+' got '+draft.featureId); failed=true; }",
+            "if(!Array.isArray(draft.operations)||draft.operations.length===0){ console.error(file+': operations must be non-empty array'); failed=true; }",
+            "const prefix='features/'+featureId+'/';",
+            "for (const op of draft.operations||[]) {",
+            "  const t=op&&op.target; if(typeof t!=='string'){ console.error('op missing target'); failed=true; continue; }",
+            "  const ok=t===prefix.slice(0,-1)||t.startsWith(prefix)||t.startsWith('docs/test-reports/');",
+            "  if(!ok){ console.error('op.target outside feature bind: '+t); failed=true; }",
+            "}",
+            "const highRisk=(draft.operations||[]).some((op)=>op && op.risk==='high');",
+            "if(draft.gates && draft.gates.blockIfFinalVerificationNotPass && draft.finalVerification!=='pass' && draft.finalVerification!=='pass-with-waivers'){",
+            "  console.error(file+': finalVerification is not pass'); failed=true;",
+            "}",
+            "if(highRisk && draft.gates && draft.gates.requireHumanIfHighRisk){",
+            "  console.log(file+': high-risk ops present; human approval required before/while apply');",
+            "}",
+            "if(failed) process.exit(1);",
+            "console.log('knowledge-sync validate ok '+file);",
+        ].join("")),
+    ].join(" ");
+    return {
+        id: "knowledge-sync-validate-shell",
+        depends_on: ["knowledge-sync-draft-pi"],
+        role: "verifier",
+        executor: "shell",
+        complexity: "LOW",
+        writePolicy: "read-only",
+        allowedPaths: [
+            ...commonReadOnlyPaths(sources),
+            `features/${featureId}/testing/sync/pending/**`,
+        ],
+        forbiddenPaths: commonForbiddenPaths(sources),
+        outputContract: `Deterministic validation of ${draftPath} (schema, featureId bind, operation targets, finalVerification gate); no worktree writes.`,
+        subtask_prompt: `Validate only ${draftPath} for featureId=${featureId} before apply.`,
+        shell: {
+            commands: [validateScript],
+            verifyEvidence: buildVerifyEvidence({
+                phase: "final",
+                quota: "full",
+                commandSource: "inline",
+                fallbackCommands: [validateScript],
+                finalFullRequired: true,
+                commandTimeoutMs: 120_000,
+            }),
+            cwd: ".",
+            timeoutMs: 120000,
+        },
+    };
+}
+export const KNOWLEDGE_SYNC_MULTI_REVIEW_PERSPECTIVES = [
+    {
+        id: "qa",
+        perspective: "QA / acceptance",
+        focus: [
+            "acceptanceVerdict and AC coverage vs evidencePointers",
+            "caseIndex completeness and non-invented pass results",
+            "defects registry consistency with open issues",
+        ],
+    },
+    {
+        id: "domain",
+        perspective: "domain / product",
+        focus: [
+            "requirement-delta risk and silent requirement rewrites",
+            "operations[] targets stay under the bound featureId",
+            "business meaning of coverage/matrix changes",
+        ],
+    },
+    {
+        id: "evidence",
+        perspective: "evidence / audit",
+        focus: [
+            "finalVerification authority is shell evidence, not prose",
+            "high-risk ops and gates.requireHumanIfHighRisk",
+            "draft schema fields and pointer-only log policy",
+        ],
+    },
+];
+export function buildKnowledgeSyncMultiReviewNodes(sources, featureId) {
+    return buildMultiPerspectiveReviewNodes({
+        sources,
+        dependsOn: ["knowledge-sync-validate-shell"],
+        nodePrefix: "knowledge-sync-review-",
+        gateId: "knowledge-sync-multi-review-gate-shell",
+        gateLabel: "knowledge-sync multi-perspective review",
+        perspectives: KNOWLEDGE_SYNC_MULTI_REVIEW_PERSPECTIVES,
+        allowedPaths: [
+            ...commonReadOnlyPaths(sources),
+            `features/${featureId}/**`,
+            "docs/test-reports/**",
+        ],
+        sharedBrief: [
+            `Bound featureId: ${featureId}. Only review draft/ops for this Feature.`,
+            `Primary draft path: ${knowledgeSyncDraftRelPath(featureId)}.`,
+            "Apply is blocked until all perspectives pass. Do not approve fabricated verification pass.",
+        ],
+        structuredVerdictGate: true,
+    });
+}
+export function buildKnowledgeSyncApplyNode(sources, featureId) {
+    const writeSet = knowledgeSyncWriteSet(featureId);
+    const draftPath = knowledgeSyncDraftRelPath(featureId);
+    return {
+        id: "knowledge-sync-apply-pi",
+        depends_on: ["knowledge-sync-multi-review-gate-shell"],
+        role: "implementer",
+        executor: "pi",
+        toolProfile: "write",
+        complexity: "HIGH",
+        writePolicy: "exclusive",
+        writeSet,
+        allowedPaths: writeSet,
+        forbiddenPaths: [
+            ...commonForbiddenPaths(sources),
+            "src/**",
+            "knowledge/testing/standards/**",
+            "conftest.py",
+            "pytest.ini",
+            "pyproject.toml",
+        ],
+        subtask_prompt: [
+            "Apply the validated knowledge-sync draft into the Feature testing knowledge base (L1).",
+            `Bound featureId: ${featureId}. Only touch features/${featureId}/ and docs/test-reports/** (writeSet is exclusive).`,
+            `From ${draftPath}, upsert under features/${featureId}/:`,
+            "- testing/acceptance-verdict.yaml",
+            "- testing/coverage-matrix.yaml",
+            "- testing/cases/** and index.yaml when payload includes caseIndex",
+            "- testing/automation-map.yaml",
+            "- testing/defects/registry.yaml and open.md",
+            "- testing/closeout-testing.md and retrospectives when provided",
+            `- features/${featureId}/requirement-delta.md only as draft/proposal unless operations mark approved product change`,
+            "Never modify other features/**, knowledge/testing/standards/**, src/**, or pytest framework files.",
+            "Do not invent AC pass without evidencePointers. Keep raw logs as pointers only.",
+            "If high-risk requirement changes lack approval, write requirement-delta.md as draft and do not merge into requirement.md/acceptance.yaml.",
+            "Stay within writeSet.",
+            buildSourceContextBlock(sources),
+        ].join("\n\n"),
+    };
+}
+export function buildKnowledgeSyncPointerNode(sources, featureId) {
+    const writeSet = knowledgeSyncPointerWriteSet(featureId);
+    return {
+        id: "knowledge-sync-pointer-pi",
+        depends_on: ["knowledge-sync-apply-pi"],
+        role: "closeout",
+        executor: "pi",
+        toolProfile: "write",
+        complexity: "MED",
+        writePolicy: "exclusive",
+        writeSet,
+        allowedPaths: writeSet,
+        forbiddenPaths: commonForbiddenPaths(sources),
+        subtask_prompt: [
+            "Write knowledge-sync audit pointers after apply.",
+            `Update features/${featureId}/testing/runs/latest.md with runId, headSha, finalVerification, maturity, evidence paths, and applied artifact refs.`,
+            `Write features/${featureId}/testing/sync/applied/KS-<timestamp>.json summarizing applied operations and source draft hash/path.`,
+            "Do not rewrite acceptance-verdict or cases here unless only adding pointer fields already applied.",
+            "Stay within writeSet. Do not touch other features. Read-only regarding src/** and .harness/**.",
+            buildSourceContextBlock(sources),
+        ].join("\n\n"),
+    };
+}
+export function buildKnowledgeSyncHybridDag(sources) {
+    const { taskConfig } = sources;
+    const featureId = resolveKnowledgeSyncFeatureId(sources);
+    const globalConstraints = [
+        ...taskConfig.hardConstraints,
+        ...(sources.constraintMarkdown
+            ? [`See 执行约束.md in task source (${sources.taskId})`]
+            : []),
+        ...STANDARD_GLOBAL_CONSTRAINTS,
+        `knowledge-sync-dag is bound to featureId=${featureId}; writes only features/${featureId}/testing/**, features/${featureId}/requirement-delta.md, and docs/test-reports/**.`,
+        "knowledge-sync must not modify other features/**, src/**, .harness/**, knowledge/testing/standards/**, or pytest framework files.",
+        "Apply is blocked unless knowledge-sync-validate-shell and multi-perspective review gate pass; final verification evidence remains the completion authority.",
+        "Multi-perspective review: QA/acceptance, domain/product, and evidence/audit must each emit VERDICT: pass before apply.",
+        "High-risk requirement/acceptance body changes require human approval via requirement-delta; do not silently rewrite requirement.md.",
+        "Raw shell logs stay as path pointers; knowledge base stores stable facts only.",
+        "Prefer structured YAML/Markdown L1 knowledge pack over vector-store-only writes.",
+    ];
+    const multiReview = buildKnowledgeSyncMultiReviewNodes(sources, featureId);
+    const spec = {
+        version: 2,
+        title: `Knowledge-sync DAG (${featureId}): ${taskConfig.title}`,
+        outputLanguage: sources.outputLanguage ?? DEFAULT_DAG_OUTPUT_LANGUAGE,
+        objective: extractObjective(sources.requirementMarkdown, taskConfig.title),
+        successCriteria: extractSuccessCriteria(sources.requirementMarkdown, sources.taskId),
+        globalConstraints,
+        defaults: {
+            ...KNOWLEDGE_SYNC_DEFAULTS,
+            contextProfile: taskConfig.contextProfile,
+        },
+        skillsByRole: KNOWLEDGE_SYNC_SKILLS_BY_ROLE,
+        executorModels: sources.executorModelMatrix ?? DEFAULT_DAG_EXECUTOR_MODELS,
+        tasks: [
+            buildKnowledgeSyncCollectNode(sources, featureId),
+            buildKnowledgeSyncDraftNode(sources, featureId),
+            buildKnowledgeSyncValidateNode(sources, featureId),
+            ...multiReview,
+            buildKnowledgeSyncApplyNode(sources, featureId),
+            buildKnowledgeSyncPointerNode(sources, featureId),
+        ],
+    };
+    stampGeneratedArtifactBindings(spec);
+    parseDagSpec(spec);
+    assertValidDagSpec(spec);
+    return spec;
+}

package/dist/workflows/dag/hybrid/templates/shared.js

@@ -0,0 +1,101 @@
+import { DEFAULT_READ_ONLY_PI_RETRY_POLICY, PLANNER_OUTPUT_LIMIT_RETRY_POLICY, PROTOCOL_AWARE_PI_RETRY_POLICY, TARGET_TEMPLATE_WRITER_TRANSPORT_RETRY_POLICY, WRITER_TRANSPORT_RETRY_POLICY, isSafeReadOnlyPiRetryCandidate, isTargetTemplateImplementPi, isWriterTransportRetryCandidate } from "../../retry-policy.js";
+import { FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID } from "../../frontend-implementation-contract.js";
+import { mergeForbiddenPaths } from "../sources.js";
+export function commonReadOnlyPaths(sources) {
+    return sources.taskConfig.allowedPaths.length > 0
+        ? sources.taskConfig.allowedPaths
+        : ["**"];
+}
+export function commonForbiddenPaths(sources) {
+    return mergeForbiddenPaths(sources.taskConfig);
+}
+export function applyDefaultReadOnlyRetryPolicy(spec) {
+    for (const task of spec.tasks) {
+        if (task.retryPolicy !== undefined)
+            continue;
+        if (isSafeReadOnlyPiRetryCandidate(task)) {
+            task.retryPolicy = task.outputProtocol
+                ? PROTOCOL_AWARE_PI_RETRY_POLICY
+                : task.role === "planner"
+                    ? PLANNER_OUTPUT_LIMIT_RETRY_POLICY
+                    : DEFAULT_READ_ONLY_PI_RETRY_POLICY;
+            continue;
+        }
+        if (isTargetTemplateImplementPi(task)) {
+            task.retryPolicy = TARGET_TEMPLATE_WRITER_TRANSPORT_RETRY_POLICY;
+            continue;
+        }
+        if (isWriterTransportRetryCandidate(task)) {
+            task.retryPolicy = WRITER_TRANSPORT_RETRY_POLICY;
+        }
+    }
+}
+export function stampGeneratedArtifactBindings(spec) {
+    const producedByNode = new Map();
+    for (const task of spec.tasks) {
+        if ((task.producesArtifacts?.length ?? 0) > 0) {
+            for (const artifact of task.producesArtifacts ?? []) {
+                producedByNode.set(task.id, artifact.artifactId);
+            }
+            continue;
+        }
+        const gate = task.shell?.jsonArtifactGate;
+        const structured = task.structuredContractOutput;
+        if (!gate && !structured)
+            continue;
+        const artifactId = `${task.id}.structured-output`;
+        const path = gate
+            ? `${gate.outputDir}/${gate.artifactName}`
+            : `contracts/candidates/${task.id}/canonical-contract.json`;
+        task.producesArtifacts = [
+            {
+                artifactId,
+                kind: "structured",
+                path,
+                mediaType: "application/json",
+                schemaId: gate?.schemaId ?? FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID,
+                revisionPolicy: "replace-file",
+            },
+        ];
+        producedByNode.set(task.id, artifactId);
+    }
+    for (const task of spec.tasks) {
+        const existing = new Set((task.consumesArtifacts ?? []).map((binding) => binding.artifactId));
+        const generated = task.depends_on.flatMap((parentNodeId) => {
+            const artifactId = producedByNode.get(parentNodeId);
+            if (!artifactId || existing.has(artifactId))
+                return [];
+            existing.add(artifactId);
+            return [
+                {
+                    artifactId,
+                    required: task.dependsPolicy !== "all-or-condition-skip",
+                },
+            ];
+        });
+        if (generated.length > 0) {
+            task.consumesArtifacts = [...(task.consumesArtifacts ?? []), ...generated];
+        }
+    }
+}
+export function mapTaskComplexity(complexity) {
+    if (complexity === "small")
+        return "LOW";
+    if (complexity === "large")
+        return "HIGH";
+    return "MED";
+}
+export function isFrontendTestPathPattern(entry) {
+    const segments = entry.replaceAll("\\", "/").split("/");
+    return segments.some((segment) => /^(?:test|tests|spec|specs|e2e|__tests__|__specs__)$/i.test(segment));
+}
+export function replaceSourceSegmentWithTestSegment(entry) {
+    const normalized = entry.replaceAll("\\", "/");
+    const segments = normalized.split("/");
+    const sourceIndex = segments.findIndex((segment) => /^(?:src|source|app|lib)$/i.test(segment));
+    if (sourceIndex < 0)
+        return null;
+    const testSegments = [...segments];
+    testSegments[sourceIndex] = "test";
+    return testSegments.join("/");
+}