@cleocode/playbooks 2026.4.88 → 2026.4.91

package/dist/policy.js

@@ -1,85 +0,0 @@
-/**
- * HITL auto-policy — evaluates whether a deterministic command requires
- * human approval before execution. Conservative defaults per OpenProse standard.
- *
- * `require-human` rules are evaluated FIRST and cannot be bypassed by
- * `auto-approve` rules even when callers append custom rules to the list.
- * The default decision for an unmatched command is `require-human` so the
- * runtime fails closed when confronted with unknown surface area.
- *
- * @task T889 / T908 / W4-9
- */
-/**
- * Conservative default policy. `require-human` rules come first for ordering
- * clarity, but evaluation order in {@link evaluatePolicy} enforces the
- * priority regardless of array position.
- */
-export const DEFAULT_POLICY_RULES = Object.freeze([
-    { pattern: /\bnpm\s+publish\b/, action: 'require-human', reason: 'publish' },
-    { pattern: /\bpnpm\s+publish\b/, action: 'require-human', reason: 'publish' },
-    { pattern: /\byarn\s+publish\b/, action: 'require-human', reason: 'publish' },
-    { pattern: /\bgit\s+push\b/, action: 'require-human', reason: 'push' },
-    { pattern: /\bgit\s+tag\b/, action: 'require-human', reason: 'tag' },
-    { pattern: /\bgh\s+release\s+create\b/, action: 'require-human', reason: 'release' },
-    { pattern: /\bgh\s+workflow\s+run\b/, action: 'require-human', reason: 'workflow-trigger' },
-    {
-        pattern: /\b(rm\s+-rf|drop\s+table|truncate|delete\s+from)\b/i,
-        action: 'require-human',
-        reason: 'destructive',
-    },
-    {
-        pattern: /\b(curl|wget|fetch)\b.*\bhttps?:/i,
-        action: 'require-human',
-        reason: 'external-api',
-    },
-    { pattern: /\b(ssh|scp|rsync)\b.+@/, action: 'require-human', reason: 'remote-access' },
-    {
-        pattern: /^pnpm\s+(test|run\s+test|biome|tsc)\b/,
-        action: 'auto-approve',
-        reason: 'safe-qa-tool',
-    },
-    {
-        pattern: /^cleo\s+(verify|check|show|find|list|status|current|next)\b/,
-        action: 'auto-approve',
-        reason: 'safe-cleo-read',
-    },
-]);
-/**
- * Evaluates a command against the supplied policy rules and returns the
- * resolved approval decision.
- *
- * Priority:
- * 1. Every `require-human` rule across the list is tested first.
- * 2. `auto-approve` rules are tested only if no block fired.
- * 3. Fallback is `{ action: 'require-human', reason: 'default' }` so
- *    unknown commands never auto-execute.
- *
- * Callers MAY pass a custom rule list, but they CANNOT relax default blocks —
- * any rule elsewhere in the list that matches with `require-human` wins over
- * any auto-approve match, regardless of order.
- *
- * @param command The fully-resolved command string (executable plus arguments).
- * @param rules The ordered rule list. Defaults to {@link DEFAULT_POLICY_RULES}.
- * @returns The approval decision including the matched reason.
- */
-export function evaluatePolicy(command, rules = DEFAULT_POLICY_RULES) {
-    for (const rule of rules) {
-        if (rule.action === 'require-human' && rule.pattern.test(command)) {
-            return {
-                action: 'require-human',
-                reason: rule.reason,
-                matchedPattern: rule.pattern.source,
-            };
-        }
-    }
-    for (const rule of rules) {
-        if (rule.action === 'auto-approve' && rule.pattern.test(command)) {
-            return {
-                action: 'auto-approve',
-                reason: rule.reason,
-                matchedPattern: rule.pattern.source,
-            };
-        }
-    }
-    return { action: 'require-human', reason: 'default' };
-}

package/dist/schema.d.ts

