CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

10.0.0 (2026-04-21)

• chore(release)!: mark memory contract cutover as breaking (4912e0b)

BREAKING CHANGES

• Memory tools and docs now enforce the new memory contract semantics (taxonomy, checkpoint/version flow, error envelope behavior, and project onboarding/sync metadata). Legacy wording and legacy contract assumptions are no longer supported.

9.14.0 (2026-04-21)

Features

• enhance knowledge propositions with room and namespace support (c769b8c)
• knowledge: add entity/relation backbone and graph traversal APIs (85686cc)
• knowledge: add temporal validity windows and as-of filtering (fbad611)
• memory: finalize production memory workflows and onboarding guidance (936b304)
• tests: add comprehensive tests for memory service operations (b4e774b)

9.13.0 (2026-03-21)

Bug Fixes

• knowledge: _build_where_clause must read inputs.categories for recall/forget (35a2049)
• knowledge: _op_store must not mutate source.category_ids or propagate re-categorization (bf89de8)
• knowledge: auto-maintain updated_at via trigger on all knowledge tables (6f5ec66)
• knowledge: wrap HNSW index creation in exception handler for pgvector compat (5f153b0)
• remove relevance_score (8e7eea8)
• workflows-mcp: fix MMR diversity reranking silently doing nothing (161d64f)
• workflows-mcp: source_type default NULL, migration v7 clears stale heuristic values (43cfbf1)
• workflows-mcp: source_type reflects ingestion mechanism, not source/path presence (8bf5b31)

Features

• knowledge: audit trail, user attribution, and lifecycle filter fixes (7440a6a)
• knowledge: expose authority and lifecycle_state in store operations (503b25b)
• knowledge: introduce junction table for per-proposition category classification (ce120c7)
• knowledge: store user_identifier in proposition metadata (795ae38)
• workflows-mcp: add filter-based archiving to forget_knowledge MCP tool (4d5b760), closes #8
• workflows-mcp: add validate_knowledge tool for USER_VALIDATED authority promotion (7a49dd2)
• workflows-mcp: add validate/invalidate_knowledge tools with enum .value bugfix (9ccf0ce)
• workflows-mcp: default diversity=True for knowledge_context (ea2e8e8)
• workflows-mcp: introduce knowledge_categories table (migration 10) (2dd6290)

Performance Improvements

• knowledge: add HNSW index on knowledge_propositions.embedding (migration v5) (a9eb5e0)

9.12.2 (2026-03-19)

Bug Fixes

• knowledge: remove updated_at from forget UPDATE and recall order allowlist (a10c712)
• knowledge: use distinct alias for item_path LEFT JOIN to avoid collision with filter JOINs (0656ac1)

9.12.1 (2026-03-19)

Bug Fixes

• knowledge: fix metadata column name, add path field, surface item_path in results (bed9a46)

9.12.0 (2026-03-13)

Features

• engine: add node_id tracking and generic operation failure detection (5a75877)
• engine: emit depends_on in block transition events (20a70d6)

9.11.0 (2026-03-10)

Features

• engine: add context_id to ExecutionContext and on_block_transition events (af597a2)

9.10.1 (2026-03-09)

Bug Fixes

• engine: sanitize YAML date values in frontmatter to ISO strings (5d829dd)

9.10.0 (2026-03-09)

Features

• engine: add batch embedding support to Embedding block (801412a)

9.9.0 (2026-03-07)

Features

• improve markdown section parsing by ignoring code blocks and add frontmatter, reference, and code block extraction capabilities. (df838a3)

9.8.1 (2026-03-06)

Bug Fixes

• knowledge: wire category_ids into store + add name resolution (b5e205c)

9.8.0 (2026-03-06)

Features

• ReadFiles: add structured sections and line-range to ReadFiles executor (09660e0)

9.7.0 (2026-03-05)

Features

• knowledge: implement MCP Tools for Knowledge (6b10a0f)

9.6.0 (2026-03-05)

Features

• complete recall and forget operations for Knowledge executor (604be76)

9.5.0 (2026-03-04)

