@tea-agent/loop-agent 0.44.0-next.12 → 0.44.0-next.14

package/dist/workflows/dag/hybrid/templates/frontend-test.js

@@ -5,6 +5,7 @@ import { assertValidDagSpec } from "../../validate.js";
 import { DEFAULT_DAG_EXECUTOR_MODELS, DEFAULT_DAG_OUTPUT_LANGUAGE, parseDagSpec } from "../../types.js";
 import { pathMatchesPattern } from "../../../../shared/git-progress.js";
 import { applyFrontendTestLayoutToText, resolveFrontendTestLayout } from "../../frontend-test-layout.js";
+import { isHarnessNamespacePath } from "../../test-artifact-namespace.js";
 import { buildFrontendTestOutcomeGateShellSnippet } from "../../frontend-test-result-contract.js";
 import { GENERATED_DAG_RUNTIME_CONTRACT, HYBRID_DEFAULTS, STANDARD_GLOBAL_CONSTRAINTS, buildDagSourceBinding, buildSourceContextBlock, extractObjective, extractSuccessCriteria, resolveDagVerifyStrategy } from "../sources.js";
 import { applyDefaultReadOnlyRetryPolicy, commonForbiddenPaths, commonReadOnlyPaths, stampGeneratedArtifactBindings, } from "./shared.js";