@@ -1,374 +0,0 @@
-/**
- * Drizzle ORM table definitions for playbook state.
- * Both tables are added to tasks.db via migration at
- * packages/core/migrations/drizzle-tasks/20260417220000_t889-playbook-tables/.
- *
- * @task T889 / T904 / W4-6
- */
-export declare const playbookRuns: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
-    name: "playbook_runs";
-    schema: undefined;
-    columns: {
-        runId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: string;
-            tableName: "playbook_runs";
-            dataType: "string";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: true;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}>;
-        playbookName: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: string;
-            tableName: "playbook_runs";
-            dataType: "string";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}>;
-        playbookHash: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: string;
-            tableName: "playbook_runs";
-            dataType: "string";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}>;
-        currentNode: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: string;
-            tableName: "playbook_runs";
-            dataType: "string";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}>;
-        bindings: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: string;
-            tableName: "playbook_runs";
-            dataType: "string";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}>;
-        errorContext: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: string;
-            tableName: "playbook_runs";
-            dataType: "string";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}>;
-        status: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: string;
-            tableName: "playbook_runs";
-            dataType: "string";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}>;
-        iterationCounts: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: string;
-            tableName: "playbook_runs";
-            dataType: "string";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}>;
-        epicId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: string;
-            tableName: "playbook_runs";
-            dataType: "string";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}>;
-        sessionId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: string;
-            tableName: "playbook_runs";
-            dataType: "string";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}>;
-        startedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: string;
-            tableName: "playbook_runs";
-            dataType: "string";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}>;
-        completedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: string;
-            tableName: "playbook_runs";
-            dataType: "string";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}>;
-    };
-    dialect: "sqlite";
-}>;
-export declare const playbookApprovals: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
-    name: "playbook_approvals";
-    schema: undefined;
-    columns: {
-        approvalId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: string;
-            tableName: "playbook_approvals";
-            dataType: "string";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: true;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}>;
-        runId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: string;
-            tableName: "playbook_approvals";
-            dataType: "string";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}>;
-        nodeId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: string;
-            tableName: "playbook_approvals";
-            dataType: "string";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}>;
-        token: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: string;
-            tableName: "playbook_approvals";
-            dataType: "string";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}>;
-        requestedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: string;
-            tableName: "playbook_approvals";
-            dataType: "string";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}>;
-        approvedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: string;
-            tableName: "playbook_approvals";
-            dataType: "string";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}>;
-        approver: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: string;
-            tableName: "playbook_approvals";
-            dataType: "string";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}>;
-        reason: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: string;
-            tableName: "playbook_approvals";
-            dataType: "string";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}>;
-        status: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: string;
-            tableName: "playbook_approvals";
-            dataType: "string";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}>;
-        autoPassed: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: string;
-            tableName: "playbook_approvals";
-            dataType: "number int53";
-            data: number;
-            driverParam: number;
-            notNull: true;
-            hasDefault: true;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}>;
-    };
-    dialect: "sqlite";
-}>;
-export type { PlaybookApproval, PlaybookApprovalStatus, PlaybookRun, PlaybookRunStatus, } from '@cleocode/contracts';

package/dist/schema.js

@@ -1,34 +0,0 @@
-/**
- * Drizzle ORM table definitions for playbook state.
- * Both tables are added to tasks.db via migration at
- * packages/core/migrations/drizzle-tasks/20260417220000_t889-playbook-tables/.
- *
- * @task T889 / T904 / W4-6
- */
-import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
-export const playbookRuns = sqliteTable('playbook_runs', {
-    runId: text('run_id').primaryKey(),
-    playbookName: text('playbook_name').notNull(),
-    playbookHash: text('playbook_hash').notNull(),
-    currentNode: text('current_node'),
-    bindings: text('bindings').notNull().default('{}'),
-    errorContext: text('error_context'),
-    status: text('status').notNull().default('running'),
-    iterationCounts: text('iteration_counts').notNull().default('{}'),
-    epicId: text('epic_id'),
-    sessionId: text('session_id'),
-    startedAt: text('started_at').notNull().default("(datetime('now'))"),
-    completedAt: text('completed_at'),
-});
-export const playbookApprovals = sqliteTable('playbook_approvals', {
-    approvalId: text('approval_id').primaryKey(),
-    runId: text('run_id').notNull(),
-    nodeId: text('node_id').notNull(),
-    token: text('token').notNull().unique(),
-    requestedAt: text('requested_at').notNull().default("(datetime('now'))"),
-    approvedAt: text('approved_at'),
-    approver: text('approver'),
-    reason: text('reason'),
-    status: text('status').notNull().default('pending'),
-    autoPassed: integer('auto_passed').notNull().default(0),
-});

package/dist/state.d.ts

