principles-disciple 1.8.1 → 1.8.3

package/{dist/utils/plugin-logger.js → src/utils/plugin-logger.ts}

@@ -1,10 +1,29 @@
 import * as fs from 'fs';
 import * as path from 'path';
+
+export interface PluginLogger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+    debug(message: string, meta?: Record<string, unknown>): void;
+}
+
+export interface PluginLoggerConfig {
+    /** Directory to store log files (typically stateDir) */
+    logDir: string;
+    /** Plugin identifier for log file naming */
+    pluginId: string;
+    /** Console logger from OpenClaw API (for dual output) */
+    consoleLogger?: PluginLogger;
+    /** Whether to also output to console */
+    echoToConsole?: boolean;
+}
+
 /**
  * Creates a plugin-specific logger that writes to its own log file.
- *
+ * 
  * Log file location: {logDir}/logs/{pluginId}.log
- *
+ * 
  * Example:
  * ```
  * const logger = createPluginLogger({
@@ -13,28 +32,32 @@ import * as path from 'path';
  *   consoleLogger: api.logger,
  *   echoToConsole: true
  * });
- *
+ * 
  * logger.info('Evolution task completed', { taskId: 'abc123' });
  * ```
  */
-export function createPluginLogger(config) {
+export function createPluginLogger(config: PluginLoggerConfig): PluginLogger {
     const { logDir, pluginId, consoleLogger, echoToConsole = true } = config;
+    
     // Ensure logs directory exists
     const logsDir = path.join(logDir, 'logs');
     if (!fs.existsSync(logsDir)) {
         fs.mkdirSync(logsDir, { recursive: true });
     }
+    
     const logFile = path.join(logsDir, `${pluginId}.log`);
-    const writeLog = (level, message, meta) => {
+    
+    const writeLog = (level: string, message: string, meta?: Record<string, unknown>) => {
         const timestamp = new Date().toISOString();
         const metaStr = meta ? ` ${JSON.stringify(meta)}` : '';
         const logLine = `${timestamp} [${level.toUpperCase()}] ${message}${metaStr}\n`;
+        
         try {
             fs.appendFileSync(logFile, logLine, 'utf-8');
-        }
-        catch {
+        } catch {
             // Silently fail if log write fails
         }
+        
         // Also echo to console if enabled
         if (echoToConsole && consoleLogger) {
             const consoleMessage = `[${pluginId}] ${message}`;
@@ -54,6 +77,7 @@ export function createPluginLogger(config) {
             }
         }
     };
+    
     return {
         info: (message, meta) => writeLog('info', message, meta),
         warn: (message, meta) => writeLog('warn', message, meta),
@@ -61,10 +85,11 @@ export function createPluginLogger(config) {
         debug: (message, meta) => writeLog('debug', message, meta),
     };
 }
+
 /**
  * Log file path for the plugin.
  * Returns the path where plugin logs are stored.
  */
-export function getPluginLogPath(logDir, pluginId) {
+export function getPluginLogPath(logDir: string, pluginId: string): string {
     return path.join(logDir, 'logs', `${pluginId}.log`);
 }

package/src/utils/subagent-probe.ts

@@ -0,0 +1,94 @@
+/**
+ * Subagent Runtime Availability Probe
+ *
+ * OpenClaw has two runtime modes:
+ * - Gateway mode: api.runtime.subagent methods are real async functions
+ * - Embedded mode: api.runtime.subagent is a Proxy that throws synchronously
+ *
+ * This utility provides a reliable way to detect which mode we're in.
+ */
+
+import type { OpenClawPluginApi } from '../openclaw-sdk.js';
+
+type SubagentRuntime = NonNullable<OpenClawPluginApi['runtime']>['subagent'];
+
+/**
+ * Try to access the global gateway subagent runtime.
+ * This is a fallback for cases where the plugin was loaded with
+ * allowGatewaySubagentBinding but the late-binding proxy isn't working.
+ */
+function getGlobalGatewaySubagent(): SubagentRuntime | null {
+  try {
+    // Access the global symbol that OpenClaw uses for gateway subagent
+    const symbol = Symbol.for('openclaw.plugin.gatewaySubagentRuntime');
+    const globalState = (globalThis as any)[symbol];
+    return globalState?.subagent ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if the subagent runtime is actually functional.
+ *
+ * In gateway mode, subagent.run is an AsyncFunction (constructor.name === 'AsyncFunction').
+ * In embedded mode, subagent.run is a regular Function that throws synchronously.
+ *
+ * We use constructor check first because it's fast and has no side effects.
+ *
+ * @param subagent - The subagent runtime object from api.runtime.subagent
+ * @returns true if the runtime is functional (gateway mode), false otherwise
+ */
+export function isSubagentRuntimeAvailable(
+  subagent: { run?: unknown } | undefined
+): boolean {
+  if (!subagent) return false;
+
+  try {
+    const runFn = subagent.run;
+    if (typeof runFn !== 'function') return false;
+
+    // In gateway mode, methods are AsyncFunction instances
+    // In embedded mode, methods are regular Function instances that throw
+    const isAsync = runFn.constructor?.name === 'AsyncFunction';
+    
+    if (isAsync) return true;
+
+    // Fallback: Check if it's a Proxy that might late-bind to the gateway subagent
+    // This handles the case where the plugin was loaded with allowGatewaySubagentBinding
+    // but the proxy hasn't resolved yet
+    const globalGateway = getGlobalGatewaySubagent();
+    if (globalGateway && typeof globalGateway.run === 'function') {
+      return globalGateway.run.constructor?.name === 'AsyncFunction';
+    }
+
+    return false;
+  } catch {
+    // Any error means unavailable
+    return false;
+  }
+}
+
+/**
+ * Get the actual subagent runtime, preferring the global gateway subagent
+ * if the passed one is not available.
+ * 
+ * This is useful for cases where the plugin was loaded with allowGatewaySubagentBinding
+ * but the late-binding proxy isn't resolving correctly.
+ */
+export function getAvailableSubagentRuntime(
+  subagent: SubagentRuntime | undefined
+): SubagentRuntime | undefined {
+  // First check if the passed subagent is available
+  if (isSubagentRuntimeAvailable(subagent)) {
+    return subagent;
+  }
+
+  // Fallback to global gateway subagent
+  const globalGateway = getGlobalGatewaySubagent();
+  if (globalGateway && isSubagentRuntimeAvailable(globalGateway)) {
+    return globalGateway;
+  }
+
+  return undefined;
+}

package/templates/langs/en/skills/ai-sprint-orchestration/EXAMPLES.md

@@ -0,0 +1,63 @@
+# AI Sprint Orchestration Examples
+
+## Example 1: baseline + validation
+
+```powershell
+node scripts/run.mjs --self-check
+node scripts/run.mjs --help
+node scripts/run.mjs --task workflow-validation-minimal
+node scripts/run.mjs --task workflow-validation-minimal-verify
+```
+
+## Example 2: custom runtime root
+
+```powershell
+node scripts/run.mjs --task workflow-validation-minimal --runtime-root D:/Temp/ai-sprint-runtime
+```
+
+## Example 3: classify a failure
+
+- `workflow bug`: package-local script still writes to repo-root `ops/ai-sprints`
+- `agent behavior issue`: reviewer omits `VERDICT` or malformed `DIMENSIONS`
+- `environment issue`: `acpx` missing or workspace not writable
+- `sample-spec issue`: validation spec asks for a field that the current product sample does not implement
+
+## Example 4: when to stop
+
+Stop the iteration after classification if:
+
+- the issue belongs to `packages/openclaw-plugin`
+- the issue depends on `D:/Code/openclaw`
+- the fix would require dashboard/stageGraph/self-optimization sprint expansion
+- the problem is a sample-side or product-side gap rather than workflow plumbing
+
+## Example 5: start from a complex bugfix template
+
+1. Copy `references/specs/bugfix-complex-template.json`
+2. Replace every placeholder in `taskContract`
+3. Narrow `executionScope` to the smallest useful round
+4. Run the packaged entrypoint with the edited spec:
+
+```powershell
+node scripts/run.mjs --task custom-bugfix --task-spec D:/path/to/your-bugfix-spec.json
+```
+
+## Example 6: start from a complex feature template
+
+1. Copy `references/specs/feature-complex-template.json`
+2. Fill `Goal`, `In scope`, `Out of scope`, `Validation commands`, and `Expected artifacts`
+3. Confirm the spec does not require product-side closure outside this milestone
+4. Run:
+
+```powershell
+node scripts/run.mjs --task custom-feature --task-spec D:/path/to/your-feature-spec.json
+```
+
+## Example 7: inspect checkpoint summary before continuation
+
+When a round ends in `revise`, inspect:
+
+- `stages/<stage>/checkpoint-summary.md`
+- `stages/<stage>/handoff.json`
+
+The next round should use the checkpoint summary as the primary carry-forward context and only fall back to full prior decision text when needed.

package/templates/langs/en/skills/ai-sprint-orchestration/REFERENCE.md

@@ -0,0 +1,136 @@
+# AI Sprint Orchestration Reference
+
+## Package layout
+
+- `scripts/run.mjs`: package-local orchestrator entrypoint
+- `scripts/lib/`: decision, contract validation, state store, spec loading, archive helpers
+- `references/specs/`: built-in validation specs
+- `references/agent-registry.json`: package-local agent/model registry
+- `references/workflow-v1-acceptance-checklist.md`: handoff checklist
+- `runtime/`: default location for run artifacts
+
+## Runtime layout
+
+Default runtime root:
+
+- `packages/openclaw-plugin/templates/langs/<lang>/skills/ai-sprint-orchestration/runtime`
+
+Subdirectories:
+
+- `runs/<run-id>/`
+- `archive/<run-id>/`
+- `tmp/sprint-agent/<run-id>/...`
+
+Override with either:
+
+- `--runtime-root <path>`
+- `AI_SPRINT_RUNTIME_ROOT=<path>`
+
+## Self check
+
+Run this first in a newly installed environment:
+
+- `node scripts/run.mjs --self-check`
+
+It verifies:
+
+- package-local references exist
+- built-in specs load
+- `agent-registry.json` exists
+- `acpx` is callable
+- runtime root is writable
+
+## Built-in specs
+
+- `workflow-validation-minimal`
+- `workflow-validation-minimal-verify`
+- `bugfix-complex-template` (copy and fill before use)
+- `feature-complex-template` (copy and fill before use)
+
+These built-in specs are package self-checks. They validate the workflow package itself, not product features.
+
+## Key artifacts
+
+For each run, inspect:
+
+- `sprint.json`
+- `timeline.md`
+- `latest-summary.md`
+- `decision.md`
+- `scorecard.json`
+
+Important persisted fields:
+
+- `outputQuality`
+- `qualityReasons`
+- `validation`
+- `nextRunRecommendation`
+- `failureClassification`
+- `failureSource`
+- `recommendedNextAction`
+
+Per-stage carry-forward artifact:
+
+- `checkpoint-summary.md`
+
+The next round should prefer `checkpoint-summary.md` as carry-forward context before falling back to a full prior `decision.md` or `handoff.json`.
+
+## Failure classification
+
+Use exactly one:
+
+- `workflow bug`: orchestration logic, artifact layout, CLI, validation, persistence
+- `agent behavior issue`: output quality or format drift despite correct workflow prompts/contracts
+- `environment issue`: missing binaries, permissions, filesystem, PATH, runtime access
+- `sample-spec issue`: the spec itself, or sample-side/product-side gaps that should not be fixed in this workflow milestone
+
+## Minimum task contract for complex work
+
+Complex bugfix and feature specs must explicitly provide:
+
+- `Goal`
+- `In scope`
+- `Out of scope`
+- `Validation commands`
+- `Expected artifacts`
+
+If any of these are missing or left as placeholders, the packaged skill refuses to start the sprint.
+
+## Execution scope limits
+
+Complex specs may define:
+
+- `maxFiles`
+- `maxChecks`
+- `maxDeliverables`
+
+The producer should declare `PLANNED_FILES`, `PLANNED_CHECKS`, and `DELIVERABLES` in the worklog before editing code. If one round would exceed scope, narrow the round or continue in a later round instead of forcing a large change through one execution.
+
+## Synchronization rule
+
+Source of truth remains:
+
+- the repository copy at `packages/openclaw-plugin/templates/langs/zh/skills/ai-sprint-orchestration`
+
+Sync the packaged copy only when the change affects:
+
+- package-local CLI behavior
+- validation behavior
+- artifact layout
+- package-local references or runtime assumptions
+
+Do not blindly mirror every upstream orchestrator edit into this package.
+
+## Current work-unit direction
+
+This package now supports a finer-grained `work-unit` layer to force tighter context boundaries between bounded units:
+
+- `workUnitId`
+- `workUnitGoal`
+- `allowedFiles`
+- `unitChecks`
+- `unitDeliverables`
+- `unitSummary`
+- `carryForwardSummary`
+
+Continuation should prefer the shorter `carryForwardSummary` before falling back to a full prior decision or handoff. The goal is to minimize cross-unit context while preserving the smallest necessary state for the next unit.

package/templates/langs/en/skills/ai-sprint-orchestration/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: ai-sprint-orchestration
+description: Run long-form coding work through the packaged AI sprint orchestrator with baseline checks, validation runs, failure classification, and workflow-only iteration discipline.
+---
+
+# AI Sprint Orchestration
+
+Use this skill when a task is large, multi-stage, or likely to need repeated review and continuation. The skill packages a local copy of the orchestrator so an agent can start from this skill directory instead of hunting through repo internals.
+
+## Use this skill for
+
+- Complex bug fixes that need investigation, implementation, and review
+- Feature work that benefits from explicit producer/reviewer decision gates
+- Workflow self-validation using the built-in validation specs
+- Long-running tasks where artifact persistence and resumability matter
+
+## Do not use this skill for
+
+- Tiny single-file edits or trivial docs fixes
+- Product-side sample gaps in `packages/openclaw-plugin`
+- Changes that require editing `D:/Code/openclaw`
+- Dashboard, stageGraph, self-optimizing sprint, or parallel orchestrator expansion
+
+## Quick start
+
+Run these commands from the skill package root:
+
+1. Package smoke check:
+   `node scripts/run.mjs --self-check`
+   `node scripts/run.mjs --help`
+2. Package-local validation:
+   `node scripts/run.mjs --task workflow-validation-minimal`
+   `node scripts/run.mjs --task workflow-validation-minimal-verify`
+3. Inspect artifacts under:
+   `runtime/`
+
+Internal smoke standard:
+
+- `node scripts/run.mjs --self-check` passes
+- `workflow-validation-minimal` reaches producer completion and produces a structured decision or classified halt
+- `workflow-validation-minimal-verify` reaches producer completion and any reviewer failure is classified, not left opaque
+
+If you also have the source repository available, you may additionally run the source baseline tests from `packages/openclaw-plugin/templates/langs/zh/skills/ai-sprint-orchestration/test/`.
+
+## Execution rules
+
+- Treat `packages/openclaw-plugin/templates/langs/zh/skills/ai-sprint-orchestration` as the canonical code source.
+- Treat this English package as a mirrored delivery copy of that canonical implementation.
+- If a run fails, classify it as exactly one of:
+  - `workflow bug`
+  - `agent behavior issue`
+  - `environment issue`
+  - `sample-spec issue`
+- If the failure is product-side or sample-side, stop after classification. Do not continue into product closure work.
+- Only fix one workflow-only issue per iteration, then rerun baseline and validation.
+- Always run `node scripts/run.mjs --self-check` before the first validation run in a new environment.
+- For complex bugfix or feature work, start from a copied template spec and fill the minimum task contract before launching the sprint.
+
+## Output expectation
+
+Each iteration should report only:
+
+- what changed
+- what ran
+- what failed
+- failure classification
+- the single next recommended iteration

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

@@ -0,0 +1,214 @@
+{
+  "$schema": "agent-registry-v1",
+  "description": "Registry of available agents and their supported models for AI sprint orchestrator. All models are FREE. Updated: 2026-04-04.",
+  "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",
+      "version": "1.3.13",
+      "models": {
+        "minimax-cn-coding-plan/MiniMax-M2.7": {
+          "description": "MiniMax M2.7 (Chinese coding plan)",
+          "pricing": "free",
+          "recommendedTimeoutSeconds": 1200,
+          "features": ["fast", "coding-optimized", "stable"],
+          "notes": "最稳定的模型，默认 producer 选择"
+        },
+        "minimax-cn-coding-plan/MiniMax-M2.5": {
+          "description": "MiniMax M2.5 (Chinese coding plan)",
+          "pricing": "free",
+          "recommendedTimeoutSeconds": 1200,
+          "features": ["fast", "coding-optimized"],
+          "notes": "能力略弱于 M2.7"
+        },
+        "minimax-cn-coding-plan/MiniMax-M2.7-highspeed": {
+          "description": "MiniMax M2.7 highspeed variant",
+          "pricing": "free",
+          "recommendedTimeoutSeconds": 900,
+          "features": ["fast", "highspeed"],
+          "notes": "高速变体"
+        },
+        "minimax-cn-coding-plan/MiniMax-M2": {
+          "description": "MiniMax M2 (Chinese coding plan)",
+          "pricing": "free",
+          "recommendedTimeoutSeconds": 1200,
+          "features": ["fast"],
+          "notes": "旧版本"
+        },
+        "minimax-cn-coding-plan/MiniMax-M2.1": {
+          "description": "MiniMax M2.1 (Chinese coding plan)",
+          "pricing": "free",
+          "recommendedTimeoutSeconds": 1200,
+          "features": ["fast"],
+          "notes": "旧版本"
+        }
+      }
+    },
+
+    "gemini": {
+      "command": "gemini --acp",
+      "description": "Gemini CLI with ACP support (全部免费)",
+      "models": {
+        "gemini-2.5-pro": {
+          "description": "Gemini 2.5 Pro — high reasoning capability",
+          "pricing": "free",
+          "recommendedTimeoutSeconds": 1800,
+          "features": ["high-reasoning"],
+          "notes": "高推理能力"
+        },
+        "gemini-2.5-flash": {
+          "description": "Gemini 2.5 Flash — fast response",
+          "pricing": "free",
+          "recommendedTimeoutSeconds": 1200,
+          "features": ["fast"],
+          "notes": "快速响应"
+        },
+        "gemini-2.5-flash-lite": {
+          "description": "Gemini 2.5 Flash Lite — lightweight",
+          "pricing": "free",
+          "recommendedTimeoutSeconds": 900,
+          "features": ["fast", "lite"],
+          "notes": "轻量版本"
+        },
+        "gemini-3-pro-preview": {
+          "description": "Gemini 3 Pro Preview — high reasoning, limited quota",
+          "pricing": "free",
+          "recommendedTimeoutSeconds": 1800,
+          "features": ["high-reasoning", "slow", "limited-quota"],
+          "notes": "高推理，但额度有限、很慢"
+        },
+        "gemini-3-flash-preview": {
+          "description": "Gemini 3 Flash Preview",
+          "pricing": "free",
+          "recommendedTimeoutSeconds": 1200,
+          "features": ["fast", "preview"],
+          "notes": "预览版本"
+        },
+        "gemini-3.1-pro-preview": {
+          "description": "Gemini 3.1 Pro Preview — high reasoning, limited quota",
+          "pricing": "free",
+          "recommendedTimeoutSeconds": 1800,
+          "features": ["high-reasoning", "slow", "limited-quota"],
+          "notes": "高推理，但额度有限、很慢"
+        },
+        "gemini-3.1-flash-lite-preview": {
+          "description": "Gemini 3.1 Flash Lite Preview — lightweight preview",
+          "pricing": "free",
+          "recommendedTimeoutSeconds": 900,
+          "features": ["fast", "lite", "preview"],
+          "notes": "轻量预览版本"
+        }
+      }
+    },
+
+    "qwen": {
+      "command": "qwen --acp",
+      "description": "Qwen Code CLI with ACP support (全部免费)",
+      "models": {
+        "qwen3.6-plus": {
+          "description": "Qwen 3.6 Plus — efficient hybrid model with leading coding performance, 1M context window",
+          "pricing": "free",
+          "recommendedTimeoutSeconds": 1200,
+          "features": ["fast", "coding-optimized", "long-context"],
+          "notes": "高效混合模型，领先编码性能，100 万 token 上下文窗口"
+        }
+      }
+    },
+
+    "claude": {
+      "command": "claude",
+      "description": "Claude Code (Anthropic)",
+      "version": "2.1.81",
+      "models": {
+        "GLM-5.1": {
+          "description": "GLM-5.1 via Claude Code adapter",
+          "pricing": "free",
+          "recommendedTimeoutSeconds": 1800,
+          "features": ["slow"],
+          "notes": "保留给 escalation/global-reviewer 角色。注意：智谱 Code Plan 限额较高，容易触发限流"
+        }
+      }
+    }
+  },
+
+  "_notes": {
+    "paid_plans": "智谱 Code Plan 和 MiniMax Code Plan 是付费套餐，但本 registry 只登记免费可用的模型。付费套餐更稳定但不改变模型列表。",
+    "codex": "codex-acp 在当前环境无法使用，不登记。",
+    "kilocode": "kilocode ACP 是 server 模式（监听端口），不是 headless prompt-response，不兼容 acpx，不登记。",
+    "qodercli": "qodercli 没有 --acp 标志，不登记。",
+    "model_discovery": "opencode 可通过 'opencode models' 自动列出模型。其他 agent（iflow, gemini, qwen）没有 CLI 列表命令，需手动维护。"
+  }
+}