principles-disciple 1.72.0 → 1.74.0

package/templates/langs/en/skills/ai-sprint-orchestration/references/agent-registry.json

@@ -4,77 +4,6 @@
   "lastUpdated": "2026-04-04",
 
   "agents": {
-    "iflow": {
-      "command": "iflow --experimental-acp",
-      "description": "iFlow CLI with ACP support (智谱 Code Plan / MiniMax Code Plan 付费套餐更稳定，但以下模型全部免费)",
-      "version": "0.5.18",
-      "models": {
-        "glm-4.7": {
-          "description": "GLM-4.7 — official recommended model, fast",
-          "pricing": "free",
-          "recommendedTimeoutSeconds": 1200,
-          "features": ["recommended", "fast"],
-          "notes": "官方推荐模型，速度快"
-        },
-        "glm-5": {
-          "description": "GLM-5 — 744B parameters, long-context",
-          "pricing": "free",
-          "recommendedTimeoutSeconds": 1800,
-          "features": ["slow", "needs-extra-time"],
-          "notes": "744B 参数，运行明显较慢。Review 任务超时必须 ≥ 1800s"
-        },
-        "qwen3-coder-plus": {
-          "description": "Qwen3-Coder-Plus — efficient coding model",
-          "pricing": "free",
-          "recommendedTimeoutSeconds": 1200,
-          "features": ["fast", "coding-optimized"],
-          "notes": "通义编码模型"
-        },
-        "deepseek-v3.2": {
-          "description": "DeepSeek V3.2",
-          "pricing": "free",
-          "recommendedTimeoutSeconds": 1200,
-          "features": ["fast"],
-          "notes": ""
-        },
-        "minimax-m2.5": {
-          "description": "MiniMax M2.5",
-          "pricing": "free",
-          "recommendedTimeoutSeconds": 1200,
-          "features": ["fast"],
-          "notes": ""
-        },
-        "kimi-k2-thinking": {
-          "description": "Kimi K2 Thinking",
-          "pricing": "free",
-          "recommendedTimeoutSeconds": 1800,
-          "features": ["reasoning"],
-          "notes": "推理型模型"
-        },
-        "kimi-k2.5": {
-          "description": "Kimi K2.5",
-          "pricing": "free",
-          "recommendedTimeoutSeconds": 1200,
-          "features": ["fast"],
-          "notes": ""
-        },
-        "kimi-k2-0905": {
-          "description": "Kimi K2 0905",
-          "pricing": "free",
-          "recommendedTimeoutSeconds": 1200,
-          "features": ["fast"],
-          "notes": ""
-        },
-        "iflow-rome-30ba3b": {
-          "description": "iFlow ROME 30BA3B",
-          "pricing": "free",
-          "recommendedTimeoutSeconds": 1200,
-          "features": ["preview"],
-          "notes": "预览版本"
-        }
-      }
-    },
-
     "opencode": {
       "command": "npx -y opencode-ai acp",
       "description": "OpenCode ACP adapter",
@@ -209,6 +138,6 @@
     "codex": "codex-acp 在当前环境无法使用，不登记。",
     "kilocode": "kilocode ACP 是 server 模式（监听端口），不是 headless prompt-response，不兼容 acpx，不登记。",
     "qodercli": "qodercli 没有 --acp 标志，不登记。",
-    "model_discovery": "opencode 可通过 'opencode models' 自动列出模型。其他 agent（iflow, gemini, qwen）没有 CLI 列表命令，需手动维护。"
+    "model_discovery": "opencode 可通过 'opencode models' 自动列出模型。其他 agent（gemini, qwen）没有 CLI 列表命令，需手动维护。"
   }
 }

package/templates/langs/en/skills/ai-sprint-orchestration/references/specs/bugfix-complex-template.json

