@trevonistrevon/pi-loop 0.5.9 → 0.6.1

package/dist/goal-verifier.js

@@ -1,198 +0,0 @@
-function uniqueById(items) {
-    const seen = new Set();
-    const result = [];
-    for (const item of items) {
-        if (seen.has(item.id))
-            continue;
-        seen.add(item.id);
-        result.push(item);
-    }
-    return result;
-}
-function selectTasks(goal, taskState) {
-    const selected = [];
-    for (const id of goal.scope.taskIds ?? []) {
-        const task = taskState.tasksById[id];
-        if (task)
-            selected.push(task);
-    }
-    for (const prefix of goal.scope.subjectPrefixes ?? []) {
-        for (const task of Object.values(taskState.tasksById)) {
-            if (task.subject.startsWith(prefix))
-                selected.push(task);
-        }
-    }
-    return uniqueById(selected);
-}
-function selectLoops(goal, loopState) {
-    const selected = [];
-    for (const id of goal.scope.loopIds ?? []) {
-        const loop = loopState.loopsById[id];
-        if (loop)
-            selected.push(loop);
-    }
-    return uniqueById(selected);
-}
-function selectMonitors(goal, monitorState) {
-    const selected = [];
-    for (const id of goal.scope.monitorIds ?? []) {
-        const monitor = monitorState.monitorsById[id];
-        if (monitor)
-            selected.push(monitor);
-    }
-    return uniqueById(selected);
-}
-export function projectGoalProgress(goal, taskState, loopState, monitorState) {
-    const tasks = selectTasks(goal, taskState);
-    const loops = selectLoops(goal, loopState);
-    const monitors = selectMonitors(goal, monitorState);
-    const timestamps = [];
-    for (const task of tasks)
-        timestamps.push(task.updatedAt);
-    for (const loop of loops)
-        timestamps.push(loop.updatedAt);
-    for (const monitor of monitors)
-        timestamps.push(monitor.completedAt ?? monitor.startedAt);
-    return {
-        totalTasks: tasks.length,
-        pendingTasks: tasks.filter(task => task.status === "pending").length,
-        inProgressTasks: tasks.filter(task => task.status === "in_progress").length,
-        completedTasks: tasks.filter(task => task.status === "completed").length,
-        activeLoops: loops.filter(loop => loop.status === "active").length,
-        pausedLoops: loops.filter(loop => loop.status === "paused").length,
-        runningMonitors: monitors.filter(monitor => monitor.status === "running").length,
-        completedMonitors: monitors.filter(monitor => monitor.status === "completed").length,
-        erroredMonitors: monitors.filter(monitor => monitor.status === "error").length,
-        stoppedMonitors: monitors.filter(monitor => monitor.status === "stopped").length,
-        lastProgressAt: timestamps.length > 0 ? Math.max(...timestamps) : undefined,
-    };
-}
-function dispatchEffect(event) {
-    return {
-        type: "DISPATCH_EVENT",
-        entityType: "goal",
-        entityId: event.entityId,
-        payload: { event },
-    };
-}
-function buildEffects(goal, at, progress, resultType, reason) {
-    return [
-        dispatchEffect({
-            type: "GOAL_VERIFICATION_STARTED",
-            at,
-            source: "coordinator",
-            entityType: "goal",
-            entityId: goal.id,
-            payload: { id: goal.id },
-        }),
-        dispatchEffect({
-            type: "GOAL_PROGRESS_RECORDED",
-            at,
-            source: "coordinator",
-            entityType: "goal",
-            entityId: goal.id,
-            payload: { id: goal.id, progress },
-        }),
-        dispatchEffect({
-            type: resultType,
-            at,
-            source: "coordinator",
-            entityType: "goal",
-            entityId: goal.id,
-            payload: { id: goal.id, reason, progress },
-        }),
-    ];
-}
-export function verifyGoal(input) {
-    const { goal, taskState, loopState, monitorState, at } = input;
-    const progress = projectGoalProgress(goal, taskState, loopState, monitorState);
-    if (goal.criteria.failure?.maxVerificationFailures !== undefined
-        && goal.verification.failures >= goal.criteria.failure.maxVerificationFailures) {
-        return {
-            progress,
-            verdict: "failed",
-            reason: "maximum verification failures reached",
-            effects: buildEffects(goal, at, progress, "GOAL_FAILED", "maximum verification failures reached"),
-        };
-    }
-    for (const monitorId of goal.criteria.failure?.anyMonitorIdsErrored ?? []) {
-        if (monitorState.monitorsById[monitorId]?.status === "error") {
-            return {
-                progress,
-                verdict: "failed",
-                reason: `monitor #${monitorId} errored`,
-                effects: buildEffects(goal, at, progress, "GOAL_FAILED", `monitor #${monitorId} errored`),
-            };
-        }
-    }
-    for (const taskId of goal.criteria.failure?.failIfTaskIdsDeleted ?? []) {
-        if (!taskState.tasksById[taskId]) {
-            return {
-                progress,
-                verdict: "failed",
-                reason: `task #${taskId} missing`,
-                effects: buildEffects(goal, at, progress, "GOAL_FAILED", `task #${taskId} missing`),
-            };
-        }
-    }
-    const requiredTasksDone = (goal.criteria.success.requiredTaskIds ?? [])
-        .every(taskId => taskState.tasksById[taskId]?.status === "completed");
-    const requiredMonitorsDone = (goal.criteria.success.requiredMonitorIdsCompleted ?? [])
-        .every(monitorId => monitorState.monitorsById[monitorId]?.status === "completed");
-    const requiredLoopsPresent = (goal.criteria.success.requiredLoopIdsPresent ?? [])
-        .every(loopId => Boolean(loopState.loopsById[loopId]));
-    const minCompletedTasksMet = progress.completedTasks >= (goal.criteria.success.minCompletedTasks ?? 0);
-    const noPendingWork = !goal.criteria.success.requireNoPendingTasksInScope
-        || (progress.pendingTasks === 0 && progress.inProgressTasks === 0);
-    const latestVerificationPass = !goal.criteria.success.requireLatestVerificationPass
-        || goal.verificationStatus === "verified";
-    const success = requiredTasksDone
-        && requiredMonitorsDone
-        && requiredLoopsPresent
-        && minCompletedTasksMet
-        && noPendingWork
-        && latestVerificationPass;
-    if (success) {
-        return {
-            progress,
-            verdict: "passed",
-            reason: "success criteria satisfied",
-            effects: buildEffects(goal, at, progress, "GOAL_VERIFICATION_PASSED", "success criteria satisfied"),
-        };
-    }
-    if (goal.criteria.blocked?.blockedIfRequiredLoopMissing && !requiredLoopsPresent) {
-        return {
-            progress,
-            verdict: "blocked",
-            reason: "required loop missing",
-            effects: buildEffects(goal, at, progress, "GOAL_BLOCKED", "required loop missing"),
-        };
-    }
-    if (goal.criteria.blocked?.blockedIfNoScopedProgressSinceMs !== undefined
-        && progress.lastProgressAt !== undefined
-        && at - progress.lastProgressAt >= goal.criteria.blocked.blockedIfNoScopedProgressSinceMs) {
-        return {
-            progress,
-            verdict: "blocked",
-            reason: "no scoped progress within configured interval",
-            effects: buildEffects(goal, at, progress, "GOAL_BLOCKED", "no scoped progress within configured interval"),
-        };
-    }
-    if (goal.criteria.blocked?.blockedIfAllTasksCompletedButVerificationFails
-        && progress.totalTasks > 0
-        && progress.pendingTasks === 0
-        && progress.inProgressTasks === 0) {
-        return {
-            progress,
-            verdict: "blocked",
-            reason: "all scoped tasks completed but verification has not passed",
-            effects: buildEffects(goal, at, progress, "GOAL_BLOCKED", "all scoped tasks completed but verification has not passed"),
-        };
-    }
-    return {
-        progress,
-        verdict: "failed",
-        reason: "success criteria not yet satisfied",
-        effects: buildEffects(goal, at, progress, "GOAL_VERIFICATION_FAILED", "success criteria not yet satisfied"),
-    };
-}

