@tea-agent/loop-agent 0.21.0 → 0.23.1

package/dist/executors/shell-executor.js

@@ -14,6 +14,7 @@ import { formatFrontendWorktreeDiffStdout, runFrontendWorktreeDiffGate, } from "
 import { formatFrontendFailureAssessStdout, formatFrontendRepairContractStdout, runFrontendFailureAssessGate, runFrontendRepairContractGate, } from "../workflows/dag/frontend-repair.js";
 import { formatFrontendPrewriteGateStdout, runFrontendPrewriteGate, } from "../workflows/dag/frontend-prewrite-gate.js";
 import { formatFrontendReviewContextStdout, runFrontendReviewContextGate, } from "../workflows/dag/frontend-review-context.js";
+import { materializeFrontendLintAssessment, materializeFrontendLintBaseline, } from "../workflows/dag/frontend-lint-baseline.js";
 import { formatTraceabilityGateStdout, materializeBackendTestCaseManifest, runBackendTestTraceabilityGate, } from "../workflows/dag/backend-test-case-manifest.js";
 import { materializeBackendTestExecutionContract } from "../workflows/dag/backend-test-execution-contract.js";
 import { materializeBackendTestResultFromRunDir, parseJunitXml } from "../workflows/dag/backend-test-result-contract.js";