@@ -33,19 +33,19 @@
   "stageTimeoutMinutes": 15,
   "stages": ["investigate", "implement-pass-1", "verify"],
   "producer": {
-    "agent": "iflow",
-    "model": "glm-4.7",
+    "agent": "opencode",
+    "model": "minimax-cn-coding-plan/MiniMax-M2.7",
     "timeoutSeconds": 180
   },
   "reviewerA": {
-    "agent": "iflow",
-    "model": "glm-4.7",
+    "agent": "opencode",
+    "model": "minimax-cn-coding-plan/MiniMax-M2.7",
     "timeoutSeconds": 120,
     "focus": "Validate root cause, behavioral change, and code correctness."
   },
   "reviewerB": {
-    "agent": "iflow",
-    "model": "glm-4.7",
+    "agent": "opencode",
+    "model": "minimax-cn-coding-plan/MiniMax-M2.7",
     "timeoutSeconds": 120,
     "focus": "Validate scope control, verification quality, and regression risk."
   },

package/templates/langs/en/skills/ai-sprint-orchestration/references/specs/feature-complex-template.json

@@ -33,19 +33,19 @@
   "stageTimeoutMinutes": 20,
   "stages": ["investigate", "implement-pass-1", "verify"],
   "producer": {
-    "agent": "iflow",
-    "model": "glm-4.7",
+    "agent": "opencode",
+    "model": "minimax-cn-coding-plan/MiniMax-M2.7",
     "timeoutSeconds": 240
   },
   "reviewerA": {
-    "agent": "iflow",
-    "model": "glm-4.7",
+    "agent": "opencode",
+    "model": "minimax-cn-coding-plan/MiniMax-M2.7",
     "timeoutSeconds": 120,
     "focus": "Validate feature behavior, acceptance criteria coverage, and architecture fit."
   },
   "reviewerB": {
-    "agent": "iflow",
-    "model": "glm-4.7",
+    "agent": "opencode",
+    "model": "minimax-cn-coding-plan/MiniMax-M2.7",
     "timeoutSeconds": 120,
     "focus": "Validate implementation scope, verification evidence, and regression risk."
   },

package/templates/langs/en/skills/ai-sprint-orchestration/references/specs/workflow-validation-minimal-verify.json

@@ -10,19 +10,14 @@
   "stageTimeoutMinutes": 5,
   "stages": ["verify"],
   "producer": {
-    "agent": "iflow",
-    "model": "glm-4.7",
+    "agent": "opencode",
+    "model": "minimax-cn-coding-plan/MiniMax-M2.7",
     "timeoutSeconds": 90
   },
   "reviewerA": {
     "agent": "opencode",
     "model": "minimax-cn-coding-plan/MiniMax-M2.7",
     "timeoutSeconds": 45,
-    "fallback": {
-      "agent": "iflow",
-      "model": "glm-4.7",
-      "timeoutSeconds": 75
-    },
     "role": "artifact_checker",
     "focus": "Verify decision.md and scorecard.json contain expected fields"
   },
@@ -30,11 +25,6 @@
     "agent": "opencode",
     "model": "minimax-cn-coding-plan/MiniMax-M2.7",
     "timeoutSeconds": 45,
-    "fallback": {
-      "agent": "iflow",
-      "model": "glm-4.7",
-      "timeoutSeconds": 75
-    },
     "role": "recommendation_checker",
     "focus": "Verify nextRunRecommendation is computed and reasonable"
   },

package/templates/langs/en/skills/ai-sprint-orchestration/references/specs/workflow-validation-minimal.json

@@ -10,19 +10,14 @@
   "stageTimeoutMinutes": 4,
   "stages": ["validate"],
   "producer": {
-    "agent": "iflow",
-    "model": "glm-4.7",
+    "agent": "opencode",
+    "model": "minimax-cn-coding-plan/MiniMax-M2.7",
     "timeoutSeconds": 90
   },
   "reviewerA": {
     "agent": "opencode",
     "model": "minimax-cn-coding-plan/MiniMax-M2.7",
     "timeoutSeconds": 45,
-    "fallback": {
-      "agent": "iflow",
-      "model": "glm-4.7",
-      "timeoutSeconds": 75
-    },
     "role": "schema_checker",
     "focus": "Verify report has all required sections, VERDICT format, DIMENSIONS format"
   },
@@ -30,11 +25,6 @@
     "agent": "opencode",
     "model": "minimax-cn-coding-plan/MiniMax-M2.7",
     "timeoutSeconds": 45,