package/docker-compose.yml

@@ -1,12 +0,0 @@
-services:
-  ci-node20:
-    build:
-      context: .
-      target: node20
-    command: sh -c "npm run typecheck && npm run lint && npm run test:coverage && npm run build"
-
-  ci-node22:
-    build:
-      context: .
-      target: node22
-    command: sh -c "npm run typecheck && npm run lint && npm run test:coverage && npm run build"

package/docs/architecture/goal-state-schema.md

@@ -1,505 +0,0 @@
-# pi-loop Goal State Schema
-
-## Purpose
-
-This document defines the reducer-owned state shape for Goals.
-
-It builds on:
-
-- `docs/architecture/state-machine-transition-map.md`
-- `docs/architecture/state-machine-test-matrix.md`
-- `docs/architecture/state-machine-reducer-event-model.md`
-
-The objective is to let Goals compose:
-
-- tasks
-- loops
-- monitors
-- verification status
-
-without reaching into runtime internals such as child-process handles, scheduler timer maps, event unsubscriptions, or Pi UI state.
-
----
-
-## 1. Design constraints
-
-The Goal schema should satisfy five constraints.
-
-1. It must be reducer-owned data, not ad hoc runtime state.
-2. It must compose existing entities rather than duplicate them.
-3. It must support read-only verification before any autonomous mutation logic is added.
-4. It must separate desired outcomes from execution mechanisms.
-5. It must remain serializable and testable without Pi mocks.
-
-In practice, this means a Goal should reference entities and interpret their state, rather than own live runtime objects.
-
----
-
-## 2. Conceptual model
-
-A Goal is a durable statement of intended progress over a bounded set of work.
-
-A Goal should answer four questions:
-
-1. **What are we trying to achieve?**
-2. **What entities count as evidence of progress?**
-3. **What counts as success, failure, or blocked state?**
-4. **What verification should occur next?**
-
-A Goal is therefore not just a label. It is a small stateful contract tying execution evidence to a desired outcome.
-
----
-
-## 3. Core types
-
-### 3.1 Goal lifecycle status
-
-```ts
-export type GoalStatus =
-  | "pending"
-  | "active"
-  | "satisfied"
-  | "blocked"
-  | "failed"
-  | "archived";
-```
-
-### Semantics
-
-- `pending` — defined but not yet activated
-- `active` — currently being pursued and still incomplete
-- `satisfied` — completion criteria have been met
-- `blocked` — progress is stalled on an unmet dependency or failed precondition
-- `failed` — terminal negative outcome under current criteria
-- `archived` — intentionally closed without further verification
-
-`pending`, `active`, and `blocked` are the main nonterminal states.
-
----
-
-### 3.2 Goal verification status
-
-Goal lifecycle status should be separate from the current verification result.
-
-```ts
-export type GoalVerificationStatus =
-  | "unknown"
-  | "checking"
-  | "verified"
-  | "unverified"
-  | "inconclusive";
-```
-
-### Why separate these?
-
-A Goal may be `active` while its verification is `unknown` or `checking`.
-A Goal may be `blocked` while its latest verification is `unverified`.
-A Goal may become `satisfied` only after a `verified` result is observed.
-
-This avoids collapsing operational progress and evidence quality into one field.
-
----
-
-### 3.3 Goal entry
-
-```ts
-export interface GoalEntry {
-  id: string;
-  title: string;
-  description: string;
-  status: GoalStatus;
-  verificationStatus: GoalVerificationStatus;
-
-  createdAt: number;
-  updatedAt: number;
-  activatedAt?: number;
-  resolvedAt?: number;
-
-  scope: GoalScope;
-  criteria: GoalCriteria;
-  progress: GoalProgressSnapshot;
-  verification: GoalVerificationState;
-
-  metadata?: Record<string, unknown>;
-}
-```
-
-This is the reducer-owned unit of record.
-
----
-
-## 4. Goal scope
-
-A Goal must explicitly declare which entities it cares about.
-
-```ts
-export interface GoalScope {
-  taskIds?: string[];
-  loopIds?: string[];
-  monitorIds?: string[];
-
-  tags?: string[];
-  subjectPrefixes?: string[];
-
-  includeFutureMatchingTasks?: boolean;
-  includeFutureMatchingLoops?: boolean;
-  includeFutureMatchingMonitors?: boolean;
-}
-```
-
-### Guidance
-
-Prefer explicit ids first.
-
-Use broader matching such as `tags` or `subjectPrefixes` only when the goal is intended to absorb future work items dynamically.
-
-### Rationale
-
-The first prototype should remain conservative. Goals should not silently claim unrelated entities.
-
----
-
-## 5. Goal criteria
-
-Criteria define what the Goal considers success, failure, or blocked state.
-
-```ts
-export interface GoalCriteria {
-  success: GoalSuccessCriteria;
-  failure?: GoalFailureCriteria;
-  blocked?: GoalBlockedCriteria;
-}
-```
-
-### 5.1 Success criteria
-
-```ts
-export interface GoalSuccessCriteria {
-  minCompletedTasks?: number;
-  requiredTaskIds?: string[];
-  requiredMonitorIdsCompleted?: string[];
-  requiredLoopIdsPresent?: string[];
-  requireNoPendingTasksInScope?: boolean;
-  requireLatestVerificationPass?: boolean;
-}
-```
-
-### 5.2 Failure criteria
-
-```ts
-export interface GoalFailureCriteria {
-  anyMonitorIdsErrored?: string[];
-  maxVerificationFailures?: number;
-  failIfTaskIdsDeleted?: string[];
-}
-```
-
-### 5.3 Blocked criteria
-
-```ts
-export interface GoalBlockedCriteria {
-  blockedIfAllTasksCompletedButVerificationFails?: boolean;
-  blockedIfNoScopedProgressSinceMs?: number;
-  blockedIfRequiredLoopMissing?: boolean;
-}
-```
-
-### Notes
-
-These criteria are intentionally simple. The first version should use deterministic declarative rules rather than a scripting language.
-
----
-
-## 6. Progress snapshot
-
-Goals should cache a reducer-owned snapshot of relevant progress so verification can be explained, not merely asserted.
-
-```ts
-export interface GoalProgressSnapshot {
-  totalTasks: number;
-  pendingTasks: number;
-  inProgressTasks: number;
-  completedTasks: number;
-
-  activeLoops: number;
-  pausedLoops: number;
-
-  runningMonitors: number;
-  completedMonitors: number;
-  erroredMonitors: number;
-  stoppedMonitors: number;
-
-  lastProgressAt?: number;
-}
-```
-
-### Why cache this?
-
-Because a Goal should be able to say why it is still active, blocked, or satisfied. The snapshot makes verification output auditable and stable in tests.
-
----
-
-## 7. Verification state
-
-Verification should retain the latest evidence, not just a boolean.
-
-```ts
-export interface GoalVerificationState {
-  attempts: number;
-  passes: number;
-  failures: number;
-  lastCheckedAt?: number;
-  lastPassedAt?: number;
-  lastFailedAt?: number;
-  lastReason?: string;
-  nextCheckAfter?: number;
-}
-```
-
-### Interpretation
-
-- `attempts` counts all verifier passes
-- `passes` and `failures` support simple policy thresholds
-- `lastReason` is human-readable justification for the last result
-- `nextCheckAfter` supports future pacing without embedding scheduler internals in the goal itself
-
----
-
-## 8. Reducer state shape
-
-```ts
-export interface GoalReducerState {
-  nextId: number;
-  goalsById: Record<string, GoalEntry>;
-}
-```
-
-This follows the same pattern already adopted by task, loop, monitor, and notification reducers.
-
----
-
-## 9. Event vocabulary
-
-The Goal reducer should start with a small event set.
-
-```ts
-export type GoalEventType =
-  | "GOAL_CREATED"
-  | "GOAL_ACTIVATED"
-  | "GOAL_PROGRESS_RECORDED"
-  | "GOAL_VERIFICATION_STARTED"
-  | "GOAL_VERIFICATION_PASSED"
-  | "GOAL_VERIFICATION_FAILED"
-  | "GOAL_BLOCKED"
-  | "GOAL_UNBLOCKED"
-  | "GOAL_SATISFIED"
-  | "GOAL_FAILED"
-  | "GOAL_ARCHIVED"
-  | "GOAL_UPDATED";
-```
-
-### Event roles
-
-- `GOAL_CREATED` — create the entry in `pending`
-- `GOAL_ACTIVATED` — move `pending -> active`
-- `GOAL_PROGRESS_RECORDED` — update derived progress snapshot
-- `GOAL_VERIFICATION_STARTED` — set `verificationStatus=checking`
-- `GOAL_VERIFICATION_PASSED` — update verification fields and potentially satisfy the goal
-- `GOAL_VERIFICATION_FAILED` — update verification fields and potentially block/fail the goal
-- `GOAL_BLOCKED` — explicit blocked transition
-- `GOAL_UNBLOCKED` — blocked -> active
-- `GOAL_SATISFIED` — terminal success
-- `GOAL_FAILED` — terminal failure
-- `GOAL_ARCHIVED` — terminal closure without claiming success
-- `GOAL_UPDATED` — title/description/criteria/scope edits
-
----
-
-## 10. Effect vocabulary
-
-The Goal reducer should emit a small effect set.
-
-```ts
-export type GoalEffectType =
-  | "PERSIST_GOAL"
-  | "DELETE_GOAL"
-  | "DISPATCH_EVENT"
-  | "REQUEST_GOAL_VERIFICATION";
-```
-
-### Intent
-
-- `PERSIST_GOAL` — save updated goal state
-- `DELETE_GOAL` — only if we later support physical deletion
-- `DISPATCH_EVENT` — derive follow-up events from verification logic
-- `REQUEST_GOAL_VERIFICATION` — ask the coordinator/effect layer to run a read-only verification pass
-
-The reducer should not directly schedule loops or inspect child processes.
-
----
-
-## 11. Derived progress rules
-
-Goals should interpret reducer-owned entity state through projection rules rather than ad hoc queries.
-
-### 11.1 Task projection
-
-Tasks in scope contribute:
-
-- `pendingTasks`
-- `inProgressTasks`
-- `completedTasks`
-- `lastProgressAt` from latest `updatedAt`
-
-### 11.2 Loop projection
-
-Loops in scope contribute:
-
-- `activeLoops`
-- `pausedLoops`
-- loop existence checks for required loop criteria
-
-### 11.3 Monitor projection
-
-Monitors in scope contribute:
-
-- `runningMonitors`
-- `completedMonitors`
-- `erroredMonitors`
-- `stoppedMonitors`
-
-### Rule
-
-Projection should be a pure helper over reducer-owned snapshots, not a runtime query API.
-
----
-
-## 12. Initial verification algorithm
-
-The first goal verifier should remain intentionally modest.
-
-### Input
-
-- one `GoalEntry`
-- current task reducer state
-- current loop reducer state
-- current monitor reducer state
-
-### Output
-
-- updated `GoalProgressSnapshot`
-- one of:
-  - `GOAL_VERIFICATION_PASSED`
-  - `GOAL_VERIFICATION_FAILED`
-  - `GOAL_BLOCKED`
-  - no terminal transition yet
-
-### Suggested order
-
-1. project scoped entities into a progress snapshot
-2. update `lastCheckedAt`
-3. check hard failure criteria first
-4. check success criteria second
-5. check blocked criteria third
-6. otherwise remain `active` with `verificationStatus=unverified` or `inconclusive`
-
-This ordering keeps failure and success decisions deterministic.
-
----
-
-## 13. Allowed and forbidden dependencies
-
-### Goal reducer may depend on
-
-- goal reducer state
-- serializable event payloads
-- projected reducer-owned task/loop/monitor snapshots provided by the coordinator
-
-### Goal reducer may not depend on
-
-- `ChildProcess` handles
-- scheduler timer maps
-- event unsubscriber handles
-- `AbortController`
-- Pi UI context
-- direct `sendMessage()` or eventbus calls
-- the raw `MonitorProcess` map
-
-This boundary is essential if goals are to remain testable and replayable.
-
----
-
-## 14. Initial invariants
-
-The first Goal implementation should enforce these invariants.
-
-1. Goal ids are monotonic.
-2. Terminal goals (`satisfied`, `failed`, `archived`) do not transition back to `active` without an explicit reopen event if such an event is later added.
-3. `resolvedAt` is set exactly when entering a terminal lifecycle state.
-4. `verificationStatus=verified` implies the last verification result was a pass.
-5. `verificationStatus=checking` is nonterminal.
-6. Goal progress is derived from scoped reducer-owned entity state, not from runtime handles.
-7. A Goal may reference future matching tasks only when that intent is explicit in `GoalScope`.
-
----
-
-## 15. Suggested storage shape
-
-If and when goals are persisted independently, the storage shape should mirror the existing reducer-backed stores.
-
-```ts
-export interface GoalStoreData {
-  nextId: number;
-  goals: GoalEntry[];
-}
-```
-
-No separate runtime-only goal fields should be serialized.
-
----
-
-## 16. Relationship to tasks #12 and #13
-
-### Task #12 — Prototype goal verifier loop
-
-This schema gives `#12` a narrow target:
-
-- implement projection helpers
-- implement read-only verification
-- emit `REQUEST_GOAL_VERIFICATION` or derived goal events
-- do not yet mutate unrelated loop/task/monitor runtime behavior
-
-### Task #13 — Document state machine migration
-
-This schema also gives `#13` a stable anchor for the final architecture narrative:
-
-- reducers own state
-- coordinator owns cross-entity dispatch
-- verifiers consume reducer-owned snapshots
-- goals remain declarative rather than runtime-coupled
-
----
-
-## 17. Recommended next implementation order
-
-1. add `GoalEntry` types and reducer state definitions
-2. add pure goal reducer tests for create/activate/update/block/satisfy/fail/archive
-3. add projection helpers over task/loop/monitor reducer states
-4. implement a read-only verifier that emits goal events
-5. only afterward consider autonomous follow-up behavior
-
----
-
-## 18. Summary
-
-We define a Goal as a reducer-owned contract over scoped task, loop, and monitor evidence.
-
-Its state should remain:
-
-- declarative
-- serializable
-- projection-driven
-- verification-oriented
-- independent of runtime internals
-
-This gives the next stage of work a disciplined base for adding goal verification without collapsing back into ad hoc control flow.