strikethroo 3.6.1 → 3.8.0

package/templates/harness/skills/st-execute-task/scripts/check-task-dependencies.cjs

@@ -33,8 +33,8 @@ __export(check_task_dependencies_exports, {
   _main: () => _main
 });
 module.exports = __toCommonJS(check_task_dependencies_exports);
-var fs4 = __toESM(require("fs"));
-var path4 = __toESM(require("path"));
+var fs5 = __toESM(require("fs"));
+var path5 = __toESM(require("path"));
 
 // src/skill-scripts/shared/plan-resolve.ts
 var fs3 = __toESM(require("fs"));
@@ -43,7 +43,7 @@ var path3 = __toESM(require("path"));
 // src/skill-scripts/shared/root.ts
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
-var EXPECTED_SCHEMA = true ? 2 : 2;
+var EXPECTED_SCHEMA = true ? 3 : 3;
 var isValidStrikethrooRoot = (strikethrooPath) => {
   try {
     if (!fs.existsSync(strikethrooPath)) return false;
@@ -244,43 +244,31 @@ var resolvePlan = (input, startPath = process.cwd()) => {
   return resolveByIdInAncestry(planId, startPath);
 };
 
-// src/skill-scripts/check-task-dependencies.ts
-var _printError = (message) => {
-  console.error(`ERROR: ${message}`);
-};
-var _printSuccess = (message) => {
-  console.log(`\u2713 ${message}`);
-};
-var _printWarning = (message) => {
-  console.log(`\u26A0 ${message}`);
-};
-var _printInfo = (message) => {
-  console.log(message);
-};
-var _extractFrontmatter = (content) => {
+// src/skill-scripts/shared/task-file.ts
+var fs4 = __toESM(require("fs"));
+var path4 = __toESM(require("path"));
+var extractFrontmatter = (content) => {
   const match = content.match(/^---\s*\r?\n([\s\S]*?)\r?\n---/);
   return match && match[1] ? match[1] : null;
 };
-var _findTaskFile = (planDir, taskId) => {
+var findTaskFile = (planDir, taskId) => {
   const taskDir = path4.join(planDir, "tasks");
-  if (!fs4.existsSync(taskDir)) {
-    return null;
-  }
-  const variations = [taskId, taskId.padStart(2, "0"), taskId.replace(/^0+/, "") || "0"];
+  if (!fs4.existsSync(taskDir)) return null;
+  const idStr = String(taskId);
+  const variations = [idStr, idStr.padStart(2, "0"), idStr.replace(/^0+/, "") || "0"];
   const uniqueVariations = [...new Set(variations)];
   try {
     const files = fs4.readdirSync(taskDir);
-    const found = uniqueVariations.reduce((acc, v) => {
+    return uniqueVariations.reduce((acc, v) => {
       if (acc) return acc;
       const match = files.find((f) => f.startsWith(`${v}--`) && f.endsWith(".md"));
       return match ? path4.join(taskDir, match) : null;
-    }, null);
-    return found;
+    }, null) ?? null;
   } catch (_err) {
     return null;
   }
 };
-var _extractDependencies = (frontmatter) => {
+var extractDependencies = (frontmatter) => {
   const lines = frontmatter.split("\n");
   const dependencies = [];
   let inDependenciesSection = false;
@@ -300,22 +288,86 @@ var _extractDependencies = (frontmatter) => {
     }
     if (inDependenciesSection && line.match(/^[ \t]*-/)) {
       const dep = line.replace(/^[ \t]*-[ \t]*/, "").replace(/[ \t]*$/, "").replace(/['"]/g, "");
-      if (dep.length > 0) {
-        dependencies.push(dep);
-      }
+      if (dep.length > 0) dependencies.push(dep);
     }
   }
   return dependencies;
 };
-var _extractStatus = (frontmatter) => {
-  const lines = frontmatter.split("\n");
-  for (const line of lines) {
+var extractStatus = (frontmatter) => {
+  for (const line of frontmatter.split("\n")) {
     if (line.match(/^status:/)) {
       return line.replace(/^status:[ \t]*/, "").replace(/^["']/, "").replace(/["']$/, "").trim();
     }
   }
   return null;
 };
+var collectTaskReadinessIssues = (planDir, taskId) => {
+  const issues = [];
+  const taskFile = findTaskFile(planDir, taskId);
+  const idLabel = String(taskId);
+  if (!taskFile || !fs4.existsSync(taskFile)) {
+    issues.push({ taskId: idLabel, kind: "missing", detail: "task file not found" });
+    return issues;
+  }
+  const taskContent = fs4.readFileSync(taskFile, "utf8");
+  const frontmatter = extractFrontmatter(taskContent);
+  if (!frontmatter) {
+    issues.push({ taskId: idLabel, kind: "missing", detail: "task frontmatter not found" });
+    return issues;
+  }
+  const status = extractStatus(frontmatter);
+  if (status === "needs-clarification") {
+    issues.push({
+      taskId: idLabel,
+      kind: "needs-clarification",
+      detail: "status is needs-clarification"
+    });
+  }
+  for (const depId of extractDependencies(frontmatter)) {
+    const depFile = findTaskFile(planDir, depId);
+    if (!depFile || !fs4.existsSync(depFile)) {
+      issues.push({
+        taskId: idLabel,
+        kind: "unresolved-dependency",
+        detail: `dependency ${depId} not found`
+      });
+      continue;
+    }
+    const depContent = fs4.readFileSync(depFile, "utf8");
+    const depFrontmatter = extractFrontmatter(depContent);
+    if (!depFrontmatter) {
+      issues.push({
+        taskId: idLabel,
+        kind: "unresolved-dependency",
+        detail: `dependency ${depId} has no frontmatter`
+      });
+      continue;
+    }
+    const depStatus = extractStatus(depFrontmatter);
+    if (depStatus !== "completed") {
+      issues.push({
+        taskId: idLabel,
+        kind: "unresolved-dependency",
+        detail: `dependency ${depId} status is ${depStatus ?? "unknown"}`
+      });
+    }
+  }
+  return issues;
+};
+
+// src/skill-scripts/check-task-dependencies.ts
+var _printError = (message) => {
+  console.error(`ERROR: ${message}`);
+};
+var _printSuccess = (message) => {
+  console.log(`\u2713 ${message}`);
+};
+var _printWarning = (message) => {
+  console.log(`\u26A0 ${message}`);
+};
+var _printInfo = (message) => {
+  console.log(message);
+};
 var _main = (startPath = process.cwd()) => {
   if (process.argv.length !== 4) {
     _printError("Invalid number of arguments");
@@ -336,20 +388,29 @@ var _main = (startPath = process.cwd()) => {
   }
   const { planDir, planId } = resolved;
   _printInfo(`Found plan directory: ${planDir}`);
-  const taskFile = _findTaskFile(planDir, taskId);
-  if (!taskFile || !fs4.existsSync(taskFile)) {
+  const taskFile = findTaskFile(planDir, taskId);
+  if (!taskFile) {
     _printError(`Task with ID ${taskId} not found in plan ${planId}`);
     process.exit(1);
   }
-  _printInfo(`Checking task: ${path4.basename(taskFile)}`);
+  _printInfo(`Checking task: ${path5.basename(taskFile)}`);
   console.log("");
-  const taskContent = fs4.readFileSync(taskFile, "utf8");
-  const frontmatter = _extractFrontmatter(taskContent);
+  const issues = collectTaskReadinessIssues(planDir, taskId);
+  const dependencyIssues = issues.filter((issue) => issue.kind === "unresolved-dependency");
+  const blockingIssues = issues.filter((issue) => issue.kind !== "unresolved-dependency");
+  if (blockingIssues.length > 0) {
+    for (const issue of blockingIssues) {
+      _printError(issue.detail);
+    }
+    process.exit(1);
+  }
+  const taskContent = fs5.readFileSync(taskFile, "utf8");
+  const frontmatter = extractFrontmatter(taskContent);
   if (!frontmatter) {
     _printError("Could not extract frontmatter from task file");
     process.exit(1);
   }
-  const dependencies = _extractDependencies(frontmatter);
+  const dependencies = extractDependencies(frontmatter);
   if (dependencies.length === 0) {
     _printSuccess("Task has no dependencies - ready to execute!");
     process.exit(0);
@@ -359,57 +420,38 @@ var _main = (startPath = process.cwd()) => {
     console.log(`  - Task ${dep}`);
   });
   console.log("");
-  let allResolved = true;
-  const unresolvedDeps = [];
-  let resolvedCount = 0;
-  const totalDeps = dependencies.length;
   _printInfo("Checking dependency status...");
   console.log("");
+  let resolvedCount = 0;
   for (const depId of dependencies) {
-    const depFile = _findTaskFile(planDir, depId);
-    if (!depFile || !fs4.existsSync(depFile)) {
-      _printError(`Dependency task ${depId} not found`);
-      allResolved = false;
-      unresolvedDeps.push(`${depId} (not found)`);
-      continue;
-    }
-    const depContent = fs4.readFileSync(depFile, "utf8");
-    const depFrontmatter = _extractFrontmatter(depContent);
-    if (!depFrontmatter) {
-      _printError(`Could not extract frontmatter from dependency task ${depId}`);
-      allResolved = false;
-      unresolvedDeps.push(`${depId} (no frontmatter)`);
-      continue;
-    }
-    const status = _extractStatus(depFrontmatter);
-    if (status === "completed") {
+    const depFile = findTaskFile(planDir, depId);
+    const depFrontmatter = depFile ? extractFrontmatter(fs5.readFileSync(depFile, "utf8")) : null;
+    const depStatus = depFrontmatter ? extractStatus(depFrontmatter) : null;
+    if (depStatus === "completed") {
       _printSuccess(`Task ${depId} - Status: completed \u2713`);
       resolvedCount++;
     } else {
-      _printWarning(`Task ${depId} - Status: ${status || "unknown"} \u2717`);
-      allResolved = false;
-      unresolvedDeps.push(`${depId} (${status || "unknown"})`);
+      _printWarning(`Task ${depId} - Status: ${depStatus ?? "unknown"} \u2717`);
     }
   }
   console.log("");
   _printInfo("=========================================");
   _printInfo("Dependency Check Summary");
   _printInfo("=========================================");
-  _printInfo(`Total dependencies: ${totalDeps}`);
+  _printInfo(`Total dependencies: ${dependencies.length}`);
   _printInfo(`Resolved: ${resolvedCount}`);
-  _printInfo(`Unresolved: ${totalDeps - resolvedCount}`);
+  _printInfo(`Unresolved: ${dependencies.length - resolvedCount}`);
   console.log("");
-  if (allResolved) {
+  if (dependencyIssues.length === 0) {
     _printSuccess(`All dependencies are resolved! Task ${taskId} is ready to execute.`);
     process.exit(0);
-  } else {
-    _printError(`Task ${taskId} has unresolved dependencies:`);
-    unresolvedDeps.forEach((dep) => {
-      console.log(dep);
-    });
-    _printInfo("Please complete the dependencies before executing this task.");
-    process.exit(1);
   }
+  _printError(`Task ${taskId} has unresolved dependencies:`);
+  dependencyIssues.forEach((issue) => {
+    console.log(issue.detail);
+  });
+  _printInfo("Please complete the dependencies before executing this task.");
+  process.exit(1);
 };
 if (require.main === module) {
   _main();

package/templates/harness/skills/st-execute-task/scripts/find-strikethroo-root.cjs

@@ -37,7 +37,7 @@ module.exports = __toCommonJS(find_strikethroo_root_exports);
 // src/skill-scripts/shared/root.ts
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
-var EXPECTED_SCHEMA = true ? 2 : 2;
+var EXPECTED_SCHEMA = true ? 3 : 3;
 var isValidStrikethrooRoot = (strikethrooPath) => {
   try {
     if (!fs.existsSync(strikethrooPath)) return false;

package/templates/harness/skills/st-execute-task/scripts/validate-plan-blueprint.cjs

@@ -39,7 +39,7 @@ var path4 = __toESM(require("path"));
 // src/skill-scripts/shared/root.ts
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
-var EXPECTED_SCHEMA = true ? 2 : 2;
+var EXPECTED_SCHEMA = true ? 3 : 3;
 var isValidStrikethrooRoot = (strikethrooPath) => {
   try {
     if (!fs.existsSync(strikethrooPath)) return false;
@@ -242,6 +242,12 @@ var resolvePlan = (input, startPath = process.cwd()) => {
   return resolveByIdInAncestry(planId, startPath);
 };
 
+// src/skill-scripts/shared/task-file.ts
+var extractFrontmatter = (content) => {
+  const match = content.match(/^---\s*\r?\n([\s\S]*?)\r?\n---/);
+  return match && match[1] ? match[1] : null;
+};
+
 // src/skill-scripts/validate-plan-blueprint.ts
 var VALID_FIELDS = [
   "planFile",
@@ -249,8 +255,47 @@ var VALID_FIELDS = [
   "taskCount",
   "blueprintExists",
   "strikethrooRoot",
-  "planId"
+  "planId",
+  "complexityScoresValid",
+  "invalidComplexityTasks"
 ];
+var validateComplexityScores = (planDir) => {
+  const tasksDir = path4.join(planDir, "tasks");
+  if (!fs4.existsSync(tasksDir)) return [];
+  let files;
+  try {
+    if (!fs4.lstatSync(tasksDir).isDirectory()) return [];
+    files = fs4.readdirSync(tasksDir).filter((f) => f.endsWith(".md")).sort();
+  } catch (_err) {
+    return [];
+  }
+  const invalid = [];
+  for (const file of files) {
+    let content;
+    try {
+      content = fs4.readFileSync(path4.join(tasksDir, file), "utf8");
+    } catch (_err) {
+      invalid.push(`${file}: unreadable`);
+      continue;
+    }
+    const frontmatter = extractFrontmatter(content);
+    const match = frontmatter ? frontmatter.match(/^\s*complexity_score\s*:\s*(.*?)\s*(?:#.*)?$/im) : null;
+    if (!match || match[1] === void 0) {
+      invalid.push(`${file}: missing complexity_score`);
+      continue;
+    }
+    const raw = match[1].trim();
+    if (!/^\d+$/.test(raw)) {
+      invalid.push(`${file}: non-integer complexity_score "${raw}"`);
+      continue;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    if (parsed < 1 || parsed > 10) {
+      invalid.push(`${file}: complexity_score ${parsed} out of range 1-10`);
+    }
+  }
+  return invalid;
+};
 var countTasks = (planDir) => {
   const tasksDir = path4.join(planDir, "tasks");
   if (!fs4.existsSync(tasksDir)) return 0;
@@ -324,13 +369,16 @@ var main = () => {
     }
     process.exit(1);
   }
+  const invalidComplexity = validateComplexityScores(resolved.planDir);
   const result = {
     planFile: resolved.planFile,
     planDir: resolved.planDir,
     strikethrooRoot: resolved.strikethrooRoot,
     planId: resolved.planId,
     taskCount: countTasks(resolved.planDir),
-    blueprintExists: checkBlueprintExists(resolved.planFile) ? "yes" : "no"
+    blueprintExists: checkBlueprintExists(resolved.planFile) ? "yes" : "no",
+    complexityScoresValid: invalidComplexity.length === 0 ? "yes" : "no",
+    invalidComplexityTasks: invalidComplexity.join("; ")
   };
   if (fieldName) {
     if (!VALID_FIELDS.includes(fieldName)) {

package/templates/harness/skills/st-full-workflow/SKILL.md

@@ -222,13 +222,48 @@ For each task, identify:
 
 A task B depends on A if B requires A's output or artifacts, modifies code created by A, or tests functionality implemented by A. Validate that the final dependency graph is acyclic.
 
-#### 7. Allocate task IDs
+#### 7. Complexity analysis
+
+For every candidate task, assign a `complexity_score` (integer 1–10) before
+writing any file. Base the score on these four dimensions:
+
+| Score | Skill breadth | Acceptance-criteria clarity | Integration surface | Decomposition depth |
+| --- | --- | --- | --- | --- |
+| 1–3 | One well-known skill | Criteria are concrete and observable | None or a single file/module | No further split possible |
+| 4–5 | One primary skill plus a familiar adjacent skill | Criteria are clear with few edge cases | One component or API boundary | Already atomic |
+| 6–7 | Two distinct skills, or one skill with ambiguous requirements | Criteria need clarification or have multiple edge cases | Multiple components or contracts | Could still be split |
+| 8–10 | Three or more skills, or cross-cutting design decisions | Criteria are vague, unknown, or depend on unresolved choices | Wide integration surface or external systems | Must be decomposed further |
+
+**Pre-emission sanity rules** — apply these before any task is written:
+
+- 3+ skills assigned → split the task into smaller tasks, each with 1–2 skills.
+- Vague acceptance criteria → sharpen them until they include at least one
+  concrete, runnable verification step.
+- Trivially small adjacent tasks → merge them into a single task.
+- Score ≥ 8 → decompose further; do not emit as-is.
+- Score 6–7 → either sharpen criteria or split; do not emit without an
+  explicit reason.
+
+**Required frontmatter:**
+
+- Every emitted task MUST include `complexity_score` (integer 1–10).
+- Optionally include `complexity_notes` when the score needs justification,
+  such as "Ambiguous API contract" or "Decomposed from a higher-score parent".
+
+**Loop-back rule:**
+
+After applying split, sharpen, or merge, re-run dependency analysis and
+re-score the adjusted tasks. Repeat this loop no more than three times. If
+complexity is still unresolved after three passes, stop and surface the
+blocker to the user.
+
+#### 8. Allocate task IDs
 
 Run `scripts/get-next-task-id.cjs <plan-id>` to obtain the first available task ID. Allocate subsequent IDs by incrementing in-process. Use the unpadded integer in the task frontmatter `id` field and the zero-padded form (`{padded-id}--{slug}`) for the filename.
 
 The slug derives from a short task title: lowercase, alphanumeric and hyphens only, collapsed, trimmed.
 
-#### 8. Emit the task files
+#### 9. Emit the task files
 
 Write each task to:
 
@@ -246,11 +281,15 @@ including required frontmatter fields:
 - `created` (YYYY-MM-DD)
 - `skills` (array of 1–2 kebab-case skills)
 
-Optional frontmatter for high-complexity or decomposed tasks:
+Required additional frontmatter:
 
-- `complexity_score` (number, 1–10, include only if >4 or for decomposed
-  tasks)
-- `complexity_notes` (string)
+- `complexity_score` (integer 1–10, required on every emitted task)
+
+Optional frontmatter:
+
+- `complexity_notes` (string) — include when the score needs justification,
+  such as "Decomposed from a cross-cutting parent task" or "Ambiguous API
+  contract".
 
 The body sections (Objective, Skills Required, Acceptance Criteria, Technical
 Requirements, Input Dependencies, Output Artifacts, Implementation Notes)
@@ -258,7 +297,7 @@ must be filled with task-specific content. Place detailed implementation
 guidance inside a `<details>` block under "Implementation Notes" — write it
 so a non-thinking LLM could execute the task from that section alone.
 
-#### 9. Validation checklist
+#### 10. Validation checklist
 
 Before declaring task generation complete, verify:
 
@@ -276,16 +315,23 @@ Before declaring task generation complete, verify:
 - Minimization applied (20–30% reduction target).
 - Test tasks focus on business logic, not framework functionality.
 - No gold-plating: only plan requirements are addressed.
+- After writing the task files, run
+  `scripts/validate-plan-blueprint.cjs <plan-id> complexityScoresValid`. Stop
+  unless it prints `yes`; if it prints `no`, run
+  `scripts/validate-plan-blueprint.cjs <plan-id> invalidComplexityTasks` to see
+  which files are missing, non-integer, or out-of-range, fix them, and re-run.
+  Every generated task must carry an integer `complexity_score` from 1 to 10.
+- Add `complexity_notes` only when a score needs explanation (typically atomic
+  tasks scoring greater than 4).
 
-#### 10. Run the POST_TASK_GENERATION_ALL hook
+#### 11. Run the POST_TASK_GENERATION_ALL hook
 
 Read `<root>/config/hooks/POST_TASK_GENERATION_ALL.md` and follow its instructions. This typically requires:
 
-- Sanity-checking complexity.
 - Appending an Execution Blueprint section to the plan document, including a Mermaid dependency diagram and explicit phase groupings.
 - Use `<root>/config/templates/BLUEPRINT_TEMPLATE.md` for structure.
 
-#### 11. Emit the Phase 2 structured summary
+#### 12. Emit the Phase 2 structured summary
 
 Conclude Phase 2 with exactly this block:
 
@@ -330,7 +376,7 @@ If `taskCount` is 0 or `blueprintExists` is `no`:
 
 #### 3. Optionally create a feature branch
 
-Run `scripts/create-feature-branch.cjs <plan-id>`. The script creates a branch named after the plan and prints the branch name. Continue execution regardless of whether a branch is created.
+Run `scripts/create-feature-branch.cjs <plan-id>` once before phase execution. Branch creation is best-effort: when the script reports that it skipped creation (for example, not on `main`/`master`), continue on the current branch and do not retry or create a branch manually. When the script exits with an error (for example, uncommitted changes on `main`/`master`), halt and report the error. Do not treat a skipped branch as a failure or spend effort working around a skip.
 
 #### 4. Load execution blueprint
 
@@ -346,10 +392,12 @@ Read these files in order:
 Use an internal task or todo tracker to monitor progress. For each phase defined in the Execution Blueprint:
 
 ##### 5a. Phase pre-execution
+Run `scripts/check-phase-readiness.cjs <plan-id> <phase-number>`. If the script exits non-zero, halt the phase and report the blocking issues before continuing.
+
 Read `<root>/config/hooks/PRE_PHASE.md` and execute its instructions before starting the phase.
 
 ##### 5b. Task dispatch
-Identify all tasks scheduled for this phase whose dependencies are fully satisfied. Read `<root>/config/hooks/PRE_TASK_EXECUTION.md` and execute its instructions before starting any implementation work.
+Identify all tasks scheduled for this phase whose dependencies are fully satisfied. Read `<root>/config/hooks/PRE_TASK_ASSIGNMENT.md` and follow its instructions for agent selection before dispatching tasks.
 
 Deploy all selected agents simultaneously using your internal Task tool. Each agent MUST: