AIMFP

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.

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.

Add completion path stage

Add/update user preference for directive

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

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

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

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

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.

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.

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).

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.

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

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

Add milestone to completion path

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.

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.

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

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

Add new entry to project database

Add entry to user settings database

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

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

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

Add project theme

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

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.

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.

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

Add new project-wide user setting to user_settings table

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.

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

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.

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.

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.

(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.

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.

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.

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.

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.

(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.

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

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

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.

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.

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.

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.

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 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.).

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