AIMFP Supportive Context — Core Reference (get_supportive_context tool)

  1. Modular — every piece of work sits on the map: theme → flow → files → module; domain logic in reusable modules (NON-NEGOTIABLE)
  2. Functional Procedural — pure functions, immutability, no OOP (NON-NEGOTIABLE)
  3. Directive-Driven — workflows loaded from DB, not memory
  4. Database-Driven — DB is source of truth
Four databases: aimfp_core.db (read-only directives/helpers), project.db (files/functions/tasks), user_preferences.db (settings), user_directives.db (Case 2 only).

1. FULL WORKFLOW (directive names in context — use get_directive_by_name() for steps)

  user: "help me create a calculator"

  SESSION START
    1. aimfp_run(is_new_session=true) → session bundle (status summary + this reference, settings,
       and only the sections that need action: notices, due backup, migrations, watchdog, deferred notes)
       .aimfp-project/ missing → offer aimfp_init or restore from backup
       .aimfp-project/ exists → read status → present next actions
       project_continue_on_start=true → auto-continue; otherwise → await user direction
    2. From bundle: cache project status, settings, supportive context
    3. Need directive details? → get_directive_by_name(name)
    4. Need directive routing? → get_flows_from_directive(name)

  INITIALIZATION (new project only — get_supportive_context(variant='init') for detail)
    5. aimfp_init(project_root) → creates dirs, DBs, blueprint template, .git if missing
    6. AI detects language/tools, prompts user → create_project() → update infrastructure
    7. project_discovery → blueprint, themes → flows (add_flow theme_ids) → modules,
       completion paths (theme_ids), milestones (flow_ids) — NO tasks
       Pre-existing FP code? → project_catalog first
    8. Routes to aimfp_status → project_progression

  WORK LOOP (project_progression state machine)
    9. get_all_completion_paths → activate first open path
    10. get_milestones_by_completion_path → activate first open milestone
    11. Create ONE task: add_task(milestone_id, name, flow_ids, priority)
        flow_ids from get_flows_for_milestone; new behaviour → add_flow + add_milestone_flows first
        Create items: add_item(reference_table='tasks', reference_id=<task_id>, name, description) or batch via add_items(reference_table='tasks', reference_id=<task_id>, items=[{name, description}, ...])
    12. Work on items: file coding loop for every file (variant='coding').
        Item done → update_item(id, status='completed') or update_items(ids, data, reference_table, reference_id)
    13. All items done → project_task_complete → update_task(status='completed')
    14. More tasks? → create next (goto 11). No → project_milestone_complete (flow review first)
    15. More milestones? → activate next (goto 10). No → project_completion_check → done
        Alternative: update_project_state(project_root, action, target_type, target_id, data)

  MID-WORK CHANGES
    16. Scope/goals change → update blueprint → add_note(note_type='evolution')
    17. Unexpected work → add_sidequest(paused_task_id, flow_ids, name, priority='critical')
    18. Related sub-work → add_subtask(name, parent_task_id, priority='high')

  USER PREFERENCE CHANGES
    19. Directive behavior change → user_preferences_update → add_directive_preference()
    20. Project-wide setting → add_user_setting / update_user_setting → add_note

  SESSION MANAGEMENT
    aimfp_run(is_new_session=false) → watchdog alerts only (at work checkpoints)
    aimfp_status() → quick position: path, milestone, focus + open items, open work, gap count.
    aimfp_status(type='summary') → full reload after lost/compacted context (includes this reference).
    get_supportive_context(variant) → reload reference material on demand.
    Task completion gate: get_task_context(task_id) → files[] lists files linked to the task; verify each has tracked functions.
    aimfp_end → audit, stop watchdog, log summary.

2. MODULARITY LAYER (the "M" in AIMFP — core, not optional)

  theme   stable project area (changes rarely, like completion paths)
  flow    one behaviour the code implements; ≥ 1 theme; evolves with milestones
  file    declares its flow_ids at reserve (null + no_flow_reason only for config/data)
  module  reusable domain code at a directory seam; feature files compose modules, never hold logic
  Links: completion path → themes, milestone → flows, task/sidequest → flow_ids, file → flows, file → module.

  Before any task: which theme? which flow(s)? which module will the logic live in?
    No fitting flow → add_flow(name, theme_ids) + add_milestone_flows. Never stretch an unrelated flow.
    No fitting module → add_module, after search_modules shows nothing to reuse.
  A flow that grows past one behaviour is split (add_flow + move_files_to_flow) — project_theme_flow_mapping.
  aimfp_status.structure = gaps on the active work; get_structure_health = all gaps. Fix in-session, don't defer.

