opencode-wait-a-minute 0.0.0-stage → 1.1.0-rc.8

package/src/skills/skill-registry.js

@@ -0,0 +1,19 @@
+export function createSkillRegistry() {
+  const skills = {};
+  return {
+    register(name, skill) {
+      skills[name] = skill;
+    },
+    lookup(name) {
+      return skills[name];
+    },
+    getDeps(name) {
+      const skill = skills[name];
+      return skill && skill.deps ? skill.deps : [];
+    },
+    checkVersion(name, version) {
+      const skill = skills[name];
+      return skill ? skill.version === version : false;
+    },
+  };
+}

package/src/skills/skill-routing.js

@@ -0,0 +1,340 @@
+/**
+ * Skill Routing Constraints — layer responsibility and dependency management.
+ *
+ * Ensures skills only modify their declared layer and respects dependencies.
+ * Prevents cross-layer contamination and skill conflicts.
+ */
+
+/**
+ * @typedef {"backend" | "frontend" | "shared" | "infrastructure"} Layer
+ */
+
+/**
+ * @typedef {Object} SkillConstraint
+ * @property {string} id - Skill ID
+ * @property {Layer[]} allowedLayers - Layers this skill can modify
+ * @property {string[]} dependsOn - Skills that must be selected first
+ * @property {string[]} conflicts - Skills that cannot coexist
+ * @property {string} reason - Why these constraints exist
+ */
+
+/**
+ * @typedef {Object} RoutingDecision
+ * @property {string} skillId
+ * @property {boolean} allowed
+ * @property {Layer} targetLayer
+ * @property {string} reason
+ * @property {"constraint" | "dependency" | "conflict" | "budget"} reasonType
+ */
+
+/** Default layer constraints for known skill types */
+const DEFAULT_CONSTRAINTS = {
+  "angular-developer": {
+    allowedLayers: ["frontend"],
+    dependsOn: [],
+    conflicts: ["nestjs-best-practices"],
+    reason: "Angular skills should only modify frontend code",
+  },
+  "nestjs-best-practices": {
+    allowedLayers: ["backend"],
+    dependsOn: [],
+    conflicts: ["angular-developer"],
+    reason: "NestJS skills should only modify backend code",
+  },
+  "frontend-boundary-protection": {
+    allowedLayers: ["frontend"],
+    dependsOn: [],
+    conflicts: [],
+    reason: "Frontend protection should only modify frontend code",
+  },
+  "backend-integrity": {
+    allowedLayers: ["backend"],
+    dependsOn: [],
+    conflicts: [],
+    reason: "Backend integrity should only modify backend code",
+  },
+  "efficient-coding": {
+    allowedLayers: ["backend", "frontend", "shared"],
+    dependsOn: [],
+    conflicts: [],
+    reason: "General coding skill, can work on any layer",
+  },
+  "architectural-governance": {
+    allowedLayers: ["backend", "frontend", "shared", "infrastructure"],
+    dependsOn: [],
+    conflicts: [],
+    reason: "Governance skill, can review any layer",
+  },
+  // mattpocock/skills — MIT licensed, vendored into skills/
+  "writing-for-agents": {
+    allowedLayers: ["shared"],
+    dependsOn: [],
+    conflicts: [],
+    reason: "Meta-skill for writing agent documents and skills",
+  },
+  "codebase-design": {
+    allowedLayers: ["shared"],
+    dependsOn: [],
+    conflicts: [],
+    reason: "Deep module design vocabulary",
+  },
+  "diagnosing-bugs": {
+    allowedLayers: ["shared"],
+    dependsOn: [],
+    conflicts: [],
+    reason: "Bug diagnosis loop for hard bugs",
+  },
+  "tdd": {
+    allowedLayers: ["shared"],
+    dependsOn: [],
+    conflicts: [],
+    reason: "Test-driven development (TDD) reference",
+  },
+  "handoff": {
+    allowedLayers: ["shared"],
+    dependsOn: [],
+    conflicts: [],
+    reason: "Compact conversation for agent handoff",
+  },
+  "wizard": {
+    allowedLayers: ["shared"],
+    dependsOn: [],
+    conflicts: [],
+    reason: "Interactive bash wizard for manual tasks",
+  },
+  "prototype": {
+    allowedLayers: ["shared"],
+    dependsOn: [],
+    conflicts: [],
+    reason: "Throwaway prototype for design questions",
+  },
+  "improve-codebase-architecture": {
+    allowedLayers: ["shared"],
+    dependsOn: [],
+    conflicts: [],
+    reason: "Scan for deepening opportunities in architecture",
+  },
+};
+
+/**
+ * Detect which layer a file belongs to based on path patterns.
+ *
+ * @param {string} filePath
+ * @returns {Layer | null}
+ */
+export function detectLayer(filePath) {
+  const lower = filePath.toLowerCase();
+
+  // Frontend patterns
+  if (
+    /\.(component|module|service|directive|pipe|html|css|scss|less)\.(ts|js)$/.test(lower) ||
+    /src[\\/]app[\\/]/.test(lower) ||
+    /src[\\/]components?[\\/]/.test(lower) ||
+    /src[\\/]pages?[\\/]/.test(lower) ||
+    /\.(jsx|tsx|vue|svelte)$/.test(lower)
+  ) {
+    return "frontend";
+  }
+
+  // Backend patterns
+  if (
+    /\.(controller|service|module|guard|interceptor|middleware|resolver)\.(ts|js)$/.test(lower) ||
+    /src[\\/](api|server|backend|nest)[\\/]/.test(lower) ||
+    /\.entity\.(ts|js)$/.test(lower) ||
+    /\.repository\.(ts|js)$/.test(lower) ||
+    /\.migration\.(ts|js)$/.test(lower)
+  ) {
+    return "backend";
+  }
+
+  // Infrastructure patterns
+  if (
+    /(dockerfile|docker-compose|\.yml|\.yaml)$/.test(lower) ||
+    /\b(infra|infrastructure|deploy|k8s|terraform)[\\/]/.test(lower) ||
+    /\.(tf|tfvars)$/.test(lower)
+  ) {
+    return "infrastructure";
+  }
+
+  // Shared patterns
+  if (
+    /\b(shared|common|utils?|helpers?|types?|constants?)[\\/]/.test(lower) ||
+    /\.(d\.ts|types\.ts)$/.test(lower)
+  ) {
+    return "shared";
+  }
+
+  return null;
+}
+
+/**
+ * Get constraints for a skill.
+ *
+ * @param {string} skillId
+ * @param {Object} skillRegistry - Skill registry (optional, for dynamic constraints)
+ * @returns {SkillConstraint}
+ */
+export function getSkillConstraints(skillId, skillRegistry = {}) {
+  // Check default constraints first
+  if (DEFAULT_CONSTRAINTS[skillId]) {
+    return { id: skillId, ...DEFAULT_CONSTRAINTS[skillId] };
+  }
+
+  // Check skill registry for declared constraints
+  const skill = skillRegistry[skillId];
+  if (skill?.constraints) {
+    return {
+      id: skillId,
+      allowedLayers: skill.constraints.allowedLayers || ["backend", "frontend", "shared"],
+      dependsOn: skill.constraints.dependsOn || [],
+      conflicts: skill.constraints.conflicts || [],
+      reason: skill.constraints.reason || "No constraints declared",
+    };
+  }
+
+  // Default: allow all layers
+  return {
+    id: skillId,
+    allowedLayers: ["backend", "frontend", "shared", "infrastructure"],
+    dependsOn: [],
+    conflicts: [],
+    reason: "No constraints declared, allowing all layers",
+  };
+}
+
+/**
+ * Check if a skill can modify a specific layer.
+ *
+ * @param {string} skillId
+ * @param {Layer} targetLayer
+ * @param {Object} skillRegistry
+ * @returns {RoutingDecision}
+ */
+export function canModifyLayer(skillId, targetLayer, skillRegistry = {}) {
+  const constraints = getSkillConstraints(skillId, skillRegistry);
+
+  if (constraints.allowedLayers.includes(targetLayer)) {
+    return {
+      skillId,
+      allowed: true,
+      targetLayer,
+      reason: `Skill ${skillId} is allowed to modify ${targetLayer}`,
+      reasonType: "constraint",
+    };
+  }
+
+  return {
+    skillId,
+    allowed: false,
+    targetLayer,
+    reason: `Skill ${skillId} is NOT allowed to modify ${targetLayer}. Allowed: ${constraints.allowedLayers.join(", ")}`,
+    reasonType: "constraint",
+  };
+}
+
+/**
+ * Check skill dependencies and conflicts.
+ *
+ * @param {string} skillId
+ * @param {string[]} selectedSkills - Currently selected skill IDs
+ * @param {Object} skillRegistry
+ * @returns {RoutingDecision[]}
+ */
+export function checkDependencies(skillId, selectedSkills, skillRegistry = {}) {
+  const decisions = [];
+  const constraints = getSkillConstraints(skillId, skillRegistry);
+
+  // Check dependencies
+  for (const dep of constraints.dependsOn) {
+    if (!selectedSkills.includes(dep)) {
+      decisions.push({
+        skillId,
+        allowed: false,
+        targetLayer: "shared",
+        reason: `Skill ${skillId} requires ${dep} to be selected first`,
+        reasonType: "dependency",
+      });
+    }
+  }
+
+  // Check conflicts
+  for (const conflict of constraints.conflicts) {
+    if (selectedSkills.includes(conflict)) {
+      decisions.push({
+        skillId,
+        allowed: false,
+        targetLayer: "shared",
+        reason: `Skill ${skillId} conflicts with ${conflict}`,
+        reasonType: "conflict",
+      });
+    }
+  }
+
+  return decisions;
+}
+
+/**
+ * Route skills with constraints validation.
+ *
+ * @param {string[]} candidateSkills - Skills to route
+ * @param {string[]} targetFiles - Files to be modified
+ * @param {Object} skillRegistry
+ * @returns {Object} Routing result
+ */
+export function routeWithConstraints(candidateSkills, targetFiles, skillRegistry = {}) {
+  const allowed = [];
+  const rejected = [];
+  const selectedLayers = new Set();
+
+  // Detect target layers
+  const targetLayers = new Set();
+  for (const file of targetFiles) {
+    const layer = detectLayer(file);
+    if (layer) targetLayers.add(layer);
+  }
+
+  // Check each candidate skill
+  for (const skillId of candidateSkills) {
+    let canRoute = true;
+    let rejectReason = "";
+
+    // Check layer constraints
+    for (const layer of targetLayers) {
+      const decision = canModifyLayer(skillId, layer, skillRegistry);
+      if (!decision.allowed) {
+        canRoute = false;
+        rejectReason = decision.reason;
+        break;
+      }
+    }
+
+    // Check dependencies and conflicts
+    const depDecisions = checkDependencies(skillId, allowed, skillRegistry);
+    const failedDeps = depDecisions.filter((d) => !d.allowed);
+    if (failedDeps.length > 0) {
+      canRoute = false;
+      rejectReason = failedDeps.map((d) => d.reason).join("; ");
+    }
+
+    if (canRoute) {
+      allowed.push(skillId);
+      for (const layer of targetLayers) {
+        selectedLayers.add(layer);
+      }
+    } else {
+      rejected.push({
+        skillId,
+        reason: rejectReason,
+      });
+    }
+  }
+
+  return {
+    allowed,
+    rejected,
+    targetLayers: Array.from(targetLayers),
+    selectedLayers: Array.from(selectedLayers),
+  };
+}
+
+export { DEFAULT_CONSTRAINTS };

