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

package/dist/worker/console/workspace-initialization.js

@@ -70,7 +70,7 @@ export class WorkspaceInitializationService {
             }
             const surface = await this.jsonFile(".harness/init-surface.json");
             const harness = await this.jsonFile("harness.json");
-            if (surface && (surface.schemaVersion !== 1 || !surface.files || typeof surface.files !== "object" || Array.isArray(surface.files))) {
+            if (surface && (![1, 2].includes(Number(surface.schemaVersion)) || !surface.files || typeof surface.files !== "object" || Array.isArray(surface.files))) {
                 throw new Error("初始化记录不完整，请检查 .harness/init-surface.json");
             }
             if (!surface && !harness) {
@@ -83,10 +83,15 @@ export class WorkspaceInitializationService {
                 }
                 return snapshot;
             }
-            const report = await this.command(["init", "check-update", "--json"], "check");
+            const report = await this.command(["init", "check-update", "--legacy-audit", "--json"], "check");
             if (!["recorded", "inferred-baseline", "missing"].includes(String(report.surfaceState)) || typeof report.ok !== "boolean") {
                 throw new Error("初始化检查返回了未知状态");
             }
+            const coreState = String(report.coreState);
+            const migrationState = String(report.migrationState);
+            if (!["ready", "blocked", "error"].includes(coreState) || !["clean", "retained", "review-required", "in-progress", "failed"].includes(migrationState)) {
+                throw new Error("初始化检查缺少核心或迁移状态");
+            }
             const actions = entries(report.deterministicActions);
             const merges = entries(report.modelMergeTasks);
             const decisions = entries(report.humanDecisions);
@@ -98,17 +103,20 @@ export class WorkspaceInitializationService {
                     const detail = typeof item.reason === "string" ? item.reason : undefined;
                     const baseline = item.type === "bootstrap-surface";
                     const itemKind = baseline ? "confirmation" : kind;
+                    const legacyCandidate = typeof item.candidateId === "string";
                     const reason = baseline ? "缺少可靠的初始化记录，不能直接判断哪些内容可覆盖。"
-                        : kind === "safe-update" ? "此项可由程序安全更新，保留项目自定义内容。"
-                            : kind === "merge" ? "现有内容与新版初始化模板不同，需要保留项目配置后合并。"
-                                : /not a directory/.test(detail ?? "") ? "这里需要一个目录，但当前路径被文件占用。"
-                                    : /removed.*local changes/.test(detail ?? "") ? "新版不再使用此文件，但它包含本地修改，需要决定保留还是删除。"
-                                        : /target path.*already exists/.test(detail ?? "") ? "迁移目标已有不同内容，需要确认两份文件如何保留。"
-                                            : "此项无法安全自动处理，请先核对检查详情，再确定处理方式。";
+                        : legacyCandidate ? "这是历史初始化候选，但当前证据不足以自动删除。"
+                            : kind === "safe-update" ? "此项可由程序安全更新，保留项目自定义内容。"
+                                : kind === "merge" ? "现有内容与新版初始化模板不同，需要保留项目配置后合并。"
+                                    : /not a directory/.test(detail ?? "") ? "这里需要一个目录，但当前路径被文件占用。"
+                                        : /removed.*local changes/.test(detail ?? "") ? "新版不再使用此文件，但它包含本地修改，需要决定保留还是删除。"
+                                            : /target path.*already exists/.test(detail ?? "") ? "迁移目标已有不同内容，需要确认两份文件如何保留。"
+                                                : "此项无法安全自动处理，请先核对检查详情，再确定处理方式。";
                     pendingItems.push({ path: item.path, kind: itemKind, reason,
                         nextStep: itemKind === "safe-update" ? "点击更新按钮即可处理。"
                             : itemKind === "merge" ? "可将下方处理说明交给智能体合并；只有需求冲突时才需你确认。"
-                                : "将处理说明交给智能体检查；需要取舍时确认方案，处理后重新检查。",
+                                : legacyCandidate ? "在对话页手动调用 /skill:init-update；Skill 会解释证据并在需要时询问，不会直接删除文件。"
+                                    : "将处理说明交给智能体检查；需要取舍时确认方案，处理后重新检查。",
                         ...(detail ? { detail } : {}) });
                 }
             }