Features

• engine: add Knowledge executor for workflow-native knowledge access (0bd8ef8)

9.4.0 (2026-03-01)

Bug Fixes

• enable iterations for for_each (0082e3e)

Features

• Add new test scripts for workflow execution analysis and unified variable resolution. (8a7563e)
• engine: emit on_block_transition events for for_each blocks (1fe7bc7)
• engine: enrich block transition events with inputs and parent references (8370f0e)

9.3.0 (2026-02-24)

Bug Fixes

• workflows-mcp: extract only declared outputs for Workflow block events (dc4caef)
• workflows-mcp: migrate Ollama executor to /api/chat with reliable structured output (3fcb941)

Features

• engine: add generic extra_headers support for LLM providers (bf3e6a5)

9.2.0 (2026-02-19)

Features

• engine: add knowledge context prefetch schema and memory namespace (658469e)

9.1.0 (2026-02-19)

Features

• workflows-mcp: add get_all() to ExecutionMemory and flush_memory_on_complete to WorkflowSchema (d3ee9a1)

9.0.0 (2026-02-19)

• feat(engine)!: add strict output type parsing and coercion for dict and list (6de95ef)

Bug Fixes

• cortex: update default threshold and key name in categorize phase (9884a06)
• engine: use safe composition model. (90dd7cc)
• pr-review: resolve Jinja2 condition and template issues (0935a90)
• pr-review: resolve Jinja2 condition and template issues (93fa320)
• workflows_mcp.engine.executors_file: allow base_path to be None and default to current directory (da9db50)
• workflows_mcp: remove unnecessary tojson filter in yaml template (a80d838)

Features

