akm-cli 0.9.0-rc.0 → 0.9.0-rc.2

package/schemas/akm-task.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://itlackey.github.io/akm/schemas/akm-task.json",
+  "title": "AKM Scheduled Task",
+  "description": "Strict version-2 YAML task definition. Exactly one target is required.",
+  "type": "object",
+  "required": ["version", "schedule"],
+  "additionalProperties": false,
+  "properties": {
+    "version": { "const": 2 },
+    "name": { "type": "string" },
+    "description": { "type": "string" },
+    "when_to_use": { "type": "string" },
+    "tags": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "schedule": { "type": "string", "minLength": 1 },
+    "enabled": { "type": "boolean" },
+    "workflow": { "type": "string", "minLength": 1 },
+    "prompt": { "type": "string", "minLength": 1 },
+    "command": {
+      "oneOf": [
+        { "type": "string", "minLength": 1 },
+        { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }
+      ]
+    },
+    "params": { "type": "object" },
+    "engine": { "type": "string", "minLength": 1 },
+    "model": { "type": "string", "minLength": 1 },
+    "timeoutMs": { "type": ["integer", "null"], "minimum": 1 },
+    "llm": { "$ref": "#/definitions/llm" }
+  },
+  "oneOf": [
+    {
+      "required": ["workflow"],
+      "not": { "anyOf": [{ "required": ["prompt"] }, { "required": ["command"] }, { "required": ["engine"] }, { "required": ["model"] }, { "required": ["timeoutMs"] }, { "required": ["llm"] }] }
+    },
+    {
+      "required": ["prompt"],
+      "not": { "anyOf": [{ "required": ["workflow"] }, { "required": ["command"] }, { "required": ["params"] }] }
+    },
+    {
+      "required": ["command"],
+      "not": { "anyOf": [{ "required": ["workflow"] }, { "required": ["prompt"] }, { "required": ["params"] }, { "required": ["engine"] }, { "required": ["model"] }, { "required": ["llm"] }] }
+    }
+  ],
+  "definitions": {
+    "llm": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "temperature": { "type": "number" },
+        "maxTokens": { "type": "integer", "minimum": 1 },
+        "supportsJsonSchema": { "type": "boolean" },
+        "extraParams": { "$ref": "#/definitions/extraParams" },
+        "contextLength": { "type": "integer", "minimum": 1 },
+        "enableThinking": { "type": "boolean" }
+      }
+    },
+    "extraParams": {
+      "type": "object",
+      "description": "Provider-specific request fields. Top-level AKM-owned fields are forbidden; credential-shaped keys are forbidden recursively after lowercase/non-alphanumeric normalization.",
+      "propertyNames": {
+        "not": {
+          "enum": ["model", "messages", "temperature", "maxtokens", "responseformat", "stream", "streamoptions", "enablethinking", "authorization", "headers", "apikey", "token", "password", "secret", "cookie", "setcookie"]
+        }
+      },
+      "additionalProperties": { "$ref": "#/definitions/extraParamValue" },
+      "x-akm-protectedTopLevelNormalizedKeys": ["model", "messages", "temperature", "maxtokens", "responseformat", "stream", "streamoptions", "enablethinking"],
+      "x-akm-recursivelyForbiddenNormalizedKeys": ["authorization", "headers", "apikey", "token", "password", "secret", "cookie", "setcookie"]
+    },
+    "extraParamValue": {
+      "anyOf": [
+        { "type": ["string", "number", "boolean", "null"] },
+        { "type": "array", "items": { "$ref": "#/definitions/extraParamValue" } },
+        {
+          "type": "object",
+          "propertyNames": {
+            "not": {
+              "enum": ["authorization", "headers", "apikey", "token", "password", "secret", "cookie", "setcookie"]
+            }
+          },
+          "additionalProperties": { "$ref": "#/definitions/extraParamValue" },
+          "x-akm-recursivelyForbiddenNormalizedKeys": ["authorization", "headers", "apikey", "token", "password", "secret", "cookie", "setcookie"]
+        }
+      ]
+    }
+  }
+}