@@ -381,7 +382,9 @@ async function executeBackendTestPipeline(input, meta) {
             const pytestTargets = mappedScripts.map(shellQuote).join(" ");
             const pytestCommand = [
                 'mkdir -p "${HARNESS_DAG_RUN_DIR}/reports"',
-                `PYTHONUTF8=1 PYTHONIOENCODING=utf-8 PYTHONDONTWRITEBYTECODE=1 python -m pytest ${pytestTargets} -v -p no:cacheprovider -o junit_logging=all -o junit_log_passing_tests=true --junitxml="\${HARNESS_DAG_RUN_DIR}/reports/backend-test.junit.xml"`,
+                'PYTHON_BIN="$(command -v python || command -v python3 || true)"',
+                'if [ -z "${PYTHON_BIN}" ]; then echo "python/python3 is required for backend-test execution" >&2; exit 127; fi',
+                `PYTHONUTF8=1 PYTHONIOENCODING=utf-8 PYTHONDONTWRITEBYTECODE=1 "\${PYTHON_BIN}" -m pytest ${pytestTargets} -v -p no:cacheprovider -o junit_logging=all -o junit_log_passing_tests=true --junitxml="\${HARNESS_DAG_RUN_DIR}/reports/backend-test.junit.xml"`,
                 "STATUS=$?",
                 'printf "%s" "${STATUS}" > "${HARNESS_DAG_RUN_DIR}/reports/backend-test-pytest-exit.txt"',
                 'if { [ "${STATUS}" -eq 0 ] || [ "${STATUS}" -eq 1 ]; } && [ -s "${HARNESS_DAG_RUN_DIR}/reports/backend-test.junit.xml" ]; then exit 0; fi',
@@ -411,9 +414,10 @@ async function executeBackendTestPipeline(input, meta) {
             });
             const htmlPath = await writeRunReport(meta.runDir, "backend-test.html", htmlContent);
             const facts = renderBackendTestFacts({ parsed, cases, pytestExitCode, junitRelativePath: "reports/backend-test.junit.xml", htmlRelativePath: "reports/backend-test.html", junitContent, htmlContent, caseValidationSummary, traceabilitySummary });
+            const markdownPath = await writeRunReport(meta.runDir, "backend-test.md", facts);
             const factsPath = await writeRunReport(meta.runDir, "backend-test-facts.md", facts);
             const sanitizedOutputs = results.map((result) => redactBackendTestOutput(result.stdout));
-            outputs.push(...sanitizedOutputs, `html=${htmlPath}`, `facts=${factsPath}`, facts);
+            outputs.push(...sanitizedOutputs, `html=${htmlPath}`, `markdown=${markdownPath}`, `facts=${factsPath}`, facts);
         }
         else if (pipeline === "contracts") {
             const wrapperPath = path.join(meta.runDir, "analyze-and-discover-backend-test-pi.json");
@@ -661,13 +665,46 @@ async function executeFrontendVerificationBundle(input, meta) {
     catch {
         beforeStatus = undefined;
     }
+    const lintResults = [];
+    for (const command of bundle.lintCommands ?? []) {
+        const commandNumber = results.length + 1;
+        const result = await executeShellCommand({
+            command,
+            cwd,
+            timeoutMs: shell.timeoutMs ?? DEFAULT_SHELL_TIMEOUT_MS,
+            envAllowlist: shell.envAllowlist,
+            dagRunMeta: { runDir: meta.runDir, runId: meta.runId },
+            outputArtifacts: {
+                stdoutPath: path.join(meta.runDir, input.task.id, "commands", `${commandNumber}.stdout.txt`),
+                stderrPath: path.join(meta.runDir, input.task.id, "commands", `${commandNumber}.stderr.txt`),
+            },
+        });
+        lintResults.push(result);
+        results.push(result);
+    }
+    let lintAssessment;
+    if ((bundle.lintCommands?.length ?? 0) > 0 &&
+        bundle.lintBaselineNodeId &&
+        (bundle.writerNodeIds?.length ?? 0) > 0) {
+        lintAssessment = await materializeFrontendLintAssessment({
+            runDir: meta.runDir,
+            workspaceRoot: input.cwd,
+            commands: bundle.lintCommands,
+            results: lintResults,
+            baselineNodeId: bundle.lintBaselineNodeId,
+            writerNodeIds: bundle.writerNodeIds,
+        });
+    }
+    const lintBlocked = lintAssessment?.status === "failed" ||
+        lintAssessment?.status === "unavailable";
     const groups = [
-        { name: "mock", commands: bundle.mockCommands },
-        { name: "static", commands: bundle.staticCommands },
-        { name: "behavior", commands: bundle.behaviorCommands },
+        { name: "mock", commands: bundle.mockCommands, labels: bundle.mockEvidence?.commandLabels ?? [] },
+        { name: "static", commands: bundle.staticCommands, labels: bundle.staticEvidence.commandLabels },
+        { name: "behavior", commands: bundle.behaviorCommands, labels: bundle.behaviorEvidence.commandLabels },
     ];
-    for (const group of groups) {
-        for (const command of group.commands) {
+    const successfulLabels = new Map();
+    for (const group of lintBlocked ? [] : groups) {
+        for (const [index, command] of group.commands.entries()) {
             const commandNumber = results.length + 1;
             const result = await executeShellCommand({
                 command,
@@ -681,6 +718,11 @@ async function executeFrontendVerificationBundle(input, meta) {
                 },
             });
             results.push(result);
+            if (result.ok && group.labels[index]) {
+                const labels = successfulLabels.get(group.name) ?? [];
+                labels.push(group.labels[index]);
+                successfulLabels.set(group.name, labels);
+            }
             if (!result.ok)
                 break;
         }
@@ -713,20 +755,36 @@ async function executeFrontendVerificationBundle(input, meta) {
         failureCategory: result.failureCategory,
         command: result.command,
     }));
-    const firstFailure = results.find((result) => !result.ok);
+    const firstFailure = lintBlocked
+        ? lintResults.find((result) => !result.ok)
+        : results
+            .filter((result) => !lintResults.includes(result))
+            .find((result) => !result.ok);
+    const lintSyntheticFailure = lintBlocked && !firstFailure
+        ? {
+            failureCategory: "invalid-output",
+            stderr: lintAssessment?.blockingReasons.join("; ") ??
+                "frontend lint assessment failed",
+        }
+        : undefined;
     let traceError;
     try {
         await runFrontendVerificationTraceGate({
             runDir: meta.runDir,
             workspaceRoot: input.cwd,
             evidence: {
+                mock: {
+                    nodeId: input.task.id,
+                    commandLabels: successfulLabels.get("mock") ?? [],
+                    commandTexts: bundle.mockCommands.slice(0, successfulLabels.get("mock")?.length ?? 0),
+                },
                 static: {
                     nodeId: input.task.id,
-                    commandLabels: bundle.staticEvidence.commandLabels,
+                    commandLabels: successfulLabels.get("static") ?? [],
                 },
                 behavior: {
                     nodeId: input.task.id,
-                    commandLabels: bundle.behaviorEvidence.commandLabels,
+                    commandLabels: successfulLabels.get("behavior") ?? [],
                 },
             },
         });
@@ -735,19 +793,26 @@ async function executeFrontendVerificationBundle(input, meta) {
         traceError = error instanceof Error ? error : new Error(String(error));
     }
     if (bundle.mode === "repair") {
-        if (firstFailure || traceError) {
+        if (firstFailure || lintSyntheticFailure || traceError) {
             return {
                 ok: false,
                 stdout: summarizeCommandResults(results).stdout,
-                stderr: firstFailure?.stderr || traceError?.message || "frontend reverify failed",
-                failureCategory: firstFailure?.failureCategory ?? "invalid-output",
+                stderr: firstFailure?.stderr ||
+                    lintSyntheticFailure?.stderr ||
+                    traceError?.message ||
+                    "frontend reverify failed",
+                failureCategory: firstFailure?.failureCategory ??
+                    lintSyntheticFailure?.failureCategory ??
+                    "invalid-output",
                 durationMs: Date.now() - started,
                 ...{ commandResults },
             };
         }
         return {
             ok: true,
-            stdout: "Frontend reverify bundle: pass",
+            stdout: lintAssessment?.status === "baseline-debt"
+                ? "Frontend reverify bundle: pass with lint baseline-debt"
+                : "Frontend reverify bundle: pass",
             stderr: "",
             failureCategory: "success",
             durationMs: Date.now() - started,
@@ -755,14 +820,22 @@ async function executeFrontendVerificationBundle(input, meta) {
         };
     }
     const failureFacts = [];
-    if (firstFailure) {
+    if (firstFailure || lintSyntheticFailure) {
+        const failureStdout = firstFailure
+            ? [firstFailure.command, firstFailure.stdout]
+                .filter(Boolean)
+                .join("\n")
+            : "";
         failureFacts.push({
             nodeId: input.task.id,
             record: {
                 status: "FINISHED",
-                failureCategory: firstFailure.failureCategory,
-                stdout: summarizeCommandResults(results).stdout,
-                stderr: firstFailure.stderr,
+                failureCategory: firstFailure?.failureCategory ??
+                    lintSyntheticFailure?.failureCategory,
+                // Keep classification scoped to the failed command. Aggregate
+                // successful output may contain unrelated writeSet-like JSON.
+                stdout: failureStdout,
+                stderr: firstFailure?.stderr ?? lintSyntheticFailure?.stderr,
                 commandResults,
             },
         });
@@ -803,6 +876,68 @@ async function executeFrontendVerificationBundle(input, meta) {
         };
     }
 }
+async function executeFrontendLintBaseline(input, meta) {
+    const started = Date.now();
+    const shell = input.task.shell;
+    const baseline = shell.frontendLintBaseline;
+    const cwd = resolveShellCwd(input.cwd, shell.cwd);
+    let beforeStatus;
+    try {
+        beforeStatus = await readGitStatusPorcelain(input.cwd);
+    }
+    catch {
+        beforeStatus = undefined;
+    }
+    const results = [];
+    for (const command of baseline.lintCommands) {
+        const commandNumber = results.length + 1;
+        results.push(await executeShellCommand({
+            command,
+            cwd,
+            timeoutMs: shell.timeoutMs ?? DEFAULT_SHELL_TIMEOUT_MS,
+            envAllowlist: shell.envAllowlist,
+            dagRunMeta: { runDir: meta.runDir, runId: meta.runId },
+            outputArtifacts: {
+                stdoutPath: path.join(meta.runDir, input.task.id, "commands", `${commandNumber}.stdout.txt`),
+                stderrPath: path.join(meta.runDir, input.task.id, "commands", `${commandNumber}.stderr.txt`),
+            },
+        }));
+    }
+    let afterStatus;
+    try {
+        afterStatus = await readGitStatusPorcelain(input.cwd);
+    }
+    catch {
+        afterStatus = undefined;
+    }
+    try {
+        const materialized = await materializeFrontendLintBaseline({
+            runDir: meta.runDir,
+            workspaceRoot: input.cwd,
+            commands: baseline.lintCommands,
+            results,
+            worktreeChanged: beforeStatus === undefined ||
+                afterStatus === undefined ||
+                beforeStatus !== afterStatus,
+        });
+        return {
+            ok: true,
+            stdout: `Frontend lint baseline: ${materialized.artifact.status}\nArtifact: ${materialized.ref.path}\nDiagnostics: ${materialized.artifact.diagnostics.length}`,
+            stderr: materialized.artifact.reason ?? "",
+            failureCategory: "success",
+            durationMs: Date.now() - started,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            stdout: "",
+            stderr: error instanceof Error ? error.message : String(error),
+            failureCategory: "invalid-output",
+            durationMs: Date.now() - started,
+        };
+    }
+}
 export async function executeDagShellNode(input, meta) {
     const shell = input.task.shell;
     if (shell?.frontendPrewriteGate) {
@@ -812,6 +947,7 @@ export async function executeDagShellNode(input, meta) {
                 runDir: meta.runDir,
                 config: shell.frontendPrewriteGate,
                 sourceBinding: meta.spec.sourceBinding,
+                workspaceRoot: input.cwd,
                 repoRoot: input.cwd,
             });
             return { ok: true, stdout: formatFrontendPrewriteGateStdout(result), stderr: "", failureCategory: "success", durationMs: Date.now() - started };
@@ -820,13 +956,20 @@ export async function executeDagShellNode(input, meta) {
             return { ok: false, stdout: "", stderr: error instanceof Error ? error.message : String(error), failureCategory: "invalid-output", durationMs: Date.now() - started };
         }
     }
+    if (shell?.frontendLintBaseline) {
+        return executeFrontendLintBaseline(input, meta);
+    }
     if (shell?.frontendVerificationBundle) {
         return executeFrontendVerificationBundle(input, meta);
     }
     if (shell?.frontendReviewContext) {
         const started = Date.now();
         try {
-            const result = await runFrontendReviewContextGate({ runDir: meta.runDir, workspaceRoot: input.cwd });
+            const result = await runFrontendReviewContextGate({
+                runDir: meta.runDir,
+                workspaceRoot: input.cwd,
+                requireBaseline: shell.frontendReviewContext.requireBaseline,
+            });
             return { ok: true, stdout: formatFrontendReviewContextStdout(result), stderr: "", failureCategory: "success", durationMs: Date.now() - started };
         }
         catch (error) {

package/dist/shared/openspec-spec.js

@@ -0,0 +1,49 @@
+/**
+ * Shared openspec specification path predicates.
+ *
+ * Canonical frontend specification directories (case-sensitive) and extension
+ * allowlist.
+ * All consumers in candidate discovery, DAG schema, prewrite gate, and observe
+ * must use these predicates to ensure a single consistent scope definition.
+ */
+/** Canonical spec directories (case-sensitive, POSIX form). */
+export const OPENSPEC_SPEC_DIRS = [
+    "openspec/schemas",
+    "openspec/project-specs",
+    "ai_workspace",
+];
+/** Allowed spec file extensions (case-insensitive). */
+export const OPENSPEC_SPEC_EXT_RE = /\.(md|mdx|json|yaml|yml)$/i;
+/**
+ * Returns `true` when `filePath` is inside one of the canonical frontend spec
+ * directories.  `filePath` must be a repo-relative POSIX path (backslashes are
+ * normalised internally).  Directory names are case-sensitive.
+ */
+export function isOpenspecSpecPath(filePath) {
+    const normalized = filePath.replaceAll("\\", "/");
+    for (const dir of OPENSPEC_SPEC_DIRS) {
+        if (normalized === dir || normalized.startsWith(dir + "/"))
+            return true;
+    }
+    return false;
+}
+/**
+ * Returns `true` when `filename` (the basename only, not a full path) has an
+ * allowed frontend specification extension.
+ */
+export function isValidOpenspecExtension(filename) {
+    return OPENSPEC_SPEC_EXT_RE.test(filename);
+}
+/** Returns `true` for a supported file inside a canonical openspec spec dir. */
+export function isOpenspecSpecFilePath(filePath) {
+    return (isOpenspecSpecPath(filePath) &&
+        isValidOpenspecExtension(filePath.replaceAll("\\", "/")));
+}
+/**
+ * Returns `true` when free-form search input references a canonical frontend
+ * specification directory with exact lowercase directory names.
+ */
+export function isOpenspecSpecSearchTarget(value) {
+    const normalized = value.replaceAll("\\", "/");
+    return /(?:^|[^A-Za-z0-9_.-])(?:openspec\/(?:schemas|project-specs)|ai_workspace)(?:\/|$)/.test(normalized);
+}

package/dist/shared/operator/capabilities.js

@@ -165,7 +165,17 @@ export function buildOperatorCapabilitiesDocument() {
             resultSchemaVersion: 1,
             envelopeSchemaVersion: 1,
             requiredErrorCodes: ["INVALID_INPUT", "OPERATION_NEEDS_RECONCILE"],
-            description: "Repo doctor (registry entry; envelope migration follow-up).",
+            description: "Repo health doctor with machine-readable report and read-only context audit (--context).",
+        },
+        {
+            action: "statsContext",
+            cli: "loop-agent stats context --last 50 --json",
+            kind: "read",
+            inputSchemaVersion: 1,
+            resultSchemaVersion: 1,
+            envelopeSchemaVersion: 1,
+            requiredErrorCodes: ["INVALID_INPUT"],
+            description: "Bounded skill-resolution / node-outcome telemetry over recent DAG runs (not compliance rates).",
         },
         {
             action: "dagReport",

package/dist/worker/console/app-data.js

@@ -39,6 +39,8 @@ export function openConsoleAppData(options) {
         staged: path.join(repoNamespace, "staged"),
         assessments: path.join(repoNamespace, "assessments"),
         interviews: path.join(repoNamespace, "interviews"),
+        chats: path.join(repoNamespace, "chats"),
+        chatSessions: path.join(repoNamespace, "chat-sessions"),
     };
     for (const dir of [
         paths.drafts,
@@ -47,6 +49,8 @@ export function openConsoleAppData(options) {
         paths.staged,
         paths.assessments,
         paths.interviews,
+        paths.chats,
+        paths.chatSessions,
     ]) {
         ensureSecureDir(dir);
     }

package/dist/worker/console/chat/instruction-skills.js

@@ -0,0 +1,217 @@
+/**
+ * Operator Chat — instruction skills whitelist (design §7.5 / plan D1).
+ *
+ * Hard rules (plan D1):
+ * - skills are READ-ONLY text context injected into the Chat system prompt;
+ * - skills are NEVER registered as executable tools;
+ * - the whitelist is a COMPILE-TIME constant (no runtime dir scan, no env override);
+ * - arbitrary pi extension / package tool / user-level ~/.pi/agent skill is
+ *   never discovered or loaded (V12);
+ * - project `.agents/skills/` (init projection) is NOT injected (prevents
+ *   target-repo injecting write instructions).
+ *
+ * Only the loop-agent repo's own audited skills are eligible. Workflow-specific
+ * skills are conditional on taskKind/workflow and loaded on demand (not in MVP
+ * operator-context default set).
+ */
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Operator-context instruction skills (plan D1, "operator-context 允许").
+ * These are read-only methodology skills. Loaded as text context for every
+ * Chat session by default.
+ *
+ * MUST stay a compile-time constant. Adding a skill requires an ADR / plan note.
+ */
+export const OPERATOR_CHAT_ALLOWED_INSTRUCTION_SKILLS = Object.freeze([
+    "grill-me",
+    "systematic-debugging",
+    "code-review-core",
+    "codebase-scout",
+    "verification-before-completion",
+    "requesting-code-review",
+    "analyze-product-requirements",
+    "analyze-product-dependencies",
+    "using-git-worktrees",
+]);
+/**
+ * Meta / governance skills that must NEVER be injected into Chat context
+ * (plan D1 "元 / 治理 skill"). Injecting these would let Chat rewrite its own
+ * governance. Listed explicitly so accidental allowlist edits are caught.
+ */
+export const OPERATOR_CHAT_DENIED_INSTRUCTION_SKILLS = Object.freeze([
+    "loop-agent",
+    "agent-worker",
+    "init-capability-evolution",
+    "ai-engineering-context",
+    "grill-with-docs",
+]);
+/**
+ * Workflow-specific skills (plan D1 "workflow-specific 允许（条件）").
+ * Only injected when the corresponding taskKind / workflow is active.
+ * NOT loaded by default in MVP Chat.
+ */
+export const OPERATOR_CHAT_WORKFLOW_CONDITIONAL_SKILLS = Object.freeze([
+    "frontend-implementation",
+    "frontend-review",
+    "frontend-verification",
+    "frontend-design-review",
+    "test-driven-development",
+    "webapp-testing",
+    "playwright-cli",
+    "playwright-cli-case-generator",
+    "browser-tools",
+]);
+const ALLOWED = new Set(OPERATOR_CHAT_ALLOWED_INSTRUCTION_SKILLS.map((s) => s.toLowerCase()));
+const DENIED = new Set(OPERATOR_CHAT_DENIED_INSTRUCTION_SKILLS.map((s) => s.toLowerCase()));
+const CONDITIONAL = new Set(OPERATOR_CHAT_WORKFLOW_CONDITIONAL_SKILLS.map((s) => s.toLowerCase()));
+export function isOperatorChatInstructionSkillAllowed(name) {
+    return ALLOWED.has(name.trim().toLowerCase());
+}
+export function isOperatorChatInstructionSkillDenied(name) {
+    return DENIED.has(name.trim().toLowerCase());
+}
+export function isOperatorChatInstructionSkillConditional(name) {
+    return CONDITIONAL.has(name.trim().toLowerCase());
+}
+export function classifyInstructionSkill(name, options) {
+    const n = name.trim().toLowerCase();
+    if (DENIED.has(n)) {
+        return { ok: false, reason: "denied-governance", name };
+    }
+    if (ALLOWED.has(n)) {
+        return { ok: true, kind: "operator-context", name };
+    }
+    if (CONDITIONAL.has(n)) {
+        const active = options?.activeWorkflowSkills ?? [];
+        const activeLower = new Set(active.map((s) => s.toLowerCase()));
+        if (activeLower.has(n)) {
+            // Conditional skill is allowed only when explicitly activated by workflow.
+            // For MVP, conditional skills are not auto-injected; callers must opt in.
+            return { ok: false, reason: "conditional-not-active", name };
+        }
+        return { ok: false, reason: "conditional-not-active", name };
+    }
+    return { ok: false, reason: "unknown", name };
+}
+/**
+ * Parse a SKILL.md frontmatter description (first `description:` line) and
+ * return the body text (frontmatter stripped). Tolerant of missing frontmatter.
+ */
+export function parseSkillFrontmatter(raw) {
+    let description = "";
+    let bodyText = raw;
+    const hasFrontmatter = raw.trimStart().startsWith("---");
+    if (hasFrontmatter) {
+        const lines = raw.split(/\r?\n/);
+        // find closing ---
+        let closeIdx = -1;
+        for (let i = 1; i < lines.length; i++) {
+            if (lines[i].trim() === "---") {
+                closeIdx = i;
+                break;
+            }
+        }
+        if (closeIdx > 0) {
+            const fm = lines.slice(1, closeIdx).join("\n");
+            bodyText = lines.slice(closeIdx + 1).join("\n").trim();
+            const descMatch = fm.match(/^description:\s*(.+)$/m);
+            if (descMatch) {
+                description = descMatch[1].trim().replace(/^["']|["']$/g, "");
+            }
+        }
+    }
+    else {
+        bodyText = raw.trim();
+    }
+    return { description, bodyText };
+}
+/**
+ * Load the operator-context instruction skills from the loop-agent repo's own
+ * `skills/` directory and return their text bodies for system-prompt injection.
+ *
+ * Security: only names in OPERATOR_CHAT_ALLOWED_INSTRUCTION_SKILLS are read;
+ * any other path is rejected before filesystem access (safe-side).
+ *
+ * @param skillsDir absolute path to the loop-agent repo `skills/` directory
+ *                  (source repo / npm pack asset, NOT target project `.agents/skills/`).
+ * @param names     override list (tests); defaults to the full allowlist.
+ */
+export async function loadOperatorChatInstructionSkills(skillsDir, names) {
+    const selected = names ?? OPERATOR_CHAT_ALLOWED_INSTRUCTION_SKILLS;
+    const loaded = [];
+    const failures = [];
+    const skipped = [];
+    for (const rawName of selected) {
+        const name = rawName.trim();
+        if (!isOperatorChatInstructionSkillAllowed(name)) {
+            skipped.push(name);
+            continue;
+        }
+        // Defense in depth: reject path traversal / governance skills even if
+        // an attacker managed to mutate the allowlist at runtime.
+        if (isOperatorChatInstructionSkillDenied(name)) {
+            skipped.push(name);
+            continue;
+        }
+        const skillPath = path.join(skillsDir, name, "SKILL.md");
+        const resolved = path.resolve(skillPath);
+        const resolvedSkillsDir = path.resolve(skillsDir);
+        if (!resolved.startsWith(resolvedSkillsDir + path.sep)) {
+            failures.push({
+                name,
+                message: "path escapes skills directory",
+            });
+            continue;
+        }
+        try {
+            const raw = await readFile(resolved, "utf8");
+            const { description, bodyText } = parseSkillFrontmatter(raw);
+            loaded.push({
+                name,
+                description,
+                bodyText,
+                charCount: bodyText.length,
+            });
+        }
+        catch (error) {
+            failures.push({
+                name,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return { loaded, failures, skipped };
+}
+/** Hard cap on total injected instruction-skill chars (token budget guard). */
+export const OPERATOR_CHAT_INSTRUCTION_CHAR_BUDGET = 24_000;
+/**
+ * Compose the system-prompt fragment listing loaded instruction skills.
+ * Each skill is rendered as a bounded text block. If total chars exceed the
+ * budget, later skills are truncated (operator-context set is small enough
+ * that truncation should not trigger in practice, but the cap is enforced).
+ */
+export function composeInstructionSkillsPrompt(skills, budget = OPERATOR_CHAT_INSTRUCTION_CHAR_BUDGET) {
+    if (skills.length === 0)
+        return "";
+    const lines = [
+        "## Operator methodology context (read-only instruction skills)",
+        "",
+        "These skills are READ-ONLY context. You may reference their methodology when reasoning, but you CANNOT execute them. All actions must go through the registered operator tools.",
+        "",
+    ];
+    let used = 0;
+    for (const skill of skills) {
+        const header = `\n### ${skill.name}${skill.description ? ` — ${skill.description}` : ""}\n`;
+        const remaining = budget - used - header.length;
+        if (remaining <= 0) {
+            lines.push(`_[${skill.name}: omitted, char budget exhausted]_`);
+            break;
+        }
+        const slice = skill.bodyText.slice(0, Math.max(0, remaining));
+        lines.push(header);
+        lines.push(slice);
+        used += header.length + slice.length;
+    }
+    return lines.join("\n");
+}