@@ -118,19 +126,20 @@ export class WorkspaceInitializationService {
                     reason: "当前模型配置或认证尚未就绪，更新文件不能解决此问题。",
                     nextStep: "检查模型定义及提供商认证，保留仍可用的模型配置，完成后重新检查。" });
             const canUpdate = pendingItems.some(item => item.kind === "safe-update");
-            const needsAttention = pendingItems.some(item => item.kind !== "safe-update") || !report.ok || report.surfaceState !== "recorded" && !canUpdate;
+            const needsAttention = pendingItems.some(item => item.kind !== "safe-update") || coreState !== "ready" || migrationState === "review-required" || migrationState === "failed" || report.surfaceState !== "recorded" && !canUpdate;
             if (needsAttention || canUpdate) {
                 const safeCount = pendingItems.filter(item => item.kind === "safe-update").length;
+                const coreReadyPrefix = coreState === "ready" ? "核心初始化已就绪；" : "";
                 const message = canUpdate
-                    ? `有 ${safeCount} 项可在此更新。${needsAttention ? "其余待处理项的原因和下一步见下方。" : "更新会保留项目自定义内容。"}`
-                    : "暂无可直接更新的内容。请按下方原因处理，完成后重新检查。";
+                    ? `${coreReadyPrefix}有 ${safeCount} 项可在此安全更新。${needsAttention ? "其余旧初始化待处理项见下方。" : "更新会保留项目自定义内容。"}`
+                    : `${coreReadyPrefix}暂无可直接更新的内容。请按下方原因处理，完成后重新检查。`;
                 if (!pendingItems.length)
                     pendingItems.push({ path: "初始化配置", kind: "confirmation",
                         reason: "检查尚未通过，但没有返回可自动更新的项目。",
                         nextStep: "复制处理说明交给智能体检查初始化记录，完成后重新检查。" });
-                return { ...this.snapshot(needsAttention ? "needs-attention" : "update-available", message, [...new Set(pendingItems.map(item => item.path))]), canUpdate, pendingItems };
+                return { ...this.snapshot(needsAttention ? "needs-attention" : "update-available", message, [...new Set(pendingItems.map(item => item.path))]), canUpdate, pendingItems, coreState: coreState, migrationState: migrationState };
             }