package/src/state/lifecycle-manager.js

@@ -0,0 +1,113 @@
+/**
+ * Lifecycle Manager — start/stop coordination with event listeners.
+ *
+ * Provides a tiny state machine coordinating ordered startup and shutdown
+ * of subsystems, emitting events for observability.
+ *
+ * States: "stopped" | "starting" | "running" | "stopping".
+ * Listeners can be attached per event.
+ *
+ * Designed for production hardening (M5-49): lets plugins register hooks
+ * that fire when the system transitions states.
+ */
+
+/**
+ * @typedef {"stopped"|"starting"|"running"|"stopping"} LifecycleState
+ */
+
+/**
+ * @typedef {Object} LifecycleListener
+ * @property {(event: {type: string, payload?: unknown}) => void} handler
+ */
+
+/**
+ * @typedef {Object} LifecycleManager
+ * @property {() => LifecycleState} getState
+ * @property {() => Promise<void>} start
+ * @property {() => Promise<void>} stop
+ * @property {(event: string, handler: Function) => () => void} on
+ * @property {(event: string, handler: Function) => void} off
+ * @property {() => boolean} isRunning
+ */
+
+/**
+ * Create a lifecycle manager.
+ * @param {Object} [opts]
+ * @param {Array<{name: string, onStart?: Function, onStop?: Function}>} [opts.components]
+ * @returns {LifecycleManager}
+ */
+export function createLifecycleManager(opts = {}) {
+  const components = opts.components ?? [];
+  /** @type {LifecycleState} */
+  let state = "stopped";
+  /** @type {Map<string, Set<Function>>} */
+  const listeners = new Map();
+
+  function emit(type, payload) {
+    const set = listeners.get(type);
+    if (!set) return;
+    for (const fn of set) {
+      try {
+        fn({ type, payload });
+      } catch (_err) {
+        // listeners must not break lifecycle
+      }
+    }
+  }
+
+  function on(event, handler) {
+    if (typeof handler !== "function") throw new TypeError("handler must be function");
+    let set = listeners.get(event);
+    if (!set) {
+      set = new Set();
+      listeners.set(event, set);
+    }
+    set.add(handler);
+    return () => off(event, handler);
+  }
+
+  function off(event, handler) {
+    const set = listeners.get(event);
+    if (!set) return;
+    set.delete(handler);
+    if (set.size === 0) listeners.delete(event);
+  }
+
+  async function start() {
+    if (state === "running" || state === "starting") return;
+    state = "starting";
+    emit("state", { from: "stopped", to: "starting" });
+    for (const comp of components) {
+      emit("start:component", { name: comp.name });
+      if (typeof comp.onStart === "function") {
+        await comp.onStart();
+      }
+    }
+    state = "running";
+    emit("state", { from: "starting", to: "running" });
+  }
+
+  async function stop() {
+    if (state === "stopped" || state === "stopping") return;
+    state = "stopping";
+    emit("state", { from: "running", to: "stopping" });
+    // stop in reverse order
+    for (const comp of [...components].reverse()) {
+      emit("stop:component", { name: comp.name });
+      if (typeof comp.onStop === "function") {
+        await comp.onStop();
+      }
+    }
+    state = "stopped";
+    emit("state", { from: "stopping", to: "stopped" });
+  }
+
+  return {
+    getState: () => state,
+    isRunning: () => state === "running",
+    start,
+    stop,
+    on,
+    off,
+  };
+}