package/schemas/akm-workflow.json

@@ -0,0 +1,372 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://itlackey.github.io/akm/schemas/akm-workflow.json",
+  "title": "AKM Workflow Program",
+  "description": "YAML workflow program for the akm CLI (Agent Knowledge Management). Files live under workflows/ with extension .yaml or .yml. Hand-authored alongside src/workflows/program/schema.ts; the enum vocabularies and patterns here are pinned against the TypeScript constants by tests/workflows/program-parser.test.ts — update both together.",
+  "type": "object",
+  "required": ["version", "name", "steps"],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "const": 2,
+      "description": "Workflow program format version. Only 2 is valid."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Workflow name."
+    },
+    "description": {
+      "type": "string",
+      "description": "Optional human-readable description."
+    },
+    "params": {
+      "type": "object",
+      "maxProperties": 128,
+      "description": "Run parameters: param name -> JSON Schema declaration. Names must be ${{ params.<name> }}-addressable identifiers.",
+      "propertyNames": {
+        "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+      },
+      "additionalProperties": {
+        "$ref": "#/definitions/jsonSchemaObject"
+      }
+    },
+    "defaults": {
+      "$ref": "#/definitions/defaults"
+    },
+    "budget": {
+      "$ref": "#/definitions/budget"
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 256,
+      "items": {
+        "$ref": "#/definitions/step"
+      }
+    }
+  },
+  "definitions": {
+    "identifier": {
+      "type": "string",
+      "pattern": "^[A-Za-z_][A-Za-z0-9_-]*$",
+      "description": "Step id: a letter or underscore first, then letters, digits, underscores, or dashes (no dots, no leading digit). This is exactly the ${{ steps.<id>.output }}-addressable grammar; dots are reserved for the .output path separator and the engine's internal <stepId>.gate node id."
+    },
+    "timeout": {
+      "description": "Duration: \"<n>ms\" | \"<n>s\" | \"<n>m\" | \"none\" (bare integers are milliseconds).",
+      "oneOf": [
+        {
+          "type": "string",
+          "pattern": "^([0-9]+(ms|s|m)?|none)$"
+        },
+        {
+          "type": "integer",
+          "minimum": 1
+        }
+      ]
+    },
+    "onError": {
+      "description": "Failure policy: fail the step on the first unit failure (default), or record failures and let the gate decide.",
+      "enum": ["fail", "continue"]
+    },
+    "llm": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "temperature": { "type": "number" },
+        "max_tokens": { "type": "integer", "minimum": 1 },
+        "supports_json_schema": { "type": "boolean" },
+        "extra_params": { "$ref": "#/definitions/extraParams" },
+        "context_length": { "type": "integer", "minimum": 1 },
+        "enable_thinking": { "type": "boolean" }
+      }
+    },
+    "extraParams": {
+      "type": "object",
+      "description": "Provider-specific request fields. Top-level AKM-owned fields are forbidden; credential-shaped keys are forbidden recursively after lowercase/non-alphanumeric normalization.",
+      "propertyNames": {
+        "not": {
+          "enum": ["model", "messages", "temperature", "maxtokens", "responseformat", "stream", "streamoptions", "enablethinking", "authorization", "headers", "apikey", "token", "password", "secret", "cookie", "setcookie"]
+        }
+      },
+      "additionalProperties": { "$ref": "#/definitions/extraParamValue" },
+      "x-akm-protectedTopLevelNormalizedKeys": ["model", "messages", "temperature", "maxtokens", "responseformat", "stream", "streamoptions", "enablethinking"],
+      "x-akm-recursivelyForbiddenNormalizedKeys": ["authorization", "headers", "apikey", "token", "password", "secret", "cookie", "setcookie"]
+    },
+    "extraParamValue": {
+      "anyOf": [
+        { "type": ["string", "number", "boolean", "null"] },
+        { "type": "array", "items": { "$ref": "#/definitions/extraParamValue" } },
+        {
+          "type": "object",
+          "propertyNames": {
+            "not": {
+              "enum": ["authorization", "headers", "apikey", "token", "password", "secret", "cookie", "setcookie"]
+            }
+          },
+          "additionalProperties": { "$ref": "#/definitions/extraParamValue" },
+          "x-akm-recursivelyForbiddenNormalizedKeys": ["authorization", "headers", "apikey", "token", "password", "secret", "cookie", "setcookie"]
+        }
+      ]
+    },
+    "reducer": {
+      "description": "How a map step folds per-item unit results into the step artifact.",
+      "enum": ["collect", "vote"]
+    },
+    "isolation": {
+      "description": "Filesystem isolation for file-mutating units (enforcement lands in R2).",
+      "enum": ["none", "worktree"]
+    },
+    "failureReason": {
+      "description": "Persisted AgentFailureReason taxonomy (src/integrations/agent/spawn.ts).",
+      "enum": [
+        "timeout",
+        "spawn_failed",
+        "non_zero_exit",
+        "parse_error",
+        "cooldown",
+        "llm_rate_limit",
+        "llm_content_filter",
+        "llm_invalid_json",
+        "content_policy_reject",
+        "unsupported_type",
+        "no_change",
+        "aborted"
+      ]
+    },
+    "jsonSchemaObject": {
+      "type": "object",
+      "description": "A JSON Schema declaration (validated as a schema by the compiler, not here)."
+    },
+    "retry": {
+      "type": "object",
+      "description": "Bounded retry on transient failures, keyed on the persisted failure_reason taxonomy.",
+      "required": ["max", "on"],
+      "additionalProperties": false,
+      "properties": {
+        "max": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Maximum retry attempts per unit."
+        },
+        "on": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/definitions/failureReason"
+          }
+        }
+      }
+    },
+    "budget": {
+      "type": "object",
+      "description": "Run-level budget ceilings, enforced by the engine per run (journal-seeded). Hitting a ceiling fails the step hard, regardless of on_error.",
+      "additionalProperties": false,
+      "properties": {
+        "max_tokens": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Ceiling on total reported token usage across the run (seeded from journaled unit rows)."
+        },
+        "max_units": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10000,
+          "description": "Ceiling on total dispatched units across the run (seeded from journaled unit rows)."
+        }
+      }
+    },
+    "defaults": {
+      "type": "object",
+      "description": "Run-level defaults, overridable per unit.",
+      "additionalProperties": false,
+      "properties": {
+        "engine": {
+          "type": "string",
+          "minLength": 1
+        },
+        "model": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Model alias (tier) or exact id; resolved per-harness at dispatch."
+        },
+        "timeout": {
+          "$ref": "#/definitions/timeout"
+        },
+        "on_error": {
+          "$ref": "#/definitions/onError"
+        },
+        "llm": {
+          "$ref": "#/definitions/llm"
+        }
+      }
+    },
+    "unit": {
+      "type": "object",
+      "description": "A single dispatchable unit: instructions plus dispatch overrides.",
+      "required": ["instructions"],
+      "additionalProperties": false,
+      "properties": {
+        "engine": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Named engine selected at workflow start."
+        },
+        "model": {
+          "type": "string",
+          "minLength": 1
+        },
+        "llm": {
+          "$ref": "#/definitions/llm"
+        },
+        "timeout": {
+          "$ref": "#/definitions/timeout"
+        },
+        "retry": {
+          "$ref": "#/definitions/retry"
+        },
+        "on_error": {
+          "$ref": "#/definitions/onError"
+        },
+        "instructions": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Instruction template. ${{ … }} expressions are parsed against the closed grammar: params.<name> | steps.<id>.output.<path> | item | item_index."
+        },
+        "output": {
+          "$ref": "#/definitions/jsonSchemaObject"
+        },
+        "env": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Env asset refs injected into the dispatched unit env."
+        },
+        "isolation": {
+          "$ref": "#/definitions/isolation"
+        }
+      }
+    },
+    "map": {
+      "type": "object",
+      "description": "Fan the unit template out over an expression-addressed item list.",
+      "required": ["over", "unit"],
+      "additionalProperties": false,
+      "properties": {
+        "over": {
+          "type": "string",
+          "minLength": 1,
+          "description": "${{ … }} expression naming the producer of the item list (e.g. ${{ steps.discover.output.files }})."
+        },
+        "concurrency": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Max concurrent units for this step; capped by the engine's global limit."
+        },
+        "reducer": {
+          "$ref": "#/definitions/reducer"
+        },
+        "unit": {
+          "$ref": "#/definitions/unit"
+        }
+      }
+    },
+    "route": {
+      "type": "object",
+      "description": "Route on an explicit ${{ … }} input to a LATER step. Targets must come after the routing step.",
+      "required": ["input", "when"],
+      "additionalProperties": false,
+      "properties": {
+        "input": {
+          "type": "string",
+          "minLength": 1,
+          "description": "${{ … }} expression naming the value to route on."
+        },
+        "when": {
+          "type": "object",
+          "minProperties": 1,
+          "maxProperties": 256,
+          "description": "Match value -> target step id.",
+          "additionalProperties": {
+            "$ref": "#/definitions/identifier"
+          }
+        },
+        "default": {
+          "$ref": "#/definitions/identifier"
+        }
+      }
+    },
+    "gate": {
+      "type": "object",
+      "description": "Completion gate criteria judged against the step artifact.",
+      "required": ["criteria"],
+      "additionalProperties": false,
+      "properties": {
+        "criteria": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "max_loops": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Evaluator-optimizer loop bound (execution lands in R2)."
+        },
+        "required": {
+          "type": "boolean",
+          "description": "When true, the gate must be judged: if no summary-validation judge is available (offline / misconfigured LLM), the step BLOCKS for a human instead of failing open and silently passing. Absent = fail-open default. The engine's --require-gates flag applies this to every criteria-bearing gate for one invocation."
+        }
+      }
+    },
+    "step": {
+      "type": "object",
+      "description": "One step of the gated spine. Exactly one of unit | map | route.",
+      "required": ["id"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "$ref": "#/definitions/identifier"
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "unit": {
+          "$ref": "#/definitions/unit"
+        },
+        "map": {
+          "$ref": "#/definitions/map"
+        },
+        "route": {
+          "$ref": "#/definitions/route"
+        },
+        "output": {
+          "$ref": "#/definitions/jsonSchemaObject"
+        },
+        "gate": {
+          "$ref": "#/definitions/gate"
+        }
+      },
+      "allOf": [
+        {
+          "oneOf": [
+            {
+              "required": ["unit"]
+            },
+            {
+              "required": ["map"]
+            },
+            {
+              "required": ["route"]
+            }
+          ]
+        }
+      ]
+    }
+  }
+}