3. USER REQUEST ROUTING

  Route IN ORDER:
  1. Matches existing task/sidequest/subtask → continue progression
  2. NEW ad-hoc work → project_task_decomposition → create task/sidequest FIRST
  3. Needs a directive workflow → get_directive_by_name(name) FIRST → follow steps
  4. Needs code research → get_file_by_name / get_function_by_name / get_interactions_by_function FIRST
  5. Status/continue/resume → answer from context, call aimfp_status() only if stale

4. AD-HOC WORK & ACCUMULATED CHANGES

  User requests outside current task → project_task_decomposition FIRST.
  Multiple small fixes/requests accumulate into trackable work. After ANY code change:
  did this modify a tracked file? Add a function? Change params/returns/types?
  If YES → AIMFP tracking mandatory immediately. "Small" ≠ "untracked."

5. NOTES REVIEW ON WORK START

  Before beginning any task/sidequest/user request:
    search_notes(search_string=<keywords>, exclude_note_types=['completed','obsolete'])
  Returns capped previews → read a relevant one in full with get_notes_comprehensive(note_id=X).
  aimfp_status(summary).recent_notes is metadata only (type, severity, reference, date): same rule.
  Empty = move on. Hits = review for decisions, deferred work, warnings.
  Handled notes → update_note(note_type='completed' or 'obsolete')
  Single-entity lookups (get_file_by_*, get_function/type/theme/flow/module_by_*, get_task_context) also return
  notes = refs to the notes attached to that entity: read relevant ones before changing it.

6. DIRECTIVE EXECUTION

  ALWAYS load before executing: get_directive_by_name(name).
  Payloads omit keys with nothing to report; a return statement arrives only with the key it is about.
  Pattern: trunk (main analysis) → branches (conditional) → fallback.
  Deep context: get_directive_content(name). Directive flows ≠ project flows.

7. FP DIRECTIVES & STATE DATABASE

  66 FP directives in 18 categories. Find with get_fp_directive_index() or search_directives(type='fp', keyword='...').
  Key categories: purity, immutability, error_handling, composition, side_effects, anti_oop, type_system, testing.
  State database: auto-created via create_state_database. Replaces mutable globals (set_var, get_var, delete_var, increment_var).

8. GIT & EVOLUTION NOTES

  Branch naming: aimfp-{user}-{number}. Git directives: git_init, git_detect_external_changes, git_create_branch, git_detect_conflicts, git_merge_branch, git_sync_state.
  Any change to blueprint/paths/themes/flows/milestones MUST have add_note(note_type='evolution').

9. EDGE CASES & RECOVERY

  Lost context? aimfp_status(type='summary') → state + this reference. get_supportive_context(variant) → reference only.
  search_directives(keyword="...") → find the right directive. aimfp_run(is_new_session=true) → full reload.
  Non-FP projects: STOP and REJECT. AIMFP is FP-only.
  DB policy: helpers FIRST → orchestrators → directives → direct SQL (last resort, reads only). Exception: user_directives.db.

10. ADDITIONAL CONTEXT (auto-provided, reload on demand via get_supportive_context(variant=X))

  variant='init'    — auto-provided with aimfp_init() return. Discovery depth, initialization, post-completion paths
  variant='coding'  — auto-provided with aimfp_run(is_new_session=true) once a milestone exists. File loop, DRY, interactions, types_functions
  variant='case2'   — auto-provided with aimfp_run(is_new_session=true) when Case 2 active. User directive pipeline, preferences

11. USER SETTINGS

  User preferences system: set_custom_return_statement (attach guidance to any helper — fires on every call), add_directive_preference (key-value prefs loaded with get_directive_by_name), add_user_setting (project-wide config), add_user_directive_note (AI interaction notes in user_directives.db). Use custom return statements for session-boundary behaviors, directive preferences for workflow customization, and user settings for project-wide flags/config.

END SUPPORTIVE CONTEXT
