@agent-plan/core 0.2.19-next.21 → 0.2.19-next.22

package/dist/task-selection.d.ts

@@ -14,6 +14,17 @@ export interface TaskRecommendation {
     deviation?: WorkDeviation;
     reason: string;
 }
+/** Whether a user-explicit task start is valid, independent of priority advice. */
+export interface ExplicitTaskStartEligibility {
+    eligible: boolean;
+    reason: string;
+}
+/**
+ * Validate an explicitly requested task start. Priority and existing active
+ * work remain advisory for explicit user choices; availability and dependency
+ * invariants remain mandatory.
+ */
+export declare function checkExplicitTaskStart(features: Feature[], phases: Phase[], taskId: string, deviations?: WorkDeviation[]): ExplicitTaskStartEligibility;
 /**
  * Pure, harness-agnostic work selector. It never mutates plan state: adapters
  * may use its recommendation as a default while still allowing an explicitly

package/dist/task-selection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-selection.d.ts","sourceRoot":"","sources":["../src/task-selection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEvE,MAAM,MAAM,sBAAsB,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;AAE5F,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,aAAa,EAAE,CAAC;IACnC,8EAA8E;IAC9E,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;CAChB;AAQD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,OAAO,EAAE,EACnB,MAAM,EAAE,KAAK,EAAE,EACf,UAAU,GAAE,aAAa,EAAO,GAC/B,kBAAkB,CAuDpB"}
+{"version":3,"file":"task-selection.d.ts","sourceRoot":"","sources":["../src/task-selection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEvE,MAAM,MAAM,sBAAsB,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;AAE5F,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,aAAa,EAAE,CAAC;IACnC,8EAA8E;IAC9E,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,mFAAmF;AACnF,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AASD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,OAAO,EAAE,EACnB,MAAM,EAAE,KAAK,EAAE,EACf,MAAM,EAAE,MAAM,EACd,UAAU,GAAE,aAAa,EAAO,GAC/B,4BAA4B,CAwB9B;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,OAAO,EAAE,EACnB,MAAM,EAAE,KAAK,EAAE,EACf,UAAU,GAAE,aAAa,EAAO,GAC/B,kBAAkB,CAuDpB"}

package/dist/task-selection.js

@@ -1,7 +1,36 @@
 const unavailable = new Set(["blocked", "waiting", "deferred", "canceled", "rejected"]);
+const hardUnavailable = new Set(["blocked", "deferred", "canceled", "rejected"]);
 const terminal = new Set(["done", "canceled", "rejected"]);
 const priority = (entity) => entity.priority && entity.priority > 0 ? entity.priority : Number.MAX_SAFE_INTEGER;
 const compare = (a, b) => priority(a) - priority(b) || a.number - b.number;
+/**
+ * Validate an explicitly requested task start. Priority and existing active
+ * work remain advisory for explicit user choices; availability and dependency
+ * invariants remain mandatory.
+ */
+export function checkExplicitTaskStart(features, phases, taskId, deviations = []) {
+    const featureById = new Map(features.map((feature) => [feature.id, feature]));
+    const candidates = phases.flatMap((phase) => phase.tasks.map((task) => ({ feature: phase.featureId ? featureById.get(phase.featureId) : undefined, phase, task })));
+    const candidate = candidates.find(({ task }) => task.id === taskId);
+    if (!candidate)
+        return { eligible: false, reason: "Requested task no longer exists." };
+    const isTemporaryOverride = deviations.some((deviation) => (deviation.state === "approved" || deviation.state === "active")
+        && deviation.temporaryTaskId === taskId);
+    const startableStatus = candidate.task.status === "planned"
+        || (candidate.task.status === "waiting" && isTemporaryOverride);
+    if (!startableStatus)
+        return { eligible: false, reason: `Task is not startable from ${candidate.task.status}.` };
+    const parentHasHardBlock = hardUnavailable.has(candidate.phase.status)
+        || (candidate.feature && hardUnavailable.has(candidate.feature.status));
+    if (parentHasHardBlock || (!isTemporaryOverride && (unavailable.has(candidate.phase.status) || (candidate.feature && unavailable.has(candidate.feature.status))))) {
+        return { eligible: false, reason: "Task belongs to an unavailable phase or feature." };
+    }
+    const taskById = new Map(candidates.map((entry) => [entry.task.id, entry]));
+    if (!isTemporaryOverride && !candidate.task.dependsOn.every((id) => taskById.get(id)?.task.status === "done")) {
+        return { eligible: false, reason: "Task dependencies are not complete." };
+    }
+    return { eligible: true, reason: "Explicit task request is startable." };
+}
 /**
  * Pure, harness-agnostic work selector. It never mutates plan state: adapters
  * may use its recommendation as a default while still allowing an explicitly

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-plan/core",
-  "version": "0.2.19-next.21",
+  "version": "0.2.19-next.22",
   "private": false,
   "description": "Harness-agnostic core for Agent Plan: schemas, persistence, ordering, status rollups, and markdown rendering.",
   "license": "MIT",