@farukada/langchain-ts-gms 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Faruk Ada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,444 @@
+# Vector-centric Goal Management System built with LangChain TypeScript and LangGraph (GMS)
+
+[![npm version](https://img.shields.io/npm/v/%40farukada%2Flangchain-ts-gms)](https://www.npmjs.com/package/@farukada/langchain-ts-gms)
+[![Sponsor](https://img.shields.io/badge/Sponsor-FarukAda-ea4aaa?logo=githubsponsors)](https://github.com/sponsors/FarukAda)
+![Node >=22](https://img.shields.io/badge/node-%3E%3D22-339933)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6)
+![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
+![CI Ready](https://img.shields.io/badge/CI-fast%20%2B%20heavy-success)
+
+GMS is a planning library for autonomous agents. It turns a goal into a hierarchical task graph (tasks + sub-tasks + dependencies), while your external agent remains responsible for execution.
+
+## Table of Contents
+
+- [What This Package Is](#what-this-package-is)
+- [Responsibility Boundary](#responsibility-boundary)
+- [System Overview](#system-overview)
+- [Quick Start](#quick-start)
+- [Use as Library](#use-as-library)
+- [Public API Reference](#public-api-reference)
+- [Package Exports](#package-exports)
+- [Tool Catalog](#tool-catalog)
+- [Configuration Reference](#configuration-reference)
+- [Production Considerations](#production-considerations)
+- [Known Non-Goals](#known-non-goals)
+- [Testing and CI](#testing-and-ci)
+- [Documentation](#documentation)
+- [Project Structure](#project-structure)
+- [License](#license)
+
+<a id="what-this-package-is"></a>
+
+## What This Package Is
+
+- **Planning-only engine**: builds plans and validates goal trees.
+- **Hierarchical model**: goal -> tasks -> sub-tasks with parent and dependency links.
+- **LangChain-native**: exports tools via the `tool()` factory from `@langchain/core/tools`.
+- **Vector-centric**: uses embeddings + Qdrant for semantic decomposition and retrieval.
+
+<a id="responsibility-boundary"></a>
+
+## Responsibility Boundary
+
+| Concern                                       | Owned by GMS | Owned by your Agent |
+| --------------------------------------------- | ------------ | ------------------- |
+| Goal decomposition into tasks/sub-tasks       | Yes          | No                  |
+| Task dependency-safe ordering                 | Yes          | No                  |
+| Goal/task retrieval and mutation tooling      | Yes          | No                  |
+| Task execution (calling APIs, tools, scripts) | No           | Yes                 |
+| Runtime retries, side effects, actuation      | No           | Yes                 |
+
+<a id="system-overview"></a>
+
+## System Overview
+
+```mermaid
+flowchart LR
+    subgraph agentRuntime [AgentRuntime]
+        agent[LangChainAgent]
+        gmsTools[GmsTools]
+        executor[TaskExecutor]
+    end
+
+    subgraph gmsLibrary [GmsLibraryInProcess]
+        workflow[createGmsWorkflow]
+        planner[gms_plan_goal]
+        lifecycle[LifecycleTools]
+    end
+
+    subgraph backingServices [BackingServices]
+        qdrant[(Qdrant)]
+        embeddings[EmbeddingsProvider]
+    end
+
+    agent --> gmsTools
+    gmsTools --> planner
+    gmsTools --> lifecycle
+    planner --> workflow
+    workflow --> qdrant
+    workflow --> embeddings
+    planner -->|"returns plan JSON"| executor
+```
+
+<a id="quick-start"></a>
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js >= 22
+- npm
+- Docker (for Qdrant)
+
+### Install
+
+```bash
+npm add @farukada/langchain-ts-gms
+```
+
+### Development infrastructure
+
+```bash
+# Start Qdrant (vector storage) and Ollama (LLM + embeddings)
+docker compose up -d qdrant
+docker compose --profile ollama up -d ollama
+```
+
+Full operational steps and troubleshooting are in [docs/operations.md](./docs/operations.md).
+
+<a id="use-as-library"></a>
+
+## Use as Library
+
+Install:
+
+```bash
+npm add @farukada/langchain-ts-gms
+```
+
+### Minimal registration
+
+```ts
+import { createGmsToolFromEnv } from "@farukada/langchain-ts-gms/tool";
+
+const planTool = await createGmsToolFromEnv();
+agent.tools.push(planTool);
+```
+
+### Full lifecycle registration
+
+```ts
+import {
+  createGmsToolFromEnv,
+  createGmsLifecycleToolsFromEnv,
+} from "@farukada/langchain-ts-gms/tool";
+
+const planTool = await createGmsToolFromEnv({
+  decomposeOptions: { topK: 5, maxDepth: 4 },
+});
+const lifecycleTools = await createGmsLifecycleToolsFromEnv();
+
+agent.tools.push(planTool, ...lifecycleTools);
+```
+
+#### `decomposeOptions`
+
+| Option     | Default | Purpose                                                                                 |
+| ---------- | ------- | --------------------------------------------------------------------------------------- |
+| `topK`     | `5`     | Number of capability vectors retrieved from Qdrant as context for the LLM decomposition |
+| `maxDepth` | `4`     | Maximum nesting depth for the hierarchical task tree                                    |
+
+Higher `topK` gives the planner more context but increases token cost. Lower `maxDepth` produces flatter plans.
+
+### Multi-tenancy
+
+All tools support an optional `tenantId` field for data isolation. When set, capability search and goal listing are scoped to the given tenant:
+
+```ts
+const planTool = await createGmsToolFromEnv();
+// The agent passes tenantId when invoking the tool:
+// { goalDescription: "...", tenantId: "org-123" }
+```
+
+Qdrant payload indexes on `metadata.tenant_id` ensure filtered queries remain fast.
+
+<a id="public-api-reference"></a>
+
+## Public API Reference
+
+### Main exports
+
+- `createGmsPlanTool(deps)`: create planning tool (`gms_plan_goal`).
+- `createGmsToolFromEnv(options)`: env-based planning tool factory.
+- `createGmsLifecycleTools(deps)`: create retrieval/mutation/validation toolset.
+- `createGmsLifecycleToolsFromEnv(options)`: env-based lifecycle factory.
+- `createAllGmsToolsFromEnv(options)`: convenience factory for both planning + lifecycle tools with shared repository instances (recommended).
+- `createPlan(input, deps)`: execute planning directly without tool wrapper.
+- `createGmsWorkflow(deps)`: lower-level LangGraph workflow factory.
+
+### Key result shape (`gms_plan_goal`)
+
+```ts
+{
+  version: "1.0",
+  goalId: string,
+  status: "planned" | "failed" | "human_approval_required",
+  tasks: Task[],
+  executionOrder: string[],
+  traceId?: string,
+  interrupt?: unknown,
+  error?: string
+}
+```
+
+### Advanced dependency wiring (explicit repositories)
+
+```ts
+import {
+  createGmsPlanTool,
+  GoalMemoryRepository,
+  createEmbeddingProvider,
+  CAPABILITIES_COLLECTION,
+} from "@farukada/langchain-ts-gms";
+
+const embeddings = createEmbeddingProvider();
+const goalRepository = new GoalMemoryRepository({ embeddings });
+const capabilityRepository = new GoalMemoryRepository({
+  embeddings,
+  collectionName: CAPABILITIES_COLLECTION,
+});
+await goalRepository.bootstrap();
+
+const planTool = createGmsPlanTool({ goalRepository, capabilityRepository });
+agent.tools.push(planTool);
+```
+
+### Production checkpointer
+
+By default, the GMS workflow uses an **in-memory checkpointer** (`MemorySaver`) — state is lost on process restart. For production, inject a persistent checkpointer via `createGmsWorkflow`:
+
+```ts
+import { SqliteSaver } from "@langchain/langgraph-checkpoint-sqlite";
+import {
+  createGmsWorkflow,
+  GoalMemoryRepository,
+  createEmbeddingProvider,
+  createChatModelProvider,
+} from "@farukada/langchain-ts-gms";
+
+const checkpointer = SqliteSaver.fromConnString("./gms.db");
+const embeddings = createEmbeddingProvider();
+const goalRepository = new GoalMemoryRepository({ embeddings });
+
+const workflow = createGmsWorkflow({
+  goalRepository,
+  checkpointer, // persists workflow state across restarts
+});
+```
+
+The `checkpointer` option is accepted by `createGmsWorkflow` (via the `WorkflowDeps` interface). The higher-level `createGmsPlanTool` and `*FromEnv` factories use `MemorySaver` internally; to override it, use `createGmsWorkflow` directly.
+
+### Human-in-the-Loop (HITL)
+
+When a plan exceeds the guardrail task-count threshold (default: 10 tasks), the workflow triggers a LangGraph `interrupt` and returns `status: "human_approval_required"`:
+
+```ts
+const result = JSON.parse(await planTool.invoke({ goalDescription: "..." }));
+
+if (result.status === "human_approval_required") {
+  // result.interrupt contains: { action, goalId, taskCount, message }
+  // Present the plan to a human for review, then resume the workflow
+  // using the thread_id (result.goalId) via the compiled workflow.
+}
+```
+
+The interrupt payload shape:
+
+```ts
+{ action: "approve_plan", goalId: string, taskCount: number, message: string }
+```
+
+### Capability seeding
+
+The planner searches the `gms_capabilities` Qdrant collection for existing capabilities to inform task decomposition. Without seeded capabilities, the LLM decomposes blindly — plans still work but are lower quality.
+
+Seed capabilities using the same `GoalMemoryRepository`:
+
+```ts
+import {
+  GoalMemoryRepository,
+  createEmbeddingProvider,
+  CAPABILITIES_COLLECTION,
+} from "@farukada/langchain-ts-gms";
+
+const embeddings = createEmbeddingProvider();
+const capRepo = new GoalMemoryRepository({
+  embeddings,
+  collectionName: CAPABILITIES_COLLECTION,
+});
+await capRepo.bootstrap();
+
+await capRepo.upsert({
+  id: crypto.randomUUID(),
+  description: "Deploy Node.js services to Kubernetes",
+  status: "planned",
+  priority: "medium",
+  tasks: [],
+  createdAt: new Date().toISOString(),
+  updatedAt: new Date().toISOString(),
+});
+```
+
+The more relevant capabilities you seed, the better the planner's task decomposition quality.
+
+<a id="package-exports"></a>
+
+## Package Exports
+
+The package exposes granular sub-path exports for tree-shaking and targeted imports:
+
+| Sub-path                                       | Provides                                                      |
+| ---------------------------------------------- | ------------------------------------------------------------- |
+| `@farukada/langchain-ts-gms`                   | All public APIs (tools, repos, domain utils, schemas)         |
+| `@farukada/langchain-ts-gms/tool`              | `createGmsPlanTool`, `createGmsLifecycleTools`, env factories |
+| `@farukada/langchain-ts-gms/tools/*`           | Individual tool factories (`planGoal`, `getGoal`, etc.)       |
+| `@farukada/langchain-ts-gms/helpers`           | Input normalization, pagination, tree filtering               |
+| `@farukada/langchain-ts-gms/types`             | `GmsToolDeps`, `GmsPlanResult`, `AllGmsTools`                 |
+| `@farukada/langchain-ts-gms/schemas/planning`  | `GmsToolInputSchema`                                          |
+| `@farukada/langchain-ts-gms/schemas/lifecycle` | All lifecycle tool input schemas                              |
+
+### Example: import individual tools
+
+```ts
+import { createGetGoalTool } from "@farukada/langchain-ts-gms/tools/getGoal";
+import { createUpdateTaskTool } from "@farukada/langchain-ts-gms/tools/updateTask";
+```
+
+<a id="tool-catalog"></a>
+
+## Tool Catalog
+
+### Planning tool
+
+- `gms_plan_goal`: create a hierarchical plan and dependency-safe `executionOrder`.
+
+### Lifecycle tools
+
+- `gms_get_goal`: fetch goal with full hierarchical tasks.
+- `gms_get_task`: fetch a single task by `goalId` + `taskId`.
+- `gms_list_tasks`: list tasks with filters and pagination.
+- `gms_search_tasks`: search tasks by text, status, priority, dependency presence.
+- `gms_list_goals`: list goals with filters and pagination.
+- `gms_update_goal`: update goal fields.
+- `gms_update_task`: update task status/result/error.
+- `gms_validate_goal_tree`: validate hierarchy and dependency invariants.
+- `gms_get_progress`: get progress counters and completion rate.
+- `gms_replan_goal`: replan using `append`, `replace_failed`, or `replace_all`.
+
+### Tool input/output reference
+
+| Tool                     | Required input     | Output focus                                               |
+| ------------------------ | ------------------ | ---------------------------------------------------------- |
+| `gms_plan_goal`          | `goalDescription`  | `goalId`, `status`, hierarchical `tasks`, `executionOrder` |
+| `gms_get_goal`           | `goalId`           | Full goal object with nested tasks                         |
+| `gms_get_task`           | `goalId`, `taskId` | Single task + `parentId` + dependency context              |
+| `gms_list_tasks`         | `goalId`           | Filtered/paginated task list + `total`                     |
+| `gms_search_tasks`       | `goalId`           | Query/filter-based paginated task results                  |
+| `gms_list_goals`         | none               | Filtered/paginated goals + `total`                         |
+| `gms_update_goal`        | `goalId`           | Updated goal status/metadata fields                        |
+| `gms_update_task`        | `goalId`, `taskId` | Updated task snapshot                                      |
+| `gms_validate_goal_tree` | `goalId`           | Invariant validation result (`valid`, `issues`)            |
+| `gms_get_progress`       | `goalId`           | Counters + completion rate                                 |
+| `gms_replan_goal`        | `goalId`           | Replan diff (`replacedTaskIds`, `newTaskIds`)              |
+
+<a id="configuration-reference"></a>
+
+## Configuration Reference
+
+Runtime environment variables:
+
+| Variable                     | Required | Default                                | Purpose                                              |
+| ---------------------------- | -------- | -------------------------------------- | ---------------------------------------------------- |
+| `NODE_ENV`                   | No       | `development`                          | Runtime mode                                         |
+| `LOG_LEVEL`                  | No       | `info`                                 | Minimum log level (`debug`, `info`, `warn`, `error`) |
+| `QDRANT_URL`                 | No       | `http://localhost:6333`                | Qdrant endpoint                                      |
+| `QDRANT_API_KEY`             | No       | -                                      | Qdrant authentication key                            |
+| `OLLAMA_HOST`                | No       | `http://localhost:11434`               | Ollama server URL                                    |
+| `OLLAMA_EMBEDDING_MODEL`     | No       | `nomic-embed-text`                     | Default embedding model                              |
+| `OLLAMA_CHAT_MODEL`          | No       | `llama3.2:3b`                          | Default chat/planning model                          |
+| `GMS_OLLAMA_EMBEDDING_MODEL` | No       | falls back to `OLLAMA_EMBEDDING_MODEL` | GMS-specific embedding model override                |
+| `GMS_OLLAMA_CHAT_MODEL`      | No       | falls back to `OLLAMA_CHAT_MODEL`      | GMS-specific chat model override                     |
+| `LANGCHAIN_TRACING_V2`       | No       | `false`                                | LangChain tracing toggle                             |
+| `LANGCHAIN_API_KEY`          | No       | -                                      | LangSmith API key when tracing is enabled            |
+
+<a id="production-considerations"></a>
+
+## Production Considerations
+
+- **Checkpointer**: Replace the default in-memory `MemorySaver` with a persistent store. See [Production checkpointer](#production-checkpointer).
+- **Capabilities**: Seed the `gms_capabilities` collection for higher-quality plans. See [Capability seeding](#capability-seeding).
+- **HITL**: Handle the `human_approval_required` status if plans exceed guardrail thresholds. See [Human-in-the-Loop](#human-in-the-loop-hitl).
+- **Multi-tenancy**: Pass `tenantId` to isolate data per organization. See [Multi-tenancy](#multi-tenancy).
+
+<a id="known-non-goals"></a>
+
+## Known Non-Goals
+
+- GMS does not execute tasks; it only plans and manages goal/task state.
+- GMS does not lock/claim tasks for concurrent workers in this package version.
+- GMS does not include audit history/event sourcing for every lifecycle mutation.
+- GMS does not enforce organization-specific policy packs out of the box; guardrails are extensible.
+
+<a id="testing-and-ci"></a>
+
+## Testing and CI
+
+### Local checks
+
+| Command                 | Purpose                                |
+| ----------------------- | -------------------------------------- |
+| `npm test`              | Unit tests (CI-safe, no external deps) |
+| `npm run test:ci`       | CI-safe unit test suite                |
+| `npm run test:watch`    | Watch mode for development             |
+| `npm run test:coverage` | Unit tests with V8 coverage            |
+
+### CI pipeline
+
+```mermaid
+flowchart LR
+    sourceChange[PushOrPullRequest]
+    validate[Validate]
+    integrationAgent[IntegrationAgent]
+    publish[PublishToNpm]
+
+    sourceChange --> validate
+    validate -->|"push to main"| integrationAgent --> publish
+```
+
+<a id="documentation"></a>
+
+## Documentation
+
+- [Documentation Index](./docs/README.md)
+- [Architecture](./docs/architecture.md)
+- [Operations Runbook](./docs/operations.md)
+- [ADR 0001: Vector-Centric GMS](./docs/adr/0001-vector-centric-gms.md)
+
+<a id="project-structure"></a>
+
+## Project Structure
+
+```text
+src/
+├── app/          # Workflow, planning, guardrails
+├── lib/          # Public library API + tools
+├── config/       # Environment configuration
+├── domain/       # Core contracts and task utilities
+└── infra/        # Qdrant, embeddings, observability
+```
+
+<a id="license"></a>
+
+## License
+
+MIT

package/dist/app/governance/guardrails.d.ts

@@ -0,0 +1,59 @@
+import type { Task } from "../../domain/contracts.js";
+/**
+ * Default forbidden patterns (case-insensitive) that block execution.
+ *
+ * @todo Consider making forbidden patterns configurable per-tenant or
+ *       per-environment via WorkflowDeps / GuardrailConfig. This would
+ *       allow teams to add domain-specific blockers without code changes.
+ */
+export declare const DEFAULT_FORBIDDEN_PATTERNS: readonly string[];
+/** Default maximum task count before requiring human approval. */
+export declare const DEFAULT_MAX_TASK_COUNT = 10;
+export interface GuardrailOptions {
+    /** Patterns (case-insensitive substrings) that block execution. Defaults to `DEFAULT_FORBIDDEN_PATTERNS`. */
+    forbiddenPatterns?: readonly string[];
+}
+export interface HumanApprovalOptions {
+    /** Maximum number of tasks (including nested) before requiring human approval. Defaults to `DEFAULT_MAX_TASK_COUNT`. */
+    maxTaskCount?: number;
+}
+/**
+ * Policy guardrail: checks proposed tasks (including nested) against forbidden patterns.
+ * Returns { allowed: false, reason } if any task violates policy.
+ *
+ * @param tasks       – hierarchical task tree
+ * @param options     – override forbidden patterns
+ * @param preFlat     – optional pre-flattened tasks to avoid redundant flattening
+ */
+export declare function checkGuardrail(tasks: Task[], options?: GuardrailOptions, preFlat?: Task[]): {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+};
+/**
+ * Determines if a plan requires human approval (e.g. many tasks, high-risk).
+ * Counts all tasks in the hierarchy.
+ *
+ * @param tasks       – hierarchical task tree
+ * @param options     – override max task count
+ * @param preFlat     – optional pre-flattened tasks to avoid redundant flattening
+ */
+export declare function requiresHumanApproval(tasks: Task[], options?: HumanApprovalOptions, preFlat?: Task[]): boolean;
+/** Combined guardrail + human approval evaluation. Flattens the task tree once. */
+export interface GuardrailResult {
+    check: {
+        allowed: true;
+    } | {
+        allowed: false;
+        reason: string;
+    };
+    needsHumanApproval: boolean;
+    flatCount: number;
+}
+/**
+ * Evaluate both policy guardrails and human-approval requirements in a single
+ * pass over the flattened task tree.
+ */
+export declare function evaluateGuardrails(tasks: Task[], guardOpts?: GuardrailOptions, approvalOpts?: HumanApprovalOptions): GuardrailResult;
+//# sourceMappingURL=guardrails.d.ts.map

package/dist/app/governance/guardrails.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardrails.d.ts","sourceRoot":"","sources":["../../../src/app/governance/guardrails.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,2BAA2B,CAAC;AAGtD;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAQvD,CAAC;AAEF,kEAAkE;AAClE,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC,MAAM,WAAW,gBAAgB;IAC/B,6GAA6G;IAC7G,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,oBAAoB;IACnC,wHAAwH;IACxH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,IAAI,EAAE,EACb,OAAO,GAAE,gBAAqB,EAC9B,OAAO,CAAC,EAAE,IAAI,EAAE,GACf;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAgBxD;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,IAAI,EAAE,EACb,OAAO,GAAE,oBAAyB,EAClC,OAAO,CAAC,EAAE,IAAI,EAAE,GACf,OAAO,CAMT;AAED,mFAAmF;AACnF,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE;QAAE,OAAO,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9D,kBAAkB,EAAE,OAAO,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,IAAI,EAAE,EACb,SAAS,GAAE,gBAAqB,EAChC,YAAY,GAAE,oBAAyB,GACtC,eAAe,CAOjB"}

package/dist/app/governance/guardrails.js

@@ -0,0 +1,73 @@
+import { flattenTasks } from "../../domain/taskUtils.js";
+/**
+ * Default forbidden patterns (case-insensitive) that block execution.
+ *
+ * @todo Consider making forbidden patterns configurable per-tenant or
+ *       per-environment via WorkflowDeps / GuardrailConfig. This would
+ *       allow teams to add domain-specific blockers without code changes.
+ */
+export const DEFAULT_FORBIDDEN_PATTERNS = [
+    "delete production",
+    "drop database",
+    "overwrite production",
+    "rm -rf /",
+    "format c:",
+    "wipe all",
+    "destroy data",
+];
+/** Default maximum task count before requiring human approval. */
+export const DEFAULT_MAX_TASK_COUNT = 10;
+/**
+ * Policy guardrail: checks proposed tasks (including nested) against forbidden patterns.
+ * Returns { allowed: false, reason } if any task violates policy.
+ *
+ * @param tasks       – hierarchical task tree
+ * @param options     – override forbidden patterns
+ * @param preFlat     – optional pre-flattened tasks to avoid redundant flattening
+ */
+export function checkGuardrail(tasks, options = {}, preFlat) {
+    const patterns = options.forbiddenPatterns ?? DEFAULT_FORBIDDEN_PATTERNS;
+    const flat = preFlat ?? flattenTasks(tasks);
+    const lower = (s) => s.toLowerCase();
+    for (const task of flat) {
+        const desc = lower(task.description);
+        for (const pattern of patterns) {
+            if (desc.includes(lower(pattern))) {
+                return {
+                    allowed: false,
+                    reason: `Task violates policy: "${pattern}" detected in "${task.description}"`,
+                };
+            }
+        }
+    }
+    return { allowed: true };
+}
+/**
+ * Determines if a plan requires human approval (e.g. many tasks, high-risk).
+ * Counts all tasks in the hierarchy.
+ *
+ * @param tasks       – hierarchical task tree
+ * @param options     – override max task count
+ * @param preFlat     – optional pre-flattened tasks to avoid redundant flattening
+ */
+export function requiresHumanApproval(tasks, options = {}, preFlat) {
+    const max = options.maxTaskCount ?? DEFAULT_MAX_TASK_COUNT;
+    const flat = preFlat ?? flattenTasks(tasks);
+    if (flat.length > max)
+        return true;
+    // Any task with critical or high risk level triggers human approval
+    return flat.some((t) => t.riskLevel === "critical" || t.riskLevel === "high");
+}
+/**
+ * Evaluate both policy guardrails and human-approval requirements in a single
+ * pass over the flattened task tree.
+ */
+export function evaluateGuardrails(tasks, guardOpts = {}, approvalOpts = {}) {
+    const flat = flattenTasks(tasks);
+    const check = checkGuardrail(tasks, guardOpts, flat);
+    const needsHumanApproval = check.allowed
+        ? requiresHumanApproval(tasks, approvalOpts, flat)
+        : false;
+    return { check, needsHumanApproval, flatCount: flat.length };
+}
+//# sourceMappingURL=guardrails.js.map

package/dist/app/governance/guardrails.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardrails.js","sourceRoot":"","sources":["../../../src/app/governance/guardrails.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAsB;IAC3D,mBAAmB;IACnB,eAAe;IACf,sBAAsB;IACtB,UAAU;IACV,WAAW;IACX,UAAU;IACV,cAAc;CACf,CAAC;AAEF,kEAAkE;AAClE,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAYzC;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAa,EACb,UAA4B,EAAE,EAC9B,OAAgB;IAEhB,MAAM,QAAQ,GAAG,OAAO,CAAC,iBAAiB,IAAI,0BAA0B,CAAC;IACzE,MAAM,IAAI,GAAG,OAAO,IAAI,YAAY,CAAC,KAAK,CAAC,CAAC;IAC5C,MAAM,KAAK,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IAC7C,KAAK,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACrC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;gBAClC,OAAO;oBACL,OAAO,EAAE,KAAK;oBACd,MAAM,EAAE,0BAA0B,OAAO,kBAAkB,IAAI,CAAC,WAAW,GAAG;iBAC/E,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAa,EACb,UAAgC,EAAE,EAClC,OAAgB;IAEhB,MAAM,GAAG,GAAG,OAAO,CAAC,YAAY,IAAI,sBAAsB,CAAC;IAC3D,MAAM,IAAI,GAAG,OAAO,IAAI,YAAY,CAAC,KAAK,CAAC,CAAC;IAC5C,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG;QAAE,OAAO,IAAI,CAAC;IACnC,oEAAoE;IACpE,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,UAAU,IAAI,CAAC,CAAC,SAAS,KAAK,MAAM,CAAC,CAAC;AAChF,CAAC;AASD;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAa,EACb,YAA8B,EAAE,EAChC,eAAqC,EAAE;IAEvC,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACjC,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;IACrD,MAAM,kBAAkB,GAAG,KAAK,CAAC,OAAO;QACtC,CAAC,CAAC,qBAAqB,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,CAAC;QAClD,CAAC,CAAC,KAAK,CAAC;IACV,OAAO,EAAE,KAAK,EAAE,kBAAkB,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;AAC/D,CAAC"}