principles-disciple 1.8.2 → 1.8.3

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "principles-disciple",
   "name": "Principles Disciple",
   "description": "Evolutionary programming agent framework with strategic guardrails and reflection loops.",
-  "version": "1.8.2",
+  "version": "1.8.3",
   "skills": [
     "./skills"
   ],
@@ -76,8 +76,8 @@
     }
   },
   "buildFingerprint": {
-    "gitSha": "787ed1c54034",
-    "bundleMd5": "f9dbcc5968920a4840ba02316515d1e4",
-    "builtAt": "2026-04-06T06:42:07.398Z"
+    "gitSha": "c159a298aac0",
+    "bundleMd5": "e54bd6b71182252dd335aa016c9caa0e",
+    "builtAt": "2026-04-06T05:28:57.508Z"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "principles-disciple",
-  "version": "1.8.2",
+  "version": "1.8.3",
   "description": "Native OpenClaw plugin for Principles Disciple",
   "type": "module",
   "main": "./dist/bundle.js",

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 列表命令，需手动维护。"
+  }
+}

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

@@ -0,0 +1,107 @@
+{
+  "id": "bugfix-complex-template",
+  "title": "Complex Bugfix Template - Replace before use",
+  "workspace": "__SKILL_PACKAGE_ROOT__",
+  "branchWorkspace": "__SKILL_PACKAGE_ROOT__",
+  "branch": "main",
+  "requiresTaskContract": true,
+  "taskContract": {
+    "goal": "<describe the bug to fix and the expected behavior after the fix>",
+    "inScope": [
+      "<target modules or files that may be changed>"
+    ],
+    "outOfScope": [
+      "<forbidden modules, unrelated refactors, product-side gaps>"
+    ],
+    "validationCommands": [
+      "<command 1>",
+      "<command 2>"
+    ],
+    "expectedArtifacts": [
+      "decision.md",
+      "scorecard.json",
+      "<optional task-specific artifact>"
+    ]
+  },
+  "executionScope": {
+    "maxFiles": 6,
+    "maxChecks": 4,
+    "maxDeliverables": 3
+  },
+  "maxRoundsPerStage": 2,
+  "maxRuntimeMinutes": 60,
+  "stageTimeoutMinutes": 15,
+  "stages": ["investigate", "implement-pass-1", "verify"],
+  "producer": {
+    "agent": "iflow",
+    "model": "glm-4.7",
+    "timeoutSeconds": 180
+  },
+  "reviewerA": {
+    "agent": "iflow",
+    "model": "glm-4.7",
+    "timeoutSeconds": 120,
+    "focus": "Validate root cause, behavioral change, and code correctness."
+  },
+  "reviewerB": {
+    "agent": "iflow",
+    "model": "glm-4.7",
+    "timeoutSeconds": 120,
+    "focus": "Validate scope control, verification quality, and regression risk."
+  },
+  "context": [
+    "This is a generic complex bugfix sprint template.",
+    "Replace all placeholder contract values before running.",
+    "Use this template only for workflow-contained bugfix work, not for product-side closure in out-of-scope repositories."
+  ],
+  "stageGoals": {
+    "investigate": [
+      "Establish the most likely root cause.",
+      "Narrow the allowed file set and verification plan.",
+      "Produce a bugfix plan that fits one bounded implementation round."
+    ],
+    "implement-pass-1": [
+      "Implement the smallest sufficient bugfix within the declared scope.",
+      "Run the planned verification commands.",
+      "Record evidence that the observed behavior changed."
+    ],
+    "verify": [
+      "Verify the fix changed the intended behavior.",
+      "Check whether any regression risk remains unverified.",
+      "Decide whether the bugfix is ready to stop, continue, or revise."
+    ]
+  },
+  "stageCriteria": {
+    "investigate": {
+      "requiredApprovals": 2,
+      "requiredProducerSections": ["SUMMARY", "CHANGES", "EVIDENCE", "CODE_EVIDENCE", "KEY_EVENTS", "HYPOTHESIS_MATRIX", "CHECKS", "OPEN_RISKS"],
+      "requiredReviewerSections": ["VERDICT", "BLOCKERS", "FINDINGS", "CODE_EVIDENCE", "HYPOTHESIS_MATRIX", "NEXT_FOCUS", "CHECKS"],
+      "scoringDimensions": ["root_cause_quality", "scope_definition"],
+      "dimensionThreshold": 3,
+      "requiredDeliverables": ["root_cause_hypothesis", "execution_plan", "verification_plan"]
+    },
+    "implement-pass-1": {
+      "requiredApprovals": 2,
+      "requiredProducerSections": ["SUMMARY", "CHANGES", "EVIDENCE", "CODE_EVIDENCE", "KEY_EVENTS", "HYPOTHESIS_MATRIX", "CHECKS", "OPEN_RISKS", "CONTRACT"],
+      "requiredReviewerSections": ["VERDICT", "BLOCKERS", "FINDINGS", "CODE_EVIDENCE", "HYPOTHESIS_MATRIX", "NEXT_FOCUS", "CHECKS"],
+      "scoringDimensions": ["behavior_change", "verification_quality", "scope_control"],
+      "dimensionThreshold": 3,
+      "requiredDeliverables": ["code_change", "verification_evidence", "risk_summary"]
+    },
+    "verify": {
+      "requiredApprovals": 2,
+      "requiredProducerSections": ["SUMMARY", "CHANGES", "EVIDENCE", "CODE_EVIDENCE", "KEY_EVENTS", "HYPOTHESIS_MATRIX", "CHECKS", "OPEN_RISKS"],
+      "requiredReviewerSections": ["VERDICT", "BLOCKERS", "FINDINGS", "CODE_EVIDENCE", "HYPOTHESIS_MATRIX", "NEXT_FOCUS", "CHECKS"],
+      "scoringDimensions": ["artifact_verification", "residual_risk"],
+      "dimensionThreshold": 3,
+      "requiredDeliverables": ["verified_behavior_change", "residual_risk_assessment"]
+    }
+  },
+  "stageRoleTimeouts": {
+    "investigate": { "producer": 180, "reviewer_a": 120, "reviewer_b": 120 },
+    "implement-pass-1": { "producer": 240, "reviewer_a": 120, "reviewer_b": 120 },
+    "verify": { "producer": 120, "reviewer_a": 90, "reviewer_b": 90 }
+  },
+  "continuationSpec": null,
+  "recoverySpec": null
+}