-            return this.snapshot("ready", "工作区配置已就绪");
+            return { ...this.snapshot("ready", migrationState === "retained" ? "核心初始化已就绪；旧初始化内容已按决定保留。" : "工作区配置已就绪"), coreState: coreState, migrationState: migrationState };
         }
         catch (error) {
             return this.snapshot("error", error instanceof Error ? error.message : "初始化状态检查失败");
@@ -182,10 +191,10 @@ export class WorkspaceInitializationService {
             if (before.state === "uninitialized") {
                 if (!model || !before.models?.some(item => item.reference === model))
                     throw new Error("请选择一个可用的初始模型；可在模型设置中完成认证后重新检查");
-                await this.command(["init", "--profile", "full", "--merge", "--client-recovery", "project", "--model", model, "--json"], "apply");
+                await this.command(["init", "--merge", "--model", model, "--json"], "apply");
             }
             else if (before.canUpdate) {
-                await this.command(["init", "update", "--apply-safe", "--client-recovery", "project", "--json"], "apply");
+                await this.command(["init", "update", "--apply-safe", "--legacy-audit", "--json"], "apply");
             }
             else if (before.state !== "ready")
                 throw new Error("没有可安全更新的内容；请查看待处理项的原因和下一步。");

package/dist/worker/delivery/package.js

@@ -48,12 +48,15 @@ const controllerIdentityEvidenceSchema = z.object({
     reportedVersion: z.string().min(1).optional(),
     packageFingerprint: z.object({
         algorithm: z.literal("sha256"),
-        scopeVersion: z.literal(1),
+        scopeVersion: z.literal(2),
         scope: z.tuple([
             z.literal("package.json"),
             z.literal("bin/**"),
             z.literal("dist/**"),
             z.literal("skills/**"),
+            z.literal("docs/templates/**"),
+            z.literal("resources/**"),
+            z.literal("resource-catalog.v1.json"),
         ]),
         value: z.string().regex(/^sha256:[a-f0-9]{64}$/),
         fileCount: z.number().int().positive(),

package/dist/worker/observe/static/operator-chrome.js

@@ -12,8 +12,7 @@
  */
 
 import { withWorkspaceQuery } from "./router.js";
-import { CONSOLE_THEMES, applyStoredConsoleTheme, setConsoleTheme } from "./console-theme.js";
-export { CONSOLE_THEMES } from "./console-theme.js";
+import { applyStoredConsoleTheme } from "./console-theme.js";
 
 export const OPERATE_TABS = Object.freeze([
 	{ id: "tasks", label: "任务", href: "/#/operate/tasks" },
@@ -711,46 +710,6 @@ export function mountOperatorChrome(root, config = {}) {
 
 		global.appendChild(el("span", "och-spacer"));
 
-		const themePicker = el("div", "och-theme");
-		const trigger = el("button", "och-theme-trigger");
-		trigger.type = "button";
-		trigger.title = "主题";
-		trigger.setAttribute("aria-label", "主题");
-		trigger.appendChild(makeIcon("theme"));
-		trigger.setAttribute("aria-expanded", "false");
-		const menu = el("div", "och-theme-menu");
-		menu.id = `${popoverId}-theme`;
-		menu.popover = "auto";
-		menu.setAttribute("role", "group");
-		menu.setAttribute("aria-label", "选择主题");
-		trigger.setAttribute("aria-controls", menu.id);
-		trigger.popoverTargetElement = menu;
-		menu.addEventListener("beforetoggle", (event) => {
-			if (event.newState !== "open") return;
-			const rect = trigger.getBoundingClientRect();
-			menu.style.top = `${rect.bottom + 6}px`;
-			menu.style.left = `${Math.max(8, Math.min(rect.right - 112, window.innerWidth - 120))}px`;
-		});
-		menu.addEventListener("toggle", (event) => {
-			trigger.setAttribute("aria-expanded", String(event.newState === "open"));
-		});
-		for (const theme of CONSOLE_THEMES) {
-			const option = el("button", "och-theme-option", theme.label);
-			option.type = "button";
-			option.dataset.theme = theme.id;
-			option.setAttribute("aria-pressed", String(theme.id === (document.documentElement.dataset.consoleTheme ?? "default")));
-			option.addEventListener("click", () => {
-				setConsoleTheme(theme.id);
-				for (const item of menu.children) {
-					item.setAttribute("aria-pressed", String(item.dataset.theme === theme.id));
-				}
-				menu.hidePopover();
-				trigger.focus();
-			});
-			menu.appendChild(option);
-		}
-		themePicker.append(trigger, menu);
-		global.appendChild(themePicker);
 
 		if (model.statusVisible && model.freshness) {
 			const fresh = el("span", "och-fresh");

package/dist/workflows/dag/backend-test-pytest-collection.js

@@ -422,7 +422,10 @@ function classifyCollectionFailure(output, evidence) {
     const blockedPatterns = [
         [/No module named ['\"](?!testcase(?:\.|['\"]))/i, "missing-third-party-module"],
         [/pytest(?:_|-)plugin|pluggy|unknown hook|unrecognized arguments/i, "pytest-plugin-or-config"],
-        [/(?:apps|src|server|api)\/[A-Za-z0-9_./-]+\.py/i, "production-module-import"],
+        // Windows Python installs live under ...\WindowsApps\...; after slash
+        // normalization that path suffix must not read as an `apps/…py`
+        // production import (pytest >= 9 includes the importlib bootstrap frame).
+        [/(?<!Windows)(?:apps|src|server|api)\/[A-Za-z0-9_./-]+\.py/i, "production-module-import"],
         [/permission denied|access is denied|timed? out|not recognized as an internal|no such file or directory.*python/i, "environment-or-spawn"],
     ];
     for (const [pattern, kind] of blockedPatterns) {

package/dist/workflows/dag/final-verification.js

@@ -3,7 +3,8 @@ import os from 'node:os';
 import path from 'node:path';
 import { DEFAULT_DAG_EXECUTOR_MODELS } from './types.js';
 import { parseDagSpec } from './types.js';
-import { loadHarnessManifest } from '../../governance/harness.js';
+import { ProjectCapabilityScanner } from '../../governance/project-capability-scanner.js';
+import { loadNormalizedProjectConfig } from '../../governance/project-config.js';
 import { loadTaskConfig } from '../../task/runtime.js';
 import { resolveCliPath } from '../../shared/path-refs.js';
 const DEFAULT_OUTPUT_DIR = os.tmpdir();
@@ -22,14 +23,13 @@ export async function initFinalVerificationDagFromTask(repoRoot, taskId, options
     };
 }
 export async function buildFinalVerificationDagFromTask(repoRoot, taskId, options = {}) {
-    const [taskConfig, manifest] = await Promise.all([
-        loadTaskConfig(repoRoot, taskId),
-        loadHarnessManifest(repoRoot),
-    ]);
+    const taskConfig = await loadTaskConfig(repoRoot, taskId);
     const taskGlob = options.taskGlob ?? taskId;
     const closeoutPath = options.closeoutPath ?? path.join(os.tmpdir(), `${taskId}-closeout-report.md`);
-    const checkRepo = manifest.scripts.checkRepo ?? 'scripts/check-repo.sh';
-    const finalVerifyCommands = [`HARNESS_ALLOW_ACTIVE_DAG_RUNS=1 bash ${checkRepo}`];
+    const finalVerifyCommands = await resolveFinalVerificationCommands({
+        repoRoot,
+        taskCommands: taskConfig.verifyCommands.map((entry) => entry.command),
+    });
     const hasChangesetSignal = taskDeclaresReleaseImpact(taskConfig);
     const tasks = [
         shellTask({
@@ -142,12 +142,12 @@ export async function buildFinalVerificationDagFromTask(repoRoot, taskId, option
             executor: 'shell',
             contextProfile: 'slim',
             writePolicy: 'read-only',
-            skills: ['ai-engineering-context'],
+            skills: ['builtin:ai-engineering-context'],
         },
         executorModels: DEFAULT_DAG_EXECUTOR_MODELS,
         skillsByRole: {
-            verifier: ['verification-before-completion'],
-            closeout: ['loop-agent', 'verification-before-completion'],
+            verifier: ['builtin:verification-before-completion'],
+            closeout: ['builtin:loop-agent', 'builtin:verification-before-completion'],
         },
         tasks,
     });
@@ -178,3 +178,38 @@ function taskDeclaresReleaseImpact(taskConfig) {
     ].join('\n');
     return /changeset|release|publish|version/i.test(haystack);
 }
+export async function resolveFinalVerificationCommandSelection(input) {
+    if (input.taskCommands.length > 0) {
+        return {
+            source: 'task-contract',
+            commands: [...new Set(input.taskCommands)],
+        };
+    }
+    const verification = (await loadNormalizedProjectConfig(input.repoRoot)).verification;
+    const configured = verification.full.length > 0
+        ? verification.full
+        : verification.standard.length > 0
+            ? verification.standard
+            : verification.quick;
+    if (configured.length > 0) {
+        return {
+            source: 'project-config',
+            commands: [...new Set(configured)],
+        };
+    }
+    const scan = await new ProjectCapabilityScanner().scan(input.repoRoot);
+    const selected = scan.verification.commands.find((candidate) => candidate.id.endsWith(':test'))
+        ?? scan.verification.commands.find((candidate) => candidate.id.endsWith(':typecheck'))
+        ?? scan.verification.commands.find((candidate) => candidate.id.endsWith(':lint'))
+        ?? scan.verification.commands[0];
+    if (scan.verification.status !== 'ready' || !selected) {
+        throw new Error(`final verification is ${scan.verification.status}; add Task Contract verification or .loop-agent/project.json verification`);
+    }
+    return {
+        source: 'capability-scanner',
+        commands: [selected.command],
+    };
+}
+async function resolveFinalVerificationCommands(input) {
+    return (await resolveFinalVerificationCommandSelection(input)).commands;
+}

package/dist/workflows/dag/hybrid/sources.js

@@ -32,16 +32,16 @@ export const HYBRID_DEFAULTS = {
     executor: "pi",
     piBackend: "sdk-first",
     contextProfile: "slim",
-    skills: ["ai-engineering-context"],
+    skills: ["builtin:ai-engineering-context"],
     writePolicy: "read-only",
 };
 export const HYBRID_SKILLS_BY_ROLE = {
-    planner: ["loop-agent"],
-    scout: ["ai-engineering-context", "codebase-scout"],
-    implementer: ["test-driven-development", "verification-before-completion"],
-    reviewer: ["requesting-code-review", "code-review-core"],
-    verifier: ["verification-before-completion", "systematic-debugging"],
-    closeout: ["loop-agent", "verification-before-completion"],
+    planner: ["builtin:loop-agent"],
+    scout: ["builtin:ai-engineering-context", "builtin:codebase-scout"],
+    implementer: ["builtin:test-driven-development", "builtin:verification-before-completion"],
+    reviewer: ["builtin:requesting-code-review", "builtin:code-review-core"],
+    verifier: ["builtin:verification-before-completion", "builtin:systematic-debugging"],
+    closeout: ["builtin:loop-agent", "builtin:verification-before-completion"],
 };
 export const FRONTEND_DEFAULTS = {
     ...HYBRID_DEFAULTS,
@@ -56,13 +56,13 @@ export const FRONTEND_SKILLS_BY_ROLE = {
     verifier: [],
     closeout: [],
 };
-export const FRONTEND_CONTRACT_SKILLS = ["frontend-contract"];
-export const FRONTEND_SCOUT_SKILLS = ["frontend-scout"];
-export const FRONTEND_PLAN_SKILLS = ["frontend-plan"];
-export const FRONTEND_BOUNDED_IMPLEMENT_SKILLS = ["frontend-bounded-implement"];
-export const FRONTEND_DESIGN_REVIEW_SKILLS = ["frontend-design-review"];
-export const FRONTEND_REVIEW_SKILLS = ["frontend-review"];
-export const FRONTEND_VERIFICATION_SKILLS = ["frontend-verification"];
+export const FRONTEND_CONTRACT_SKILLS = ["builtin:frontend-contract"];
+export const FRONTEND_SCOUT_SKILLS = ["builtin:frontend-scout"];
+export const FRONTEND_PLAN_SKILLS = ["builtin:frontend-plan"];
+export const FRONTEND_BOUNDED_IMPLEMENT_SKILLS = ["builtin:frontend-bounded-implement"];
+export const FRONTEND_DESIGN_REVIEW_SKILLS = ["builtin:frontend-design-review"];
+export const FRONTEND_REVIEW_SKILLS = ["builtin:frontend-review"];
+export const FRONTEND_VERIFICATION_SKILLS = ["builtin:frontend-verification"];
 export const IMPLEMENT_WRITESET_PLACEHOLDER = "REPLACE/WITH/NARROW/IMPLEMENT/PATHS/**";
 export const GENERATED_DAG_RUNTIME_CONTRACT = {
     schemaVersion: DAG_RUNTIME_CONTRACT_SCHEMA_VERSION,

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

@@ -1787,12 +1787,12 @@ export const BACKEND_TEST_DEFAULTS = {
     writePolicy: "read-only",
 };
 export const BACKEND_TEST_SKILLS_BY_ROLE = {
-    planner: ["loop-agent"],
+    planner: ["builtin:loop-agent"],
     scout: [],
-    implementer: ["test-driven-development", "verification-before-completion"],
-    reviewer: ["requesting-code-review", "code-review-core"],
-    verifier: ["verification-before-completion", "systematic-debugging"],
-    closeout: ["loop-agent", "verification-before-completion"],
+    implementer: ["builtin:test-driven-development", "builtin:verification-before-completion"],
+    reviewer: ["builtin:requesting-code-review", "builtin:code-review-core"],
+    verifier: ["builtin:verification-before-completion", "builtin:systematic-debugging"],
+    closeout: ["builtin:loop-agent", "builtin:verification-before-completion"],
 };
 export function applyBackendTestWorkspaceControl(spec, control, layoutTestRoot, controlExplicit = false) {
     // D4: the canonical `.harness/testcase` root is Git-ignored, so a Git-status

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

@@ -640,11 +640,11 @@ 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),

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