-    "fallback": {
-      "agent": "iflow",
-      "model": "glm-4.7",
-      "timeoutSeconds": 75
-    },
     "role": "quality_checker",
     "focus": "Verify outputQuality is computed correctly, qualityReasons are meaningful"
   },

package/templates/langs/en/skills/ai-sprint-orchestration/scripts/run.mjs

@@ -29,6 +29,11 @@ const acpxBin = (() => {
   const r = spawnSync(cmd, ['acpx'], { encoding: 'utf8' });
   if (r.status === 0) {
     const lines = r.stdout.trim().split(/\r?\n/);
+    // On Windows, prefer .cmd file over the Unix shell script (no extension)
+    if (process.platform === 'win32') {
+      const cmdFile = lines.find(l => l.trim().toLowerCase().endsWith('.cmd'));
+      if (cmdFile) return cmdFile.trim();
+    }
     const symlink = lines[0].trim();
     try {
       return fs.realpathSync(symlink);
@@ -86,7 +91,7 @@ function configureRuntimeRoots(rootPath) {
 
 function checkAcpxAvailable() {
   return process.platform === 'win32'
-    ? spawnSync('powershell.exe', ['-NoProfile', '-Command', 'acpx --version'], {
+    ? spawnSync(process.env.COMSPEC || 'cmd.exe', ['/d', '/s', '/c', `"${acpxBin}" --version`], {
         encoding: 'utf8',
         shell: false,
         timeout: 10_000,
@@ -129,6 +134,24 @@ function runSelfCheck() {
   const acpxCheck = checkAcpxAvailable();
   record('acpx_available', acpxCheck.status === 0, (acpxCheck.stdout || acpxCheck.stderr || '').trim() || `status=${acpxCheck.status}`);
 
+  // Check which agents are available by running a quick version check
+  try {
+    const registry = readJson(path.join(referencesRoot, 'agent-registry.json'));
+    const agentNames = Object.keys(registry.agents || {});
+    for (const agentName of agentNames) {
+      try {
+        const agentCheck = process.platform === 'win32'
+          ? spawnSync(process.env.COMSPEC || 'cmd.exe', ['/d', '/s', '/c', `"${acpxBin}" --format quiet --timeout 30 ${agentName} exec "echo available"`], { encoding: 'utf8', shell: false, timeout: 45_000 })
+          : spawnSync(nodeBin, [acpxBin, '--format', 'quiet', '--timeout', '30', agentName, 'exec', 'echo available'], { encoding: 'utf8', shell: false, timeout: 45_000 });
+        record(`agent:${agentName}`, agentCheck.status === 0, agentCheck.status === 0 ? 'available' : `status=${agentCheck.status}`);
+      } catch (agentErr) {
+        record(`agent:${agentName}`, false, agentErr.message);
+      }
+    }
+  } catch (registryErr) {
+    record('agent_registry_read', false, registryErr.message);
+  }
+
   const probePath = path.join(runtimeRoot, '.self-check-write-probe.tmp');
   try {
     fs.writeFileSync(probePath, 'ok', 'utf8');
@@ -273,7 +296,7 @@ function updateSummary(runDir, lines) {
 function inferFailureClassification({ summary = '', blockers = [], reviewerTimeouts = null, reviewerViolations = null }) {
   const combined = [summary, ...(blockers ?? [])].join(' ').toLowerCase();
 
-  if (/acpx|path|enoent|eacces|eprem|permission|writable|runtime root|command not found|not available/.test(combined)) {
+  if (/acpx|path|enoent|eacces|eprem|permission|writable|runtime root|command not found|not available|failed to spawn|spawn.*enoent|exit status|status 1|status 130|taskkill|comspec/.test(combined)) {
     return {
       failureClassification: 'environment issue',
       failureSource: 'runtime environment',
@@ -289,7 +312,7 @@ function inferFailureClassification({ summary = '', blockers = [], reviewerTimeo
     };
   }
 
-  if ((reviewerTimeouts?.length ?? 0) > 0 || (reviewerViolations?.length ?? 0) > 0 || /missing reports|schema violation|report invalidated|timed out|agent .*failed|verdict|dimensions/.test(combined)) {
+  if ((reviewerTimeouts?.length ?? 0) > 0 || (reviewerViolations?.length ?? 0) > 0 || /missing reports|schema violation|report invalidated|timed out|verdict|dimensions/.test(combined)) {
     return {
       failureClassification: 'agent behavior issue',
       failureSource: 'role execution or report quality',
@@ -297,6 +320,14 @@ function inferFailureClassification({ summary = '', blockers = [], reviewerTimeo
     };
   }
 
+  if (/agent .*failed/.test(combined)) {
+    return {
+      failureClassification: 'environment issue',
+      failureSource: 'agent runtime',
+      recommendedNextAction: 'Check agent availability and environment setup before retrying.',
+    };
+  }
+
   return {
     failureClassification: 'workflow bug',
     failureSource: 'orchestrator runtime',
@@ -439,12 +470,12 @@ function runAgent({ cwd, agent, model, prompt, timeoutSeconds = 1800, failLogPat
   let result;
   try {
     if (process.platform === 'win32') {
+      const comspec = process.env.COMSPEC || 'cmd.exe';
       result = spawnSync(
-        'powershell.exe',
+        comspec,
         [
-          '-NoProfile',
-          '-Command',
-          `acpx --cwd $env:AI_SPRINT_CWD --approve-all --model $env:AI_SPRINT_MODEL --timeout $env:AI_SPRINT_TIMEOUT ${agent} exec -f $env:AI_SPRINT_PROMPT`,
+          '/d', '/s', '/c',
+          `"${acpxBin}" --cwd "%AI_SPRINT_CWD%" --approve-all --model "%AI_SPRINT_MODEL%" --timeout "%AI_SPRINT_TIMEOUT%" ${agent} exec -f "%AI_SPRINT_PROMPT%"`,
         ],
         {
           cwd,
@@ -574,9 +605,10 @@ function runAgentAsync({ cwd, agent, model, prompt, timeoutSeconds = 1800, promp
 
     try {
       if (process.platform === 'win32') {
-        proc = spawn('powershell.exe', [
-          '-NoProfile', '-Command',
-          `acpx --cwd $env:AI_SPRINT_CWD --approve-all --model $env:AI_SPRINT_MODEL --timeout $env:AI_SPRINT_TIMEOUT ${agent} exec -f $env:AI_SPRINT_PROMPT`,
+        const comspec = process.env.COMSPEC || 'cmd.exe';
+        proc = spawn(comspec, [
+          '/d', '/s', '/c',
+          `"${acpxBin}" --cwd "%AI_SPRINT_CWD%" --approve-all --model "%AI_SPRINT_MODEL%" --timeout "%AI_SPRINT_TIMEOUT%" ${agent} exec -f "%AI_SPRINT_PROMPT%"`,
         ], {
           cwd,
           encoding: 'utf8',
@@ -833,9 +865,10 @@ function runAgentWithProgressCheck({
     // Spawn the agent process
     try {
       if (process.platform === 'win32') {
-        proc = spawn('powershell.exe', [
-          '-NoProfile', '-Command',
-          `acpx --cwd $env:AI_SPRINT_CWD --approve-all --model $env:AI_SPRINT_MODEL --timeout $env:AI_SPRINT_TIMEOUT ${agent} exec -f $env:AI_SPRINT_PROMPT`,
+        const comspec = process.env.COMSPEC || 'cmd.exe';
+        proc = spawn(comspec, [
+          '/d', '/s', '/c',
+          `"${acpxBin}" --cwd "%AI_SPRINT_CWD%" --approve-all --model "%AI_SPRINT_MODEL%" --timeout "%AI_SPRINT_TIMEOUT%" ${agent} exec -f "%AI_SPRINT_PROMPT%"`,
         ], {
           cwd,
           encoding: 'utf8',
@@ -1176,8 +1209,8 @@ export function getIsolationDir(runId, stageName, role) {
 }
 
 /**
- * Find report in iflow isolation directory.
- * iflow writes to runtime/tmp/sprint-agent/{runId}/{stage}-{role}/{report}.md
+ * Find report in agent isolation directory.
+ * Agent writes to runtime/tmp/sprint-agent/{runId}/{stage}-{role}/{report}.md
  *
  * IMPORTANT: Uses runId directly for isolation lookup, not fragile timestamp extraction.
  * This ensures different runs have unique isolation directories and prevents cross-contamination.
@@ -2608,6 +2641,9 @@ async function executeStage(runDir, state, spec) {
         worktreePath: worktreeInfo?.worktreePath,
         worklogPath: producerWorklogPath,
       });
+      if (result.status !== 0) {
+        throw new Error(`Agent exited with status ${result.status}: ${result.stderr || 'no stderr'}`);
+      }
       producerOutput = result.stdout;
       extensionsUsed = result.extensionsUsed ?? 0;
       if (extensionsUsed > 0) {

package/templates/langs/en/skills/evolve-task/SKILL.md

@@ -10,7 +10,7 @@ You must execute the following steps in order (no skipping). ARGUMENTS: $ARGUMEN
 - Read the last entry in memory/CHECKPOINT.md
 - Read the last 3 entries in memory/ISSUE_LOG.md
 - Read recent decisions in memory/DECISIONS.md
-- If .state/.pain_flag exists, handle breakpoint recovery first
+- Runtime V2 pain diagnosis uses task input/context, not `.state/.pain_flag`
 
 ## Step 1: Read Runtime Parameters & Self-Check
 - Read .principles/PROFILE.json, understand risk_paths, gate, tests.commands.
@@ -51,7 +51,7 @@ Output:
 
 ## Step 6: Delegate Planner (Movie Script Plan)
 - Planner outputs Plan (steps/commands/metrics/rollback).
-- Write plan to PLAN.md (STATUS line must exist).
+- Write plan to a planning document for owner review.
 - **Task Sync**: 
   - If `CLAUDE_CODE_TASK_LIST_ID` is set, you must convert the Plan's core steps to Native Tasks (via natural language command "Add task..." or related tools).
   - If not set and in interactive mode, prompt user: "Recommend running `export CLAUDE_CODE_TASK_LIST_ID=task-$(date +%s)` to enable persistent task tracking."
@@ -59,7 +59,7 @@ Output:
 - **Performance Evaluation**: After task completion, write to `.state/.verdict.json`. Format follows `@.principles/schemas/agent_verdict_schema.json`.
 
 ## Step 7: Delegate Implementer (Execution)
-- Implementer can only execute according to PLAN. Any deviation must first update PLAN.
+- Implementer executes according to the plan from Step 6. Any deviation must first be approved by updating the plan.
 - **Performance Evaluation**: After task completion, write to `.state/.verdict.json` based on verification results. Format follows `@.principles/schemas/agent_verdict_schema.json`.
 
 ## Step 8: Delegate Reviewer (Review)

package/templates/langs/en/skills/pd-cli-operator/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: pd-cli-operator
+description: Use this skill when operating the Principles Disciple `pd` CLI: probing runtime health, manually recording pain, inspecting tasks/runs/candidates/artifacts, intaking candidates, viewing flow policy, or cleaning legacy state. It routes CLI commands safely and forbids direct `.state/.pain_flag` writes.
+disable-model-invocation: false
+---
+
+# PD CLI Operator
+
+Use the `pd` CLI as the supported operator surface. Do not modify PD state files by hand unless a command explicitly says to do so.
+
+## Runtime V2 Pain Diagnosis
+
+Manual pain diagnosis:
+```bash
+pd pain record --reason "<reason>" --score <0-100> --workspace "<workspace>" --json
+```
+
+Success requires:
+- `status` is `succeeded`
+- `candidateIds` is non-empty
+- `ledgerEntryIds` is non-empty
+
+Forbidden:
+- Do not write `.state/.pain_flag`.
+- Do not use `write_file`, shell redirection, `Set-Content`, `Out-File`, or `node -e` to create pain flags.
+
+## Health And Policy
+
+Runtime probe:
+```bash
+pd runtime probe --runtime pi-ai --workspace "<workspace>" --json
+```
+
+Flow policy:
+```bash
+pd runtime flow show --workspace "<workspace>" --json
+```
+
+## Inspect Runtime V2 Objects
+
+Tasks and runs:
+```bash
+pd task show --task-id "<taskId>" --json
+pd run show --run-id "<runId>" --json
+```
+
+Candidates and artifacts:
+```bash
+pd candidate list --workspace "<workspace>" --json
+pd candidate show --candidate-id "<candidateId>" --workspace "<workspace>" --json
+pd artifact show --artifact-id "<artifactId>" --workspace "<workspace>" --json
+```
+
+Manual intake:
+```bash
+pd candidate intake --candidate-id "<candidateId>" --workspace "<workspace>" --json
+```
+
+## Legacy Admin
+
+Only when explicitly cleaning old state:
+```bash
+pd legacy cleanup --workspace "<workspace>" --dry-run
+pd legacy cleanup --workspace "<workspace>" --apply
+```
+
+Never use legacy cleanup as a diagnosis trigger.

package/templates/langs/en/skills/pd-diagnostician/SKILL.md

@@ -89,7 +89,7 @@ You are a professional root cause analysis expert. You MUST strictly follow the
 **Goal**: Collect sufficient factual evidence, avoid analysis based on assumptions.
 
 **Execution Steps**:
-1. Read `.state/.pain_flag` to get full context of Pain signal
+1. Use the Runtime V2 task input/context as the Pain signal source. Do not read `.state/.pain_flag` as the primary diagnosis input.
 2. Read last 100 lines of `.state/logs/events.jsonl`
 3. Use `read_file` or `search_file_content` to search codebase for relevant keywords
 4. Record all evidence sources (file path:line number)

package/templates/langs/en/skills/pd-mentor/SKILL.md

@@ -185,7 +185,7 @@ For complex scenarios, combine multiple skills:
 
 | Scenario | Combined Flow |
 |----------|---------------|
-| Major refactor | `/pd-evolve` → `plan-script` → `deductive-audit` → execute |
+| Major refactor | `/pd-evolve` → `deductive-audit` → execute |
 | System optimization | `/pd-status` → `evolve-system` → `root-cause` |
 | Project review | `/pd-daily` → `/pd-okr` → `reflection-log` |
 
@@ -196,7 +196,6 @@ These skills are usually called automatically by the system, but advanced users
 - `triage` - Issue triage
 - `root-cause` - Root cause analysis
 - `deductive-audit` - Deductive audit
-- `plan-script` - Plan orchestration
 - `reflection` - Metacognitive reflection
 - `reflection-log` - Reflection logging
 
@@ -211,7 +210,7 @@ A: GFI (Global Friction Index) measures the system's "pain level", range 0-100.
 A: EP is earned through successful task completion and problem resolution. Failures may deduct EP but have protection mechanisms. Reaching EP thresholds automatically upgrades your tier, unlocking more permissions (larger code modification limits).
 
 **Q: What is Pain Signal?**
-A: Pain Signal is a problem signal detected by the system, stored in `.state/.pain_flag`. When triggered, the system starts the evolution loop.
+A: Pain Signal is a problem signal detected by the system. Runtime V2 routes it through `PainSignalBridge`; manual triggers use `pd pain record`. `.state/.pain_flag` is legacy compatibility only.
 
 **Q: How to view installed tool capabilities?**
 A: Check `.state/SYSTEM_CAPABILITIES.json` or run `/pd-bootstrap` to rescan.

package/templates/langs/en/skills/pd-pain-signal/SKILL.md

@@ -1,52 +1,30 @@
 ---
 name: pd-pain-signal
-description: Manually inject a pain signal into the evolution system. Trigger conditions: (1) User reports agent stuck/looping/unresponsive (2) User says "record this issue", "force reflection", "trigger pain", "create pain signal", "人工注入 pain", "创建一个痛苦信号" (3) Tool failure with no follow-up action (4) User provides human intervention feedback. Mandatory enforcement: any manual pain flag creation scenario MUST use this skill, no bypassing allowed.
+description: Manually trigger a Principles Disciple Runtime V2 pain diagnosis. Use this when the user reports the agent is stuck, looping, unresponsive, or asks to record/trigger a pain signal. Mandatory path: use `pd pain record`; never write `.state/.pain_flag` and never use legacy write_pain_flag tooling.
 disable-model-invocation: false
 ---
 
-# Pain Signal (Force Pain Signal)
+# Pain Signal (Runtime V2)
 
-You are now the "Manual Intervention Pain" component.
+Manual pain diagnosis must enter Runtime V2 through the CLI:
 
-**Task**:
-1. Record the user's feedback `$ARGUMENTS` as a **high-priority** pain signal.
-2. Inform the user that the signal has been injected, and suggest waiting for the next Hook trigger (e.g., Stop or PreCompact) or manually running `/reflection-log`.
-
-**Mandatory Enforcement**:
-
-When you need to create, write, or manually create a pain flag, you **MUST** use this skill via the `write_pain_flag` tool. Any bypassing of this skill to directly operate on files violates the mandatory constraint of this skill.
+```bash
+pd pain record --reason "<reason>" --score <0-100> --workspace "<workspace>" --json
+```
 
-**Absolutely forbidden**:
-- ❌ Writing to `.state/.pain_flag` directly (any method)
-- ❌ Using bash heredoc (`cat <<EOF > .pain_flag`)
-- ❌ Using `echo "..." > .pain_flag`
-- ❌ Using `Set-Content` / `Out-File` or other PowerShell file-writing cmdlets
-- ❌ Using `node -e` to call `writePainFlag` or `buildPainFlag`
-- ❌ Any method that `toString()` a JavaScript object to the file
-- ❌ Using `exec` tool to invoke shell commands to write the pain_flag file
+## Forbidden
 
-**Why use the tool?**
-The `write_pain_flag` tool encapsulates correct KV-format serialization, ensuring `.pain_flag` is never corrupted. Historically, direct file writes caused `[object Object]` corruption and field loss (painScore → score mapping failure). Using the tool is the only safe path.
+- Do not write `.state/.pain_flag` directly.
+- Do not use `write_file`, shell redirection, `Set-Content`, `Out-File`, `node -e`, or any other file-writing method to create `.state/.pain_flag`.
+- Do not use `write_pain_flag`. That was a legacy path.
 
-**Parameters**:
-- `reason` (required): The reason for the pain signal — describe what went wrong
-- `score` (optional): Pain score 0-100, default 80 (manual intervention)
-- `source` (optional): Source, default `human_intervention`
-- `is_risky` (optional): Whether this is a high-risk action, default false
+## Verify
 
-**Example**:
-```
-write_pain_flag({
-  reason: "Agent edited a file without reading it first, breaking existing logic",
-  score: 85,
-  source: "human_intervention",
-  is_risky: false
-})
+Use:
+```bash
+pd runtime probe --runtime pi-ai --workspace "<workspace>" --json
+pd candidate list --workspace "<workspace>" --json
+pd runtime flow show --workspace "<workspace>" --json
 ```
 
-**Workflow**:
-1. Recognize trigger condition → read this skill
-2. Call `write_pain_flag` tool with `reason` and other parameters
-3. Confirm tool executed successfully (returns ✅)
-4. Inform user the pain signal has been injected; evolution system will process it on next heartbeat
-5. Do NOT perform any direct file write operations after this
+Success requires non-empty `candidateIds` and `ledgerEntryIds`.

package/templates/langs/en/skills/pd-runtime-v2/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: pd-runtime-v2
+description: Use this skill when manually triggering, verifying, or debugging Principles Disciple Runtime V2 pain diagnosis. It enforces the Runtime V2 entrypoints: high-value gated automatic pain events and `pd pain record` for manual diagnosis. It forbids writing `.state/.pain_flag` directly.
+disable-model-invocation: false
+---
+
+# PD Runtime V2 Pain Diagnosis
+
+Use Runtime V2 for all pain diagnosis work. Do not use legacy pain flag files as an entrypoint.
+
+## Entry Points
+
+Automatic:
+- Tool failures first accumulate GFI/friction.
+- Only high-value episodes enter Runtime V2: high GFI, repeated same failure, severe semantic pain, LLM paralysis, or explicit manual pain.
+- Approved `pain_detected` events enter `PainSignalBridge`.
+- The bridge runs `DiagnosticianRunner`, commits candidates, and intakes them into the ledger.
+
+Manual:
+```bash
+pd pain record --reason "<reason>" --score <0-100> --workspace "<workspace>" --json
+```
+
+Forbidden:
+- Do not write `.state/.pain_flag`.
+- Do not use `write_file`, shell redirection, `Set-Content`, `Out-File`, `node -e`, or any other file-writing method to create `.state/.pain_flag`.
+- Do not use a `write_pain_flag` tool. Runtime V2 does not use that tool.
+
+## Status Commands
+
+Runtime health:
+```bash
+pd runtime probe --runtime pi-ai --workspace "<workspace>" --json
+```
+
+Flow policy:
+```bash
+pd runtime flow show --workspace "<workspace>" --json
+```
+
+Candidates:
+```bash
+pd candidate list --workspace "<workspace>" --json
+pd candidate show --candidate-id "<candidateId>" --workspace "<workspace>" --json
+```
+
+## Success Criteria
+
+A diagnosis is successful only when:
+- `status` is `succeeded`
+- `candidateIds` is non-empty
+- `ledgerEntryIds` is non-empty
+
+Task creation alone is not success. A run without candidates or ledger entries is failed/retried/incomplete.
+
+## If Manual Diagnosis Is Needed
+
+1. Use `pd pain record`.
+2. Inspect JSON output.
+3. If `candidateIds` or `ledgerEntryIds` is empty, treat it as not completed.
+4. Use `pd candidate list/show` and `pd runtime flow show` for follow-up.

package/templates/langs/zh/core/AGENTS.md

@@ -17,8 +17,7 @@
 基于**项目战场**中的相对路径进行决策：
 
 - **项目最高战略**: `./memory/STRATEGY.md`
-- **项目物理计划**: `./PLAN.md`
-- **痛觉反射信号**: `./.state/.pain_flag`
+- **痛觉反射信号**: Runtime V2 `PainSignalBridge`（手动触发使用 `pd pain record`；`.state/.pain_flag` 仅为 legacy compatibility）
 - **系统能力快照**: `./.state/SYSTEM_CAPABILITIES.json`
 
 ---
@@ -63,7 +62,7 @@
 
 ### 心跳时应该检查（轮流执行）：
 
-- **痛觉与进化**: 检查 `.pain_flag`、`EVOLUTION_QUEUE.json`
+- **痛觉与进化**: 检查 Runtime V2 诊断（`pd pain record`、candidate、ledger）和 `EVOLUTION_QUEUE.json`；`.pain_flag` 仅为 legacy compatibility
 - **战略对齐**: 对比 `CURRENT_FOCUS.md`，确保未偏离重点
 - **环境健康**: 检查工具链状态、项目根目录整洁度
 
@@ -158,12 +157,13 @@
 你默认处于架构师模式。
 
 - **L1 (直接执行)**：单文件微调、文档维护 → 直接操作
-- **L2 (委派协议)**：重大变更 → **必须**更新 `./PLAN.md` 并使用 `pd_spawn_agent` 工具委派任务
+- **L2 (委派协议)**：重大变更 → 建议先描述计划并获得 owner 确认后再执行
 
-### 状态机门禁 (State Machine Gating)
+### 计划引导 (Planning Guidance)
 
-- **唯一事实源**：`./PLAN.md`
-- **物理拦截**：插件已激活。若 `PLAN.md` 非 `READY` 且尝试修改风险路径，调用将被阻断
+- 对复杂任务，建议先起草计划文档并获得 owner 批准后再做大幅修改
+- 这是行为建议，不是内置门禁 — PD 默认不强制"先计划后执行"
+- 若 owner 批准的 RuleHost 规则强制了计划行为，该规则会自动生效
 - **防止污染**：禁止将执行层细节写回战略文档
 
 ---