@@ -1,96 +0,0 @@
-/**
- * State layer for playbook runtime — CRUD against playbook_runs + playbook_approvals.
- * Uses node:sqlite DatabaseSync for consistency with rest of CLEO.
- *
- * All JSON-shaped columns (`bindings`, `iteration_counts`) are serialized to
- * text at the write boundary and strictly parsed on read. Parse failures throw
- * rather than silently reset state, per the data-integrity contract of ADR-013.
- *
- * Multi-column updates and cross-table operations run inside a BEGIN/COMMIT
- * transaction so partial failures cannot leave the run in a half-mutated state.
- *
- * @task T889 / T904 / W4-8
- */
-import type { DatabaseSync } from 'node:sqlite';
-import type { PlaybookApproval, PlaybookRun, PlaybookRunStatus } from '@cleocode/contracts';
-/**
- * Input payload for {@link createPlaybookRun}. `playbookHash` MUST be a stable
- * digest of the `.cantbook` source so replays can prove definition parity.
- */
-export interface CreatePlaybookRunInput {
-    playbookName: string;
-    playbookHash: string;
-    epicId?: string;
-    sessionId?: string;
-    initialBindings?: Record<string, unknown>;
-}
-/**
- * Input payload for {@link createPlaybookApproval}. Callers MUST supply an
- * opaque `token` — approval resume flows look up runs by this value.
- */
-export interface CreatePlaybookApprovalInput {
-    runId: string;
-    nodeId: string;
-    token: string;
-    autoPassed?: boolean;
-}
-/**
- * Filter options for {@link listPlaybookRuns}. All fields are optional; when
- * omitted the call returns the most recent runs ordered by `started_at DESC`.
- */
-export interface ListPlaybookRunsOptions {
-    status?: PlaybookRunStatus;
-    epicId?: string;
-    limit?: number;
-}
-/**
- * Inserts a new playbook run with a freshly generated UUID, `status='running'`,
- * and the provided initial bindings. Returns the hydrated {@link PlaybookRun}
- * read back from the row so callers see all server-defaulted columns
- * (`started_at`, empty `iteration_counts`, etc.).
- */
-export declare function createPlaybookRun(db: DatabaseSync, input: CreatePlaybookRunInput): PlaybookRun;
-/**
- * Fetches a playbook run by its primary key. Returns `null` when the run
- * does not exist. Never throws on missing rows.
- */
-export declare function getPlaybookRun(db: DatabaseSync, runId: string): PlaybookRun | null;
-/**
- * Applies a partial patch to a playbook run inside a transaction so mixed
- * column updates (e.g. `status` + `currentNode`) commit atomically. Returns
- * the fully-hydrated run read back after commit.
- */
-export declare function updatePlaybookRun(db: DatabaseSync, runId: string, patch: Partial<Omit<PlaybookRun, 'runId' | 'startedAt'>>): PlaybookRun;
-/**
- * Lists playbook runs filtered by status and/or epic. Defaults to `ORDER BY
- * started_at DESC` so the newest runs surface first for dashboards.
- */
-export declare function listPlaybookRuns(db: DatabaseSync, opts?: ListPlaybookRunsOptions): PlaybookRun[];
-/**
- * Deletes a playbook run by primary key. Returns `true` if a row was removed.
- * CASCADE wipes all associated approvals via the foreign-key constraint on
- * `playbook_approvals.run_id`.
- */
-export declare function deletePlaybookRun(db: DatabaseSync, runId: string): boolean;
-/**
- * Inserts a new approval record with a freshly generated UUID, `status='pending'`,
- * and the caller-supplied opaque token. Returns the hydrated
- * {@link PlaybookApproval} so callers see the server-defaulted `requested_at`.
- */
-export declare function createPlaybookApproval(db: DatabaseSync, input: CreatePlaybookApprovalInput): PlaybookApproval;
-/**
- * Fetches an approval by its opaque token. Returns `null` if no row matches.
- * The token column carries a UNIQUE constraint so at most one row is returned.
- */
-export declare function getPlaybookApprovalByToken(db: DatabaseSync, token: string): PlaybookApproval | null;
-/**
- * Applies a partial patch to an approval record inside a transaction. Used by
- * the approval-resume flow to transactionally set both `status` and
- * `approved_at` when a human resolves a HITL checkpoint.
- */
-export declare function updatePlaybookApproval(db: DatabaseSync, approvalId: string, patch: Partial<Omit<PlaybookApproval, 'approvalId' | 'requestedAt'>>): PlaybookApproval;
-/**
- * Lists all approvals for a given run, ordered by `requested_at ASC` so the
- * first HITL checkpoint surfaces first.
- */
-export declare function listPlaybookApprovals(db: DatabaseSync, runId: string): PlaybookApproval[];