package/src/state/operational-state.js

@@ -0,0 +1,198 @@
+/**
+ * Context State Machine — derives operational state from isolated states.
+ *
+ * Connects Task lifecycle, Run lifecycle, Evidence lifecycle,
+ * Context routing, and Verification into a single derived state.
+ *
+ * The operational state is DERIVED, not persisted.
+ * It answers: "What can the agent do right now?"
+ */
+
+/**
+ * @typedef {"PROPOSED" | "ASKING" | "IMPLEMENTING" | "VERIFYING" | "COMPLETE" | "BLOCKED" | "CONFLICTED" | "DEGRADED"} OperationalState
+ */
+
+/**
+ * @typedef {Object} StateInputs
+ * @property {string} executionState - Current task execution state
+ * @property {string} routingStatus - Context router status
+ * @property {string} evidenceStatus - Evidence validity status
+ * @property {string} verificationStatus - Verification lifecycle status
+ * @property {boolean} hasActiveRun - Whether there's an active run
+ * @property {boolean} hasUnresolvedAssumptions - Whether there are blocking assumptions
+ */
+
+/** All valid operational states */
+export const OPERATIONAL_STATES = new Set([
+  "PROPOSED",
+  "ASKING",
+  "IMPLEMENTING",
+  "VERIFYING",
+  "COMPLETE",
+  "BLOCKED",
+  "CONFLICTED",
+  "DEGRADED",
+]);
+
+/**
+ * Derive operational state from multiple state inputs.
+ *
+ * @param {StateInputs} inputs
+ * @returns {{ state: OperationalState, reason: string, blockers: string[] }}
+ */
+export function deriveOperationalState(inputs) {
+  const {
+    executionState = "INITIALIZING",
+    routingStatus = "COMPLETE",
+    evidenceStatus = "valid",
+    verificationStatus = "UNVERIFIED",
+    hasActiveRun = false,
+    hasUnresolvedAssumptions = false,
+  } = inputs;
+
+  const blockers = [];
+
+  // Terminal: COMPLETED → DONE
+  if (executionState === "COMPLETED") {
+    return {
+      state: "COMPLETE",
+      reason: "task completed",
+      blockers: [],
+    };
+  }
+
+  // CONFLICTED: routing has conflicts (check before BLOCKED)
+  if (routingStatus === "CONFLICTED") {
+    return {
+      state: "CONFLICTED",
+      reason: "context conflicts detected",
+      blockers: ["context conflicts unresolved"],
+    };
+  }
+
+  // ASKING: waiting for authorization
+  if (executionState === "WAITING_AUTHORIZATION") {
+    return {
+      state: "ASKING",
+      reason: "waiting for authorization",
+      blockers: [],
+    };
+  }
+
+  // BLOCKED: multiple conditions
+  if (executionState === "FAILED") {
+    blockers.push("execution failed");
+  }
+  if (evidenceStatus === "invalidated") {
+    blockers.push("evidence invalidated");
+  }
+  if (hasUnresolvedAssumptions) {
+    blockers.push("unresolved decision-critical assumptions");
+  }
+  if (executionState === "BLOCKED") {
+    blockers.push("execution blocked");
+  }
+
+  if (blockers.length > 0) {
+    return {
+      state: "BLOCKED",
+      reason: blockers.join("; "),
+      blockers,
+    };
+  }
+
+  // VERIFYING: in verification phase
+  if (executionState === "VERIFYING" || verificationStatus === "VERIFYING") {
+    return {
+      state: "VERIFYING",
+      reason: "verification in progress",
+      blockers: [],
+    };
+  }
+
+  // DEGRADED: working but with issues
+  if (routingStatus === "PARTIAL") {
+    return {
+      state: "DEGRADED",
+      reason: "partial context available",
+      blockers: [],
+    };
+  }
+  if (evidenceStatus === "superseded") {
+    return {
+      state: "DEGRADED",
+      reason: "evidence superseded",
+      blockers: [],
+    };
+  }
+
+  // IMPLEMENTING: actively executing
+  if (executionState === "EXECUTING" || hasActiveRun) {
+    return {
+      state: "IMPLEMENTING",
+      reason: "execution in progress",
+      blockers: [],
+    };
+  }
+
+  // PROPOSED: initial state
+  return {
+    state: "PROPOSED",
+    reason: "task proposed, not yet started",
+    blockers: [],
+  };
+}
+
+/**
+ * Check if an action is allowed in the current operational state.
+ *
+ * @param {OperationalState} state
+ * @param {string} action
+ * @returns {{ allowed: boolean, reason: string }}
+ */
+export function canPerformAction(state, action) {
+  const allowed = {
+    PROPOSED: ["start", "plan", "ask"],
+    ASKING: ["respond", "cancel"],
+    IMPLEMENTING: ["execute", "observe", "evidence", "pause"],
+    VERIFYING: ["verify", "evidence", "fail"],
+    COMPLETE: [],
+    BLOCKED: ["resolve", "cancel"],
+    CONFLICTED: ["resolve", "cancel"],
+    DEGRADED: ["execute", "observe", "evidence", "pause"],
+  };
+
+  const actions = allowed[state] || [];
+  if (actions.includes(action)) {
+    return { allowed: true, reason: `${action} allowed in ${state}` };
+  }
+
+  return {
+    allowed: false,
+    reason: `${action} not allowed in ${state}. Allowed: ${actions.join(", ") || "none"}`,
+  };
+}
+
+/**
+ * Generate operational state report.
+ *
+ * @param {StateInputs} inputs
+ * @returns {Object} Report with state, reason, blockers, allowed actions
+ */
+export function generateOperationalReport(inputs) {
+  const { state, reason, blockers } = deriveOperationalState(inputs);
+
+  const allActions = ["start", "plan", "ask", "respond", "cancel", "execute", "observe", "evidence", "pause", "verify", "fail", "resolve"];
+  const allowedActions = allActions.filter((a) => canPerformAction(state, a).allowed);
+
+  return {
+    state,
+    reason,
+    blockers,
+    allowedActions,
+    inputs,
+    derivedAt: Date.now(),
+  };
+}
+
+export default deriveOperationalState;

package/src/state/projections.js

@@ -0,0 +1,47 @@
+/**
+ * Projection Engine — derive state from an event stream via reducer.
+ *
+ * Given a reducer function and initial state, applies events one-by-one
+ * to produce a current derived state. Production hardening (M5-52).
+ */
+
+/**
+ * @typedef {Object} Projection
+ * @property {*} getState
+ * @property {(event: {type: string, payload?: unknown}) => *} apply
+ * @property {() => number} version
+ * @property {() => void} reset
+ */
+
+/**
+ * Create a projection from a reducer.
+ * @param {(state: *, event: {type: string, payload?: unknown}) => *} reducer
+ * @param {*} initialState
+ * @returns {Projection}
+ */
+export function createProjection(reducer, initialState) {
+  if (typeof reducer !== "function") throw new TypeError("reducer must be function");
+  let state = initialState;
+  let v = 0;
+
+  function apply(event) {
+    state = reducer(state, event);
+    v++;
+    return state;
+  }
+
+  function getState() {
+    return state;
+  }
+
+  function version() {
+    return v;
+  }
+
+  function reset() {
+    state = initialState;
+    v = 0;
+  }
+
+  return { getState, apply, version, reset };
+}