@@ -62,7 +63,7 @@ export function buildFrontendTestHybridDag(sources) {
     const maxCasesPerBatchLiteral = String(config.maxCasesPerBatch);
     const checklistScript = [
         "const fs=require('fs'),path=require('path');",
-        "const root='testcase/frontend/cases';",
+        `const root='${layout.casesDir}';`,
         "const draft=path.join(root,'manifest.draft.json');",
         "const final=path.join(root,'manifest.json');",
         "const manifestPath=fs.existsSync(draft)?draft:(fs.existsSync(final)?final:null);",
@@ -84,8 +85,8 @@ export function buildFrontendTestHybridDag(sources) {
         " if(typeof c.caseId==='string'&&/^AC-/i.test(c.caseId))issues.push({ruleId:'case-id-is-ac',caseId:id,detail:'do not use acceptance id as caseId; put AC-FE-* only in acIds'});",
         " const casePath=typeof c.casePath==='string'?c.casePath:null;",
         " if(!casePath||!fs.existsSync(casePath)){issues.push({ruleId:'case-file-missing',caseId:id,detail:String(casePath)});continue;}",
-        " if(typeof c.caseId==='string'&&casePath!=='testcase/frontend/cases/'+c.caseId+'.md')issues.push({ruleId:'case-path-mismatch',caseId:id,detail:casePath+' must equal testcase/frontend/cases/'+c.caseId+'.md'});",
-        " const body=fs.readFileSync(casePath,'utf8');",
+        " if(typeof c.caseId==='string'&&casePath!=='${layout.casesDir}/'+c.caseId+'.md')issues.push({ruleId:'case-path-mismatch',caseId:id,detail:casePath+' must equal ${layout.casesDir}/'+c.caseId+'.md'});",
+        " const body=fs.readFileSync(casePath,'utf8').replace(/\\bplaywright_cli\\b/g,'playwright-cli');",
         " if(!openRe.test(body))issues.push({ruleId:'open-prefix',caseId:id,detail:'missing playwright-cli open --browser=chrome <absolute-url>; playwright-cli is strongly recommended for browser execution'});",
         ,
         " const m=body.match(/playwright-cli\\s+open\\s+--browser=chrome\\s+(https?:\\/\\/\\S+)/i);",
@@ -117,7 +118,7 @@ export function buildFrontendTestHybridDag(sources) {
         JSON.stringify([
             "const fs=require('fs'),path=require('path');",
             "function fail(ruleId,detail){ const msg=JSON.stringify({ruleId:ruleId,detail:String(detail||'')}); console.error('frontend-test manifest blocked: '+msg); throw new Error('frontend-test manifest blocked: '+ruleId+(detail?(': '+detail):'')); }",
-            "const draft='testcase/frontend/cases/manifest.draft.json',file='testcase/frontend/cases/manifest.json',tmp=file+'.tmp';",
+            `const draft='${layout.casesDir}/manifest.draft.json',file='${layout.casesDir}/manifest.json',tmp=file+'.tmp';`,
             "if(!fs.existsSync(draft)) fail('draft-missing','missing '+draft);",
             "let manifest; try{manifest=JSON.parse(fs.readFileSync(draft,'utf8'));}catch(e){fail('draft-invalid-json',e&&e.message||e);}",
             "if(manifest.schemaVersion!==1) fail('draft-schema','schemaVersion must be 1');",
@@ -138,8 +139,8 @@ export function buildFrontendTestHybridDag(sources) {
             " if(typeof c.dimension!=='string'||!dims.has(c.dimension)) fail('invalid-dimension',String(c.dimension));",
             " if(!Array.isArray(c.acIds)||c.acIds.length===0||c.acIds.some(a=>typeof a!=='string'||!a.trim())) fail('ac-mapping','invalid acIds for '+c.caseId);",
             " for(const ac of c.acIds){ if(!acIdRe.test(ac)) fail('ac-id-shape','acIds entry must be AC-* acceptance id, not caseId: '+ac); if(truncatedAcRe.test(ac)||(declaredAc.size===0&&truncatedUndeclaredAcRe.test(ac))) fail('ac-id-truncated','acIds entry is a truncated acceptance id (missing feature prefix or sequence number): '+ac); if(declaredAc.size>0&&!declaredAc.has(ac)) fail('unknown-ac',ac+' not in sourceBinding; repair generator input or AC list'); }",
-            " c.casePath='testcase/frontend/cases/'+c.caseId+'.md';",
-            " c.evidenceDir='testcase/frontend/evidence/'+c.caseId+'/';",
+            ` c.casePath='${layout.casesDir}/'+c.caseId+'.md';`,
+            ` c.evidenceDir='${layout.evidenceDir}/'+c.caseId+'/';`,
             " for(const k of ['casePath','evidenceDir']){ const v=c[k]; if(typeof v!=='string'||path.isAbsolute(v)||v.includes('..')) fail('unsafe-path',k+': '+String(v)); }",
             " if(!fs.existsSync(c.casePath)) fail('case-file-missing','missing case file '+c.casePath+' (filename must equal caseId.md)');",
             " if(seenCasePath.has(c.casePath)) fail('duplicate-case-path',c.casePath); seenCasePath.add(c.casePath);",
@@ -158,7 +159,7 @@ export function buildFrontendTestHybridDag(sources) {
             "const runDir=process.env.HARNESS_DAG_RUN_DIR; if(!runDir)throw new Error('missing HARNESS_DAG_RUN_DIR');",
             "const resultPath=path.join(runDir,'contracts','frontend-test-result.json'); if(!fs.existsSync(resultPath))throw new Error('missing '+resultPath);",
             "const r=JSON.parse(fs.readFileSync(resultPath,'utf8')); const findings=Array.isArray(r.advisoryFindings)?r.advisoryFindings:[];",
-            "const reports='testcase/frontend/reports'; fs.mkdirSync(reports,{recursive:true});",
+            `const reports='${layout.reportsDir}'; fs.mkdirSync(reports,{recursive:true});`,
             "const esc=v=>String(v??'').replaceAll('&','&amp;').replaceAll('<','&lt;').replaceAll('>','&gt;').replaceAll('\\\"','&quot;');",
             "const labels={cases:'用例总数',passed:'通过',failed:'失败',blocked:'阻塞'}; const totals=r.totals||{}; const missing=r.acceptanceCoverage&&Array.isArray(r.acceptanceCoverage.missing)?r.acceptanceCoverage.missing:[];",
             "const md=['# 前端测试质量建议报告','','> Advisory：以下 finding 用于改进测试资产和证据质量，不阻塞后续流程。','','## 执行摘要','',...Object.entries(labels).map(([k,v])=>'- '+v+': '+Number(totals[k]||0)),'- 执行结果: '+String(r.outcome||'unknown'),'- 缺失 AC: '+(missing.join(', ')||'无'),'','## 建议项','',...(findings.length?findings.map(f=>'- ['+f.ruleId+']'+(f.caseId?' '+f.caseId:'')+': '+f.detail):['- 未发现建议项。']),''];",
@@ -197,7 +198,7 @@ export function buildFrontendTestHybridDag(sources) {
             writeSet: ragWriteSet,
             allowedPaths: [...ragWriteSet],
             forbiddenPaths: forbidden,
-            outputContract: "Write testcase/frontend/rag/standard-scenarios.v1.json for generate-time standard scenario coverage. Copy docs/templates or harness.json governanceRoot templates (including ai_workspace/loop-agent/templates) when present; otherwise write the minimal STD-FE-SMOKE-ENTRY fallback.",
+            outputContract: `Write ${layout.ragDir}/standard-scenarios.v1.json for generate-time standard scenario coverage. Copy docs/templates or harness.json governanceRoot templates (including ai_workspace/loop-agent/templates) when present; otherwise write the minimal STD-FE-SMOKE-ENTRY fallback.`,
             subtask_prompt: "Prepare frontend-test package: materialize standard-scenarios.v1.json into the RAG package from docs/templates, governanceRoot/templates, or the init-projected ai_workspace/loop-agent/templates path.",
             shell: {
                 commands: [],
@@ -218,10 +219,10 @@ export function buildFrontendTestHybridDag(sources) {
             writeSet: ragWriteSet,
             allowedPaths: [...commonReadOnlyPaths(sources), ...ragWriteSet],
             forbiddenPaths: forbidden,
-            outputContract: "Write short testcase/frontend/rag/context.md and coverage-map.md with a model-resolved non-production baseUrl/baseUrlSource from task source config, environmentProbe=pending, and capability notes.",
+            outputContract: `Write short ${layout.ragDir}/context.md and coverage-map.md with a model-resolved non-production baseUrl/baseUrlSource from task source config, environmentProbe=pending, and capability notes.`,
             subtask_prompt: [
                 "Build the frontend test RAG package (keep it short).",
-                "Read task source, routes/components/API or Mock facts, and execution contract. Write only testcase/frontend/rag/context.md and coverage-map.md.",
+                `Read task source, routes/components/API or Mock facts, and execution contract. Write only ${layout.ragDir}/context.md and coverage-map.md.`,
                 "Prefer fixed fields: baseUrl, baseUrlSource, environmentProbe, AC table, capability matrix (backend real/mock, pagination data, HTTP observation, error injection), risks, forbidden hosts. Do not paste large implementation dumps.",
                 "Base URL resolution (required): read the bound task source and config/environment references. Prefer TARGET_URL/targetUrl as the concrete tested entry, then BASE_URL/baseUrl or FRONTEND_BASE_URL/frontendUrl, then LOGIN_URL/loginUrl; accept common casing and underscore/kebab/space variants. Choose one absolute non-production http(s) URL, never API-only or production hosts. If no usable URL exists, use http://localhost:5173. Write `baseUrl: <url>`, `baseUrlSource: <bound source path>|default-localhost-5173`, and `environmentProbe: pending`. Include exact start prefix: playwright-cli open --browser=chrome <resolved-base-url> with the concrete selected URL.",
                 buildSourceContextBlock(sources),
@@ -238,7 +239,7 @@ export function buildFrontendTestHybridDag(sources) {
             allowedPaths: [...ragWriteSet],
             forbiddenPaths: forbidden,
             outputContract: "Fail-closed environment preflight: absolute non-production baseUrl + curl HTTP reachability; writes environmentProbe facts; unreachable => blockedReason frontend-base-url-unreachable with errorClass (connection-refused / dns-unresolved / connect-timeout / http-N / curl-exit-N). Node ERROR so generate/map do not run. Does not start the app.",
-            subtask_prompt: "Parse the resolved absolute baseUrl from testcase/frontend/rag/context.md, reject production/non-http(s)/credential/query/fragment URLs, then probe it with curl HEAD and GET fallback (connect/max-time; no auth/cookie). 2xx/3xx => reachable and continue. Connection refused (curl 7) records errorClass=connection-refused and tells the operator to start the local app (scripts/serve.sh or npm start) then rerun from this node. 4xx/5xx/DNS/timeout/TLS => blockedReason frontend-base-url-unreachable with a distinct errorClass. Missing curl => blockedReason curl-unavailable. Do not start the app. Fixture/reset remain soft guidance.",
+            subtask_prompt: `Parse the resolved absolute baseUrl from ${layout.ragDir}/context.md, reject production/non-http(s)/credential/query/fragment URLs, then probe it with curl HEAD and GET fallback (connect/max-time; no auth/cookie). 2xx/3xx => reachable and continue. Connection refused (curl 7) records errorClass=connection-refused and tells the operator to start the local app (scripts/serve.sh or npm start) then rerun from this node. 4xx/5xx/DNS/timeout/TLS => blockedReason frontend-base-url-unreachable with a distinct errorClass. Missing curl => blockedReason curl-unavailable. Do not start the app. Fixture/reset remain soft guidance.`,
             shell: {
                 commands: [],
                 frontendTestEnvironmentProbe: {},
@@ -261,22 +262,22 @@ export function buildFrontendTestHybridDag(sources) {
             outputContract: "Write executable Markdown frontend cases, index.md, and manifest.draft.json schemaVersion 1 only; the exclusive shell materializer promotes the validated draft to manifest.json. Do not write manifest.json or test source code.",
             subtask_prompt: [
                 "Use skill playwright-cli-case-generator.",
-                "Read testcase/frontend/rag/standard-scenarios.v1.json and cover priority=must scenarios (or record GAP in coverage-map). Include ## 测试点 and ## 测试步骤 in each case.",
+                `Read ${layout.ragDir}/standard-scenarios.v1.json and cover priority=must scenarios (or record GAP in coverage-map). Include ## 测试点 and ## 测试步骤 in each case.`,
                 ...(uiAnchorsLedgerInstruction ? [uiAnchorsLedgerInstruction] : []),
-                "Read only testcase/frontend/rag/context.md, testcase/frontend/rag/coverage-map.md, and the draft case paths testcase/frontend/cases/FE-*.md, testcase/frontend/cases/index.md, and testcase/frontend/cases/manifest.draft.json. Write only those same draft paths. Do not write testcase/frontend/cases/manifest.json.",
+                `Read only ${layout.ragDir}/context.md, ${layout.ragDir}/coverage-map.md, and the draft case paths ${layout.casesDir}/FE-*.md, ${layout.casesDir}/index.md, and ${layout.casesDir}/manifest.draft.json. Write only those same draft paths. Do not write ${layout.casesDir}/manifest.json.`,
                 "Generate Markdown cases, index.md and manifest.draft.json (schemaVersion 1; cases[] with caseId, casePath, dimension, acIds, evidenceDir).",
                 "HARD ID CONTRACT (do not confuse these):",
                 "- caseId / filename MUST be FE-<FEATURE>-<NNN>-<dimension> (example FE-LOGIN-001-core). NEVER use AC-FE-* as caseId or filename.",
                 "- acIds MUST list acceptance criteria only: AC-FE-* / AC-* from the declared task list (example AC-FE-001). NEVER put FE-* case ids into acIds.",
-                "- casePath MUST equal testcase/frontend/cases/<caseId>.md; evidenceDir MUST equal testcase/frontend/evidence/<caseId>/. Materialize will rewrite paths, but files must already use caseId filenames.",
+                `- casePath MUST equal ${layout.casesDir}/<caseId>.md; evidenceDir MUST equal ${layout.evidenceDir}/<caseId>/. Materialize will rewrite paths, but files must already use caseId filenames.`,
                 `Declared acceptance ids for this task (use only these in acIds when non-empty): ${declaredAcIds.length > 0 ? declaredAcIds.join(", ") : "(none extracted - still use AC-* shape, never FE-* case ids)"}.`,
                 "dimensions: core|boundary|flow|backend only.",
                 "Prefer a small smoke suite (default max roughly 4-8 cases unless task frontendTest.maxCasesPerBatch is higher). Never invent unavailable API fields or credentials. Do not create pytest or Playwright source.",
                 "HARD playwright-cli-only: every browser step must use repo skill playwright-cli declared commands only. Forbidden: bare `playwright`, `npx playwright`, `playwright test`, `@playwright/test`, Node Playwright API, or generating Playwright/Pytest source. No fallback when playwright-cli is unavailable - case must instruct blocked evidence playwright-cli-unavailable.",
-                "Copy the resolved absolute baseUrl from testcase/frontend/rag/context.md after the environment probe has marked it reachable. Every browser start command must be exactly: playwright-cli open --browser=chrome <resolved-base-url-from-context.md> with that concrete URL. Never leave a base-url placeholder. Use default browser session only; never write -s=<case-id>.",
+                `Copy the resolved absolute baseUrl from ${layout.ragDir}/context.md after the environment probe has marked it reachable. Every browser start command must be exactly: playwright-cli open --browser=chrome <resolved-base-url-from-context.md> with that concrete URL. Never leave a base-url placeholder. Use default browser session only; never write -s=<case-id>.`,
                 "HARD dynamic refs: executable playwright-cli lines must never contain an angle-bracket token such as <fresh-ref> or descriptive <...> placeholder. Use only shell-safe documentation placeholders `eX`, `eY`, ...; each means the real `eNN` ref parsed from the immediately preceding latest `snapshot`. Write a fresh snapshot before every element reference. eX/eY are never literal structured-tool arguments; a later snapshot invalidates prior refs, so never reuse stale refs.",
                 "HARD file-output argv: use canonical `--filename` only. Screenshot uses `playwright-cli screenshot --filename final.png` (a real ref may precede the flag); PDF uses `playwright-cli pdf --filename final.pdf`; snapshot without filename is response-only and a snapshot file uses `playwright-cli snapshot --filename snapshot.txt`. Never generate `playwright-cli screenshot <path>`, use `--path`, `--output`, or `--file`, or pass an output path as a positional target.",
-                "Each case must be independently reproducible with fixture/reset, UI reset, snapshot-before-ref, evidence write point under testcase/frontend/evidence/<case-id>/. If the isolated environment is unavailable, require writing blocked evidence before any browser command.",
+                `Each case must be independently reproducible with fixture/reset, UI reset, snapshot-before-ref, evidence write point under ${layout.evidenceDir}/<case-id>/. If the isolated environment is unavailable, require writing blocked evidence before any browser command.`,
                 "U/D data ownership (required for modify/delete): (1) Only mutate data whose ownership is proven by current login identity + observable UI/API owner fields - never by name/guessed id/list order alone. (2) If current user has no data, create tagged cleanable data in current-user context, then U/D, then cleanup+verify. (3) Else only task-authorized Mock, labeled as Mock (not real backend proof). (4) If ownership unverifiable and create/Mock unavailable: write blocked with blockedReason current-user-data-unavailable | data-ownership-unverifiable | safe-test-data-setup-unavailable - do not risk cross-user data. (5) Never touch other users, shared fixtures, production, or non-cleanable data.",
             ].join("\n\n"),
         },
@@ -307,7 +308,7 @@ export function buildFrontendTestHybridDag(sources) {
             allowedPaths: [...ragWriteSet, ...caseDraftWriteSet],
             forbiddenPaths: forbidden,
             outputContract: "Apply the one permitted frontend case revision to FE-*.md, index.md, and manifest.draft.json only; the exclusive shell materializer remains the sole writer of manifest.json. No browser execution or evidence writes.",
-            subtask_prompt: "This is the only permitted case revision. Read the first review findings and the RAG package. Revise only testcase/frontend/cases/FE-*.md, testcase/frontend/cases/index.md, and testcase/frontend/cases/manifest.draft.json; preserve traceable AC mappings. Preserve the dynamic-ref contract: executable playwright-cli lines use only eX/eY-style shell-safe documentation placeholders, never <...>; each placeholder is resolved from the immediately preceding latest snapshot and stale refs are not reused. Do not write testcase/frontend/cases/manifest.json, execute a browser, or write evidence. HARD: Never delete case files; only edit in place or add missing cases. Preserve the full planned suite, index.md, and manifest.draft.json.",
+            subtask_prompt: `This is the only permitted case revision. Read the first review findings and the RAG package. Revise only ${layout.casesDir}/FE-*.md, ${layout.casesDir}/index.md, and ${layout.casesDir}/manifest.draft.json; preserve traceable AC mappings. Preserve the dynamic-ref contract: executable playwright-cli lines use only eX/eY-style shell-safe documentation placeholders, never <...>; each placeholder is resolved from the immediately preceding latest snapshot and stale refs are not reused. Do not write ${layout.casesDir}/manifest.json, execute a browser, or write evidence. HARD: Never delete case files; only edit in place or add missing cases. Preserve the full planned suite, index.md, and manifest.draft.json.`,
         }, {
             id: "review-frontend-cases-final-pi",
             depends_on: ["revise-frontend-cases-pi"],
@@ -411,9 +412,9 @@ export function buildFrontendTestHybridDag(sources) {
                 writePolicy: "exclusive",
                 writeGuardPolicy: "tools-only",
                 allowedPaths: [
-                    "testcase/frontend/cases/{{case.caseId}}.md",
-                    "testcase/frontend/rag/context.md",
-                    "testcase/frontend/rag/coverage-map.md",
+                    `${layout.casesDir}/{{case.caseId}}.md`,
+                    `${layout.ragDir}/context.md`,
+                    `${layout.ragDir}/coverage-map.md`,
                     `${evidenceRoot}/{{case.caseId}}/**`,
                 ],
                 forbiddenPaths: forbidden,
@@ -422,7 +423,7 @@ export function buildFrontendTestHybridDag(sources) {
                 subtaskPromptTemplate: [
                     "Primary job: EXECUTE case {{case.caseId}} from {{case.casePath}} with skill playwright-cli (fresh Pi session; do not use /new). playwright-cli-only: never bare Playwright CLI/API/test runner; no fallback.",
                     "Use the structured playwright_cli tool for every browser action. Do not request or search for bash. Do not execute raw shell commands. Translate each playwright-cli line in the case Markdown into one playwright_cli tool call ({command, args?, timeoutSeconds?}).",
-                    "1) Read the concrete baseUrl from testcase/frontend/rag/context.md; it has already passed the environment shell safety/reachability gate. Start browser ONLY via playwright_cli command=open with args [--browser=chrome, <that-concrete-baseUrl>] (default session only; no -s=). 2) Dynamic refs: eX/eY in case Markdown are documentation placeholders, never tool args. Immediately before every structured playwright_cli call that references an element, parse the current real eNN from the immediately preceding latest snapshot and pass only that real eNN; never send literal `eX`/`eY`. A new snapshot invalidates prior refs, so never reuse stale refs. File outputs are canonical: screenshot args [--filename, final.png] (or [e5, --filename, final.png] for a real target), PDF args [--filename, final.pdf], and snapshot writes a file only with [--filename, snapshot.txt]; snapshot without filename is response-only. Never use --path, --output, --file, or any output path as a positional target. Follow case steps with snapshot before element refs using only playwright_cli. A passed case requires this same child receipt order: successful open → successful find → controller post-execution cleanup. Only successful find is a meaningful assertion; snapshot, goto, screenshot, request/console, click/fill and other ordinary interactions cannot establish passed authority. 3) Only when preflight or playwright_cli tool explicitly fails may you write blocked evidence (blockedReason playwright-cli-unavailable | frontend-base-url-unreachable); never invent CLI-unavailable solely because bash is absent. Unique-control early stop: when an AC names a specific control that is absent from the first post-navigation snapshot after reaching the required state (and no setup-required gate appeared), do ONE find with the case's literal as evidence; if it returns 0 matches, record status=blocked with blockedReason unique-control-unavailable citing that single find - do NOT re-explore with alternative literals, repeated snapshots, navigation detours, or rerun loops. 4) For U/D: enforce current-user ownership / create-or-mock-or-blocked; never mutate other users' data.",
+                    `1) Read the concrete baseUrl from ${layout.ragDir}/context.md; it has already passed the environment shell safety/reachability gate. Start browser ONLY via playwright_cli command=open with args [--browser=chrome, <that-concrete-baseUrl>] (default session only; no -s=). 2) Dynamic refs: eX/eY in case Markdown are documentation placeholders, never tool args. Immediately before every structured playwright_cli call that references an element, parse the current real eNN from the immediately preceding latest snapshot and pass only that real eNN; never send literal \`eX\`/\`eY\`. A new snapshot invalidates prior refs, so never reuse stale refs. File outputs are canonical: screenshot args [--filename, final.png] (or [e5, --filename, final.png] for a real target), PDF args [--filename, final.pdf], and snapshot writes a file only with [--filename, snapshot.txt]; snapshot without filename is response-only. Never use --path, --output, --file, or any output path as a positional target. Follow case steps with snapshot before element refs using only playwright_cli. A passed case requires this same child receipt order: successful open → successful find → controller post-execution cleanup. Only successful find is a meaningful assertion; snapshot, goto, screenshot, request/console, click/fill and other ordinary interactions cannot establish passed authority. 3) Only when preflight or playwright_cli tool explicitly fails may you write blocked evidence (blockedReason playwright-cli-unavailable | frontend-base-url-unreachable); never invent CLI-unavailable solely because bash is absent. Unique-control early stop: when an AC names a specific control that is absent from the first post-navigation snapshot after reaching the required state (and no setup-required gate appeared), do ONE find with the case's literal as evidence; if it returns 0 matches, record status=blocked with blockedReason unique-control-unavailable citing that single find - do NOT re-explore with alternative literals, repeated snapshots, navigation detours, or rerun loops. 4) For U/D: enforce current-user ownership / create-or-mock-or-blocked; never mutate other users' data.`,
                     "Always write {{case.evidenceDir}}execution.md and {{case.evidenceDir}}case-result.json with caseId={{case.caseId}}, status passed|failed|blocked, evidencePaths (relative under evidenceDir). blocked needs non-empty blockedReason. After writing, self-check the same contract; if self-check fails, rewrite both files as status=blocked blockedReason=invalid-evidence-shape (never leave missing/malformed evidence).",
                     "Business failed/blocked is a recorded result, not a node failure. Close browser via playwright_cli command=close. Return compact JSON (<=1200 chars): {caseId,status,evidencePaths,errorSummary,tokens}.",
                 ].join("\n\n"),
@@ -442,11 +443,11 @@ export function buildFrontendTestHybridDag(sources) {
             : `rerun-candidates-round${round}.json`;
         const selectCommand = [
             "const fs=require('fs'),path=require('path');",
-            "const manifestPath='testcase/frontend/cases/manifest.json';",
+            `const manifestPath='${layout.casesDir}/manifest.json';`,
             "if(!fs.existsSync(manifestPath)){process.stdout.write(JSON.stringify({cases:[]}));process.exit(0);}",
             "const manifest=JSON.parse(fs.readFileSync(manifestPath,'utf8'));const cases=[];",
-            "for(const c of (manifest.cases||[])){const evidenceDir=(c.evidenceDir||('testcase/frontend/evidence/'+c.caseId+'/')).replace(/\\/+$/,'')+'/';const resultPath=path.join(evidenceDir,'case-result.json');const execPath=path.join(evidenceDir,'execution.md');let reason=null;let attempt=0;let missing=false;if(!fs.existsSync(resultPath)){missing=true;reason='missing-result-files';}else{try{const r=JSON.parse(fs.readFileSync(resultPath,'utf8'));attempt=Number(r.rerunAttempt||0)||0;if(r.status==='blocked')reason='blocked';if(r.status==='failed')reason='failed-retry';if(!r.status){missing=true;reason='missing-result-files';}}catch(_){missing=true;reason='missing-result-files';}}if(!fs.existsSync(execPath)&&reason!=='blocked'){missing=true;reason=reason||'missing-result-files';}const should=(reason==='blocked'||reason==='failed-retry'||missing)&&attempt<" + String(round) + ";if(should){cases.push({caseId:c.caseId,casePath:c.casePath||('testcase/frontend/cases/'+c.caseId+'.md'),evidenceDir,dimension:c.dimension||'core',acIds:c.acIds||[],rerunAttempt:attempt+1,reason:reason||'blocked'});}}",
-            `fs.mkdirSync('testcase/frontend/evidence',{recursive:true});fs.writeFileSync('testcase/frontend/evidence/${candidateArtifact}',JSON.stringify({schemaVersion:1,cases},null,2)+'\\n');process.stdout.write(JSON.stringify({cases}));`,
+            `for(const c of (manifest.cases||[])){const evidenceDir=(c.evidenceDir||('${layout.evidenceDir}/'+c.caseId+'/')).replace(/\\/+$/,'')+'/';const resultPath=path.join(evidenceDir,'case-result.json');const execPath=path.join(evidenceDir,'execution.md');let reason=null;let attempt=0;let missing=false;if(!fs.existsSync(resultPath)){missing=true;reason='missing-result-files';}else{try{const r=JSON.parse(fs.readFileSync(resultPath,'utf8'));attempt=Number(r.rerunAttempt||0)||0;if(r.status==='blocked')reason='blocked';if(r.status==='failed')reason='failed-retry';if(!r.status){missing=true;reason='missing-result-files';}}catch(_){missing=true;reason='missing-result-files';}}if(!fs.existsSync(execPath)&&reason!=='blocked'){missing=true;reason=reason||'missing-result-files';}const should=(reason==='blocked'||reason==='failed-retry'||missing)&&attempt<` + String(round) + `;if(should){cases.push({caseId:c.caseId,casePath:c.casePath||('${layout.casesDir}/'+c.caseId+'.md'),evidenceDir,dimension:c.dimension||'core',acIds:c.acIds||[],rerunAttempt:attempt+1,reason:reason||'blocked'});}}`,
+            `fs.mkdirSync('${layout.evidenceDir}',{recursive:true});fs.writeFileSync('${layout.evidenceDir}/${candidateArtifact}',JSON.stringify({schemaVersion:1,cases},null,2)+'\\n');process.stdout.write(JSON.stringify({cases}));`,
         ].join("");
         tasks.push({
             id: selectorId,
@@ -455,8 +456,8 @@ export function buildFrontendTestHybridDag(sources) {
             executor: "shell",
             complexity: "LOW",
             writePolicy: "exclusive",
-            writeSet: ["testcase/frontend/evidence/**"],
-            allowedPaths: [...casesWriteSet, "testcase/frontend/evidence/**"],
+            writeSet: [`${evidenceRoot}/**`],
+            allowedPaths: [...casesWriteSet, `${evidenceRoot}/**`],
             forbiddenPaths: forbidden,
             outputContract: `Stdout JSON {cases} for blocked or missing-result-file cases eligible for rerun round ${round}/${maxRerunAttempts}.`,
             subtask_prompt: "Select frontend-test cases eligible for this bounded rerun round.",
@@ -501,9 +502,9 @@ export function buildFrontendTestHybridDag(sources) {
                     writePolicy: "exclusive",
                     writeGuardPolicy: "tools-only",
                     allowedPaths: [
-                        "testcase/frontend/cases/{{case.caseId}}.md",
-                        "testcase/frontend/rag/context.md",
-                        "testcase/frontend/rag/coverage-map.md",
+                        `${layout.casesDir}/{{case.caseId}}.md`,
+                        `${layout.ragDir}/context.md`,
+                        `${layout.ragDir}/coverage-map.md`,
                         `${evidenceRoot}/{{case.caseId}}/**`,
                     ],
                     forbiddenPaths: forbidden,
@@ -512,7 +513,7 @@ export function buildFrontendTestHybridDag(sources) {
                     subtaskPromptTemplate: [
                         "RERUN attempt {{case.rerunAttempt}} for {{case.caseId}} (reason={{case.reason}}). Rewrite the authoritative execution.md and case-result.json; its final status replaces the earlier case result.",
                         "Primary job: EXECUTE case {{case.caseId}} from {{case.casePath}} with skill playwright-cli (fresh Pi session). Use structured playwright_cli only; headless open.",
-                        "Read the concrete baseUrl from testcase/frontend/rag/context.md and start via playwright_cli command=open with args [--browser=chrome, <that-concrete-baseUrl>]. Passed requires open → find → cleanup receipts.",
+                        `Read the concrete baseUrl from ${layout.ragDir}/context.md and start via playwright_cli command=open with args [--browser=chrome, <that-concrete-baseUrl>]. Passed requires open → find → cleanup receipts.`,
                         "Unique-control early stop: if the first post-navigation snapshot lacks the control an AC names (and no setup-required gate appeared), one find returning 0 matches is sufficient evidence - write status=blocked blockedReason unique-control-unavailable instead of exploratory retries.",
                         "Always write {{case.evidenceDir}}execution.md and {{case.evidenceDir}}case-result.json with caseId, status, evidencePaths, rerunAttempt={{case.rerunAttempt}}. Write fixed sections `### 执行摘要` and `### 实际执行步骤` to execution.md when available.",
                     ].join("\n\n"),
@@ -531,7 +532,7 @@ export function buildFrontendTestHybridDag(sources) {
         complexity: "LOW",
         writePolicy: "exclusive",
         writeSet: [`${evidenceRoot}/**`],
-        allowedPaths: ["testcase/frontend/cases/**", `${evidenceRoot}/**`],
+        allowedPaths: [`${layout.casesDir}/**`, `${evidenceRoot}/**`],
         forbiddenPaths: forbidden,
         outputContract: "Evidence validation (advisory missing/malformed does not fail the node; hard-fail only path escape) then hash-bound frontend-test-result-v1. Node success means result-v1 was written, not that all cases passed.",
         subtask_prompt: "Validate case evidence then materialize authoritative frontend-test-result-v1. Missing/malformed case evidence is advisory; only unsafe evidence paths hard-fail. Do not use Pi prose as input.",
@@ -549,8 +550,8 @@ export function buildFrontendTestHybridDag(sources) {
         executor: "shell",
         complexity: "LOW",
         writePolicy: "exclusive",
-        writeSet: ["testcase/frontend/reports/**"],
-        allowedPaths: ["testcase/frontend/**"],
+        writeSet: [`${layout.reportsDir}/**`],
+        allowedPaths: [`${layout.testRoot}/**`],
         forbiddenPaths: forbidden,
         outputContract: "Deterministic L-5 (optional) plus main frontend-test-report.md/html from frontend-test-result-v1. Pipeline acceptance = result-v1 + main HTML.",
         subtask_prompt: "Render operational reports from frontend-test-result-v1 only. Do not invent coverage. Main HTML is required; L-5 follows frontendTest.reports.l5.",
@@ -596,10 +597,10 @@ export function buildFrontendTestHybridDag(sources) {
             complexity: "MED",
             writePolicy: "exclusive",
             writeGuardPolicy: "tools-only",
-            writeSet: ["testcase/frontend/reports/**"],
-            allowedPaths: ["testcase/frontend/**"],
+            writeSet: [`${layout.reportsDir}/**`],
+            allowedPaths: [`${layout.testRoot}/**`],
             forbiddenPaths: forbidden,
-            outputContract: "Optional retrospective under testcase/frontend/reports/frontend-test-retrospect-<date>.md. Not required for pipeline acceptance.",
+            outputContract: `Optional retrospective under ${layout.reportsDir}/frontend-test-retrospect-<date>.md. Not required for pipeline acceptance.`,
             subtask_prompt: "Write optional frontend-test retrospective after result + reports. Do not recompute L-5. Pipeline success does not require this file.",
         });
     }
@@ -617,7 +618,7 @@ export function buildFrontendTestHybridDag(sources) {
         "Environment preflight must parse the retrieve-authored context.md baseUrl, reject unsafe/non-production violations, and curl-probe it before generate; unreachable or curl-unavailable ends preflight as blocked (frontend-base-url-unreachable|curl-unavailable) so generate/map do not run.",
         "U/D cases must prove current-user data ownership or create cleanable current-user data or authorized Mock; otherwise blocked (current-user-data-unavailable|data-ownership-unverifiable|safe-test-data-setup-unavailable) without cross-user mutation.",
         "Token settings are post-case stop thresholds, never a hard provider token cap. Unstarted cases after a threshold are blocked: token-budget-exhausted.",
-        "Pipeline acceptance for frontend-test is frontend-test-result-v1 plus the main report under testcase/frontend/reports/frontend-test-report.html; case pass rate and outcome=passed are quality signals; retrospect is opt-in (frontendTest.reports.retrospect).",
+        `Pipeline acceptance for frontend-test is frontend-test-result-v1 plus the main report under ${layout.reportsDir}/frontend-test-report.html; case pass rate and outcome=passed are quality signals; retrospect is opt-in (frontendTest.reports.retrospect).`,
         blockingReview
             ? "frontendTest.reviewMode=blocking: a frontend case review must emit VERDICT: pass before checklist/manifest materialization; request-revision blocks browser execution."
             : "frontendTest.reviewMode is off|advisory by default: mechanical checklist-shell gates materialize/execute; LLM review is not a hard browser gate.",
@@ -639,23 +640,43 @@ export function buildFrontendTestHybridDag(sources) {
         },
         skillsByRole: {
             planner: [],
-            scout: ["playwright-cli"],
-            implementer: ["playwright-cli"],
+            scout: ["builtin:playwright-cli"],
+            implementer: ["builtin:playwright-cli"],
             reviewer: [],
-            verifier: ["playwright-cli"],
-            closeout: ["verification-before-completion"],
+            verifier: ["builtin:playwright-cli"],
+            closeout: ["builtin:verification-before-completion"],
         },
         executorModels: sources.executorModelMatrix ?? DEFAULT_DAG_EXECUTOR_MODELS,
         verifyStrategy: resolveDagVerifyStrategy(sources.taskConfig),
         tasks,
     };
     applyFrontendTestLayoutToDagSpec(spec, layout);
+    applyFrontendTestHarnessRootGuard(spec, layout);
     applyDefaultReadOnlyRetryPolicy(spec);
     stampGeneratedArtifactBindings(spec);
     parseDagSpec(spec);
     assertValidDagSpec(spec);
     return spec;
 }
+/**
+ * D4: when the frozen frontend-test root lives under `.harness/` the whole tree
+ * is Git-ignored, so Git-status write guards would see empty diffs for real
+ * writes. Flip every file-writing node (and the dynamic browser child) from
+ * tools-only to the bounded filesystem snapshot channel instead.
+ */
+export function applyFrontendTestHarnessRootGuard(spec, layout) {
+    if (!isHarnessNamespacePath(layout.testRoot))
+        return;
+    for (const task of spec.tasks) {
+        if (task.writeGuardPolicy === "tools-only") {
+            task.writeGuardPolicy = "filesystem-only";
+        }
+        const child = task.dynamicExpansion?.childTask;
+        if (child?.writeGuardPolicy === "tools-only") {
+            child.writeGuardPolicy = "filesystem-only";
+        }
+    }
+}
 export function applyFrontendTestLayoutToDagSpec(spec, layout) {
     if (layout.isDefault) {
         spec.frontendTestLayout = layout;

package/dist/workflows/dag/hybrid/templates/kg-bootstrap.js

@@ -8,12 +8,12 @@ export const KG_BOOTSTRAP_DEFAULTS = {
     writePolicy: "read-only",
 };
 export const KG_BOOTSTRAP_SKILLS_BY_ROLE = {
-    planner: ["loop-agent"],
-    scout: ["codebase-scout"],
-    implementer: ["verification-before-completion"],
-    reviewer: ["requesting-code-review"],
-    verifier: ["verification-before-completion", "systematic-debugging"],
-    closeout: ["loop-agent", "verification-before-completion"],
+    planner: ["builtin:loop-agent"],
+    scout: ["builtin:codebase-scout"],
+    implementer: ["builtin:verification-before-completion"],
+    reviewer: ["builtin:requesting-code-review"],
+    verifier: ["builtin:verification-before-completion", "builtin:systematic-debugging"],
+    closeout: ["builtin:loop-agent", "builtin:verification-before-completion"],
 };
 export function buildKgBootstrapInlineNodeScript(lines) {
     return ["node", "-e", JSON.stringify(lines.join(""))].join(" ");

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

@@ -7,12 +7,12 @@ export const KNOWLEDGE_SYNC_DEFAULTS = {
     writePolicy: "read-only",
 };
 export const KNOWLEDGE_SYNC_SKILLS_BY_ROLE = {
-    planner: ["loop-agent"],
+    planner: ["builtin:loop-agent"],
     scout: [],
-    implementer: ["verification-before-completion"],
-    reviewer: ["requesting-code-review"],
-    verifier: ["verification-before-completion", "systematic-debugging"],
-    closeout: ["loop-agent", "verification-before-completion"],
+    implementer: ["builtin:verification-before-completion"],
+    reviewer: ["builtin:requesting-code-review"],
+    verifier: ["builtin:verification-before-completion", "builtin:systematic-debugging"],
+    closeout: ["builtin:loop-agent", "builtin:verification-before-completion"],
 };
 export function buildMultiPerspectiveReviewAggregateScript(fromNodeIds, label) {
     if (fromNodeIds.length === 0) {

package/dist/workflows/dag/skill-instructions.js

@@ -3,9 +3,20 @@ import { access, readFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { builtinSkillReferenceResourceId, builtinSkillResourceId, createControllerContextProvider, } from "../../governance/resource-catalog.js";
 export const DEFAULT_SKILL_INSTRUCTION_MAX_CHARS = 3_000;
 export const DEFAULT_SKILL_INSTRUCTION_TOTAL_MAX_CHARS = 12_000;
 const SKILL_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+const SKILL_REFERENCE_PATTERN = /^(?:(builtin|project|user):)?([A-Za-z0-9][A-Za-z0-9_-]*)$/;
+function parseSkillReference(reference) {
+    const match = SKILL_REFERENCE_PATTERN.exec(reference);
+    if (!match)
+        return undefined;
+    return {
+        ...(match[1] ? { source: match[1] } : {}),
+        name: match[2],
+    };
+}
 async function fileExists(filePath) {
     try {
         await access(filePath);
@@ -35,22 +46,26 @@ function bundledSkillCandidatePaths(name) {
 }
 function buildSkillCandidatePaths(input) {
     const candidates = [];
-    const agentDir = input.env.PI_CODING_AGENT_DIR;
-    if (agentDir) {
-        candidates.push(normalizeCandidate(path.join(agentDir, "skills", input.name, "SKILL.md")), normalizeCandidate(path.join(agentDir, "skills", `${input.name}.md`)));
+    if (!input.source || input.source === "user") {
+        const agentDir = input.env.PI_CODING_AGENT_DIR;
+        if (agentDir) {
+            candidates.push(normalizeCandidate(path.join(agentDir, "skills", input.name, "SKILL.md")), normalizeCandidate(path.join(agentDir, "skills", `${input.name}.md`)));
+        }
+        const piSkillsDir = path.join(input.homeDir, ".pi", "agent", "skills");
+        candidates.push(normalizeCandidate(path.join(piSkillsDir, input.name, "SKILL.md")), normalizeCandidate(path.join(piSkillsDir, `${input.name}.md`)));
     }
-    const piSkillsDir = path.join(input.homeDir, ".pi", "agent", "skills");
-    candidates.push(normalizeCandidate(path.join(piSkillsDir, input.name, "SKILL.md")), normalizeCandidate(path.join(piSkillsDir, `${input.name}.md`)));
-    // Canonical target-project repo-local skill path.
-    candidates.push(normalizeCandidate(path.join(input.cwd, ".agents", "skills", input.name, "SKILL.md")));
-    // Source-repository compatibility: the loop-agent package itself still ships
-    // bundled skills under `skills/`, and local source development may resolve them
-    // before the package fallback is found.
-    candidates.push(normalizeCandidate(path.join(input.cwd, "skills", input.name, "SKILL.md")));
-    if (input.name === "loop-agent") {
-        candidates.push(normalizeCandidate(path.join(input.cwd, "skill", "SKILL.md")));
+    if (!input.source || input.source === "project") {
+        // Canonical target-project repo-local skill path.
+        candidates.push(normalizeCandidate(path.join(input.cwd, ".agents", "skills", input.name, "SKILL.md")));
+        // Legacy project-local Skill path. Explicit builtin references never consult it.
+        candidates.push(normalizeCandidate(path.join(input.cwd, "skills", input.name, "SKILL.md")));
+        if (input.name === "loop-agent") {
+            candidates.push(normalizeCandidate(path.join(input.cwd, "skill", "SKILL.md")));
+        }
+    }
+    if (!input.source || input.source === "builtin") {
+        candidates.push(...bundledSkillCandidatePaths(input.name));
     }
-    candidates.push(...bundledSkillCandidatePaths(input.name));
     return Array.from(new Set(candidates));
 }
 const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
@@ -207,7 +222,7 @@ async function resolveSkillReferences(input) {
             });
             continue;
         }
-        if (!(await fileExists(resolvedPath))) {
+        if (!input.packageSkill && !(await fileExists(resolvedPath))) {
             unresolvedReferences.push({
                 name,
                 path: refPath,
@@ -216,7 +231,13 @@ async function resolveSkillReferences(input) {
             continue;
         }
         try {
-            const content = await readFile(resolvedPath, "utf-8");
+            const packageResource = input.packageSkill
+                ? await input.packageSkill.provider.readText(builtinSkillReferenceResourceId(input.packageSkill.name, refPath))
+                : undefined;
+            const content = packageResource?.text ?? await readFile(resolvedPath, "utf-8");
+            if (packageResource && path.resolve(packageResource.absolutePath) !== resolvedPath) {
+                throw new Error(`catalog path mismatch for ${refPath}`);
+            }
             const contentSha256 = sha256(content);
             const bytes = Buffer.byteLength(content, "utf-8");
             const budget = Math.max(0, Math.min(declaration.maxChars ?? input.perReferenceMaxChars, remainingTotal));
@@ -224,7 +245,7 @@ async function resolveSkillReferences(input) {
             input.resolvedReferencePaths.add(resolvedPath);
             references.push({
                 name,
-                path: resolvedPath,
+                path: packageResource?.id ?? resolvedPath,
                 sha256: contentSha256,
                 bytes,
                 ...(truncated ? { truncated: true } : {}),
@@ -232,7 +253,7 @@ async function resolveSkillReferences(input) {
             remainingTotal = Math.max(0, remainingTotal - Math.min(content.length, budget));
             sections.push([
                 `Reference: ${name}`,
-                `Path: ${resolvedPath}`,
+                `${packageResource ? "Resource" : "Path"}: ${packageResource?.id ?? resolvedPath}`,
                 `Sha256: ${contentSha256}`,
                 excerpt,
             ].join("\n"));
@@ -263,7 +284,7 @@ function buildResolvedPromptText(input) {
     const lines = [
         `Skill: ${input.name}`,
         "Resolution: resolved",
-        `Path: ${input.filePath}`,
+        `${input.locationKind}: ${input.location}`,
         `Sha256: ${input.contentSha256}`,
         "Injection mode: bounded-inline",
         "Instructions:",
@@ -308,29 +329,62 @@ export async function resolveDagSkillInstructions(skills, options) {
     let remainingTotal = options.totalMaxChars ?? DEFAULT_SKILL_INSTRUCTION_TOTAL_MAX_CHARS;
     const resolved = [];
     const resolvedReferencePaths = new Set();
+    let packageProvider;
     for (const name of skills) {
-        if (!SKILL_NAME_PATTERN.test(name)) {
+        const reference = parseSkillReference(name);
+        if (!reference || !SKILL_NAME_PATTERN.test(reference.name)) {
             const error = `invalid skill name: ${name}`;
             resolved.push({
                 name,
                 resolution: "error",
+                sourceKind: "auto",
                 error,
                 injectionMode: "name-only",
                 promptText: buildErrorPromptText({ name, error }),
             });
             continue;
         }
-        const searchedPaths = buildSkillCandidatePaths({
-            name,
-            cwd: options.cwd,
-            env,
-            homeDir,
-        });
-        const filePath = await findFirstExistingFile(searchedPaths);
+        let packageContent;
+        let filePath;
+        let searchedPaths = [];
+        if (reference.source === "builtin") {
+            const logicalResourceId = builtinSkillResourceId(reference.name);
+            try {
+                packageProvider ??= await createControllerContextProvider();
+                const resource = await packageProvider.readText(logicalResourceId);
+                filePath = resource.absolutePath;
+                packageContent = resource.text;
+                searchedPaths = [resource.absolutePath];
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                resolved.push({
+                    name,
+                    resolution: "error",
+                    sourceKind: "builtin",
+                    logicalResourceId,
+                    error: message,
+                    injectionMode: "name-only",
+                    promptText: buildErrorPromptText({ name, error: message }),
+                });
+                continue;
+            }
+        }
+        else {
+            searchedPaths = buildSkillCandidatePaths({
+                name: reference.name,
+                ...(reference.source ? { source: reference.source } : {}),
+                cwd: options.cwd,
+                env,
+                homeDir,
+            });
+            filePath = await findFirstExistingFile(searchedPaths);
+        }
         if (!filePath) {
             resolved.push({
                 name,
                 resolution: "missing",
+                sourceKind: reference.source ?? "auto",
                 searchedPaths,
                 injectionMode: "name-only",
                 promptText: buildMissingPromptText({ name, searchedPaths }),
@@ -338,7 +392,7 @@ export async function resolveDagSkillInstructions(skills, options) {
             continue;
         }
         try {
-            const content = await readFile(filePath, "utf-8");
+            const content = packageContent ?? await readFile(filePath, "utf-8");
             const { frontmatter, body } = splitSkillFrontmatter(content);
             const instructionContent = frontmatter ? body : content;
             const referenceDeclarations = frontmatter
@@ -354,11 +408,17 @@ export async function resolveDagSkillInstructions(skills, options) {
                 remainingTotal,
                 perReferenceMaxChars: perSkillMaxChars,
                 resolvedReferencePaths,
+                ...(reference.source === "builtin" && packageProvider
+                    ? { packageSkill: { name: reference.name, provider: packageProvider } }
+                    : {}),
             });
             remainingTotal = afterReferences;
             const { promptText, truncated } = buildResolvedPromptText({
                 name,
-                filePath,
+                location: reference.source === "builtin"
+                    ? builtinSkillResourceId(reference.name)
+                    : filePath,
+                locationKind: reference.source === "builtin" ? "Resource" : "Path",
                 content: instructionContent,
                 contentSha256,
                 bytes,
@@ -368,7 +428,13 @@ export async function resolveDagSkillInstructions(skills, options) {
             resolved.push({
                 name,
                 resolution: "resolved",
-                path: filePath,
+                sourceKind: reference.source ?? "auto",
+                ...(reference.source === "builtin" && packageProvider
+                    ? {
+                        logicalResourceId: builtinSkillResourceId(reference.name),
+                        catalogDigest: packageProvider.identity.catalogDigest,
+                    }
+                    : { path: filePath }),
                 sha256: contentSha256,
                 bytes,
                 truncated,
@@ -385,14 +451,18 @@ export async function resolveDagSkillInstructions(skills, options) {
             resolved.push({
                 name,
                 resolution: "error",
-                path: filePath,
+                sourceKind: reference.source ?? "auto",
+                ...(reference.source === "builtin"
+                    ? { logicalResourceId: builtinSkillResourceId(reference.name) }
+                    : { path: filePath }),
                 error: message,
                 injectionMode: "name-only",
                 promptText: buildErrorPromptText({ name, error: message }),
             });
         }
     }
-    if (options.includeLearnedPatterns && skills.includes("loop-agent")) {
+    if (options.includeLearnedPatterns
+        && skills.some((skill) => skill === "loop-agent" || skill === "builtin:loop-agent")) {
         const learned = await resolveLearnedPatternInstructions({
             cwd: options.cwd,
             maxChars: Math.max(0, Math.min(perSkillMaxChars, remainingTotal)),

package/dist/workflows/dag/skill-snapshot.js

@@ -32,6 +32,9 @@ const unresolvedReferenceSchema = z.object({
 const resolvedInstructionSchema = z.object({
     name: z.string().min(1),
     resolution: z.enum(["resolved", "missing", "error"]),
+    sourceKind: z.enum(["builtin", "project", "user", "auto"]).optional(),
+    logicalResourceId: z.string().min(1).optional(),
+    catalogDigest: z.string().regex(/^[a-f0-9]{64}$/).optional(),
     path: z.string().min(1).optional(),
     sha256: z.string().regex(/^[a-f0-9]{64}$/).optional(),
     bytes: z.number().int().nonnegative().optional(),