package/dist/commands/improve/improve-profiles.js

@@ -1,168 +0,0 @@
-// This Source Code Form is subject to the terms of the Mozilla Public
-// License, v. 2.0. If a copy of the MPL was not distributed with this
-// file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import profileCatchup from "../../assets/profiles/catchup.json" with { type: "json" };
-import profileConsolidate from "../../assets/profiles/consolidate.json" with { type: "json" };
-import profileDefault from "../../assets/profiles/default.json" with { type: "json" };
-import profileFrequent from "../../assets/profiles/frequent.json" with { type: "json" };
-import profileGraphRefresh from "../../assets/profiles/graph-refresh.json" with { type: "json" };
-import profileMemoryFocus from "../../assets/profiles/memory-focus.json" with { type: "json" };
-import profileProactiveMaintenance from "../../assets/profiles/proactive-maintenance.json" with { type: "json" };
-import profileQuick from "../../assets/profiles/quick.json" with { type: "json" };
-import profileRecombineOnly from "../../assets/profiles/recombine-only.json" with { type: "json" };
-import profileReflectDistill from "../../assets/profiles/reflect-distill.json" with { type: "json" };
-import profileSynthesize from "../../assets/profiles/synthesize.json" with { type: "json" };
-import profileThorough from "../../assets/profiles/thorough.json" with { type: "json" };
-import { parseAssetRef } from "../../core/asset/asset-ref.js";
-import { ConfigError } from "../../core/errors.js";
-/** Profile name used as the final fallback when nothing else resolves. */
-const FALLBACK_PROFILE_NAME = "default";
-// Built-in default allowed types per process
-export const DEFAULT_ALLOWED_TYPES = {
-    reflect: ["agent", "command", "knowledge", "lesson", "memory", "skill", "wiki", "workflow"],
-    distill: ["memory"],
-    consolidate: ["memory"],
-};
-// Built-in profiles are loaded from embedded JSON files in src/assets/profiles/.
-// To add a new profile: create a new .json file there, import it above, and add
-// it to this map. No code change needed beyond those two steps.
-const BUILTIN_PROFILES = {
-    default: profileDefault,
-    quick: profileQuick,
-    thorough: profileThorough,
-    "memory-focus": profileMemoryFocus,
-    "graph-refresh": profileGraphRefresh,
-    frequent: profileFrequent,
-    consolidate: profileConsolidate,
-    catchup: profileCatchup,
-    synthesize: profileSynthesize,
-    "reflect-distill": profileReflectDistill,
-    "proactive-maintenance": profileProactiveMaintenance,
-    "recombine-only": profileRecombineOnly,
-};
-/**
- * Default enabled-state for known improve processes when neither the user
- * profile nor the built-in default profile specifies an override.
- *
- * These mirror the legacy `LlmFeatureFlags` defaults so callers that bypass
- * the profile system (rare — most run through `resolveImproveProfile`) get
- * the same answer.
- */
-const IMPROVE_PROCESS_DEFAULTS = {
-    reflect: true,
-    distill: true,
-    consolidate: true,
-    memoryInference: true,
-    graphExtraction: true,
-    validation: false,
-    // session-extraction reads native session files from claude-code / opencode
-    // and queues durable-insight proposals. Default on — opt out via
-    // profiles.improve.default.processes.extract.enabled: false.
-    extract: true,
-    // proposal-queue triage drains the standing backlog. Opt-in (default off),
-    // like `validation` — needs an explicit `enabled: true`.
-    triage: false,
-    // Layer 2 proactive-maintenance selector. Opt-in (default off) — surfaces
-    // stale high-value assets on a schedule. Enable per-profile with an explicit
-    // `processes.proactiveMaintenance.enabled: true`.
-    proactiveMaintenance: false,
-    // #609 recombine / synthesize pass — whole-corpus cross-episodic
-    // generalization. Opt-in (default off); enable per-profile with an explicit
-    // `processes.recombine.enabled: true`.
-    recombine: false,
-    // #615 procedural-compilation pass — detects recurring successful ordered
-    // action sequences and compiles them into workflow proposals. Opt-in (default
-    // off); enable per-profile with an explicit `processes.procedural.enabled: true`.
-    procedural: false,
-};
-/**
- * Compute the effective enabled-state for a named improve process.
- *
- * Resolution order: explicit `profile.processes.<name>.enabled` (boolean) →
- * the built-in {@link IMPROVE_PROCESS_DEFAULTS} fallback → `false`.
- */
-export function resolveProcessEnabled(processName, profile) {
-    const processes = profile.processes;
-    const entry = processes?.[processName];
-    if (entry && typeof entry.enabled === "boolean")
-        return entry.enabled;
-    return IMPROVE_PROCESS_DEFAULTS[processName] ?? false;
-}
-function deepMerge(base, override) {
-    if (typeof base !== "object" || base === null)
-        return override ?? base;
-    const result = { ...base };
-    for (const key of Object.keys(override)) {
-        const ov = override[key];
-        // Treat `null` the same as `undefined` so user overrides never wipe a
-        // built-in field with `null`. The on-disk parser already strips nulls,
-        // but the programmatic API exposes this path and callers occasionally
-        // pass JSON-shaped objects with explicit nulls.
-        if (ov !== undefined && ov !== null) {
-            const bv = base[key];
-            if (typeof bv === "object" && bv !== null && typeof ov === "object" && ov !== null && !Array.isArray(bv)) {
-                result[key] = deepMerge(bv, ov);
-            }
-            else {
-                result[key] = ov;
-            }
-        }
-    }
-    return result;
-}
-export function resolveImproveProfile(name, config) {
-    const requestedName = name ??
-        (typeof config.defaults?.improve === "string" ? config.defaults.improve : undefined) ??
-        FALLBACK_PROFILE_NAME;
-    const hasBuiltin = requestedName in BUILTIN_PROFILES;
-    const hasUserDefined = !!config.profiles?.improve?.[requestedName];
-    // An unknown profile name is a HARD error. Silently falling back to the
-    // default (proactive-off) profile is the −96% incident class: a cron pinned
-    // to `--profile reflect-distill` ran the default for weeks because the name
-    // only existed in one host's config and the resolver swallowed the miss.
-    if (!hasBuiltin && !hasUserDefined) {
-        const valid = [
-            ...new Set([...Object.keys(BUILTIN_PROFILES), ...Object.keys(config.profiles?.improve ?? {})]),
-        ].sort();
-        throw new ConfigError(`Improve profile "${requestedName}" not found. Valid profiles: ${valid.join(", ")}.`, "UNKNOWN_IMPROVE_PROFILE");
-    }
-    const builtin = BUILTIN_PROFILES[requestedName] ?? BUILTIN_PROFILES[FALLBACK_PROFILE_NAME];
-    const userOverride = config.profiles?.improve?.[requestedName] ?? {};
-    return deepMerge(builtin, userOverride);
-}
-export function shouldSkipRef(ref, processName, profile) {
-    const cfg = profile.processes?.[processName];
-    // Check if the process itself is disabled
-    if (cfg?.enabled === false)
-        return { skip: true, reason: "process-disabled" };
-    const parsed = parseAssetRef(ref);
-    const allowed = cfg?.allowedTypes ?? DEFAULT_ALLOWED_TYPES[processName];
-    if (!allowed.includes(parsed.type))
-        return { skip: true, reason: "type-filter" };
-    // Hardcoded: wiki raw directories are never processed by any improve process.
-    if (parsed.type === "wiki" && parsed.name.split("/")[1] === "raw") {
-        return { skip: true, reason: "raw-wiki" };
-    }
-    return { skip: false, reason: "" };
-}
-/**
- * Planner-level pre-filter: return `true` when every per-ref improve pass that
- * participates in the in-loop dispatch (today: `reflect` and `distill`) would
- * refuse this ref under the active profile. Such refs cannot produce any work
- * downstream — they only generate synthetic skip actions and inflate
- * `plannedRefs` by a constant factor per cron run.
- *
- * Companion to `shouldSkipRef`. The 2026-05-27 planner/profile/metrics deep
- * analysis (`/tmp/akm-health-investigations/planner-profile-metrics-deep-analysis.md`)
- * documents the 99.07% synthetic-skip emission rate this pre-filter eliminates.
- *
- * NOTE: passes that operate on their own candidate set (consolidate,
- * memoryInference, graphExtraction) are deliberately excluded — they do not
- * iterate `plannedRefs` per-ref, so a ref being profile-incompatible at the
- * reflect+distill layer says nothing about their work.
- */
-export function isProfileFilteredForAllPasses(ref, profile) {
-    const reflectSkip = shouldSkipRef(ref, "reflect", profile);
-    const distillSkip = shouldSkipRef(ref, "distill", profile);
-    return reflectSkip.skip && distillSkip.skip;
-}