• add embedding executor and safe accessor (9b04dce)
• add reload_workflows tool (8d9a2df)
• add test for git-pr-setup short GitHub and GitLab URLs and improve job queue test stability by using a slower workflow. (9a533f7)
• add timeout configuration to investigation and pr-review workflows (299ad91)
• agents/cortex: aggregate and expose total token usage across all LLM calls (c5f5c51)
• agents/cortex: enhance cortex agent with surprisal and g-score integration (2513ddd)
• agents: add agent-pr-review with hierarchical state tracking (e84950d)
• agents: add iteration and memory management workflows (a07ff12)
• agents: implement CORTEX cognitive architecture (1b2b582)
• cortex, state-management, resolver: add dict combine method and enhance cortex capabilities and state management (373ef73)
• cortex: add EVALUATE/REFINE loop to gather phase and renumber ACT (f3ba393)
• cortex: add llm call tracking and refactor phase task registration (fab9b7e)
• cortex: add ripgrep search with fallback to grep in gather-search capability (b5a4f77)
• cortex: optimize output by querying child syntheses from task tree (b89c667)
• cortex: restructure agent phases and add atomic capabilities (c861c20)
• cortex: revamp cognitive phases to v2 architecture (5e59e8c)
• engine/sql: add sql executor with multi-backend support and connection pooling (f314519)
• engine: allow operations and inputs fields to accept JSON strings (6668ad8)
• engine: enhance error handling and json parsing in execution and resolution (c640d73)
• enhance read_files block to accept patterns as a JSON string or array, with updated schema, documentation, and new tests, and add .DS_Store to gitignore. (236c32f)
• git: add GitHub App authentication and post-review workflows (89527c6)
• git: add workflow template to parse and checkout git PR/MR repositories (f644b96)
• pr-review: add task hierarchy visualization (7613538)
• pr-review: implement memory storage and retrieval in PR review workflows (a532f81)
• sql: add model-based CRUD support with Active Record-style API (de02905)
• state-management: add aggregate status helper outputs (096904a)
• state-management: add depth attribute to tasks for hierarchical state management (cc6d0a2)
• state-management: add state management workflow with audit trail (16cb8ee)
• state-visualize: add agent-state-visualize workflow (be817dc)
• Update workflow execution functions and tests to return and handle CallToolResult objects, and simplify version script string manipulation. (7039f87)
• workflows-mcp: add ephemeral execution memory (SQLite) (3b56617)
• workflows: Cleanup workflows and fix engine issues (#37) (37db9e9)

BREAKING CHANGES

• The 'json' output type is deprecated and replaced by explicit 'dict' and 'list' types that enforce JSON parsing and type validation. Users must update output types in workflows and tests from 'json' to 'dict' or 'list' accordingly to avoid errors.

Replace legacy 'json' output type with explicit 'dict' and 'list' types that enforce JSON parsing with type validation. Modify output coercion to serialize dicts/lists as JSON strings for shell inputs. Update workflow runner to correctly extract block outputs. Adjust test workflows and snapshots to use 'dict' instead of 'json' for output types. This improves type safety and clarity in output handling.

8.1.0 (2026-02-19)

Features

• workflows-mcp: add ephemeral execution memory (SQLite) (42925f3)

8.0.0 (2025-12-09)

• feat(resolver)!: handle missing secrets gracefully and add git-checkout template (b8d0279)
• refactor(git-commit)!: restructure git commit workflow with llm prompt files (553229a)

Bug Fixes

• ci: fix schema validation error for commit output (a851403)
• engine: preserve for_each pause metadata and resume iterations (2014ebf)
• engine: serialize nested execution state in pause_metadata (3154cb9)
• git-auth: use jinja for URL pattern matching in resolve_url (38361e6)
• git-auth: use POSIX-compatible shell syntax for credential discovery (8aed833)
• git-checkout: add clone success condition to get_commit_sha/get_branch (75db338)
• git-checkout: create branch when ref doesn't exist (e6b8fc7)
• git-commit: add missing dependency from analyze_changes to stage_files (8da6d5e)
• git: correct has_changes detection and dependency handling (32fe808)
• test-git-checkout: make summary dependencies optional (203f126)
• tools: Add consistent resume instructions to paused workflow messages (0ee7766)
• transform-design: fix YAML serialization of nested lists in blocks (300b0be)
• workflow-creator: prevent infinite recursion on empty LLM responses (e4d07a0)
• workflow-creator: resolve nested template issue in read_file calls (9b9fd99)
• workflows: allow 'tmp' in for_each and expose metadata.depth for templates (901d142)

Features

• agents: add layer4 code-assistant-agent template (72bbbb9), closes hi#level
• auth: introduce git-auth template and enhance git-checkout (d9cebcc)
• engine: add executor examples and make LLM schema OpenAI-compatible (954f26b)
• engine: generate llm-compatible schema and support literal for_each (fde69a8)
• git: update git-checkout workflow (1996cfc)
• inputs: support {{tmp}} resolution in input defaults (ff51efe)
• llm: add generated llm block reference, generator, and CI verification (9c7b40b)
• workflow-creator: add complexity analysis, decomposition, and validation improvements (4ad1f8a)
• workflow-creator: add continue_on_error option to yaml configs (7d0469d)
• workflow-creator: add support for tags in workflow creation (d9d9da3)
• workflow-creator: improve workflow display with dynamic titles and explanations (0e65e5a)
• workflow-creator: update workflow-creator templates and bootstrap, add workspace input (ed66fc3)
• workflow: add workflow-creator agent templates and imagegen schema (d3c8242)
• workflows_mcp: add three-level nested workflow handling with pause/resume support (be0d4ca)
• workflows: improve nested workflow pause/resume handling (cdc973b)

BREAKING CHANGES

• renamed input 'working_dir' to 'workspace', 'auto_commit' to 'auto', and 'commit_message' to 'message'; requires updating workflow configurations

split commit generation into system and user prompts, update input names (workspace, auto, message), improve documentation clarity

• What breaks and why:

• Workflows or callers that previously relied on SecretNotFoundError being raised by the UnifiedVariableResolver will no longer receive that exception; the resolver now substitutes an empty string and logs a warning. This changes error signaling semantics and may allow workflows that previously failed to continue with an empty secret value, potentially leading to downstream behavioural differences or silent misconfiguration.

Migration steps:

1. Audit workflows that depend on missing-secret errors to perform explicit failure handling. Update them to validate secret values where presence is required (for example, test for empty string and explicitly fail if needed).
2. If you need the old behavior (fail on missing secrets), modify your resolver usage to re-check secret_values after resolution and raise or abort when a secret value is empty, or adjust SecretProxy/providers to raise a different exception type for required secrets.
3. Search for code paths that assumed exception-based control flow from secret lookups and update to handle empty-string defaults explicitly.

Alternative approaches:

• Mark secrets as required at workflow/step level so missing secrets are detected earlier and surfaced as configuration errors.

• If you control the secret provider, configure it to return a distinct error type for required-secret failures so callers can still differentiate missing-secret vs. provider errors.

• unified_resolver: when a secret lookup returns SecretNotFoundError, log a warning and default the secret value to an empty string instead of re-raising. Other exceptions from secret providers are still propagated.

• templates: add a new comprehensive git-checkout workflow template (src/workflows_mcp/templates/git/git-checkout.yaml).

• tools: clarify the resume_workflow message to include the response parameter example.

These changes make workflows more resilient to optional/missing secrets and add a reusable git checkout template.

7.1.0 (2025-11-18)

Features

• ReadFiles: simplify content output for single file reads (25aa538)
• ReadFiles: simplify content output for single file reads (#33) (7430945)

7.0.0 (2025-11-17)

• feat(engine)!: introduce workflow-scoped tmp path and migrate templates (4422538)

Bug Fixes

• git-commit: replace escape sequence handling in commit message template (9b57b1a)
• tests: replace bash-specific substring syntax with POSIX-compatible printf (edd966c)

Code Refactoring

• remove render template executor and related functionality (3f7cd09)

Features

• engine: add comprehensive interpolation support for EditFile operations (a29f325)
• engine: implement unified variable resolver with rule-based transformation pipeline (befea5f)
• file operations: add readfiles support with glob patterns and base path (aad24e7)
• workflows-mcp: Add profile fallback for portable LLM workflows (85df48f)

Performance Improvements

• ci: improve ci pipeline efficiency (67bd33c)

BREAKING CHANGES

• This changes runtime behavior that may break existing workflows:

What breaks and why:

• $SCRATCH usage removed/deprecated: templates and workflows that relied on the literal $SCRATCH path or shell environment substitution will no longer write/read to that path. The code now expects workflow templates to use the jinja variable {{tmp}} which is resolved to the execution scratch dir.
• Absolute path allowance tightened: previously some $SCRATCH-based handling allowed absolute output paths; executors now only permit absolute paths if the path is inside the configured scratch directory or the output schema explicitly sets unsafe=true. Absolute paths outside the scratch directory will be disallowed, which can change behavior for blocks that wrote to arbitrary absolute locations.
• Secrets materialization semantics changed: if secrets were pre-materialized as a plain dict in the jinja context, the resolver now merges existing values with newly fetched secrets instead of treating them the same as a SecretProxy. This can alter how secret values are looked up/overwritten.
• validate.py now recursively scans YAML (*.yaml, *.yml) which may surface additional validation errors for files that were previously ignored.

Migration steps for users:

1. Update all workflows and templates to replace any occurrences of $SCRATCH with {{tmp}} in commands, file paths, and CreateFile/ReadFiles inputs.
2. For scripts that relied on absolute paths previously allowed via $SCRATCH, either:
   • change to use paths under {{tmp}} (recommended), or
   • explicitly mark outputs as unsafe in the output schema (not recommended unless necessary).
3. Ensure any code that injected secrets into the jinja context provides a SecretProxy where possible; if an existing dict is used intentionally, verify merge semantics meet expectations.
4. Re-run validation (validate.py) and tests to catch any additional YAML files that now get scanned.

Alternative approaches if migration is not immediately possible:

• As a stopgap, workflows can set an environment variable SCRATCH inside block inputs to mimic prior behavior, or modify blocks to write to a path referenced by {{tmp}} by injecting the same value into the jinja context. However, migrating to {{tmp}} is the supported path forward.

Add a workflow-scoped jinja variable {{tmp}} (mapped to the execution scratch dir) and migrate templates/tests to use it; tighten Shell executor path handling; improve secret materialization; add a local LLM mock for tests and update snapshots. Key changes:

• expose "tmp" in workflow jinja context (workflow_runner)
• replace $SCRATCH usages in templates and tests with {{tmp}} and update schema examples
• ShellExecutor: treat raw paths as already-resolved values, allow absolute paths only when they reside inside the scratch dir or when output schema marks unsafe
• UnifiedVariableResolver: handle already-materialized secrets (dict) by merging with newly fetched secrets instead of overwriting
• add a local LLM mock and tests for LLM executor; add/update snapshots
• broaden validate.py to scan YAML recursively
• remove/replace several README/template docs and update many test workflows

These changes unify temporary-path handling, improve security around absolute paths, fix secret materialization issues, and make LLM-related tests hermetic.

• removes the RenderTemplate executor and all associated code, including schema validation, template rendering logic, and test workflows that depended on it. this change simplifies the file operation executors by removing the template rendering capability and updates existing workflows to use alternative approaches like Shell commands or CreateFile blocks. the RenderTemplate functionality was replaced with direct shell command execution and content rendering in templates, reducing complexity and removing the dependency on jinja2 templating for these use cases.
• engine: Replace legacy VariableResolver with new architecture that provides:

• Expression classification for optimal Jinja2 routing
• Rule-based transformation pipeline (security, syntax, namespace)
• Enhanced context with BlockProxy and SecretProxy
• SandboxedEnvironment for template rendering security
• Clean separation of concerns between rules and evaluation

Key components:

• UnifiedVariableResolver: Main resolver orchestrating transformation pipeline
• ExpressionClassifier: Routes expressions to appropriate evaluation methods
• TransformRule system: Modular, priority-based transformation rules
• BlockProxy: ADR-007 shortcuts and nested block access
• SecretProxy: Lazy secret loading with audit logging
• Security rules: Forbidden namespace blocking, secret tracking
• Syntax rules: Bracket notation normalization, special character handling

Updates:

• RenderTemplateExecutor uses SandboxedEnvironment instead of Environment
• BlockOrchestrator switches to UnifiedVariableResolver
• Legacy variables.py preserved as variables.py.bak
• Test workflows and snapshots reorganized for new resolver

6.5.0 (2025-11-12)

Features

• engine: add comprehensive interpolation support for EditFile operations (f3b890e)
• engine: add EditFile block for deterministic file editing (029a188)
• engine: add EditFile block for deterministic file editing (#28) (0b64c3a)
• tests: enhance variable resolution test suite with comprehensive validation (bb048f2)

6.4.0 (2025-11-12)

Bug Fixes

• make job queue status filter test resilient to race conditions (de50e10), closes #27

Features

• unified job architecture with async execution and queue support (#27) (bca1d1c)

6.3.0 (2025-11-10)

Features

• for_each: add dynamic key interpolation and fractal execution s… (#24) (3f404e5)
• for_each: add dynamic key interpolation and fractal execution support (a938de6)

6.2.0 (2025-11-08)

Features

• llm: add profile-based configuration system (d7acdb8)
• llm: add profile-based configuration system (#23) (d0a124c)

6.1.1 (2025-11-07)

Bug Fixes

• schema: resolve LLMProvider $ref by moving nested $defs to root level (4b402f7)
• schema: resolve LLMProvider $ref by moving nested $defs to root level (#21) (5f13750)

6.1.0 (2025-11-07)

Features

• engine: add interpolatable field support for dynamic type resolution (652a1ce)
• engine: add interpolatable field support for dynamic type resolution (#20) (c860c44)

6.0.0 (2025-11-06)

• refactor(engine)!: replace _internal dict with strongly-typed ExecutionInternal model (15df1b1)

Features

• ADR-009: add outcome field to distinguish operation failure from executor crash (e3e2d45)
• engine: implement for_each type preservation and empty collection handling (0e2f8ab)

BREAKING CHANGES

• HttpCallInput field names changed. Update workflows to use 'json' instead of 'body_json' and 'content' instead of 'body_text'.
• ADR-009: NodeMeta now includes 'outcome' field

ADR-009 Implementation - Phase 2: Outcome Field

Changes:

• Added 'outcome' field to NodeMeta with values: success, failure, crash, n/a
• Updated all NodeMeta factory methods to set appropriate outcome values
• Modified orchestrator.py to pass outcome="crash" for executor exceptions
• For_each parent aggregates outcome from children (crash > failure > success)
• Fixed resume_workflow status check from .is_failed() to .failed property
• Added model_validator to Execution for checkpoint deserialization

Key Outcomes:

• Operation failure: executor runs, operation fails (e.g., exit 1) - outcome="failure"
• Executor crash: executor crashes with exception - outcome="crash"
• Skipped blocks: never executed - outcome="n/a"
• Successful blocks: operation succeeded - outcome="success"

Test Status: 88/91 tests passing (96.7%)

• 2 resume_workflow tests failing (investigation ongoing - MCP server crash issue)
• 1 secrets-http-auth test failing (external httpbin.org 503 error)

Files Modified:

• src/workflows_mcp/engine/node_meta.py: Added outcome field, updated factories
• src/workflows_mcp/engine/orchestrator.py: Pass outcome="crash" for exceptions
• src/workflows_mcp/engine/workflow_runner.py: Fixed .is_failed() → .failed
• src/workflows_mcp/engine/execution.py: Added model_validator for checkpoint deserialization

See: docs/adr/ADR-009-FOR-EACH-ABSTRACTION.md

5.0.0 (2025-11-04)

Code Refactoring

• unify int/float types to num and fix composition bug (0537afc)

Features

• LLMCall: BREAKING CHANGE Add support for LLM Executor (4d831fe)
• LLMCall: BREAKING CHANGE Add support for LLM Executor (#18) (5a54cb9)

BREAKING CHANGES

• LLMCall: **

• Workflow YAML files using type: int or type: float should migrate to type: num

---

• Workflow YAML files using type: int or type: float should migrate to type: num

4.4.0 (2025-11-02)

Bug Fixes

• release: use deploy key (18e1fc9)

Features

• add comprehensive secrets management system (31d2732)
• add comprehensive secrets management system (#17) (6927464)
• tests: normalise snapshots (91f4059)

4.3.0 (2025-11-01)

Features

• add HttpCall block executor for HTTP/REST API integration (9ca2b70)
• add HttpCall block executor for HTTP/REST API integration (#16) (76d1714)

4.2.0 (2025-11-01)

Bug Fixes

• checkpointing: properly handle checkpoint config for nested workflows (b79740b)

Features

• workflows: add process-todo-create-issues workflow template (e932de3)
• workflows: add process-todo-create-issues workflow template (#11) (309564d)

4.1.0 (2025-10-30)

Bug Fixes

• server: improve graceful shutdown and fix naming convention (86b66eb)

Features

• github: add interactive issue creation workflow (52da77f)

4.0.3 (2025-10-27)

Bug Fixes

• git: quote condition value to fix YAML syntax (97ae68f)
• git: use env vars for safe commit message handling (#6) (807e61c)
• git: use env vars for safe message handling (GitHub Actions pattern) (48297ea)
• yaml: quote all unquoted {{...}} variable references (0e2b476)

4.0.2 (2025-10-27)

Bug Fixes

• git: fix boolean expression syntax and shell expansion issues (daa1d75)
• git: fix boolean expression syntax and shell expansion issues (#4) (176c60d)

4.0.1 (2025-10-26)

Bug Fixes

• remove EchoBlock in favor of Shell executor (#1) (678d259)

4.0.0 (2025-10-26)

• chore!: migrate to AGPL-3.0 license (3431aab)

BREAKING CHANGES

• License changed from GPL-3.0 to AGPL-3.0-or-later. This license change requires users to provide source code access when the software is used over a network. All existing functionality is preserved.