# AIMFP (pypi · aimfp)

Database-driven directives and project tracking for modular functional-procedural AI coding

- Trust score: 76/100 (medium)
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-11-05

## Components

- pypi · `aimfp`: 76/100 (this document), [markdown](https://verifymcp.io/servers/aryanduntley-aimfp/aimfp.md), [page](https://verifymcp.io/servers/aryanduntley-aimfp/aimfp)

## Channel facts

- Registry: `pypi`
- Package: `aimfp`
- Version: `1.70.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-11-05.

- **Supply Chain Security**: 100/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - Runs setuptools.build_meta at install time, a recognised build step with no custom scripting around it.
  - 0 of 1 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 84/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to aryanduntley/aimfp).
  - License check failed: the license (PolyForm-Noncommercial-1.0.0) isn't a recognized OSI-approved license.
  - Actively maintained (last published 4 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 72/100
  - AI-judged instruction clarity (good).
  - Tool/resource definitions use about 29231 tokens (~97/item across 300 items; 300 tools + 0 resources), lean.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 0/100
  - Stability not yet verified: not enough scan history yet (needs a 30-day window).
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Tool Safety**: 96/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - 30 of 36 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation; "detect_conflicts_before_merge" implies "merge" and declares readOnlyHint instead, contradicting what its own name says it does.
  - An AI judge read all 301 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 60/100
  - Spec-recency check failed: implements MCP spec 2025-06-18; the latest is 2026-07-28.

**Unverified: 1 category.** A category scored 0 because we could not verify it: a data source with nothing on this package, evidence we could not reach, or a check we could not run. We only credit what we can confirm.

## Install

### How do I install the AIMFP MCP server?

AIMFP runs locally as a PyPI package, launched with uvx aimfp. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add aryanduntley-aimfp -- uvx aimfp
```

### Cursor

```json
{
  "mcpServers": {
    "aryanduntley-aimfp": {
      "command": "uvx",
      "args": [
        "aimfp"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "aryanduntley-aimfp": {
      "command": "uvx",
      "args": [
        "aimfp"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add aryanduntley-aimfp -- uvx aimfp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "aryanduntley-aimfp": {
      "type": "local",
      "command": [
        "uvx",
        "aimfp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add aryanduntley-aimfp --command uvx --arg aimfp
```

### Hermes

```yaml
mcp_servers:
  aryanduntley-aimfp:
    command: "uvx"
    args: ["aimfp"]
```

### Netclaw

```json
{
  "McpServers": {
    "aryanduntley-aimfp": {
      "Transport": "stdio",
      "Command": "uvx",
      "Arguments": [
        "aimfp"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add aryanduntley-aimfp -t stdio -c uvx -a aimfp
```

### Other

```json
{
  "mcpServers": {
    "aryanduntley-aimfp": {
      "command": "uvx",
      "args": [
        "aimfp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-11-01 (score 76, +15)

- [security improvement] Malware scan: unverified → pass

### 2026-10-31 (score 61)

First indexed and scored.

## MCP tools (300)

### `acknowledge_notice` (~131 tokens)

Mark a notice as delivered so it never fires again for this project. Writes to acknowledged_notices in user_preferences.db; the notice text itself lives in the read-only core database and is untouched. Call only AFTER acting on the notice — for an action_required notice that means after the user has actually answered, not merely been asked.

Input parameters:

- `notice_key` (string, required): Notice identifier from get_pending_notices (e.g. 'backup_interval_intro')
- `outcome` (string): Short record of what the user decided (e.g. 'set backup_interval_days=14'). Kept for audit and worth filling in.

### `activate_user_directive` (~66 tokens)

Set directive status to 'active' and record activated_at timestamp, only for a directive a person approved and that is unchanged since (approval content hash). Does NOT deploy services - AI handles deployment via directive workflow.

Input parameters:

- `directive_id` (integer, required): ID of the directive to activate

### `add_completion_path` (~107 tokens)

Add completion path stage

Input parameters:

- `description` (string): Description
- `name` (string, required): Completion path name (e.g., 'setup', 'core dev', 'finish')
- `order_index` (integer): Order position (1, 2, 3...)
- `status` (string): 'pending', 'in_progress', 'completed'
- `theme_ids` (array): Themes (stable project areas) this path advances. Optional here; link later with add_path_themes.

### `add_directive_preference` (~80 tokens)

Add/update user preference for directive

Input parameters:

- `active` (boolean): Whether preference is active
- `description` (string): Optional note on what this preference does, stored with it in directive_preferences
- `directive_name` (string, required): Directive name
- `preference_key` (string, required): Preference key
- `preference_value` (string, required): Preference value

### `add_file_flows` (~53 tokens)

Batch-assign multiple files to flows. Skips existing links silently. More efficient than multiple add_file_to_flow calls.

Input parameters:

- `links` (array, required): Array of [file_id, flow_id] tuples to create

### `add_file_to_flow` (~72 tokens)

Assign a finalized file to an architectural flow. Every finalized file needs at least one flow assignment to stay architecturally connected.

Input parameters:

- `file_id` (integer, required): File ID (from reserve_file/finalize_file)
- `flow_id` (integer, required): Flow ID (from add_flow or get_all_flows)

### `add_file_to_module` (~56 tokens)

Assign a file to a module. Creates module_files junction entry. Same pattern as add_file_to_flow.

Input parameters:

- `file_id` (integer, required): File ID to assign
- `module_id` (integer, required): Module ID to assign to

### `add_files_to_module` (~57 tokens)

Batch assign multiple files to modules. More efficient than multiple add_file_to_module calls. Skips duplicates silently, fails fast on missing entities.

Input parameters:

- `links` (array, required): List of [file_id, module_id] tuples to assign

### `add_flow` (~126 tokens)

Add a project flow (evolving behaviour/architecture description) linked to at least one theme. theme_ids is required: a flow never exists without a theme.

Input parameters:

- `ai_generated` (boolean): True if AI-generated
- `confidence_score` (number): Confidence score 0-1
- `description` (string): Flow description
- `name` (string, required): Flow name
- `theme_ids` (array, required): IDs of the theme(s) this flow belongs to — at least one. Every flow belongs to a theme; pick from get_all_themes() or add_theme() first.

### `add_flow_themes` (~80 tokens)

Batch-link flows to themes (flow_themes). Every flow must belong to at least one theme; use this to fix theme-less flows or give a flow a second theme.

Input parameters:

- `links` (array, required): Array of [flow_id, theme_id] pairs. One pair links one; many pairs (any mix of flow_ids) apply atomically.

### `add_interaction` (~149 tokens)

Record a dependency between two functions by name (call, chain, borrow, compose, pipe). Interactions are how the AI traces dependency graphs. An edge already tracked is not duplicated (already_existed=true).

Input parameters:

- `description` (string): What the dependency is (optional)
- `interaction_type` (string, required): Interaction type ('call', 'chain', 'borrow', 'compose', 'pipe')
- `is_indirect` (boolean): True for a deliberate edge the code makes indirectly (dispatch through a tuple/table of functions, a chain data-flow link): audit_interactions never reports it as stale.
- `source` (string, required): Source function name
- `target` (string, required): Target function name

### `add_interactions` (~125 tokens)

Batch-record function dependencies by ID. More efficient than multiple add_interaction calls for tracking all cross-function dependencies. Edges already tracked (same source, target, type) are skipped and counted in skipped_count; ids stay in input order.

Input parameters:

- `interactions` (array, required): Array of tuples [(source_function_id, target_function_id, interaction_type, description[, is_indirect]), ...] - type: 'call', 'chain', 'borrow', 'compose', 'pipe'. Optional 5th element is_indirect (b…

### `add_item` (~112 tokens)

Create a single work item under a task, subtask, or sidequest. Items are the smallest trackable units of work.

Input parameters:

- `description` (string): Item description
- `name` (string, required): Item name
- `reference_id` (integer, required): ID of the parent task, subtask, or sidequest
- `reference_table` (string, required): 'tasks', 'subtasks', or 'sidequests'
- `status` (string): 'pending', 'in_progress', 'completed' (default: pending)

### `add_items` (~87 tokens)

Batch-create multiple work items under a single parent in one call. All items created with status 'pending'.

Input parameters:

- `items` (array, required): Array of {name: string, description?: string} objects
- `reference_id` (integer, required): ID of the parent task, subtask, or sidequest
- `reference_table` (string, required): 'tasks', 'subtasks', or 'sidequests'

### `add_milestone` (~99 tokens)

Add milestone to completion path

Input parameters:

- `completion_path_id` (integer, required): Completion path ID this milestone belongs to
- `description` (string): Milestone description
- `flow_ids` (array): Flows this milestone builds or changes. Optional here; link later with add_milestone_flows.
- `name` (string, required): Milestone name
- `status` (string): 'pending', 'in_progress', 'completed', 'blocked'

### `add_milestone_flows` (~93 tokens)

Batch-link milestones to the flows (evolving behaviour) they build or change (milestone_flows). A milestone that introduces new behaviour should get a NEW flow (add_flow) rather than growing an existing flow's description.

Input parameters:

- `links` (array, required): Array of [milestone_id, flow_id] pairs. One pair links one; many pairs (any mix of milestone_ids) apply atomically.

### `add_module` (~133 tokens)

Create a new module (reusable code boundary). A module maps to a directory. Files are assigned explicitly via add_file_to_module. Use external_dependencies to record wrapped libraries.

Input parameters:

- `description` (string): What this module does
- `external_dependencies` (array): Libraries/services this module wraps (e.g., ['walletconnect', 'stripe'])
- `name` (string, required): Module name (e.g., 'wallet_connection', 'validation')
- `path` (string, required): Directory path relative to source root (e.g., 'src/wallet_connection/')
- `purpose` (string): Domain concern this module owns (one sentence)

### `add_note` (~263 tokens)

Record a decision, architecture change, or context event in the project's audit trail. Supports typed notes with optional directive linking.

Input parameters:

- `content` (string, required): Note content/message
- `directive_name` (string): Optional directive context for note
- `note_type` (string, required): 'clarification', 'pivot', 'research', 'entry_deletion', 'warning', 'error', 'info', 'auto_summary', 'decision', 'evolution', 'analysis', 'task_context', 'external', 'summary'
- `reference_id` (integer): ID of the referenced table entry
- `reference_table` (string): project.db table this note is attached to (e.g. 'files', 'tasks', 'flows', 'completion_path'). Must be an existing project.db table name, exactly: unknown names are refused, because the getters that…
- `send_with_directive` (boolean): If true and directive_name set, note is included when that directive is retrieved. Turns notes into contextual reminders that travel with their directive.
- `severity` (string): 'info', 'warning', 'error' (default 'info')
- `source` (string): 'ai', 'user', or 'directive' (default 'ai')

### `add_path_themes` (~74 tokens)

Batch-link completion paths to the themes (stable project areas) they advance (completion_path_themes). Themes change rarely, like paths.

Input parameters:

- `links` (array, required): Array of [completion_path_id, theme_id] pairs. One pair links one; many pairs (any mix of completion_path_ids) apply atomically.

### `add_project_entry` (~35 tokens)

Add new entry to project database

Input parameters:

- `data` (object, required): Field-value pairs
- `table` (string, required): Table name

### `add_settings_entry` (~35 tokens)

Add entry to user settings database

Input parameters:

- `data` (object, required): Field-value pairs
- `table` (string, required): Table name

### `add_sidequest` (~129 tokens)

Create an urgent interruption that pauses the current task. Use for bug fixes, blockers, or unexpected work discovered mid-task.

Input parameters:

- `description` (string): Sidequest description
- `flow_ids` (array): JSON array of flow IDs
- `name` (string, required): Sidequest name
- `paused_subtask_id` (integer): If sidequest during subtask
- `paused_task_id` (integer, required): ID of the task being paused for this sidequest
- `priority` (string): Sidequest priority (default: critical)
- `status` (string): Sidequest status (default: pending)

### `add_subtask` (~100 tokens)

Create a focused sub-unit of work under a parent task. The parent is paused until all subtasks complete.

Input parameters:

- `description` (string): Subtask description
- `name` (string, required): Subtask name
- `parent_task_id` (integer, required): Parent task ID
- `priority` (string): 'low', 'medium', 'high', 'critical'
- `status` (string): 'pending', 'in_progress', 'completed', 'blocked'

### `add_task` (~107 tokens)

Create a task under a milestone with flow associations. Tasks are created ONE at a time as work progresses, not all at once.

Input parameters:

- `description` (string): Task description
- `flow_ids` (array): JSON array of flow IDs
- `milestone_id` (integer, required): ID of the milestone this task belongs to
- `name` (string, required): Task name
- `priority` (string): Task priority (default: medium)
- `status` (string): Task status (default: pending)

### `add_theme` (~61 tokens)

Add project theme

Input parameters:

- `ai_generated` (boolean): True if AI-generated, False if user-created
- `confidence_score` (number): Confidence score 0-1
- `description` (string): Theme description
- `name` (string, required): Theme name

### `add_tracking_note` (~162 tokens)

Add tracking note to user_preferences.db (only when tracking enabled)

Input parameters:

- `content` (string, required): Note content/message
- `directive_name` (string): Directive that created this note
- `metadata_json` (string): Additional context as JSON string
- `note_type` (string, required): 'fp_analysis', 'user_interaction', 'validation', 'performance', 'debug'
- `reference_id` (integer): Optional ID if referencing project.db entity
- `reference_name` (string): Name of referenced entity (e.g., function name, file path)
- `reference_type` (string): Type of reference (e.g., 'function', 'file', 'directive')
- `severity` (string): 'info', 'warning', 'error' (default 'info')

### `add_types_functions` (~106 tokens)

Link tracked types to the functions that use them with a role (factory, transformer, validator, etc.). Enables 'what functions use TypeX?' queries. Links already tracked are skipped and counted in skipped_count instead of failing the batch.

Input parameters:

- `relationships` (array, required): Array of tuples [(type_id, function_id, role), ...] - role: 'factory', 'transformer', 'operator', 'pattern_matcher', 'accessor', 'validator', 'combinator'

### `add_user_custom_entry` (~85 tokens)

Add entry to user_directives.db table. Returns inserted record with ID. Every key must be a column of the table; on user_directives the approval columns and status='active' are refused, so a new directive always starts unapproved.

Input parameters:

- `data` (object, required): Field-value pairs to insert
- `table` (string, required): Table name in user_directives.db

### `add_user_directive_note` (~190 tokens)

Add note to user_directives.db notes table for AI record-keeping

Input parameters:

- `content` (string, required): Note content/message
- `metadata_json` (string): Additional context as JSON string
- `note_type` (string, required): 'implementation', 'validation', 'execution', 'dependency', 'error', 'optimization', 'user_feedback', 'lifecycle', 'testing', 'general', 'deferred', 'completed', 'obsolete', 'entry_deletion'
- `reference_id` (integer): Optional ID linking to user_directives, helper_functions, etc.
- `reference_name` (string): Name of referenced entity (e.g., directive name, helper name, file path)
- `reference_type` (string): Type of reference: 'directive', 'helper', 'dependency', 'file'
- `severity` (string): 'info', 'warning', 'error' (default 'info')

### `add_user_setting` (~68 tokens)

Add new project-wide user setting to user_settings table

Input parameters:

- `description` (string): Description of the setting
- `scope` (string): Setting scope (default 'project')
- `setting_key` (string, required): Setting key (must be unique)
- `setting_value` (string, required): Setting value

### `aimfp_end` (~120 tokens)

Session termination orchestrator. Gathers session audit data: reads watchdog state and final reminders, queries all files and functions from DB for AI to cross-reference, reads recent notes and task state. Stops watchdog process if running. Returns structured audit data for AI to interpret and act on. No analysis logic — AI determines what is stale or missing. Also runs the tracking audit (functions, interactions, descriptions) over the session's uncommitted changes (or the in-progress work item's files without git) and returns data.audit with counts, verdict and report_path.

### `aimfp_init` (~53 tokens)

Phase 1 mechanical setup orchestrator for project initialization. Atomically creates directories, databases with schemas, and templates. No deep logic - pure mechanical operations.

Input parameters:

- `project_root` (string, required): Path to project root directory

### `aimfp_run` (~84 tokens)

Main entry point orchestrator. Called on session start (is_new_session=true) for full context bundle, and at work checkpoints (is_new_session=false) for watchdog alerts only.

Input parameters:

- `is_new_session` (boolean): Whether this is a new session start. Use true for first interaction, new session, or after long breaks. Use false (default) for continuation work.

### `aimfp_status` (~159 tokens)

Project status in three tiers. Default 'quick' is the cheap position check for completion loops; 'summary' is the reload after lost or compacted context. Structure (themes/flows/modules) is attached to the work and files shown, never listed whole.

Input parameters:

- `type` (string): Tier: 'quick' (default) = position only (path, milestone, focused work with item names, their flows/themes, other open work, structure gap count), for completion loops and 'where am I' checks. 'summa…

### `apply_audit_fixes` (~923 tokens)

Apply audit findings in ONE call and ONE transaction, with a restore manifest written in the same transaction. Name report categories (report + apply) so thousands of IDs never pass through the conversation, hold back reviewed false positives for this call with exclude={category: [ids]} or for good with exempt=[...], and/or pass explicit changes. Every report finding is re-checked against its row first: an edge whose endpoints changed since the audit, or an entity already gone or renamed, is skipped with a reason. One entry_deletion note lists every deleted row (cascaded edges and type links included) and the old values of every changed row, so any change can be undone. Judgement categories (unconfirmed_interactions, dangling_mentions, missing_functions, untracked_files) are refused: they need prose, a mark, or reconcile_paths. Description review lists (unbaselined_needs_review, stale_descriptions) apply as baselines once reviewed: exclude the ones whose prose you are rewriting.

Input parameters:

- `add_interactions` (array): Edges to add (interaction_type defaults to 'call').
- `add_type_links` (array): types_functions links to add.
- `apply` (array): Finding categories of the report to apply. missing_interactions=add, stale_interactions=delete (indirect edges kept), repoint_interactions=move source/target, stale_functions/stale_types=delete (casc…
- `baseline_hash_function_ids` (array): Functions whose current code hash is recorded as matching their description. Only after reviewing purpose/parameters/returns.
- `cleanup` (boolean): Delete the report file after a successful real run.
- `delete_function_ids` (array): Functions to delete; their interactions and type links cascade and are recorded in the manifest.
- `delete_interaction_ids` (array): Interactions to delete.
- `delete_type_ids` (array): Types to delete; their type links cascade and are recorded in the manifest.
- `dry_run` (boolean): Do everything, then roll back: the result is exactly what a real run does.
- `exclude` (object): Findings of applied categories to hold back (reviewed false positives), as {category: [ids]}: interaction_id for stale/repoint_interactions, function_id for stale_functions/param_mismatch/unbaselined…
- `exempt` (array): Reviewed findings that are NOT drift (schema 1.16): [{category, function_id | type_id, reason?}], reason defaulting to the call's. Audits list them under 'exempted' (info) instead of the category, so…
- `mark_indirect_ids` (array): Interactions to mark is_indirect: deliberate edges the code makes indirectly. Audits never flag them; report deletes skip them.
- `reason` (string, required): Why these changes are made; recorded in the restore-manifest note.
- `refresh_signature_function_ids` (array): Functions whose parameters are re-read from the source (names, order, types, required/default), keeping each surviving parameter's description.
- `repoint_interactions` (array): Edges to move to a new source and/or target.
- `report` (string): report_path returned by an audit tool (project-relative path, absolute path, or bare file name in the audit folder).
- `unexempt_ids` (array): audit_exemptions ids (exemption_id in an audit's 'exempted' list) to remove; the finding is reported again. Removed rows go into the manifest.
- `unmark_indirect_ids` (array): Interactions to clear is_indirect on.

### `apply_state_changeset` (~227 tokens)

(For use with InterCommAIMFP) Apply a semantic changeset onto the current-main project.db as a 3-way merge (base@base_main_commit vs branch intent vs current main). Accepts EITHER the inline changeset object OR a changeset_id handle (loaded server-side). Auto-applies non-overlapping changes, mints canonical IDs for genuinely new entities, rewrites all references to canonical IDs, and returns EVERY conflict as structured data for the master/AI to review — it never guesses on a conflict. Mutates the working .aimfp-project/project.db in place after taking a backup; a genuine failure rolls back and restores the backup.

Input parameters:

- `changeset` (object): The changeset object produced by export_state_changeset (provenance, entities[], references[]). Optional when changeset_id is given.
- `changeset_id` (string): Handle returned by export_state_changeset; loads the persisted changeset from .aimfp-project/changesets/ so you never re-transcribe the full object. Used only when changeset is omitted.

### `audit_descriptions` (~528 tokens)

Audit function and type descriptions for drift from the code. Read-only. stale_descriptions: the function's code changed after its purpose/parameters/returns were written (functions.source_hash, recorded on every prose write, differs from the current code hash; formatting, comments and docstrings never change the hash). dangling_mentions: a description names a callable that exists nowhere — 'name()' or 'snake_name(...)' not defined, imported or called anywhere in the tracked Python files, not tracked, not a builtin or Python keyword, and not vocabulary the code writes in its string literals (a whole-string identifier or 'name(' in a string: DSL built-ins such as jsonencode, parse_json); attribute calls, ALLCAPS and 'file(s)' plurals are ignored. Described functions with no hash yet are triaged against the code: unbaselined_descriptions (info) pass and can be baselined in one call; unbaselined_needs_review (info) carry triage reasons (recorded parameter names or return type differing from the code, a purpose under three words, snake_case/backticked names in the prose that neither the function nor the rest of its file uses — names, imports, string words, plural or singular forms count), the recorded prose and a code excerpt; a name found nowhere in the repo (any file under the project root the exclusion stack keeps) ranks priority 'high' with signature mismatches, one found elsewhere ranks 'low', and lists are sorted high first. stale_descriptions carry the same triage, priority and excerpt. Warnings only — never blocks a task. Scope selectors combine as a union; with none, the whole project (tracked files plus untracked source files) is audited. Writes the full report to <project folder>/audit/ and returns counts + samples + report_path.

Input parameters:

- `file_ids` (array): Tracked file IDs to audit.
- `module_path` (string): Audit every file under this project-relative directory.
- `paths` (array): Project-relative file paths to audit (tracked or not).
- `since_commit` (string): Audit files changed since this git ref ('HEAD' = uncommitted work, or a branch/commit): committed, staged, unstaged and new untracked files.
- `task_id` (integer): Audit the files linked to this task (a task includes its subtasks' files).
- `task_type` (string): 'task' (default), 'subtask' or 'sidequest' — the kind of work item task_id names.

### `audit_functions` (~404 tokens)

Audit tracked files, functions and types against the source. Read-only. Python files (full fidelity): missing_functions (public, untracked), stale_functions (tracked, gone from the source; a module-level `f = partial(...)`, lambda or alias binding of the name counts as defined), incomplete_functions (purpose/parameters/returns empty), malformed_json (not one JSON encoding of a list/object; double-encoded is fixable), reserved_functions (never finalized), param_mismatch (recorded parameters vs the signature: names, order, required vs default), missing_types, stale_types (name defined nowhere in the file), incomplete_types, missing_type_links (a tracked type named in a signature with no types_functions link, role suggested), files_without_functions (informational). Every file: missing_files (tracked, gone from disk), untracked_files. Regex languages only report names_only_missing (warning) and never claim anything stale. Tracking _private functions is optional: untracked ones are never reported, tracked ones get every check. Scope selectors combine as a union; with none, the whole project (tracked files plus untracked source files) is audited. Writes the full report to <project folder>/audit/ and returns counts + samples + report_path.

Input parameters:

- `file_ids` (array): Tracked file IDs to audit.
- `module_path` (string): Audit every file under this project-relative directory.
- `paths` (array): Project-relative file paths to audit (tracked or not).
- `since_commit` (string): Audit files changed since this git ref ('HEAD' = uncommitted work, or a branch/commit): committed, staged, unstaged and new untracked files.
- `task_id` (integer): Audit the files linked to this task (a task includes its subtasks' files).
- `task_type` (string): 'task' (default), 'subtask' or 'sidequest' — the kind of work item task_id names.

### `audit_interactions` (~570 tokens)

Audit tracked interactions against the call graph the code makes, for the callers in scope. Read-only. Expected edges: calls AND functions used as values (map(fn, xs), partial, dispatch dicts built in the body), credited through untracked same-file helpers, resolved through imports, aliases and re-exports. Categories: missing_interactions (code makes it, DB lacks it), stale_interactions (provably gone: every use of the target's name in the caller resolves to something else — another function, a local or loop variable, a method on a value — or there is none), repoint_interactions (a stale edge that is the same dependency moved: call moved to another function in the same file, or target moved under the same name — one change, not delete+add), unconfirmed_interactions (may be real but unprovable, each with a reason: name resolves ambiguously, called through a record field or factory several functions are stored under, a callback parameter of the target's name, the name as a string in a lookup position (call argument such as getattr's, subscript key, list/tuple/set element; never a dict-literal key, comparison or assignment), a non-Python target: mark indirect or delete), indirect_interactions (is_indirect edges) and non_call_interactions (chain/compose/pipe/borrow types): informational, never flagged. Confirmed without being expected (never reported, never asked to be added): self-recursion, functions held in a module-level table the caller reads (dispatch), a .field() call when the target is the only tracked function stored under that field anywhere (Rec(field=target)), a non-Python function called as name( in the caller's string literals (SQL). Python callers only (full fidelity); other files listed in unchecked_files. Scope selectors combine as a union; with none, the whole project (tracked files plus untracked source files) is audited. Writes the full report to <project folder>/audit/ and returns counts + samples + report_path.

Input parameters:

- `file_ids` (array): Tracked file IDs to audit.
- `module_path` (string): Audit every file under this project-relative directory.
- `paths` (array): Project-relative file paths to audit (tracked or not).
- `since_commit` (string): Audit files changed since this git ref ('HEAD' = uncommitted work, or a branch/commit): committed, staged, unstaged and new untracked files.
- `task_id` (integer): Audit the files linked to this task (a task includes its subtasks' files).
- `task_type` (string): 'task' (default), 'subtask' or 'sidequest' — the kind of work item task_id names.

### `audit_tracking` (~434 tokens)

Run EVERY tracking audit over one scope with one code index and one report: files, functions, types, parameters, JSON encoding, type links (audit_functions), interactions with repoints (audit_interactions), stale prose and dangling mentions (audit_descriptions), plus modularity gaps (structure_gaps). Read-only. The same audit gates task/subtask/sidequest completion (over the item's linked files), runs in aimfp_end over uncommitted work, runs per changed file in the watchdog, and runs in CI as `aimfp audit`. Scope selectors combine as a union; with none, the whole project (tracked files plus untracked source files) is audited. Writes the full report to <project folder>/audit/ and returns counts + samples + block/warn verdict + report_path.

Input parameters:

- `file_ids` (array): Tracked file IDs to audit.
- `full` (array): Finding categories to return inline in full, whatever sample_limit says (e.g. ['stale_descriptions']). Unknown category names are an error.
- `include` (array): Audits to run (default all): functions (files, functions, types, parameters, JSON, type links), interactions (missing/stale/repoint edges), descriptions (stale prose, dangling mentions), structure (m…
- `module_path` (string): Audit every file under this project-relative directory.
- `paths` (array): Project-relative file paths to audit (tracked or not).
- `sample_limit` (integer): Findings shown inline per category (default 5; 0 = counts only). The report file always has every finding.
- `since_commit` (string): Audit files changed since this git ref ('HEAD' = uncommitted work, or a branch/commit): committed, staged, unstaged and new untracked files.
- `task_id` (integer): Audit the files linked to this task (a task includes its subtasks' files).
- `task_type` (string): 'task' (default), 'subtask' or 'sidequest' — the kind of work item task_id names.

### `backfill_semantic_keys` (~150 tokens)

(For use with InterCommAIMFP) Mint stable identity keys for any rows that lack one: slugs on work-hierarchy rows (milestones, tasks, subtasks, sidequests, items) and entity_key on functions/types — e.g. rows that predate those columns. OPTIONAL one-time prep: run once on main (and commit) only when a pre-v1.11 project is about to start multi-agent parallel work, so every clone inherits stable baseline keys that export_state_changeset can match. Unnecessary for solo projects (keys never read) and for projects started fresh on v1.11+ (keys minted at creation — no-op). Idempotent.

### `batch_update_progress` (~124 tokens)

Update multiple project items atomically. Used after code generation or bulk operations to ensure consistency.

Input parameters:

- `continue_on_error` (boolean): Stop on first error or continue processing remaining updates
- `transaction` (boolean): All-or-nothing commit vs independent updates
- `updates` (array, required): List of update objects: [{target_type, target_id, action, data}, ...] data.audit_override_reason completes a task/subtask/sidequest despite blocking tracking-audit findings (recorded as a warning not…

### `blueprint_has_changed` (~37 tokens)

Check if ProjectBlueprint.md has changed using Git or filesystem timestamp

Input parameters:

- `blueprint_path` (string, required): Absolute path to ProjectBlueprint.md file

### `catalog_files` (~121 tokens)

Register existing files in project.db in a single phase. For code already on disk: rows are written finalized (is_reserved=0) with ID naming off, because existing filenames are fixed and cannot carry an _id_ suffix. Use INSTEAD OF reserve_files/finalize_files when adopting an existing codebase. Idempotent on path; re-cataloging keeps a stored name or language that is omitted.

Input parameters:

- `files` (array, required): Array of {name, path, language} objects. 'path' is project-relative and is the identity key.

### `catalog_functions` (~139 tokens)

Register existing functions in project.db in a single phase. Use INSTEAD OF reserve_functions/finalize_functions when adopting an existing codebase. Idempotent on (file_id, name), so a re-scan after source changes refreshes signatures instead of duplicating them. Only supplied fields are overwritten: an omitted or blank purpose, parameters or returns keeps the stored value, so a refresh never erases prose.

Input parameters:

- `functions` (array, required): Array of {name, file_id, purpose, parameters, returns} objects. 'parameters' is a list of param dicts and 'returns' a dict; both are JSON-encoded on write.

### `catalog_types` (~99 tokens)

Register existing type definitions in project.db in a single phase. Use INSTEAD OF reserve_types/finalize_types when adopting an existing codebase. Idempotent on (file_id, name); definition is always refreshed, an omitted description keeps the stored one.

Input parameters:

- `types` (array, required): Array of {name, file_id, definition, description} objects. 'definition' is a dict describing the type shape and is JSON-encoded on write.

### `check_directive_health` (~324 tokens)

Assess every user directive and report which need attention. The health states, in the order they are checked: 'unapproved' (status is active but no person approved it, so dispatch withholds it); 'needs_reapproval' (approved, but the trigger, action or implementation file changed since, or it was approved before schema 1.5 without a content hash; dispatch and activation refuse it until the user approves again); 'error' (the directive's own status is error); 'overdue' (next_scheduled_time is in the past, meaning the runner said when it would next fire and did not); 'skipping' (consecutive_skip_count is at or above skip_threshold with no run since the last skip, meaning the runner is alive but keeps skipping occurrences, usually because the host is down at the scheduled time); 'degraded' (error rate at or above the threshold); 'never_run' (active but never executed; when dispatch errors exist, the detail says the runner is running but refusing or failing to dispatch, otherwise that the runner may not be deployed); or 'ok'. Returns a verdict per directive with a one-line explanation and the skip fields, plus a count per state, designed to render as a single sentence at session start.

Input parameters:

- `error_rate_threshold` (number): Error rate at or above which a directive is reported degraded
- `project_root` (string): Project root; defaults to the session root
- `skip_threshold` (integer): Consecutive skipped occurrences at or above which a directive is reported skipping

### `check_scheduled_backup_due` (~98 tokens)

Check whether a scheduled backup is overdue, measured from the LAST BACKUP. Distinct from the inactivity rule (backup_duration), which measures time since the last project change and therefore only ever fires on dormant projects — an actively developed project would otherwise never be backed up. Governed by backup_interval_days; 0 disables scheduling. Called automatically by aimfp_run(is_new_session=true); available standalone for hosts that want the check on demand.

### `clear_watchdog` (~55 tokens)

Clear watchdog reminders after they have been reviewed and handled. Reminders persist in .aimfp-project/watchdog/reminders.json until this is called. Call after addressing all watchdog findings (file deletions, unregistered files, etc.).

### `core_allowed_check_constraints` (~65 tokens)

Returns list of allowed values for CHECK constraint enum fields in aimfp_core.db. Parses schema to extract CHECK(field IN (...)) constraints.

Input parameters:

- `field` (string, required): Field name to get allowed values for
- `table` (string, required): Table name to check for CHECK constraints

### `create_project` (~144 tokens)

Initialize project entry (one per database)

Input parameters:

- `goals` (array, required): Array of goal strings (e.g., ['Fast computation', 'No OOP'])
- `name` (string, required): Project name (e.g., 'MatrixCalculator')
- `purpose` (string, required): Project purpose (e.g., 'Build a pure functional matrix math library')
- `status` (string): 'active', 'paused', 'completed', 'abandoned'
- `user_directives_status` (string): NULL (Case 1), 'pending_discovery', 'pending_parse', 'in_progress', 'active', 'disabled'
- `version` (integer): Tracks idea evolution (starts at 1)

### `create_project_backup` (~93 tokens)

Create a backup of .aimfp-project/ right now, ignoring any threshold. Zips everything except backups/ and watchdog/, adds a generated backup_summary.md, and rotates old archives per the backup_count setting, naming every archive it deletes (rotated, plus a warning sentence). The on-demand counterpart to the automatic inactivity check — call this when aimfp_run reports a scheduled backup due, or before any risky operation.

### `create_state_database` (~51 tokens)

Create per-project state database (.state/runtime.db) from SQL schema. FP-compliant replacement for mutable global variables.

Input parameters:

- `source_directory` (string, required): Absolute path to project source directory (from infrastructure.source_directory)

### `create_user_branch` (~40 tokens)

Create work branch following aimfp-{user}-{number} convention

Input parameters:

- `purpose` (string, required): Branch purpose description
- `user` (string, required): Username

### `deactivate_user_directive` (~44 tokens)

Set directive status to 'paused'. Does NOT stop services - AI handles service shutdown via directive workflow.

Input parameters:

- `directive_id` (integer, required): ID of the directive to deactivate

### `delete_completion_path` (~80 tokens)

Delete completion path with milestone validation

Input parameters:

- `id` (integer, required): Completion path ID
- `note_reason` (string, required): Deletion reason
- `note_severity` (string, required): 'info', 'warning', 'error'
- `note_source` (string, required): 'ai' or 'user'
- `note_type` (string): 'entry_deletion'

### `delete_custom_return_statement` (~73 tokens)

Delete custom return statement(s) for a helper function. By ID, by text, or all for a helper.

Input parameters:

- `helper_name` (string, required): Helper function name
- `statement` (string): Specific statement text to delete (optional)
- `statement_id` (integer): Specific row ID to delete (optional)

### `delete_file` (~82 tokens)

Delete file with comprehensive cross-reference validation

Input parameters:

- `file_id` (integer, required): File ID to delete
- `note_reason` (string, required): Deletion reason
- `note_severity` (string, required): 'info', 'warning', 'error'
- `note_source` (string, required): 'ai' or 'user'
- `note_type` (string): 'entry_deletion'

### `delete_flow` (~80 tokens)

Delete flow with file validation

Input parameters:

- `flow_id` (integer, required): Flow ID to delete
- `note_reason` (string, required): Deletion reason
- `note_severity` (string, required): 'info', 'warning', 'error'
- `note_source` (string, required): 'ai' or 'user'
- `note_type` (string): 'entry_deletion'

### `delete_function` (~226 tokens)

Delete a function, deciding explicitly what happens to its interactions: refused (with the edges listed) unless repoint_to moves them to the function that took over its job, or confirm_cascade removes them. Every moved or removed edge is recorded in the deletion note so it can be undone. Type relationships must be unlinked first.

Input parameters:

- `confirm_cascade` (boolean): Delete the function's interactions with it. Without repoint_to or confirm_cascade, a function with interactions is refused and the edges are listed.
- `function_id` (integer, required): Function ID to delete
- `note_reason` (string, required): Deletion reason
- `note_severity` (string, required): 'info', 'warning', 'error'
- `note_source` (string, required): 'ai' or 'user'
- `note_type` (string): 'entry_deletion'
- `repoint_to` (integer): Function ID that takes over this function's interactions (the split/move case). Edges that would become self-edges or duplicates are dropped. Every moved or dropped edge is written into the deletion…

### `delete_interaction` (~78 tokens)

Delete interaction

Input parameters:

- `interaction_id` (integer, required): Interaction ID to delete
- `note_reason` (string, required): Deletion reason
- `note_severity` (string, required): 'info', 'warning', 'error'
- `note_source` (string, required): 'ai' or 'user'
- `note_type` (string): 'entry_deletion'

### `delete_item` (~77 tokens)

Delete item with status validation

Input parameters:

- `id` (integer, required): Item ID
- `note_reason` (string, required): Deletion reason
- `note_severity` (string, required): 'info', 'warning', 'error'
- `note_source` (string, required): 'ai' or 'user'
- `note_type` (string): 'entry_deletion'

### `delete_milestone` (~80 tokens)

Delete milestone with task validation

Input parameters:

- `id` (integer, required): Milestone ID
- `note_reason` (string, required): Deletion reason
- `note_severity` (string, required): 'info', 'warning', 'error'
- `note_source` (string, required): 'ai' or 'user'
- `note_type` (string): 'entry_deletion'

### `delete_module` (~38 tokens)

Delete a module. CASCADE removes module_files junction entries. Files themselves are NOT deleted.

Input parameters:

- `module_id` (integer, required): Module ID to delete

### `delete_note` (~26 tokens)

Delete note (discouraged)

Input parameters:

- `id` (integer, required): Note ID to delete

### `delete_project_entry` (~92 tokens)

Smart delete with automatic routing to specialized functions when needed

Input parameters:

- `id` (integer, required): Record ID
- `note_reason` (string, required): Deletion reason
- `note_severity` (string, required): "info", "warning", "error"
- `note_source` (string, required): "ai" or "user"
- `note_type` (string, required): "entry_deletion"
- `table` (string, required): Table name

### `delete_reserved` (~121 tokens)

Delete abandoned reserved entries (escape hatch for cancelled reserve operations)

Input parameters:

- `id` (integer, required): Reserved record ID to delete
- `note_reason` (string, required): Deletion reason (e.g., 'User cancelled operation', 'Correcting reservation error')
- `note_severity` (string, required): 'info', 'warning', 'error'
- `note_source` (string, required): 'ai' or 'user'
- `note_type` (string): 'entry_deletion'
- `table` (string, required): Table name (must be 'files', 'functions', or 'types')

### `delete_settings_entry` (~42 tokens)

Delete entry from user_preferences.db table

Input parameters:

- `record_id` (integer, required): Record ID to delete
- `table` (string, required): Table name in user_preferences.db

### `delete_sidequest` (~86 tokens)

Delete sidequest with item validation (same logic as delete_task)

Input parameters:

- `id` (integer, required): Sidequest ID
- `note_reason` (string, required): Deletion reason
- `note_severity` (string, required): 'info', 'warning', 'error'
- `note_source` (string, required): 'ai' or 'user'
- `note_type` (string): 'entry_deletion'

### `delete_subtask` (~86 tokens)

Delete subtask with item validation (same logic as delete_task)

Input parameters:

- `id` (integer, required): Subtask ID
- `note_reason` (string, required): Deletion reason
- `note_severity` (string, required): 'info', 'warning', 'error'
- `note_source` (string, required): 'ai' or 'user'
- `note_type` (string): 'entry_deletion'

### `delete_task` (~77 tokens)

Delete task with item validation

Input parameters:

- `id` (integer, required): Task ID
- `note_reason` (string, required): Deletion reason
- `note_severity` (string, required): 'info', 'warning', 'error'
- `note_source` (string, required): 'ai' or 'user'
- `note_type` (string): 'entry_deletion'

### `delete_theme` (~80 tokens)

Delete theme with flow validation

Input parameters:

- `note_reason` (string, required): Deletion reason
- `note_severity` (string, required): 'info', 'warning', 'error'
- `note_source` (string, required): 'ai' or 'user'
- `note_type` (string): 'entry_deletion'
- `theme_id` (integer, required): Theme ID to delete

### `delete_type` (~80 tokens)

Delete type with relationship validation

Input parameters:

- `note_reason` (string, required): Deletion reason
- `note_severity` (string, required): 'info', 'warning', 'error'
- `note_source` (string, required): 'ai' or 'user'
- `note_type` (string): 'entry_deletion'
- `type_id` (integer, required): Type ID to delete

### `delete_type_function` (~80 tokens)

Remove type-function relationship

Input parameters:

- `id` (integer, required): types_functions junction table ID
- `note_reason` (string, required): Deletion reason
- `note_severity` (string, required): 'info', 'warning', 'error'
- `note_source` (string, required): 'ai' or 'user'
- `note_type` (string): 'entry_deletion'

### `delete_user_custom_entry` (~118 tokens)

Delete entry from user_directives.db table, writing an entry_deletion note in the same transaction

Input parameters:

- `note_reason` (string): Why the row was deleted; recorded in the entry_deletion note ('no reason given' when omitted)
- `note_source` (string): Who deleted it: 'ai', 'user', or 'directive' (default 'ai'); stored in the note's metadata_json
- `record_id` (integer, required): Record ID to delete
- `table` (string, required): Table name in user_directives.db

### `detect_conflicts_before_merge` (~37 tokens)

Dry-run merge analysis - retrieves potential conflict data for AI to evaluate

Input parameters:

- `source_branch` (string, required): Branch to merge from

### `detect_external_changes` (~20 tokens)

Compare current Git HEAD with project.last_known_git_hash

### `detect_state_conflicts` (~127 tokens)

(For use with InterCommAIMFP) OPTIONAL pre-apply planning aid: export each pending worker branch and report where two or more branches touch the SAME semantic entity or edge, so the master can re-partition or deliberately order integration BEFORE applying any changeset. Pure read (built entirely from export_state_changeset). An overlap is a heuristic warning, not a verdict — the authoritative 3-way resolution still happens in apply_state_changeset.

Input parameters:

- `branches` (array, required): List of {branch, base_commit, worker_id?} objects to cross-reference for semantic-key overlap

### `execute_merge` (~35 tokens)

Execute git merge and return result. Updates work_branches table on success.

Input parameters:

- `source_branch` (string, required): Branch to merge from

### `export_state_changeset` (~261 tokens)

(For use with InterCommAIMFP) Export a semantic changeset of project.db between two committed git states (branch point -> branch tip), expressed entirely in stable semantic keys (file path, file+function/type name, module/theme/flow/path name, and work-hierarchy slugs) with branch-local integer PKs stripped. Each entity is classified add/modify/delete and each edge add/remove. This is the integer-free artifact the master applies to merge a worker's project-state into main without binary-blob conflicts or PK collisions. The changeset is ALSO persisted server-side under .aimfp-project/changesets/ and a small changeset_id handle + counts summary are returned, so the master can drive apply by handle instead of re-transcribing the full object. Pure read of git blobs (the export itself never mutates project.db); persistence writes only a JSON file under .aimfp-project/.

Input parameters:

- `base_commit` (string, required): Git commit the branch was based on (the 3-way base / branch point)
- `branch` (string, required): Git ref (branch name or commit) whose committed project.db is the branch intent
- `worker_id` (string): Optional InterCommAIMFP worker identity; the master supplies it

### `file_has_changed` (~35 tokens)

Check if file changed using Git (if available) or filesystem timestamp

Input parameters:

- `file_id` (integer, required): File ID to check

### `finalize_file` (~128 tokens)

Mark a reserved file as tracked after writing it to disk. The path must be a regular file relative to the project root: '.', a directory, or a path leaving the project is refused. Triggers flow assignment and function/type tracking checks.

Input parameters:

- `file_id` (integer, required): Reserved ID
- `language` (string, required): Language
- `name` (string, required): Final name with _id_xx suffix
- `path` (string, required): File path
- `skip_id_naming` (boolean): If true, skip _id_XX pattern validation (for files where ID naming was skipped during reservation)

### `finalize_files` (~75 tokens)

Batch-finalize multiple reserved files after writing them to disk. All-or-nothing operation. Each path must be a regular file relative to the project root ('.' or a directory is refused).

Input parameters:

- `files` (array, required): Array of file objects [{file_id, name, path, language, skip_id_naming?}, ...]

### `finalize_function` (~120 tokens)

Mark a reserved function as tracked after writing it. Triggers interaction and type-function relationship checks.

Input parameters:

- `file_id` (integer, required): File ID
- `function_id` (integer, required): Reserved function ID
- `name` (string, required): Final name with _idxx suffix
- `parameters` (array): Function parameters
- `purpose` (string): Function purpose
- `returns` (object): Return value specification
- `skip_id_naming` (boolean): If true, skip _id_XX pattern validation (for functions where ID naming was skipped during reservation)

### `finalize_functions` (~61 tokens)

Batch-finalize multiple reserved functions after writing them. Triggers interaction and type-function checks for all.

Input parameters:

- `functions` (array, required): Array of function objects [{function_id, name, file_id, purpose, parameters, returns, skip_id_naming?}, ...]

### `finalize_type` (~115 tokens)

Finalize reserved type after creation

Input parameters:

- `definition_json` (object, required): ADT definition
- `description` (string): Type description
- `file_id` (integer): File ID where type is defined
- `links` (object): Links to related functions
- `name` (string, required): Final name with _idxx suffix
- `skip_id_naming` (boolean): If true, skip _id_XX pattern validation (for types where ID naming was skipped during reservation)
- `type_id` (integer, required): Reserved type ID

### `finalize_types` (~48 tokens)

Finalize multiple reserved types

Input parameters:

- `types` (array, required): Array of type objects [{type_id, name, definition_json, description, links, file_id, skip_id_naming?}, ...]

### `find_directive_by_intent` (~69 tokens)

Match a natural-language user request to the most relevant directive(s). Use when the user describes what they want and you need to find which directive handles it.

Input parameters:

- `threshold` (number): Confidence threshold
- `user_request` (string, required): User's natural language request describing behavior to change

### `find_directives_by_intent_keyword` (~60 tokens)

Find directive IDs matching one or more intent keywords (direct keyword lookup)

Input parameters:

- `keywords` (required): Single keyword string or array of keywords
- `match_mode` (string): "any" for OR logic, "all" for AND logic

### `get_active_user_directives` (~28 tokens)

Get all user directives with status='active'. Convenience query for checking active directive count.

### `get_all_completion_paths` (~32 tokens)

Get the project's ordered completion roadmap (stages from setup through completion). Each path contains milestones which contain tasks.

### `get_all_directive_keywords` (~25 tokens)

Get list of all unique intent keywords available for searching (simple list)

### `get_all_directive_names` (~80 tokens)

Get list of all directive names (or filtered by types). Returns names only, NOT full directive data. AI queries by name when needs details.

Input parameters:

- `types` (array): Optional array of directive types to filter: ['fp', 'project', 'git', 'user_preferences', 'user_system']. If not provided, returns ALL directive names.

### `get_all_directives` (~20 tokens)

Load all directives for caching (special orchestrator)

### `get_all_flows` (~114 tokens)

Get project flows (architectural groupings describing intended behavior): all of them, or the ones in flow_ids. Lean by default (descriptions null); detail_level='full' for descriptions. Check BEFORE starting any task to understand the architecture.

Input parameters:

- `detail_level` (string): 'lean' (default): descriptions are null. 'full': descriptions included.
- `flow_ids` (array): Only these flows, ordered by ID. IDs with no flow are named in return_statements. Omit for every flow.

### `get_all_infrastructure` (~34 tokens)

Get all infrastructure entries including standard fields (even if empty). Returns complete infrastructure table for session bundling and status reports.

### `get_all_intent_keywords_with_counts` (~24 tokens)

Get all unique intent keywords with usage counts for analytics

### `get_all_modules` (~26 tokens)

Get all modules in the project. Returns list of all module records sorted by name.

### `get_all_themes` (~30 tokens)

Get all project themes (high-level architectural areas). Use to orient on project structure before starting work.

### `get_categories` (~13 tokens)

Get all directive categories

### `get_category_by_name` (~29 tokens)

Get category by name (fairly frequent)

Input parameters:

- `category_name` (string, required): Category name

### `get_claude_permissions` (~180 tokens)

Returns the Claude Code allowlist (.claude/settings.local.json contents) that pre-approves every AIMFP MCP tool, so the user is not prompted once per tool on first use. Allowlist is derived live from the tool registry so it can never drift. Does NOT write any file — returns ready-to-write JSON + target path; the AI writes/merges it, keeping AIMFP's 'never write outside .aimfp-project/' guarantee intact. Call when the user asks to set up AIMFP permissions or skip approval prompts.

Input parameters:

- `existing_settings` (string): Current text of the project's .claude/settings.local.json if it already exists (read it and pass it in). When given, the result is a merge that preserves all non-AIMFP permissions and other top-level…

### `get_completion_loop_target` (~30 tokens)

Get where to loop back after completing directive

Input parameters:

- `from_directive` (string, required): Directive name

### `get_completion_paths_by_status` (~34 tokens)

Get completion paths filtered by status

Input parameters:

- `status` (string, required): 'pending', 'in_progress', 'completed'

### `get_core_fields` (~28 tokens)

Get field names and types for a specific table

Input parameters:

- `table` (string, required): Table name

### `get_core_schema` (~21 tokens)

Get complete schema for core database (all tables and fields)

### `get_core_tables` (~16 tokens)

List all tables in core database

### `get_current_branch` (~15 tokens)

Get current Git branch name

### `get_current_commit_hash` (~17 tokens)

Get current Git HEAD commit hash

### `get_current_progress` (~145 tokens)

Single entry point for scoped project status queries. Replaces 5-10 separate helper calls with one flexible query.

Input parameters:

- `detail_level` (string): 'minimal' (counts), 'lean' (default: key columns, open work first, 50 rows), 'full' (every column, every row). 'standard' is accepted as 'lean'.
- `filters` (object): WHERE-like conditions: {field: value} or {field: {operator: value}}
- `scope` (string): What to retrieve: 'tasks', 'milestones', 'completion_paths', 'files', 'functions', 'flows', 'themes', 'infrastructure', 'all'

### `get_databases` (~18 tokens)

Get list of all available databases with metadata

### `get_directive_by_name` (~92 tokens)

Load a directive's workflow steps, preferences, and linked notes by name. ALWAYS call BEFORE executing any workflow — directives are the authoritative source, not memory.

Input parameters:

- `directive_name` (string, required): Directive name to look up
- `project_root` (string): Project root directory. When provided, also retrieves directive preferences from user_preferences.db and linked notes (send_with_directive=1) from project.db.

### `get_directive_content` (~84 tokens)

Read and return the full MD documentation file for a directive. Resolves the md_file_path from aimfp_core.db to an absolute path within the installed package, reads the file, and returns content + absolute path + token estimate.

Input parameters:

- `directive_name` (string, required): Directive name (e.g., 'fp_purity', 'aimfp_init', 'project_file_write')

### `get_directive_execution_stats` (~148 tokens)

Read execution statistics from directive_executions joined to directive names and statuses, for one user directive or all of them. Includes a derived error_rate per row. This is how the AI sees what the user's automation did while no session was open — executions, successes, errors, average and maximum duration, and the last recorded error. On a database at schema 1.3 or later, each row also carries skip_count, consecutive_skip_count, last_skip_time, last_skip_reason, condition_latched and last_condition_eval_time.

Input parameters:

- `directive_id` (integer): One directive, or omit for all
- `project_root` (string): Project root; defaults to the session root

### `get_directive_flows` (~138 tokens)

General-purpose query for directive flows by category, type, or directive names. Complements the navigation helpers (get_flows_from_directive, get_flows_to_directive, get_wildcard_flows), which answer where a specific directive routes.

Input parameters:

- `flow_category` (string): Filter by category: 'project', 'fp', 'user_preferences', 'git'
- `flow_type` (string): Filter by type: 'status_branch', 'completion_loop', 'conditional', 'error'
- `from_directive` (string): Filter by source directive name
- `to_directive` (string): Filter by target directive name

### `get_directive_keywords` (~29 tokens)

Get all intent keywords for a specific directive

Input parameters:

- `directive_id` (integer, required): Directive ID

### `get_directives_by_category` (~28 tokens)

Get all directives in a category

Input parameters:

- `category_name` (string, required): Category name

### `get_directives_by_type` (~65 tokens)

Get all directives filtered by type (orchestration vs reference)

Input parameters:

- `include_md_content` (boolean): Include full MD file content
- `type` (string, required): One of: 'fp', 'project', 'git', 'user_system', 'user_preference'

### `get_directives_for_helper` (~34 tokens)

Get all directives that use a helper (reciprocal lookup)

Input parameters:

- `helper_name` (string, required): Helper name

### `get_directives_with_intent_keywords` (~69 tokens)

Search directives by intent keywords and return full directive objects

Input parameters:

- `include_keyword_matches` (boolean): Include which keywords matched
- `keywords` (required): Single keyword or array of keywords
- `match_mode` (string): "any" for OR logic, "all" for AND logic

### `get_file_by_name` (~59 tokens)

Look up a tracked file by name — use BEFORE reading source files. Returns metadata, path, and ID for follow-up queries.

Input parameters:

- `file_name` (string, required): File name to look up (e.g., 'calculator_id_42.py')

### `get_file_by_path` (~56 tokens)

Look up a tracked file by path — use BEFORE reading source files. Returns file metadata and ID for follow-up queries.

Input parameters:

- `file_path` (string, required): File path to look up (e.g., 'src/calculator.py')

### `get_file_ids_from_flows` (~40 tokens)

Get all file IDs associated with flows

Input parameters:

- `flow_ids` (array, required): Array of flow IDs [1, 3, 5]

### `get_files_by_flow` (~27 tokens)

Get all files for a flow

Input parameters:

- `flow_id` (integer, required): Flow ID

### `get_files_by_flow_context` (~39 tokens)

Get all files for a flow with functions embedded in each file dict.

Input parameters:

- `flow_id` (integer, required): Flow ID to get files for

### `get_flow_by_name` (~32 tokens)

Get flow by name (fairly frequent)

Input parameters:

- `flow_name` (string, required): Flow name to look up

### `get_flows_for_file` (~28 tokens)

Get all flows for a file

Input parameters:

- `file_id` (integer, required): File ID

### `get_flows_for_milestone` (~50 tokens)

Get the flows a milestone builds or changes (id, name, description). Use for task flow_ids and before starting milestone work.

Input parameters:

- `milestone_id` (integer, required): Milestone ID

### `get_flows_for_theme` (~28 tokens)

Get all flows for a theme

Input parameters:

- `theme_id` (integer, required): Theme ID

### `get_flows_from_directive` (~45 tokens)

Get all flows originating from a directive (what comes next?). Returns raw flow data - AI evaluates conditions.

Input parameters:

- `from_directive` (string, required): Source directive name

### `get_flows_to_directive` (~43 tokens)

Get all directive flows leading to a directive (what leads here?). Useful for understanding directive prerequisites.

Input parameters:

- `to_directive` (string, required): Target directive name

### `get_fp_directive_index` (~27 tokens)

Get lightweight FP directive index grouped by category (names only, not full definitions)

### `get_from_core` (~53 tokens)

Get records by ID(s), or all records if empty array

Input parameters:

- `id_array` (array, required): Array of integer IDs to fetch, **empty array [] returns ALL records**
- `table` (string, required): Table name

### `get_from_core_where` (~90 tokens)

Flexible filtering with structured JSON conditions

Input parameters:

- `conditions` (object, required): Field-value pairs (AND logic), e.g., `{"type": "fp", "category": "purity"}`
- `limit` (integer): Maximum rows to return
- `orderby` (string): Sort order, e.g., "name ASC" or "id DESC"
- `table` (string, required): Table name

### `get_from_project` (~53 tokens)

Get records by ID(s) - **EMPTY ARRAY NOT ALLOWED**

Input parameters:

- `id_array` (array, required): Array of integer IDs - **MUST contain at least one ID**
- `table` (string, required): Table name

### `get_from_project_where` (~60 tokens)

Flexible filtering with structured JSON conditions

Input parameters:

- `conditions` (object, required): Field-value pairs (AND logic)
- `limit` (integer): Maximum rows to return
- `orderby` (string): Sort order
- `table` (string, required): Table name

### `get_from_settings` (~53 tokens)

Get records by ID(s) - **EMPTY ARRAY NOT ALLOWED**

Input parameters:

- `id_array` (array, required): Array of integer IDs - **MUST contain at least one ID**
- `table` (string, required): Table name

### `get_from_settings_where` (~43 tokens)

Flexible filtering with structured JSON conditions

Input parameters:

- `conditions` (object, required): Field-value pairs (AND logic)
- `table` (string, required): Table name in user_preferences.db

### `get_from_user_custom` (~64 tokens)

Get records by ID(s) from user_directives.db - **EMPTY ARRAY NOT ALLOWED**

Input parameters:

- `id_array` (array, required): Array of integer IDs - **MUST contain at least one ID**
- `table` (string, required): Table name in user_directives.db

### `get_from_user_custom_where` (~52 tokens)

Flexible filtering with structured JSON conditions on user_directives.db tables

Input parameters:

- `conditions` (object, required): Field-value pairs combined with AND logic
- `table` (string, required): Table name in user_directives.db

### `get_function_by_name` (~139 tokens)

Look up a tracked function by name with file location — use BEFORE reading source files. Returns purpose, parameters, returns, and file path.

Input parameters:

- `details_only` (boolean): If true, return only id/name + purpose/parameters/returns (when AI already has the rest)
- `file_id` (integer): Only the function defined in this tracked file.
- `file_path` (string): Only the function defined in this project-relative file (names are not unique across files).
- `function_name` (string, required): Function name to look up
- `include_details` (boolean): If false, omit purpose/parameters/returns for lightweight listing

### `get_functions_by_file` (~96 tokens)

Get all tracked function signatures for a file — use BEFORE reading source code. Often provides everything needed without opening the file.

Input parameters:

- `details_only` (boolean): If true, return only id/name + purpose/parameters/returns (when AI already has the rest)
- `file_id` (integer, required): File ID to get functions for
- `include_details` (boolean): If false, omit purpose/parameters/returns for lightweight listing

### `get_git_status` (~19 tokens)

Get comprehensive Git state snapshot (orchestrator)

### `get_helper_by_name` (~32 tokens)

Get specific helper function details (high-frequency)

Input parameters:

- `helper_name` (string, required): Helper name to look up

### `get_helpers_are_sub` (~21 tokens)

Get all sub-helpers (is_sub_helper=true)

### `get_helpers_are_tool` (~19 tokens)

Get all MCP tools (is_tool=true)

### `get_helpers_by_database` (~40 tokens)

Get all helpers for a specific database

Input parameters:

- `target_database` (string, required): Database name ('core', 'project', 'settings', 'user_custom')

### `get_helpers_for_directive` (~70 tokens)

Get the list of MCP tools available for a directive workflow. Use to discover which tools to call when executing a directive's steps.

Input parameters:

- `directive_name` (string, required): Name of the directive to get helpers for
- `include_helpers_data` (boolean): If true, includes full helper_functions data

### `get_hooks` (~136 tokens)

Get AIMFP's library surface for code running OUTSIDE AIMFP (src/aimfp/hooks/). Hooks are NOT MCP tools and you cannot call them — they are imported by code that is not AIMFP, such as a generated Use Case 2 automation runner firing from cron or systemd with no AI session open. Your relationship to a hook is that you WRITE CODE CALLING IT during user_directive_implement. Queries is_hook=1 affirmatively; it replaced get_helpers_not_tool_not_sub, which described hooks as the absence of two other flags and so returned an empty list silently for as long as nothing populated that gap.

### `get_incomplete_completion_paths` (~18 tokens)

Get all non-completed paths

### `get_incomplete_items` (~51 tokens)

Get incomplete items for any parent type

Input parameters:

- `for_id` (integer, required): Parent ID
- `for_table` (string, required): "tasks", "subtasks", "sidequests" (accepts singular)

### `get_incomplete_milestones` (~78 tokens)

Get all non-completed milestones

Input parameters:

- `detail_level` (string): 'lean' (default): descriptions are null. 'full': descriptions included.
- `include_task_counts` (boolean): Attach task_counts to each milestone: {pending, in_progress, blocked, completed, total} (zeros included), from one grouped query.

### `get_incomplete_sidequests` (~19 tokens)

Get all non-completed sidequests

### `get_incomplete_subtasks` (~19 tokens)

Get all non-completed subtasks

### `get_incomplete_subtasks_by_task` (~31 tokens)

Get incomplete subtasks for specific task

Input parameters:

- `task_id` (integer, required): Task ID

### `get_incomplete_tasks` (~88 tokens)

Get all unfinished tasks (pending, in_progress, blocked) as flat task rows. Does NOT include subtasks, sidequests or items: use get_open_work for the whole open tree (tasks with their open items and subtasks, plus sidequests) in one call.

Input parameters:

- `detail_level` (string): 'lean' (default): descriptions are null. 'full': descriptions included.

### `get_incomplete_tasks_by_milestone` (~58 tokens)

Get open tasks for a milestone with related subtasks/sidequests

Input parameters:

- `milestone_id` (integer, required): ID of the milestone to query tasks for
- `skip_pending` (boolean): If true, excludes pending tasks

### `get_infrastructure_by_type` (~46 tokens)

Get all infrastructure of specific type

Input parameters:

- `type` (string, required): Infrastructure type (e.g., 'language', 'package', 'testing', 'database', 'build_tool')

### `get_interactions_by_file` (~100 tokens)

Get all interactions involving functions in a file or a set of files (file_ids), each with source and target function names and file paths — one call for a feature's whole dependency picture.

Input parameters:

- `file_id` (integer): File ID to look up interactions for
- `file_ids` (array): Several file IDs at once (combined with file_id): every edge touching any of them, each once, with source/target names and paths.

### `get_interactions_by_function` (~92 tokens)

Get all interactions for a function (both as source and target) — trace dependency graphs

Input parameters:

- `file_path` (string): With function_name: only the function defined in this project-relative file.
- `function_id` (integer): Exact function ID (takes precedence over function_name).
- `function_name` (string): Function name to look up (all functions with that name unless file_path narrows it).

### `get_items_for_sidequest` (~50 tokens)

Get items for sidequest

Input parameters:

- `sidequest_id` (integer, required): Sidequest ID
- `status` (string): 'pending', 'in_progress', 'completed' (NULL = all)

### `get_items_for_subtask` (~50 tokens)

Get items for subtask

Input parameters:

- `status` (string): 'pending', 'in_progress', 'completed' (NULL = all)
- `subtask_id` (integer, required): Subtask ID

### `get_items_for_task` (~51 tokens)

Get items for task, optionally filtered by status

Input parameters:

- `status` (string): 'pending', 'in_progress', 'completed' (NULL = all)
- `task_id` (integer, required): Task ID

### `get_merge_history` (~142 tokens)

(For use with InterCommAIMFP) Read tool over the existing merge_history and work_branches tables: which branches were integrated, when, with how many conflicts, by whom. Lets the master answer 'has this branch already been applied?' (idempotency / resume after interruption) and gives a human an audit trail. Pure read; small surface over data merge_worker_branch records.

Input parameters:

- `branch` (string): Optional source-branch filter (exact match on merge_history.source_branch and work_branches.branch_name)
- `since` (string): Optional ISO timestamp lower bound on merge_history.merge_timestamp (e.g. '2026-06-26')

### `get_milestones_by_path` (~91 tokens)

Get all milestones for a completion path

Input parameters:

- `completion_path_id` (integer, required): Completion path ID
- `detail_level` (string): 'lean' (default): descriptions are null. 'full': descriptions included.
- `include_task_counts` (boolean): Attach task_counts to each milestone: {pending, in_progress, blocked, completed, total} (zeros included), from one grouped query.

### `get_milestones_by_status` (~96 tokens)

Get milestones filtered by status

Input parameters:

- `detail_level` (string): 'lean' (default): descriptions are null. 'full': descriptions included.
- `include_task_counts` (boolean): Attach task_counts to each milestone: {pending, in_progress, blocked, completed, total} (zeros included), from one grouped query.
- `status` (string, required): 'pending', 'in_progress', 'completed', 'blocked'

### `get_module_by_name` (~39 tokens)

Get module by name. Returns module record with path, purpose, and external_dependencies.

Input parameters:

- `name` (string, required): Module name to look up

### `get_module_by_path` (~28 tokens)

Get module by directory path.

Input parameters:

- `path` (string, required): Directory path to look up

### `get_module_dependencies` (~51 tokens)

Get cross-module dependencies. Finds interactions where a function in this module calls a function in a different module via module_files junction. Returns aggregated counts per target module.

Input parameters:

- `module_id` (integer, required): Module ID

### `get_module_files` (~32 tokens)

Get all files assigned to a module via module_files junction table.

Input parameters:

- `module_id` (integer, required): Module ID

### `get_module_for_file` (~39 tokens)

Find which module a file belongs to. Reverse lookup via module_files junction table.

Input parameters:

- `file_id` (integer, required): File ID to look up

### `get_module_functions` (~37 tokens)

Get all functions in module files. Joins through module_files junction to files to functions.

Input parameters:

- `module_id` (integer, required): Module ID

### `get_module_types` (~37 tokens)

Get all types in module files. Joins through module_files junction to files to types.

Input parameters:

- `module_id` (integer, required): Module ID

### `get_next_completion_path` (~19 tokens)

Get lowest order_index with status != completed

### `get_notes_comprehensive` (~227 tokens)

Query notes with structured filters (id, type, reference, source, severity, directive). Use note_id to read one note in full, e.g. after search_notes returned a preview.

Input parameters:

- `directive_name` (string): Filter by directive name
- `exclude_note_types` (array): List of note_type values to exclude from results (e.g., ['completed', 'obsolete'])
- `limit` (integer): Maximum notes returned, newest first (default: all)
- `note_id` (integer): Exact note ID — returns that single note with full content. Errors if not found or excluded by other filters
- `note_type` (string): Filter by note_type
- `preview_chars` (integer): Cap each note's content at this many characters (default: full content)
- `reference_id` (integer): Filter by reference ID
- `reference_table` (string): Filter by reference table
- `severity` (string): Filter by severity ('info', 'warning', 'error')
- `source` (string): Filter by source ('ai', 'user', 'directive')

### `get_open_work` (~130 tokens)

Every open task (pending, in_progress, blocked) with its open items and open subtasks (each with open items), plus open sidequests with their open items, in one read-only call. Ordered in_progress first, then by priority. Replaces get_incomplete_tasks followed by one get_items_for_task per task.

Input parameters:

- `include_descriptions` (boolean): Add truncated descriptions to each task, subtask and sidequest. Off keeps the payload small.
- `milestone_id` (integer): Limit to tasks of one milestone (and their subtasks and sidequests). Omit for all open work.

### `get_pending_notices` (~105 tokens)

Get one-time release notices this project has not yet been shown. Returns ONLY unacknowledged notices, already filtered for applicability — a notice pinned to a schema version stays hidden until that database has actually reached it. An empty result is the normal steady state. Called automatically by aimfp_run(is_new_session=true), which puts the result in data.notices and omits the key entirely when nothing is pending, so you never need to call this yourself in a normal session.

### `get_project` (~15 tokens)

Get project metadata (single entry)

### `get_project_fields` (~32 tokens)

Get field names and types for a specific table

Input parameters:

- `table` (string, required): Table name to get fields for

### `get_project_json_parameters` (~37 tokens)

Get available fields for table to use with generic add/update operations

Input parameters:

- `table` (string, required): Table name to get available fields for

### `get_project_root` (~17 tokens)

Get project root directory from infrastructure table

### `get_project_schema` (~16 tokens)

Get complete schema for project database

### `get_project_tables` (~16 tokens)

List all tables in project database

### `get_recent_directive_errors` (~131 tokens)

Tail the JSON-lines directive error log, newest first, optionally filtered to one directive. Each record carries directive_id, error_type, message, timestamp, and a full traceback when the failure came from a handler exception. The database keeps only the last error per directive (store_last_error_only defaults to 1), so this file is the only place error history survives.

Input parameters:

- `directive_id` (integer): Filter to one directive, or omit for all
- `limit` (integer): Maximum records to return, newest first
- `project_root` (string): Project root; defaults to the session root

### `get_settings_fields` (~32 tokens)

Get field names and types for a specific table

Input parameters:

- `table` (string, required): Table name to get fields for

### `get_settings_json_parameters` (~37 tokens)

Get available fields for table to use with generic add/update operations

Input parameters:

- `table` (string, required): Table name to get available fields for

### `get_settings_schema` (~17 tokens)

Get complete schema for user settings database

### `get_settings_tables` (~17 tokens)

List all tables in user settings database

### `get_sidequest_files` (~88 tokens)

Get the files worked on for a sidequest (task_files junction). Files are linked automatically when reserved, finalized, cataloged, or updated (and when their functions/types are finalized, cataloged, or updated) while a work item is in_progress — the most recent in_progress sidequest, else subtask, else task.

Input parameters:

- `sidequest_id` (integer, required): Sidequest ID

### `get_sidequest_flows` (~31 tokens)

Get flow IDs for a sidequest

Input parameters:

- `sidequest_id` (integer, required): Sidequest ID

### `get_sidequests_comprehensive` (~123 tokens)

Advanced sidequest search

Input parameters:

- `date_range_created` (array): [start_date, end_date]
- `date_range_updated` (array): [start_date, end_date]
- `limit` (integer): Maximum results
- `priority` (string): 'low', 'medium', 'high', 'critical'
- `status` (string): 'pending', 'in_progress', 'completed', 'blocked' (NULL = all)
- `subtask_id` (integer): Filter by paused subtask
- `task_id` (integer): Filter by paused task

### `get_source_directory` (~17 tokens)

Get project source directory from infrastructure table

### `get_state_operations_template` (~41 tokens)

Return the Python state_operations.py template content for AI to adapt to the project's language. Use this to retrieve the CRUD helper template for .state/runtime.db.

### `get_structure_health` (~127 tokens)

Report the project's modularity layer and every gap in it: themes -> flows -> files, open paths -> themes, open milestones -> flows, module membership. Gaps: flows without theme, themes without flows, files without flow (and no no_flow_reason), files under a module path but in no module, open paths without themes, open milestones without flows, oversized flow descriptions (split candidates). The same report appears in aimfp_status, aimfp_end and watchdog reminders.

Input parameters:

- `include_summary` (boolean): Also return the themes/flows/paths/milestones map (default true)

### `get_subtasks_by_task` (~56 tokens)

Get subtasks for task, optionally filtered by status

Input parameters:

- `status` (string): 'pending', 'in_progress', 'completed', 'blocked' (NULL = all)
- `task_id` (integer, required): Task ID

### `get_subtasks_comprehensive` (~108 tokens)

Advanced subtask search

Input parameters:

- `date_range_created` (array): [start_date, end_date]
- `date_range_updated` (array): [start_date, end_date]
- `limit` (integer): Maximum results
- `priority` (string): 'low', 'medium', 'high', 'critical'
- `status` (string): 'pending', 'in_progress', 'completed', 'blocked' (NULL = all)
- `task_id` (integer): Filter by task

### `get_supportive_context` (~126 tokens)

Returns supportive context reference documents by variant. All variants auto-provided: core + coding by aimfp_run(is_new_session=true) for initialized projects, case2 by aimfp_run when Case 2 active, init by aimfp_init(). Also callable on demand to reload stale context.

Input parameters:

- `variant` (string): Which context to load: 'core' (workflow, routing, edge cases — default), 'init' (discovery depth, initialization), 'coding' (file loop, DRY, interactions, types), 'case2' (Use Case 2 pipeline)

### `get_system_prompt` (~194 tokens)

Returns the AIMFP system prompt (AIMFP's record-keeping backbone) plus where and how to place it. The user's FIRST move — especially for plugin installs where nothing was downloaded — is to ask the AI to add the AIMFP system prompt; the AI calls this and writes the file. Does NOT write anything: returns the prompt text + target path + placement policy; the AI does the write, keeping AIMFP's 'never write outside .aimfp-project/' guarantee. AIMFP content is always placed FIRST; if the existing instructions file is extensive the AI must review/consolidate with the user instead of blindly prepending.

Input parameters:

- `existing_content` (string): Current text of the target instructions file (e.g. CLAUDE.md) if it already exists — read it and pass it in so the placement guidance can account for size/consolidation. Omit/empty if there is no exi…

### `get_task_context` (~257 tokens)

Get complete context for resuming work on a specific task/subtask/sidequest. Single call retrieves item + associated items + linked files + their functions and modules + flows + optionally interactions and notes. Files are linked automatically when reserved, finalized, cataloged, or updated (and when their functions/types are finalized, cataloged, or updated) while a work item is in_progress — the most recent in_progress sidequest, else subtask, else task. A task's context includes its subtasks' files. Uses cached project root internally.

Input parameters:

- `detail_level` (string): 'lean' (default): the work item in full; items with descriptions only while open; flows id/name; files with their functions as id/name; modules id/name/path/purpose. 'full': every record as stored (f…
- `include_history` (boolean): Include note history for task
- `include_interactions` (boolean): Include function dependency interactions
- `task_id` (integer, required): ID of the task/subtask/sidequest
- `task_type` (string): Type of task: 'task', 'subtask', 'sidequest'. Auto-detected from task_id if omitted.

### `get_task_files` (~92 tokens)

Get the files worked on for a task, including files linked to its subtasks (task_files junction). Files are linked automatically when reserved, finalized, cataloged, or updated (and when their functions/types are finalized, cataloged, or updated) while a work item is in_progress — the most recent in_progress sidequest, else subtask, else task.

Input parameters:

- `task_id` (integer, required): Task ID

### `get_task_flows` (~46 tokens)

Get the architectural flow IDs for a task. Use to understand which part of the codebase a task touches and find relevant files.

Input parameters:

- `task_id` (integer, required): Task ID

### `get_tasks_by_milestone` (~88 tokens)

Get the tasks of a milestone (any status, or one status with status=...). Lean by default: descriptions null.

Input parameters:

- `detail_level` (string): 'lean' (default): descriptions are null. 'full': descriptions included.
- `milestone_id` (integer, required): Milestone ID
- `status` (string): Only tasks with this status. Omit for every status.

### `get_tasks_comprehensive` (~109 tokens)

Advanced task search with multiple filters

Input parameters:

- `date_range_created` (array): [start_date, end_date]
- `date_range_updated` (array): [start_date, end_date]
- `limit` (integer): Maximum results
- `milestone_id` (integer): Filter by milestone
- `priority` (string): 'low', 'medium', 'high', 'critical'
- `status` (string): 'pending', 'in_progress', 'completed', 'blocked' (NULL = all)

### `get_theme_by_name` (~32 tokens)

Get theme by name (fairly frequent)

Input parameters:

- `theme_name` (string, required): Theme name to look up

### `get_themes_for_flow` (~28 tokens)

Get all themes for a flow

Input parameters:

- `flow_id` (integer, required): Flow ID

### `get_themes_for_path` (~37 tokens)

Get the themes a completion path advances (id, name, description).

Input parameters:

- `completion_path_id` (integer, required): Completion path ID

### `get_tracking_notes` (~74 tokens)

Get tracking notes with optional filters

Input parameters:

- `directive_name` (string): Filter by directive_name
- `note_type` (string): Filter by note_type
- `reference_name` (string): Filter by reference_name
- `reference_type` (string): Filter by reference_type
- `severity` (string): Filter by severity

### `get_tracking_settings` (~15 tokens)

Get all tracking feature flags

### `get_type_by_name` (~99 tokens)

Look up a tracked type by name with full definition and file location — use BEFORE reading source files. Returns definition_json and description.

Input parameters:

- `details_only` (boolean): If true, return only id/name + definition_json/description/links (when AI already has the rest)
- `include_details` (boolean): If false, omit definition_json/description/links for lightweight listing
- `type_name` (string, required): Type name to look up

### `get_unassigned_files` (~38 tokens)

Find files not assigned to any module. Useful for identifying tracking gaps — domain logic files that should belong to a module but haven't been assigned.

### `get_user_custom_fields` (~38 tokens)

Get field names and types for a specific table in user_directives.db

Input parameters:

- `table` (string, required): Table name to get fields for

### `get_user_custom_json_parameters` (~48 tokens)

Get available fields for table to use with generic add/update operations. Returns field names, types, and whether required.

Input parameters:

- `table` (string, required): Table name to get available fields for

### `get_user_custom_schema` (~19 tokens)

Get complete schema SQL for user directives database

### `get_user_custom_tables` (~18 tokens)

List all tables in user directives database

### `get_user_directive_by_name` (~34 tokens)

Get a single user directive by its unique name

Input parameters:

- `name` (string, required): Directive name (exact match)

### `get_user_directive_notes` (~136 tokens)

Get notes from user_directives.db with optional filters. All filters are AND logic. No filters returns all notes.

Input parameters:

- `exclude_note_types` (array): List of note_type values to exclude from results (e.g., ['completed', 'obsolete'])
- `limit` (integer): Maximum number of notes to return (default 100)
- `note_type` (string): Filter by note_type
- `reference_id` (integer): Filter by reference_id
- `reference_name` (string): Filter by reference_name
- `reference_type` (string): Filter by reference_type
- `severity` (string): Filter by severity

### `get_user_setting` (~33 tokens)

Get project-wide user setting by key (fairly frequent)

Input parameters:

- `setting_key` (string, required): Setting key to retrieve

### `get_user_settings` (~30 tokens)

Get all user settings from user_settings table (complements get_user_setting which gets one setting by key)

### `get_wildcard_flows` (~61 tokens)

Get all directive flows from wildcard '*' source (available from ANY context). Includes FP references, utilities, cross-cutting concerns.

Input parameters:

- `flow_type` (string): Optional filter: 'reference_consultation', 'utility', 'conditional', etc.

### `init_user_directives_db` (~42 tokens)

Initialize user_directives.db for Case 2 (custom directive automation) projects. Creates the database from schema. Call when project transitions to Case 2.

### `link_files_to_task` (~164 tokens)

Link files to a task, subtask, or sidequest (task_files junction) so get_task_context and get_task_files return them. Files are linked automatically when reserved, finalized, cataloged, or updated (and when their functions/types are finalized, cataloged, or updated) while a work item is in_progress — the most recent in_progress sidequest, else subtask, else task. Use this for files worked on before the item was in_progress, or to correct a link.

Input parameters:

- `file_ids` (array, required): File IDs to link
- `task_id` (integer, required): ID of the task, subtask, or sidequest
- `task_type` (string): 'task', 'subtask', or 'sidequest' (default 'task')

### `list_active_branches` (~22 tokens)

List all AIMFP work branches from work_branches table

### `list_project_backups` (~65 tokens)

List available backup archives, newest first, with size, modification time, and which targets each one actually contains. Read-only. Call BEFORE restore_project_backup: a backup only holds databases that existed when it was taken, so an older archive may not carry every target you want.

### `load_directive_preferences` (~35 tokens)

Load all active preferences for a directive (high-frequency)

Input parameters:

- `directive_name` (string, required): Directive name to load preferences for

### `merge_worker_branch` (~298 tokens)

(For use with InterCommAIMFP) ONE-CALL branch-ref merge orchestrator: takes a branch name and runs the whole documented sequence internally — export_state_changeset, optional source text-merge (keeping main's project.db, never blob-merging it), then apply_state_changeset — returning only a small result/conflict summary. The ~8k-token changeset never crosses the agent boundary, so a real fan-out stops serializing on the master hand-carrying blobs. Idempotent like apply; records a merge_history row; conflicts are still returned as structured data (never guessed). Mutates the working project.db (after backup) and leaves the source merge uncommitted for you to review and commit.

Input parameters:

- `base_commit` (string): 3-way base / branch point. Default = git merge-base(HEAD, branch)
- `branch` (string, required): Git ref of the worker branch to integrate, e.g. 'aimfp-alice-001'
- `on_conflict` (string): 'report' to apply DB state even if the source merge conflicts, or 'abort' to stop before applying
- `source` (string): 'auto' to also text-merge the branch's SOURCE into main (keeping main's project.db), or 'skip' to merge only DB state
- `worker_id` (string): Optional InterCommAIMFP worker identity (provenance + status hint)

### `merge_worker_branches` (~186 tokens)

(For use with InterCommAIMFP) Batch wrapper over merge_worker_branch: integrate a list of worker branches one at a time, each moving main forward and re-minting against the prior. 'additive-first' ordering lands the low-risk purely-additive branches before any structural/deleting ones. Each branch goes through the full export->source-merge->apply sequence; conflicts are surfaced per branch, never guessed.

Input parameters:

- `branches` (array, required): List of branch names (strings) or {branch, base_commit?, worker_id?} objects to integrate one at a time
- `on_conflict` (string): 'stop' to halt the batch on the first branch that returns conflicts, or 'continue' to integrate the rest
- `order` (string): 'as-listed' or 'additive-first' (branches with no delete/remove ops integrate first)

### `migrate_databases` (~141 tokens)

Migrate all pending project databases to current schema versions, in place. Per database: refuses if another connection has it open, write-locks it, keeps a pre-migration copy at <project folder>/backups/<db>_pre_migration_v<old>_<YYYYMMDD>.db (never overwriting an earlier copy), rebuilds it from the new schema SQL (shared columns via ATTACH), verifies row counts and atomically swaps the rebuilt file in. A count mismatch or any error leaves the original untouched (placed=false, error). Nothing is left in temp folders.

Input parameters:

- `aimfp_folder` (string): AIMFP project directory name

### `move_files_to_flow` (~87 tokens)

Re-point many files from one flow to another in one transaction — the tool for splitting an oversized flow or retiring one. Moves links only; files are never touched. Files not in the source flow are skipped.

Input parameters:

- `file_ids` (array, required): Files to move
- `from_flow_id` (integer, required): Flow they leave
- `to_flow_id` (integer, required): Flow they join

### `move_flows_to_theme` (~81 tokens)

Re-point many flows from one theme to another in one transaction (e.g. when a theme is split or merged). Flows not in the source theme are skipped.

Input parameters:

- `flow_ids` (array, required): Flows to move
- `from_theme_id` (integer, required): Theme they leave
- `to_theme_id` (integer, required): Theme they join

### `plan_disjoint_partitions` (~199 tokens)

(For use with InterCommAIMFP) Compute DISJOINT file/module partitions so parallel workers don't overlap — the cheap complexity lever that converts most semantic conflicts into non-events. Only AIMFP can compute this well because it owns the function->function interaction graph and type-usage edges that define real dependency boundaries. Builds an undirected file-coupling graph (interaction edges + type-usage edges + module co-membership), takes connected components as atomic ownership units (never split), and bin-packs whole components into n_workers balanced partitions. Returns proposed per-worker ownership sets plus shared/contended files. Pure read; a planning aid you may tweak or override.

Input parameters:

- `n_workers` (integer): Number of partitions to pack components into. Omit for one partition per connected component.
- `targets` (array): File paths, module names, or task/milestone slugs to partition. Omit to partition every tracked file.

### `project_allowed_check_constraints` (~63 tokens)

Returns list of allowed values for CHECK constraint enum fields in project.db. Parses schema to extract CHECK(field IN (...)) constraints.

Input parameters:

- `field` (string, required): Field name to get allowed values for
- `table` (string, required): Table name to check for CHECK constraints

### `query_core` (~42 tokens)

Execute complex SQL WHERE clause (advanced, rare use)

Input parameters:

- `query` (string, required): WHERE clause without "WHERE" keyword
- `table` (string, required): Table name

### `query_project` (~42 tokens)

Execute complex SQL WHERE clause (advanced, rare use)

Input parameters:

- `query` (string, required): WHERE clause without "WHERE" keyword
- `table` (string, required): Table name

### `query_project_state` (~165 tokens)

Flexible SQL-like query interface for complex project queries. Provides powerful filtering and joining capabilities without writing raw SQL.

Input parameters:

- `entity` (string, required): Primary table to query: 'tasks', 'subtasks', 'sidequests', 'milestones', 'files', 'functions', 'flows', 'themes', etc.
- `filters` (object): WHERE-like conditions with operators: {field: value} or {field: {op: 'gt', value: 5}}
- `joins` (array): Relations to include via LEFT JOIN: ['milestones', 'files']
- `limit` (integer): Maximum results (pagination)
- `offset` (integer): Skip first N results (pagination)
- `sort` (string): ORDER BY clause: 'field ASC' or 'field DESC'

### `query_settings` (~45 tokens)

Execute complex SQL WHERE clause (advanced, rare use)

Input parameters:

- `table` (string, required): Table name in user_preferences.db
- `where_clause` (string): SQL WHERE clause for filtering

### `query_user_custom` (~54 tokens)

Execute complex SQL WHERE clause on user_directives.db (advanced, rare use)

Input parameters:

- `table` (string, required): Table name in user_directives.db
- `where_clause` (string): WHERE clause without 'WHERE' keyword

### `reconcile_paths` (~363 tokens)

Bring the tracking of changed files up to date in ONE call and one transaction (after a git pull, external edits, or edits made outside reserve/finalize). Per path: an untracked file is cataloged with its functions and types; a tracked file gets functions/types newly present in its source cataloged (existing rows and their prose are never touched) and those no longer in the source reported; a tracked file gone from disk is renamed as declared in renames, else to the one untracked path in the call with the same file name, else reported missing; a legacy row recorded at a folder path ('.' or a directory) is adopted by the one new file with its name instead of being duplicated (reported in files_renamed). Then adds the affected files' call edges (Python), skipping edges already tracked, and reports tracked call edges whose target the caller no longer references, directly or through the untracked same-file helpers it uses (stale_interactions). A tracked _private function is never reported missing just because include_private is false. Never deletes anything. Honours watchdog exclusions.

Input parameters:

- `dry_run` (boolean): Do everything, then roll back: the report is exactly what a real run would do.
- `include_private` (boolean): Also catalog _private functions and types (default true, like scan_source_tree).
- `paths` (array, required): Project-relative paths of files that changed (e.g. from git diff --name-only, or the files you just edited).
- `renames` (array): Moves to apply first, as [{from, to}] project-relative paths. Needed when a file was renamed as well as moved; take them from git diff -M --name-status (R lines). Both paths are reconciled.

### `remove_file_from_flow` (~65 tokens)

Remove a file-flow link from the file_flows junction table. Use when reassigning a file to a different flow or preparing for file deletion.

Input parameters:

- `file_id` (integer, required): File ID to unlink
- `flow_id` (integer, required): Flow ID to unlink from

### `remove_file_from_module` (~54 tokens)

Remove a file from a module. Deletes module_files junction entry. File itself is not deleted.

Input parameters:

- `file_id` (integer, required): File ID to remove
- `module_id` (integer, required): Module ID to remove from

### `remove_files_from_module` (~57 tokens)

Batch remove multiple files from modules. More efficient than multiple remove_file_from_module calls. Skips non-existent entries, reports modules left empty.

Input parameters:

- `links` (array, required): List of [file_id, module_id] tuples to remove

### `remove_flow_themes` (~147 tokens)

Batch-unlink flows from themes. A note is required. Refused (whole batch) if any flow would be left with no theme — link the replacement first, or use move_flows_to_theme.

Input parameters:

- `links` (array, required): Array of [flow_id, theme_id] pairs. One pair links one; many pairs (any mix of flow_ids) apply atomically.
- `note_reason` (string, required): Why the links are removed (required; written as an entry_deletion note on each owner row)
- `note_severity` (string, required): 'info', 'warning', 'error'
- `note_source` (string, required): 'ai', 'user', or 'directive'

### `remove_milestone_flows` (~150 tokens)

Batch-unlink milestones from flows. A note is required. Refused (whole batch) while an open task or sidequest of that milestone still lists the flow in its flow_ids — update those first.

Input parameters:

- `links` (array, required): Array of [milestone_id, flow_id] pairs. One pair links one; many pairs (any mix of milestone_ids) apply atomically.
- `note_reason` (string, required): Why the links are removed (required; written as an entry_deletion note on each owner row)
- `note_severity` (string, required): 'info', 'warning', 'error'
- `note_source` (string, required): 'ai', 'user', or 'directive'

### `remove_path_themes` (~121 tokens)

Batch-unlink completion paths from themes. A note is required.

Input parameters:

- `links` (array, required): Array of [completion_path_id, theme_id] pairs. One pair links one; many pairs (any mix of completion_path_ids) apply atomically.
- `note_reason` (string, required): Why the links are removed (required; written as an entry_deletion note on each owner row)
- `note_severity` (string, required): 'info', 'warning', 'error'
- `note_source` (string, required): 'ai', 'user', or 'directive'

### `reorder_all_completion_paths` (~18 tokens)

Fix gaps and duplicates in order_index

### `reorder_completion_path` (~39 tokens)

Change order_index for a completion path

Input parameters:

- `id` (integer, required): Completion path ID
- `new_order_index` (integer, required): New order position

### `reserve_file` (~261 tokens)

Reserve a file ID before writing code, declaring the flow(s) it implements — part of the mandatory reserve-write-finalize tracking flow. flow_ids is required: a list of flows, or an explicit null for a file with no flow. Returns ID to embed in filename.

Input parameters:

- `flow_ids` (required): REQUIRED. Flow ID(s) this file implements (get_all_flows / get_task_flows / get_flows_for_milestone). Pass null EXPLICITLY only for a file that belongs to no flow (config, data, fixtures, package mar…
- `language` (string, required): Programming language (e.g., 'python', 'javascript', 'typescript')
- `name` (string, required): Preliminary file name (will have _id_xxx appended)
- `no_flow_reason` (string): Why the file belongs to no flow (only with flow_ids=null), e.g. 'build config'. Recorded on the file so structure checks skip it.
- `path` (string, required): File path relative to project root
- `skip_id_naming` (boolean): If true, skip ID embedding in name (for __init__.py, .db files, MCP tools, or user preference). Sets id_in_name=0 in database.

### `reserve_files` (~103 tokens)

Batch-reserve file IDs before writing code, each declaring the flow(s) it implements (flow_ids list, or explicit null for no flow). Atomic: all reserve or none.

Input parameters:

- `files` (array, required): Array of file objects [{name, path, language, flow_ids, skip_id_naming?, no_flow_reason?}, ...]. flow_ids is required per file: a list of flow IDs, or null explicitly for a file with no flow (config,…

### `reserve_function` (~158 tokens)

Reserve a function ID before writing code. Include purpose, parameters, and returns — null fields make functions invisible to future sessions.

Input parameters:

- `file_id` (integer): File ID where the function will be defined (or pass file_path)
- `file_path` (string): Project-relative path of the tracked file, instead of file_id (both given must agree)
- `name` (string, required): Function name (will have _idxxx appended)
- `parameters` (array): Function parameters
- `purpose` (string): Function purpose
- `returns` (object): Return value specification
- `skip_id_naming` (boolean): If true, skip ID embedding in name (for MCP tools, private functions excluded). Sets id_in_name=0 in database.

### `reserve_functions` (~61 tokens)

Batch-reserve function IDs before writing multiple functions. Include purpose/parameters/returns for every function.

Input parameters:

- `functions` (array, required): Array of function objects [{name, file_id | file_path, purpose, parameters, returns, skip_id_naming?}, ...]

### `reserve_type` (~140 tokens)

Reserve a type ID before writing the definition. Include definition_json and description — null fields force full file reads in future sessions.

Input parameters:

- `definition_json` (object, required): ADT definition (e.g., {'type': 'enum', 'variants': ['A', 'B']})
- `description` (string): Type description
- `file_id` (integer): File ID where type is defined
- `links` (object): Links to related functions
- `name` (string, required): Type name (will have _idxxx appended)
- `skip_id_naming` (boolean): If true, skip ID embedding in name. Sets id_in_name=0 in database.

### `reserve_types` (~59 tokens)

Batch-reserve type IDs before writing multiple type definitions. Include definition_json and description for every type.

Input parameters:

- `types` (array, required): Array of type objects [{name, definition_json, description, links, file_id, skip_id_naming?}, ...]

### `restore_project_backup` (~195 tokens)

Restore selected databases from a backup archive, side-by-side rather than in place. Every requested member is extracted to a temporary file FIRST; only once all extractions succeed is anything live touched. The current file is then moved into backups/ as 'replaced-<timestamp>-<filename>' and the restored copy moved into position. Nothing is ever deleted, so the displaced state remains recoverable.

Input parameters:

- `backup_name` (string): Archive to restore from (e.g. 'aimfp-backup-2026-08-09.zip'). Defaults to the most recent. Get valid names from list_project_backups.
- `databases`: Which members to restore: any of 'project', 'user_preferences', 'user_directives', 'blueprint', or 'all'. Accepts a list or comma-separated string. Defaults to everything the archive contains. Be spe…

### `scan_call_graph` (~155 tokens)

Build the interaction graph for already-cataloged functions: which tracked function calls which. Read-only — returns tuples shaped for add_interactions, which does the writing. Run AFTER catalog_files and catalog_functions. Resolution is conservative and strictest-first (explicit import, then same-file, then module alias, then project-wide unique name), following re-export chains through modules that define no functions of their own. Ambiguous targets are dropped and counted rather than guessed at, because a wrong edge sends future refactors chasing dependencies that do not exist.

Input parameters:

- `module_path` (string): Project-relative subtree to limit analysis to. Only the CALLING side is narrowed — functions outside it still resolve as targets, so cross-module edges are never lost.

### `scan_source_tree` (~184 tokens)

Read-only inventory of an existing codebase for adoption into AIMFP tracking. Walks source_directory applying the watchdog's exact exclusion stack (built-in exclusions + watchdog_excluded_* settings + .watchdogignore), extracts signatures, and reports tracked vs untracked. Writes nothing — review the inventory, then register with catalog_files/catalog_functions/catalog_types.

Input parameters:

- `include_nested` (boolean): Include functions defined inside other functions
- `include_private` (boolean): Include underscore-prefixed functions and types
- `module_path` (string): Project-relative subtree to narrow the scan to (e.g. 'src/aimfp/helpers/project'). Defaults to the whole source_directory. Use this to adopt a large codebase one module at a time.
- `untracked_only` (boolean): Report only files with no existing database record. Use on re-scans to see just what is new.

### `search_directives` (~196 tokens)

Find directives by type, category, or keyword when you know the domain but not the exact directive name. Multi-word input is split into words; a row matches if ANY word prefix-matches ("disk space free" finds get_free_disk_space). Rows matching more words rank first. Punctuation is ignored, so no FTS syntax is needed or honored. Common stopwords (the, of, and, ...) are ignored unless the query is nothing but stopwords. Keyword results are ordered by name/description relevance.

Input parameters:

- `category` (string): Directive category filter (e.g., 'purity', 'error_handling', 'task_management')
- `keyword` (string): Free-text search over directive names, descriptions, and intent keywords, one or more words (e.g. 'task decomposition')
- `type` (string): Directive type filter: 'fp', 'project', 'user-system', 'user-pref', 'git'

### `search_functions` (~191 tokens)

Search tracked functions by name or purpose with relevance ranking. Multi-word input is split into words; a row matches if ANY word prefix-matches ("disk space free" finds get_free_disk_space). Rows matching more words rank first. Punctuation is ignored, so no FTS syntax is needed or honored. Common stopwords (the, of, and, ...) are ignored unless the query is nothing but stopwords. Results are capped by limit; total_count reports all matches.

Input parameters:

- `details_only` (boolean): If true, return only id/name + purpose/parameters/returns
- `include_details` (boolean): If false, omit purpose/parameters/returns for lightweight listing
- `limit` (integer): Maximum functions returned, best matches first (default 20)
- `search_string` (string, required): Free-text search over function name and purpose, one or more words (e.g. 'disk space free')

### `search_modules` (~173 tokens)

Search modules by name, purpose, or description with relevance ranking. Multi-word input is split into words; a row matches if ANY word prefix-matches ("disk space free" finds get_free_disk_space). Rows matching more words rank first. Punctuation is ignored, so no FTS syntax is needed or honored. Common stopwords (the, of, and, ...) are ignored unless the query is nothing but stopwords. Results are capped by limit; total_count reports all matches.

Input parameters:

- `detail_level` (string): 'lean' (default): description is null, purpose kept. 'full': description included.
- `limit` (integer): Maximum modules returned, best matches first (default 20)
- `search_string` (string, required): Free-text search over module name, purpose, and description, one or more words

### `search_notes` (~280 tokens)

Search past decisions and context by keyword. Multi-word input is split into words; a row matches if ANY word prefix-matches ("disk space free" finds get_free_disk_space). Rows matching more words rank first. Punctuation is ignored, so no FTS syntax is needed or honored. Common stopwords (the, of, and, ...) are ignored unless the query is nothing but stopwords. Returns capped previews by default; read a note in full with get_notes_comprehensive(note_id=X).

Input parameters:

- `directive_name` (string): Optional filter by directive name
- `exclude_note_types` (array): List of note_type values to exclude from results (e.g., ['completed', 'obsolete'])
- `limit` (integer): Maximum notes returned, best matches first (default 20)
- `note_type` (string): Optional filter by note_type
- `preview_chars` (integer): Cap each note's content at this many characters (default 300; 0 = full content)
- `reference_id` (integer): Optional filter by reference ID
- `reference_table` (string): Optional filter by reference table
- `search_string` (string, required): Free-text search over note content, one or more words (e.g. 'hash digest')
- `severity` (string): Optional filter by severity
- `source` (string): Optional filter by source

### `search_tracking_notes` (~69 tokens)

Search tracking note content with optional filters

Input parameters:

- `directive_name` (string): Optional filter by directive_name
- `note_type` (string): Optional filter by note_type
- `reference_type` (string): Optional filter by reference_type
- `search_string` (string, required): Search string for note content

### `search_types` (~185 tokens)

Search tracked types by name or description with relevance ranking. Multi-word input is split into words; a row matches if ANY word prefix-matches ("disk space free" finds get_free_disk_space). Rows matching more words rank first. Punctuation is ignored, so no FTS syntax is needed or honored. Common stopwords (the, of, and, ...) are ignored unless the query is nothing but stopwords. Results are capped by limit; total_count reports all matches.

Input parameters:

- `details_only` (boolean): If true, return only id/name + definition_json/description/links
- `include_details` (boolean): If false, omit definition_json/description/links for lightweight listing
- `limit` (integer): Maximum types returned, best matches first (default 20)
- `search_string` (string, required): Free-text search over type name and description, one or more words

### `search_user_directive_notes` (~124 tokens)

Search note content in user_directives.db with optional additional filters

Input parameters:

- `exclude_note_types` (array): List of note_type values to exclude from results (e.g., ['completed', 'obsolete'])
- `limit` (integer): Maximum number of notes to return (default 100)
- `note_type` (string): Optional filter by note_type
- `reference_type` (string): Optional filter by reference_type
- `search_string` (string, required): Search string for note content (case-insensitive LIKE match)
- `severity` (string): Optional filter by severity

### `search_user_directives` (~111 tokens)

Search user directives with optional filters. At least one filter required.

Input parameters:

- `domain` (string): Filter by domain (exact match, e.g. 'home_automation', 'aws_infrastructure')
- `name` (string): Filter by directive name (LIKE match, case-insensitive)
- `source_file` (string): Filter by source_file path (LIKE match)
- `status` (string): Filter by status (exact match)
- `trigger_type` (string): Filter by trigger_type (exact match)

### `set_custom_return_statement` (~107 tokens)

Add a custom return statement for a helper function. Extends core return_statements with user-defined guidance, context, or preferences. To modify: delete first, then set new statement.

Input parameters:

- `active` (boolean): Whether statement is active (default true)
- `description` (string): Why this was added (optional context)
- `helper_name` (string, required): Helper function name (should match aimfp_core.db helper_functions.name)
- `statement` (string, required): Custom return statement text

### `summarize_state_changeset` (~168 tokens)

(For use with InterCommAIMFP) Cheap, low-token counts summary of ONE branch's changeset — add/modify/delete per entity kind, add/remove per reference kind, touched files/modules, and warning count — WITHOUT returning the full ~8k-token object. Affordable to read for every pending branch before deciding apply order. Identify the changeset by changeset_id (loads the persisted artifact) or by branch+base_commit (re-exports). Pure read.

Input parameters:

- `base_commit` (string): 3-way base / branch point (used with branch)
- `branch` (string): Git ref whose changeset to summarize (requires base_commit)
- `changeset_id` (string): Handle from a prior export_state_changeset (loads the persisted artifact, no git work)

### `swap_completion_paths_order` (~42 tokens)

Swap order_index of two completion paths

Input parameters:

- `id1` (integer, required): First completion path ID
- `id2` (integer, required): Second completion path ID

### `sync_git_state` (~20 tokens)

Update project.last_known_git_hash with current Git HEAD

### `toggle_tracking_feature` (~36 tokens)

Enable/disable tracking feature

Input parameters:

- `enabled` (boolean, required): Enable or disable
- `feature_name` (string, required): Tracking feature name

### `unlink_files_from_task` (~99 tokens)

Remove file links from a task, subtask, or sidequest — e.g. a file auto-linked to the wrong in_progress item. Does not touch the files.

Input parameters:

- `file_ids` (array, required): File IDs to unlink
- `task_id` (integer, required): ID of the task, subtask, or sidequest
- `task_type` (string): 'task', 'subtask', or 'sidequest' (default 'task')

### `update_completion_path` (~73 tokens)

Update completion path

Input parameters:

- `description` (string): New description (NULL = don't update)
- `id` (integer, required): Completion path ID
- `name` (string): New name (NULL = don't update)
- `status` (string): 'pending', 'in_progress', 'completed' (NULL = don't update)

### `update_directive_preference` (~75 tokens)

Update existing directive preference in directive_preferences table

Input parameters:

- `active` (boolean): Update active status
- `description` (string): Update description
- `directive_name` (string, required): Directive name
- `preference_key` (string, required): Preference key to update (must exist)
- `preference_value` (string): New preference value

### `update_file` (~108 tokens)

Update file metadata

Input parameters:

- `file_id` (integer, required): File ID to update
- `language` (string): Language (NULL = don't update)
- `name` (string): New file name (NULL = don't update)
- `no_flow_reason` (string): Mark the file as belonging to no flow, with why (config, data) — structure checks then skip it. Empty string clears it (NULL = don't update).
- `path` (string): New file path (NULL = don't update)

### `update_flow` (~93 tokens)

Update flow metadata

Input parameters:

- `confidence_score` (number): New confidence score (NULL = don't update)
- `description` (string): What the flow does now; replaces the old text. Not an evolution log: history goes in add_note(note_type='evolution') (NULL = don't update)
- `flow_id` (integer, required): Flow ID to update
- `name` (string): New name (NULL = don't update)

### `update_function` (~82 tokens)

Update function metadata

Input parameters:

- `function_id` (integer, required): Function ID to update
- `name` (string): New function name (NULL = don't update)
- `parameters` (array): New parameters (NULL = don't update)
- `purpose` (string): New purpose (NULL = don't update)
- `returns` (object): New return specification (NULL = don't update)

### `update_function_file_location` (~56 tokens)

Move function to different file (rarely used)

Input parameters:

- `function_id` (integer, required): Function ID to move
- `new_file_id` (integer, required): New file ID
- `old_file_id` (integer, required): Current file ID

### `update_functions_for_file` (~53 tokens)

Update multiple functions in a single file

Input parameters:

- `file_id` (integer, required): File ID
- `functions` (array, required): Array of function update objects [{function_id, name, purpose, parameters, returns}, ...]

### `update_interaction` (~160 tokens)

Update interaction metadata

Input parameters:

- `description` (string): New description (NULL = don't update)
- `interaction_id` (integer, required): Interaction ID to update
- `interaction_type` (string): 'call', 'chain', 'borrow', 'compose', 'pipe' (NULL = don't update)
- `is_indirect` (boolean): Mark (true) or clear (false) the deliberate-indirect flag (NULL = don't update). True for a deliberate edge the code makes indirectly (dispatch through a tuple/table of functions, a chain data-flow l…
- `source_function_id` (integer): New source (NULL = don't update)
- `target_function_id` (integer): New target (NULL = don't update)

### `update_item` (~91 tokens)

Update a single item's status, name, or description. Primary use: marking items in_progress or completed as work progresses.

Input parameters:

- `description` (string): New description (NULL = don't update)
- `id` (integer, required): Item ID
- `name` (string): New name (NULL = don't update)
- `status` (string): 'pending', 'in_progress', 'completed' (NULL = don't update)

### `update_items` (~120 tokens)

Batch-update multiple items with the same field values. Primary use: marking multiple items completed at once when parent completes.

Input parameters:

- `data` (object, required): Field-value pairs to apply to all items (e.g., {status: 'completed'})
- `ids` (array, required): Array of item IDs to update
- `reference_id` (integer, required): ID of the parent task, subtask, or sidequest that owns every item in ids
- `reference_table` (string, required): Parent the items must belong to: 'tasks', 'subtasks', or 'sidequests'

### `update_milestone` (~116 tokens)

Update milestone status, name, or description. When completing, check if all milestones in the path are done to cascade completion.

Input parameters:

- `completion_path_id` (integer): New completion path ID (NULL = don't update)
- `description` (string): New description (NULL = don't update)
- `id` (integer, required): Milestone ID
- `name` (string): New name (NULL = don't update)
- `status` (string): 'pending', 'in_progress', 'completed', 'blocked' (NULL = don't update)

### `update_module` (~79 tokens)

Update module metadata. Only non-None fields are updated.

Input parameters:

- `description` (string): New description
- `external_dependencies` (array): New dependencies list
- `module_id` (integer, required): Module ID to update
- `name` (string): New name
- `path` (string): New path
- `purpose` (string): New purpose

### `update_note` (~188 tokens)

Update note metadata

Input parameters:

- `content` (string): Update note content
- `directive_name` (string): Update directive name
- `id` (integer, required): Note ID to update
- `note_type` (string): Update note_type
- `reference_id` (integer): Update reference ID
- `reference_table` (string): New reference table (NULL = don't update). The project.db table the note is attached to (e.g. 'files', 'tasks', 'flows', 'completion_path'). Must be an existing project.db table name, exactly: unknow…
- `send_with_directive` (boolean): Update send_with_directive flag. If true and directive_name set, note is included when that directive is retrieved.
- `severity` (string): Update severity
- `source` (string): Update source

### `update_project` (~131 tokens)

Update project metadata

Input parameters:

- `goals` (array): Array of goal strings (NULL = don't update)
- `name` (string): Project name (NULL = don't update)
- `purpose` (string): Project purpose (NULL = don't update)
- `status` (string): 'active', 'paused', 'completed', 'abandoned' (NULL = don't update)
- `user_directives_status` (string): NULL, 'pending_discovery', 'pending_parse', 'in_progress', 'active', 'disabled' (NULL = don't update)
- `version` (integer): Version number (NULL = don't update)

### `update_project_entry` (~43 tokens)

Update existing entry

Input parameters:

- `data` (object, required): Field-value pairs to update
- `id` (integer, required): Record ID
- `table` (string, required): Table name

### `update_project_root` (~49 tokens)

Update project root in infrastructure table. Failsafe: Inserts if not exists (should never happen, initialized by SQL).

Input parameters:

- `new_project_root` (string, required): New project root path (absolute path)

### `update_project_state` (~205 tokens)

Orchestrated state change for tasks, milestones, and paths. Maps actions (start_task, complete_task, block_task, etc.) to correct status updates and note creation.

Input parameters:

- `action` (string, required): Operation: 'start_task', 'complete_task', 'pause_task', 'resume_task', 'block_task', 'unblock_task', 'start_subtask', 'complete_subtask', etc.
- `create_note` (boolean): Auto-log action as note in notes table
- `data` (object): Action-specific data (e.g., blocked_by, completion_notes) data.audit_override_reason completes a task/subtask/sidequest despite blocking tracking-audit findings (recorded as a warning note); completi…
- `target_id` (integer, required): ID of target entity
- `target_type` (string, required): Entity type: 'task', 'subtask', 'sidequest', 'milestone', 'completion_path'

### `update_settings_entry` (~53 tokens)

Update entry in user settings database

Input parameters:

- `data` (object, required): Field-value pairs to update
- `record_id` (integer, required): Record ID to update
- `table` (string, required): Table name in user_preferences.db

### `update_sidequest` (~202 tokens)

Update sidequest metadata

Input parameters:

- `audit_override_reason` (string): Complete despite blocking tracking-audit findings in the linked files. Recorded as a warning note with the outstanding counts; use only when the drift is understood and will be fixed in follow-up wor…
- `description` (string): New description (NULL = don't update)
- `flow_ids` (array): Array of flow IDs (NULL = don't update)
- `id` (integer, required): Sidequest ID
- `name` (string): New name (NULL = don't update)
- `paused_subtask_id` (integer): New paused subtask ID (NULL = don't update)
- `paused_task_id` (integer): New paused task ID (NULL = don't update)
- `priority` (string): 'low', 'medium', 'high', 'critical' (NULL = don't update)
- `status` (string): 'pending', 'in_progress', 'completed', 'blocked' (NULL = don't update)

### `update_source_directory` (~30 tokens)

Update existing source directory in infrastructure table

Input parameters:

- `new_source_dir` (string, required): New source directory path

### `update_subtask` (~163 tokens)

Update subtask metadata

Input parameters:

- `audit_override_reason` (string): Complete despite blocking tracking-audit findings in the linked files. Recorded as a warning note with the outstanding counts; use only when the drift is understood and will be fixed in follow-up wor…
- `description` (string): New description (NULL = don't update)
- `id` (integer, required): Subtask ID
- `name` (string): New name (NULL = don't update)
- `priority` (string): 'low', 'medium', 'high', 'critical' (NULL = don't update)
- `status` (string): 'pending', 'in_progress', 'completed', 'blocked' (NULL = don't update)
- `task_id` (integer): New task ID (NULL = don't update)

### `update_task` (~186 tokens)

Update task metadata

Input parameters:

- `audit_override_reason` (string): Complete despite blocking tracking-audit findings in the linked files. Recorded as a warning note with the outstanding counts; use only when the drift is understood and will be fixed in follow-up wor…
- `description` (string): New description (NULL = don't update)
- `flow_ids` (array): Array of flow IDs [1, 3, 5] (NULL = don't update)
- `id` (integer, required): Task ID
- `milestone_id` (integer): New milestone ID (NULL = don't update)
- `name` (string): New name (NULL = don't update)
- `priority` (string): 'low', 'medium', 'high', 'critical' (NULL = don't update)
- `status` (string): 'pending', 'in_progress', 'completed', 'blocked' (NULL = don't update)

### `update_theme` (~68 tokens)

Update theme metadata

Input parameters:

- `confidence_score` (number): New confidence score (NULL = don't update)
- `description` (string): New description (NULL = don't update)
- `name` (string): New name (NULL = don't update)
- `theme_id` (integer, required): Theme ID to update

### `update_type` (~83 tokens)

Update type metadata

Input parameters:

- `definition_json` (object): New definition (NULL = don't update)
- `description` (string): New description (NULL = don't update)
- `file_id` (integer): New file_id (NULL = don't update)
- `name` (string): New name (NULL = don't update)
- `type_id` (integer, required): Type ID to update

### `update_type_function_role` (~68 tokens)

Update relationship role only

Input parameters:

- `function_id` (integer, required): Function ID
- `role` (string, required): 'factory', 'transformer', 'operator', 'pattern_matcher', 'accessor', 'validator', 'combinator'
- `type_id` (integer, required): Type ID

### `update_user_custom_entry` (~138 tokens)

Update entry in user_directives.db table. Every key must be a column of the table (compared without case). On user_directives the approval columns (approved, approved_at, approved_by, approval_hash) and status='active' are refused: approval is a person's decision, recorded by the user's own path (`aimfp directives approve`, or a host calling aimfp.hooks.approval), and activation goes through activate_user_directive.

Input parameters:

- `data` (object, required): Field-value pairs to update
- `record_id` (integer, required): Record ID to update
- `table` (string, required): Table name in user_directives.db

### `update_user_setting` (~68 tokens)

Update existing project-wide user setting in user_settings table

Input parameters:

- `description` (string): New description (optional)
- `scope` (string): New scope (optional)
- `setting_key` (string, required): Setting key to update (must exist)
- `setting_value` (string): New setting value

### `user_directives_allowed_check_constraints` (~67 tokens)

Returns list of allowed values for CHECK constraint enum fields in user_directives.db. Parses schema to extract CHECK(field IN (...)) constraints.

Input parameters:

- `field` (string, required): Field name to get allowed values for
- `table` (string, required): Table name to check for CHECK constraints

### `user_preferences_allowed_check_constraints` (~65 tokens)

Returns list of allowed values for CHECK constraint enum fields in user_preferences.db. Parses schema to extract CHECK(field IN (...)) constraints.

Input parameters:

- `field` (string, required): Field name to get allowed values for
- `table` (string, required): Table name to check for CHECK constraints

### `validate_action_config` (~196 tokens)

Checks an action_config against AIMFP's envelope for its action_type BEFORE the row is written; add_user_custom_entry and update_user_custom_entry refuse a non-conforming config. AIMFP validates the ENVELOPE ONLY. api_call, script_execution and notification are generic, so AIMFP can specify them fully. function_call and command name a target that exists in the caller's own project, so AIMFP checks that a target is named and well-formed but never that it resolves - caller_resolved=true marks exactly that, and means 'the shape is right, now check it resolves'. Unknown keys are errors, not ignored. On failure, errors names every offending key and grammar carries the expected envelope.

Input parameters:

- `action_config` (object, required): The config to check, as an object or a JSON string
- `action_type` (string, required): 'api_call', 'script_execution', 'function_call', 'command', or 'notification'

### `validate_trigger_config` (~194 tokens)

Checks a trigger_config against AIMFP's grammar for its trigger_type BEFORE the row is written. add_user_custom_entry and update_user_custom_entry refuse a non-conforming config, so calling this first turns a rejected insert into a fixed config. Time triggers are a discriminated union on 'kind' (interval/daily/weekly/monthly); event, condition and manual have fixed shapes. Unknown keys are errors, not ignored - a typo'd schedule key is the silent failure this exists to surface, because a schedule that never fires produces no log line and no recorded error. On failure, errors names every offending key and grammar carries the expected shape for that trigger_type, so the AI is told what IS expected rather than guessing.

Input parameters:

- `trigger_config` (object, required): The config to check, as an object or a JSON string
- `trigger_type` (string, required): 'time', 'event', 'condition', or 'manual'

### `verify_fanout_ready` (~130 tokens)

(For use with InterCommAIMFP) Pre-fan-out preflight on current main: cheap insurance against silent fan-out corruption. Asserts (a) every relevant row has a stable identity key (hierarchy slugs + function/type entity_key — i.e. backfill_semantic_keys has nothing left to do), (b) .aimfp-project/project.db is committed (clean working tree for that path) so every clone shares the same base, and (c) no schema migration is pending. Returns {ready, blockers}. Run on main BEFORE spawning workers. Pure read.

## Diagnostics

Captured diagnostic sections: Provenance, Install scripts, Dependencies. The full working is on the page: https://verifymcp.io/servers/aryanduntley-aimfp/aimfp#diagnostics

## Score history

- 2026-11-05: 76
- 2026-11-04: 76
- 2026-11-03: 76
- 2026-11-02: 76
- 2026-11-01: 76
- 2026-10-31: 61

## Common questions

### What is the AIMFP MCP server?

AIMFP is an MCP server listed in the public MCP registry as io.github.aryanduntley/aimfp. Database-driven directives and project tracking for modular functional-procedural AI coding. This page covers its PyPI package (aimfp).

### Is the AIMFP MCP server safe to use?

AIMFP scores 76 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 5 November 2026. Its build provenance is signed and verified. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the AIMFP MCP server expose?

AIMFP exposes 300 tools: acknowledge_notice, activate_user_directive, add_completion_path, add_directive_preference, add_file_flows, and 295 more. Their descriptions and schemas cost roughly 27,909 tokens of context every time the server is loaded.

### Is the AIMFP MCP server still maintained?

AIMFP is still listed as active in the MCP registry. We last reached this channel on 5 November 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

### What licence is the AIMFP MCP server under?

AIMFP declares the PolyForm-Noncommercial-1.0.0 licence, which is not on the OSI-approved list. Read the terms before using it at work, and note this covers the source only, not the cost of any service it calls.

## Links

- PyPI project: https://pypi.org/project/aimfp/
- Socket report: https://socket.dev/pypi/package/aimfp
- Repository: https://github.com/aryanduntley/aimfp
- Changelog RSS feed: https://verifymcp.io/servers/aryanduntley-aimfp/aimfp.xml
- Changelog JSON feed: https://verifymcp.io/servers/aryanduntley-aimfp/aimfp.json
- HTML version of this page: https://verifymcp.io/servers/aryanduntley-aimfp/aimfp