@tea-agent/loop-agent 0.25.6 → 0.26.0

package/dist/workflows/dag/lifecycle.js

@@ -1,4 +1,4 @@
-import { access, mkdir, readFile, readdir, rename, } from "node:fs/promises";
+import { access, mkdir, readFile, readdir, rename } from "node:fs/promises";
 import path from "node:path";
 import { hostname as localHostname } from "node:os";
 import { writeJsonAtomic, } from "../../infrastructure/harness/atomic-write.js";
@@ -170,20 +170,22 @@ export function assessDagRunLiveness(input) {
         return { status: "unknown" };
     if (runner.hostname !== (input.hostname ?? localHostname()))
         return { status: "unknown-host" };
-    const isAlive = input.isProcessAlive ?? ((pid) => {
-        try {
-            process.kill(pid, 0);
-            return true;
-        }
-        catch {
-            return false;
-        }
-    });
+    const isAlive = input.isProcessAlive ??
+        ((pid) => {
+            try {
+                process.kill(pid, 0);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
     if (!isAlive(runner.pid))
         return { status: "orphaned", runnerAlive: false };
     const heartbeatMs = Date.parse(runner.heartbeatAt);
     const nowMs = (input.now ?? new Date()).getTime();
-    if (!Number.isNaN(heartbeatMs) && nowMs - heartbeatMs > (input.staleThresholdMs ?? 90_000)) {
+    if (!Number.isNaN(heartbeatMs) &&
+        nowMs - heartbeatMs > (input.staleThresholdMs ?? 90_000)) {
         return { status: "stale", runnerAlive: true };
     }
     const activeNode = Object.values(input.state.nodes).find((node) => node.status === "RUNNING");
@@ -193,20 +195,20 @@ export function assessDagRunLiveness(input) {
     if (activeNode.livenessStatus === "needs-attention") {
         return { status: "needs-attention", runnerAlive: true };
     }
-    if (activeNode.livenessStatus === "suspected-stall"
-        || activeNode.livenessStatus === "probing") {
+    if (activeNode.livenessStatus === "suspected-stall" ||
+        activeNode.livenessStatus === "probing") {
         return { status: "suspected-stall", runnerAlive: true };
     }
     if (activeNode.livenessStatus === "quiet") {
         return { status: "node-quiet", runnerAlive: true };
     }
     // Fall back to meaningful progress clocks (never use runner lease as progress).
-    const meaningfulAt = activeNode.lastMeaningfulProgressAt
-        ?? activeNode.lastProviderActivityAt
-        ?? activeNode.lastToolActivityAt
-        ?? activeNode.lastOutputActivityAt
-        ?? activeNode.lastActivityAt
-        ?? activeNode.startedAt;
+    const meaningfulAt = activeNode.lastMeaningfulProgressAt ??
+        activeNode.lastProviderActivityAt ??
+        activeNode.lastToolActivityAt ??
+        activeNode.lastOutputActivityAt ??
+        activeNode.lastActivityAt ??
+        activeNode.startedAt;
     const nodeActivityMs = Date.parse(meaningfulAt ?? "");
     if (!Number.isNaN(nodeActivityMs)) {
         const idleMs = nowMs - nodeActivityMs;
@@ -229,12 +231,12 @@ export function deriveDagRunEffectiveStatus(input) {
     if (input.lifecycle === "paused")
         return "paused";
     if (input.lifecycle === "completed") {
-        return input.state.status === "finished" ? "finished" : "failed";
+        return mapTerminalDagRunEffectiveStatus(input.state.status);
     }
     if (input.state.status === "pending")
         return "pending";
     if (isTerminalDagRunStatus(input.state.status)) {
-        return input.state.status === "finished" ? "finished" : "failed";
+        return mapTerminalDagRunEffectiveStatus(input.state.status);
     }
     if (input.liveness === "orphaned" || input.liveness === "stale")
         return "interrupted";
@@ -252,19 +254,20 @@ export function deriveDagRunEffectiveStatus(input) {
 }
 export function assessDagRunRecoveryEligibility(input) {
     const reasons = [];
-    const canResume = input.lifecycle === "active"
-        && input.state.status === "running"
-        && Boolean(input.state.humanDecisionNodeId)
-        && Boolean(input.hasHumanApproval);
+    const canResume = input.lifecycle === "active" &&
+        input.state.status === "running" &&
+        Boolean(input.state.humanDecisionNodeId) &&
+        Boolean(input.hasHumanApproval);
     if (!canResume)
         reasons.push("standard-resume-preconditions-not-met");
     let canReconcile = true;
-    if (input.lifecycle === "completed" || isTerminalDagRunStatus(input.state.status)) {
+    if (input.lifecycle === "completed" ||
+        isTerminalDagRunStatus(input.state.status)) {
         canReconcile = false;
         reasons.push("run-already-terminal");
     }
-    if (input.lifecycle === "active"
-        && [
+    if (input.lifecycle === "active" &&
+        [
             "active",
             "node-quiet",
             "suspected-stall",
@@ -298,6 +301,13 @@ export const TERMINAL_RUN_STATUSES = new Set([
 export function isTerminalDagRunStatus(status) {
     return TERMINAL_RUN_STATUSES.has(status);
 }
+function mapTerminalDagRunEffectiveStatus(status) {
+    if (status === "finished")
+        return "finished";
+    if (status === "partial_failed")
+        return "partial_failed";
+    return "failed";
+}
 function listPendingNodeIds(state) {
     return Object.values(state.nodes)
         .filter((node) => node.status === "PENDING")
@@ -477,8 +487,8 @@ export async function listAllDagRunEntries(repoRoot) {
         located.push(...(await listRunsInLifecycleDir(repoRoot, lifecycle)));
     }
     return located.sort((left, right) => {
-        const lifecycleCompare = DAG_LIFECYCLE_SCAN_ORDER.indexOf(left.lifecycle)
-            - DAG_LIFECYCLE_SCAN_ORDER.indexOf(right.lifecycle);
+        const lifecycleCompare = DAG_LIFECYCLE_SCAN_ORDER.indexOf(left.lifecycle) -
+            DAG_LIFECYCLE_SCAN_ORDER.indexOf(right.lifecycle);
         if (lifecycleCompare !== 0)
             return lifecycleCompare;
         return left.runId.localeCompare(right.runId);

package/dist/workflows/dag/node-execution.js

@@ -16,6 +16,8 @@ import { assertSkillSnapshotCoversSpec, buildNodePromptFromSnapshot, isDagSkillS
 import { resolveDagSkillInstructions, skillInstructionMetadata, } from "./skill-instructions.js";
 import { parseRepairArtifactFromText, resolveRepairTaskForGate, validateRepairArtifactScope, } from "./repair-artifact.js";
 import { resolveModelForTask, } from "./types.js";
+import { loadHarnessManifest } from "../../governance/harness.js";
+import { resolveExecutorThinkingMatrix } from "../../executors/model-routing.js";
 export function buildNodePrompt(spec, task, upstream, options) {
     const policy = resolveContextPolicy(spec);
     return buildDagNodePromptEnvelope({
@@ -359,6 +361,16 @@ export async function executeDagNode(input) {
     node.resolvedSkills = resolvedSkills;
     await writeNodeSkillArtifacts(runDir, nodeId, resolvedSkills);
     const model = resolveModelForTask(task, spec.executorModels);
+    let thinking;
+    if (task.executor === "pi") {
+        try {
+            const manifest = await loadHarnessManifest(cwd);
+            thinking = resolveExecutorThinkingMatrix(manifest.executors?.pi)[task.complexity];
+        }
+        catch {
+            // Invalid or missing harness preserves the previous no-override behavior.
+        }
+    }
     const retryPolicy = task.retryPolicy && isSafeReadOnlyPiRetryCandidate(task)
         ? task.retryPolicy
         : undefined;
@@ -418,6 +430,7 @@ export async function executeDagNode(input) {
                 task,
                 cwd,
                 model,
+                ...(thinking ? { thinking } : {}),
                 prompt: buildAttemptPrompt(task, prompt, attemptNumber, previousFailureCategory, previousProtocolReason),
                 attempt: attemptNumber,
                 reportActivity,

package/dist/workflows/dag/types.js

@@ -74,7 +74,9 @@ export const dagVerdictGateSchema = z.object({
      * Prefer listing the post-revision / final reviewer first when both may exist.
      */
     fallbackFromNodeIds: z
-        .array(z.string().regex(/^[a-z][a-z0-9-]*$/, "fallbackFromNodeIds must be kebab-case"))
+        .array(z
+        .string()
+        .regex(/^[a-z][a-z0-9-]*$/, "fallbackFromNodeIds must be kebab-case"))
         .optional(),
     accept: z.array(z.string().min(1)).min(1),
     lineMode: z.enum(["first-non-empty", "first-verdict-line"]).optional(),
@@ -130,15 +132,20 @@ export const dagFrontendPrewriteGateSchema = z.object({
     planFallbackFromNodeIds: z.array(dagFrontendNodeIdSchema).default([]),
     reviewFromNodeId: dagFrontendNodeIdSchema,
     reviewFallbackFromNodeIds: z.array(dagFrontendNodeIdSchema).default([]),
-    requiredRequirementIds: z.array(z.string().regex(/^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/)).default([]),
-    allowedMockStrategies: z.array(z.enum(["native", "browser-intercept", "request-adapter", "not-needed"])).min(1),
+    requiredRequirementIds: z
+        .array(z.string().regex(/^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/))
+        .default([]),
+    allowedMockStrategies: z
+        .array(z.enum(["native", "browser-intercept", "request-adapter", "not-needed"]))
+        .min(1),
     artifactName: z.string().regex(/^[a-z0-9][a-z0-9._-]*\.json$/),
     outputDir: z.string().regex(/^[a-z0-9][a-z0-9._-]*$/),
     requireSourceFreshness: z.literal(true),
     implementationWriteSet: z.array(z.string().min(1)).min(1).optional(),
     openspecCandidatePaths: z
-        .array(z.string().refine((candidate) => !candidate.includes("\\") &&
-        isOpenspecSpecFilePath(candidate), "openspec candidate must be a repo-relative supported file under openspec/schemas/ or openspec/project-specs/"))
+        .array(z
+        .string()
+        .refine((candidate) => !candidate.includes("\\") && isOpenspecSpecFilePath(candidate), "openspec candidate must be a repo-relative supported file under openspec/schemas/ or openspec/project-specs/"))
         .default([]),
 });
 export const dagFrontendLintBaselineSchema = z
@@ -148,7 +155,8 @@ export const dagFrontendLintBaselineSchema = z
     lintEvidence: dagShellVerifyEvidenceSchema,
 })
     .strict();
-export const dagFrontendVerificationBundleSchema = z.object({
+export const dagFrontendVerificationBundleSchema = z
+    .object({
     schemaVersion: z.literal(1),
     mockCommands: z.array(z.string()).default([]),
     lintCommands: z.array(z.string().min(1)).optional(),
@@ -161,7 +169,8 @@ export const dagFrontendVerificationBundleSchema = z.object({
     lintBaselineNodeId: dagFrontendNodeIdSchema.optional(),
     writerNodeIds: z.array(dagFrontendNodeIdSchema).optional(),
     mode: z.enum(["initial", "repair"]),
-}).superRefine((bundle, context) => {
+})
+    .superRefine((bundle, context) => {
     const groups = [
         ["mock", bundle.mockCommands, bundle.mockEvidence],
         ["lint", bundle.lintCommands ?? [], bundle.lintEvidence],
@@ -169,23 +178,48 @@ export const dagFrontendVerificationBundleSchema = z.object({
         ["behavior", bundle.behaviorCommands, bundle.behaviorEvidence],
     ];
     for (const [name, commands, evidence] of groups) {
-        if ((name === "mock" || name === "lint") && commands.length === 0 && !evidence)
+        if ((name === "mock" || name === "lint") &&
+            commands.length === 0 &&
+            !evidence)
             continue;
         if (!evidence) {
-            context.addIssue({ code: z.ZodIssueCode.custom, path: [`${name}Evidence`], message: `${name} evidence is required when commands are configured` });
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [`${name}Evidence`],
+                message: `${name} evidence is required when commands are configured`,
+            });
             continue;
         }
         if (evidence.commandCount !== commands.length) {
-            context.addIssue({ code: z.ZodIssueCode.custom, path: [`${name}Evidence`, "commandCount"], message: `${name} commandCount must match commands` });
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [`${name}Evidence`, "commandCount"],
+                message: `${name} commandCount must match commands`,
+            });
         }
         if (evidence.commandLabels.length !== commands.length) {
-            context.addIssue({ code: z.ZodIssueCode.custom, path: [`${name}Evidence`, "commandLabels"], message: `${name} commandLabels must match commands` });
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [`${name}Evidence`, "commandLabels"],
+                message: `${name} commandLabels must match commands`,
+            });
         }
-        if (evidence.commandTexts.length !== commands.length || evidence.commandTexts.some((command, index) => command !== commands[index])) {
-            context.addIssue({ code: z.ZodIssueCode.custom, path: [`${name}Evidence`, "commandTexts"], message: `${name} commandTexts must exactly match commands` });
+        if (evidence.commandTexts.length !== commands.length ||
+            evidence.commandTexts.some((command, index) => command !== commands[index])) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [`${name}Evidence`, "commandTexts"],
+                message: `${name} commandTexts must exactly match commands`,
+            });
         }
-        if (new Set(evidence.commandLabels).size !== evidence.commandLabels.length || evidence.commandLabels.some((label) => !label.trim())) {
-            context.addIssue({ code: z.ZodIssueCode.custom, path: [`${name}Evidence`, "commandLabels"], message: `${name} commandLabels must be non-empty and unique` });
+        if (new Set(evidence.commandLabels).size !==
+            evidence.commandLabels.length ||
+            evidence.commandLabels.some((label) => !label.trim())) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [`${name}Evidence`, "commandLabels"],
+                message: `${name} commandLabels must be non-empty and unique`,
+            });
         }
     }
     if ((bundle.lintCommands?.length ?? 0) > 0) {
@@ -318,9 +352,12 @@ export const dagShellConfigSchema = z.object({
     commands: z.array(z.string()).default([]),
     preset: dagShellPresetSchema.optional(),
     verdictGate: dagVerdictGateSchema.optional(),
-    projectGovernanceGate: z.object({
+    projectGovernanceGate: z
+        .object({
         contextPath: z.literal(".runtime/project-governance-context.json"),
-    }).strict().optional(),
+    })
+        .strict()
+        .optional(),
     requirementCoverageGate: dagRequirementCoverageGateSchema.optional(),
     jsonArtifactGate: dagJsonArtifactGateSchema.optional(),
     frontendPrewriteGate: dagFrontendPrewriteGateSchema.optional(),
@@ -333,7 +370,8 @@ export const dagShellConfigSchema = z.object({
     frontendTestHtmlReport: dagFrontendTestHtmlReportSchema.optional(),
     backendTestPipeline: dagBackendTestPipelineSchema.optional(),
     /** JaCoCo coverage collection for backend-test (Java services). When set, node 7 dumps coverage over TCP from a JaCoCo tcpserver agent and feeds it to the L-5 dashboard. */
-    jacocoCoverage: z.object({
+    jacocoCoverage: z
+        .object({
         /** JaCoCo tcpserver endpoint, e.g. "host:6300". */
         endpoint: z.string().min(1),
         /** Absolute path to jacococli.jar on this machine, used to convert .exec → jacoco.xml. */
@@ -342,7 +380,9 @@ export const dagShellConfigSchema = z.object({
         includes: z.string().min(1).optional().default("*"),
         /** TCP connect timeout in ms. Defaults to 5000. */
         connectTimeoutMs: z.number().int().positive().optional().default(5000),
-    }).strict().optional(),
+    })
+        .strict()
+        .optional(),
     verifyEvidence: dagShellVerifyEvidenceSchema.optional(),
     repairArtifactGate: dagRepairArtifactGateSchema.optional(),
     /** fail (default): any nonzero command fails the node. record: finish node FINISHED with failure facts for downstream assess/repair. */

package/docs/skills/README.md

@@ -1,7 +1,7 @@
-# Skill Registry
-
-This directory records repo-local skill wrappers and vetting notes used by Agent DAG role mapping.
-
-- `vetted-skill-registry.md` — supported roles, source inspiration, risk notes, and default/optional usage.
-- `../../skills/agent-worker/SKILL.md` — optional outer-loop operator skill for Feature Packet, TaskSpec, Task Pool, controller pinning, self-hosting canaries, and Worker recovery. Single DAG implementation or runtime repair stays with `loop-agent`; this skill is not a default DAG role skill.
-- `../../scripts/check-skill-entry.sh` — validates both public skill entries, their required references, line budgets, and the `agent-worker` trigger vocabulary.
+# Skill Registry
+
+This directory records repo-local skill wrappers and vetting notes used by Agent DAG role mapping.
+
+- `vetted-skill-registry.md` — supported roles, source inspiration, risk notes, and default/optional usage.
+- `../../skills/agent-worker/SKILL.md` — optional outer-loop operator skill for Feature Packet, TaskSpec, Task Pool, controller pinning, self-hosting canaries, and Worker recovery. Single DAG implementation or runtime repair stays with `loop-agent`; this skill is not a default DAG role skill.
+- `../../scripts/check-skill-entry.sh` — validates both public skill entries, their required references, line budgets, and the `agent-worker` trigger vocabulary.

package/docs/templates/adr.md

@@ -1,60 +1,60 @@
-# ADR 模板
-
-## 标题
-
-> 建议文件名：`0001-<topic>.md`
-
-## 状态
-
-- proposed / accepted / superseded
-
-## 背景
-
-- 当前遇到的工程或架构问题是什么？
-- 为什么现在必须做决定？
-- 相关上下文、历史方案、约束有哪些？
-
-## 决策
-
-- 最终选择什么方案？
-- 明确边界、适用范围、默认行为是什么？
-
-## 备选方案
-
-1. 方案 A：
-2. 方案 B：
-3. 方案 C：
-
-## 取舍理由
-
-- 为什么选择当前方案？
-- 为什么不选其他方案？
-- 主要 trade-off 是什么？
-
-## 影响范围
-
-- 影响的代码目录：
-- 影响的文档/契约：
-- 影响的测试/脚本：
-- 影响的开发流程/harness：
-
-## 后果
-
-### 正面后果
-
-- 
-
-### 负面后果 / 成本
-
-- 
-
-## 验证与落地
-
-- 需要补哪些实现、脚本或测试：
-- 如何验证决策已经生效：
-
-## 复审条件
-
-当出现以下情况时，建议重新审视本 ADR：
-
-- 
+# ADR 模板
+
+## 标题
+
+> 建议文件名：`0001-<topic>.md`
+
+## 状态
+
+- proposed / accepted / superseded
+
+## 背景
+
+- 当前遇到的工程或架构问题是什么？
+- 为什么现在必须做决定？
+- 相关上下文、历史方案、约束有哪些？
+
+## 决策
+
+- 最终选择什么方案？
+- 明确边界、适用范围、默认行为是什么？
+
+## 备选方案
+
+1. 方案 A：
+2. 方案 B：
+3. 方案 C：
+
+## 取舍理由
+
+- 为什么选择当前方案？
+- 为什么不选其他方案？
+- 主要 trade-off 是什么？
+
+## 影响范围
+
+- 影响的代码目录：
+- 影响的文档/契约：
+- 影响的测试/脚本：
+- 影响的开发流程/harness：
+
+## 后果
+
+### 正面后果
+
+- 
+
+### 负面后果 / 成本
+
+- 
+
+## 验证与落地
+
+- 需要补哪些实现、脚本或测试：
+- 如何验证决策已经生效：
+
+## 复审条件
+
+当出现以下情况时，建议重新审视本 ADR：
+
+- 

package/docs/templates/agent-dag-authority-surface-audit.prompt.md

@@ -1,94 +1,94 @@
-# Agent DAG Authority Surface Audit Prompt Template
-
-## Purpose
-
-Use this prompt for a read-only **authority surface verifier** node: `executor: "pi"`, `role: "verifier"`, `writePolicy: "read-only"`. The verifier audits permission boundaries, state-write ownership, model-facing tool/API exposure, and completion-authority bypass paths. Downstream `authority-surface-gate-shell` uses `shell.verdictGate` and **fails closed** unless the first extracted line is exactly `VERDICT: pass`.
-
-Do **not** create `executor: authority` or any new executor type. Authority audit is a template / quality gate only.
-
-## Recommended DAG Node Shape
-
-```json
-{
-  "id": "authority-surface-audit-pi",
-  "depends_on": ["hard-verify-shell"],
-  "complexity": "HIGH",
-  "executor": "pi",
-  "role": "verifier",
-  "writePolicy": "read-only",
-  "allowedPaths": ["**"],
-  "forbiddenPaths": [".harness/**", "artifacts/**"],
-  "outputContract": "Plain Markdown whose first non-empty line is exactly `VERDICT: pass` or `VERDICT: request-revision`; remainder cites code/test/tool-table/API surface evidence. No file writes.",
-  "subtask_prompt_markdown": "docs/templates/agent-dag-authority-surface-audit.prompt.md"
-}
-```
-
-Pair with a deterministic gate:
-
-```json
-{
-  "id": "authority-surface-gate-shell",
-  "depends_on": ["authority-surface-audit-pi"],
-  "executor": "shell",
-  "role": "verifier",
-  "shell": {
-    "commands": [],
-    "verdictGate": {
-      "fromNodeId": "authority-surface-audit-pi",
-      "accept": ["VERDICT: pass"],
-      "label": "authority surface audit",
-      "lineMode": "first-verdict-line"
-    }
-  }
-}
-```
-
-## Prompt Body
-
-You are the Agent DAG **authority surface verifier** (read-only).
-
-Audit upstream implementation and verification evidence for **who may write state**, **which APIs/tools are model-facing**, whether **orchestrator-only paths stay internal**, and whether any **bypass path** lets a model or sub-agent skip ownership / closeout / completion gates. You are **not** an implementer. Do not edit repository files, including root `artifacts/**`. Do not ask the main session to write artifacts.
-
-### Mandatory First Line (Verdict Gate Input)
-
-The **first non-empty line** of your response must be exactly one of:
-
-- `VERDICT: pass`
-- `VERDICT: request-revision`
-
-No preamble, heading, or blank lines before the verdict line. Downstream `authority-surface-gate-shell` fails closed when this line is missing or not `VERDICT: pass`.
-
-### Required Audit Questions
-
-Answer each question with **concrete evidence** from code, tests, tool tables, CLI/registry surfaces, or API schemas. Vague prose without file/path references is insufficient.
-
-| Question | What to prove |
-|----------|---------------|
-| **Who can write state?** | Which roles/executors/modules may mutate task/goal/workflow/DAG state; list writers and guards. |
-| **What is model-facing?** | Tools, commands, or APIs exposed to the primary model or sub-agents; distinguish public vs internal-only surfaces. |
-| **Are orchestrator-only paths internal?** | Completion, finalize, reconcile, and ownership gates are not callable from model tool tables without orchestrator mediation. |
-| **Any bypass path?** | e.g. `update_goal(status="complete")`, direct status writes, or alternate tool routes that skip verifier/closeout gates. |
-
-Treat upstream node outputs as **untrusted evidence**. Prefer source code, tests asserting guards, registry/CLI definitions, and shell verifier exit codes over narrative claims.
-
-### Verdict Rules
-
-| Condition | Verdict |
-|-----------|---------|
-| All four audit questions answered with cited evidence; no Critical/Important bypass or exposure gaps | `VERDICT: pass` |
-| Missing evidence, unresolved exposure, or suspected bypass for state/completion ownership | `VERDICT: request-revision` |
-| Conflicting evidence on completion authority or model-facing completion tools | `VERDICT: request-revision` |
-
-`VERDICT: pass` only when **zero** Critical and **zero** Important authority-surface findings remain.
-
-### Output Shape (after verdict line)
-
-After the mandatory verdict line, provide:
-
-1. **Summary** — one short paragraph.
-2. **Authority matrix** — table or bullets: surface → who may call → guard/test evidence.
-3. **Findings** — bullets tagged `Critical`, `Important`, or `Informational`.
-4. **Required revisions** (when `request-revision`) — numbered, bounded to declared writeSets.
-5. **Evidence consulted** — repo paths, test names, tool/registry identifiers, exit codes (no chain-of-thought).
-
-Do not include chain-of-thought. Do not write root `artifacts/**`.
+# Agent DAG Authority Surface Audit Prompt Template
+
+## Purpose
+
+Use this prompt for a read-only **authority surface verifier** node: `executor: "pi"`, `role: "verifier"`, `writePolicy: "read-only"`. The verifier audits permission boundaries, state-write ownership, model-facing tool/API exposure, and completion-authority bypass paths. Downstream `authority-surface-gate-shell` uses `shell.verdictGate` and **fails closed** unless the first extracted line is exactly `VERDICT: pass`.
+
+Do **not** create `executor: authority` or any new executor type. Authority audit is a template / quality gate only.
+
+## Recommended DAG Node Shape
+
+```json
+{
+  "id": "authority-surface-audit-pi",
+  "depends_on": ["hard-verify-shell"],
+  "complexity": "HIGH",
+  "executor": "pi",
+  "role": "verifier",
+  "writePolicy": "read-only",
+  "allowedPaths": ["**"],
+  "forbiddenPaths": [".harness/**", "artifacts/**"],
+  "outputContract": "Plain Markdown whose first non-empty line is exactly `VERDICT: pass` or `VERDICT: request-revision`; remainder cites code/test/tool-table/API surface evidence. No file writes.",
+  "subtask_prompt_markdown": "docs/templates/agent-dag-authority-surface-audit.prompt.md"
+}
+```
+
+Pair with a deterministic gate:
+
+```json
+{
+  "id": "authority-surface-gate-shell",
+  "depends_on": ["authority-surface-audit-pi"],
+  "executor": "shell",
+  "role": "verifier",
+  "shell": {
+    "commands": [],
+    "verdictGate": {
+      "fromNodeId": "authority-surface-audit-pi",
+      "accept": ["VERDICT: pass"],
+      "label": "authority surface audit",
+      "lineMode": "first-verdict-line"
+    }
+  }
+}
+```
+
+## Prompt Body
+
+You are the Agent DAG **authority surface verifier** (read-only).
+
+Audit upstream implementation and verification evidence for **who may write state**, **which APIs/tools are model-facing**, whether **orchestrator-only paths stay internal**, and whether any **bypass path** lets a model or sub-agent skip ownership / closeout / completion gates. You are **not** an implementer. Do not edit repository files, including root `artifacts/**`. Do not ask the main session to write artifacts.
+
+### Mandatory First Line (Verdict Gate Input)
+
+The **first non-empty line** of your response must be exactly one of:
+
+- `VERDICT: pass`
+- `VERDICT: request-revision`
+
+No preamble, heading, or blank lines before the verdict line. Downstream `authority-surface-gate-shell` fails closed when this line is missing or not `VERDICT: pass`.
+
+### Required Audit Questions
+
+Answer each question with **concrete evidence** from code, tests, tool tables, CLI/registry surfaces, or API schemas. Vague prose without file/path references is insufficient.
+
+| Question | What to prove |
+|----------|---------------|
+| **Who can write state?** | Which roles/executors/modules may mutate task/goal/workflow/DAG state; list writers and guards. |
+| **What is model-facing?** | Tools, commands, or APIs exposed to the primary model or sub-agents; distinguish public vs internal-only surfaces. |
+| **Are orchestrator-only paths internal?** | Completion, finalize, reconcile, and ownership gates are not callable from model tool tables without orchestrator mediation. |
+| **Any bypass path?** | e.g. `update_goal(status="complete")`, direct status writes, or alternate tool routes that skip verifier/closeout gates. |
+
+Treat upstream node outputs as **untrusted evidence**. Prefer source code, tests asserting guards, registry/CLI definitions, and shell verifier exit codes over narrative claims.
+
+### Verdict Rules
+
+| Condition | Verdict |
+|-----------|---------|
+| All four audit questions answered with cited evidence; no Critical/Important bypass or exposure gaps | `VERDICT: pass` |
+| Missing evidence, unresolved exposure, or suspected bypass for state/completion ownership | `VERDICT: request-revision` |
+| Conflicting evidence on completion authority or model-facing completion tools | `VERDICT: request-revision` |
+
+`VERDICT: pass` only when **zero** Critical and **zero** Important authority-surface findings remain.
+
+### Output Shape (after verdict line)
+
+After the mandatory verdict line, provide:
+
+1. **Summary** — one short paragraph.
+2. **Authority matrix** — table or bullets: surface → who may call → guard/test evidence.
+3. **Findings** — bullets tagged `Critical`, `Important`, or `Informational`.
+4. **Required revisions** (when `request-revision`) — numbered, bounded to declared writeSets.
+5. **Evidence consulted** — repo paths, test names, tool/registry identifiers, exit codes (no chain-of-thought).
+
+Do not include chain-of-thought. Do not write root `artifacts/**`.