pwa-debug-layer CLAUDE.md

AIMFP MODE ACTIVE — MANDATORY BEHAVIORAL RULES

These rules are NON-NEGOTIABLE. Violating any creates tracking gaps and invisible project damage. Use AIMFP tracking over memory

FIRST — BEFORE ANYTHING ELSE

CALL aimfp_run(is_new_session=true)

• Your FIRST ACTION every session no matter how user begins their initial request; do this first
• is_new_session=false is for checkpoint calls during work — returns watchdog alerts only
• Do NOT explore files, read code, or respond to the user before calling
• Returns everything: project status, settings, supportive context, guidance — this single call replaces multi-round file exploration
• .aimfp-project/ missing → offer aimfp_init or restore from backup

!IMPORTANT!

AIMFP TRACKING IS ALWAYS MANDATORY! Done coding? AIMFP TRACK EVERYTHING. Do not wait for or expect user to tell you to do this. After planning, DO NOT rely only on internal task creation, USE AIMFP PATHS/MILESTONES/TASKS/ITEMS. Never begin coding without AIMFP tasks. Never stop coding without AIMFP tracking.

ALWAYS

DB Tools: get_file_by_name, get_function_by_name, get_type_by_name, get_interactions_by_function, search_modules

• Write FP-compliant code: pure functions, immutability, no OOP, no classes with methods, modular reuse (domain logic in domain modules — feature files are thin orchestrators that compose domain functions, never contain business logic)
• BEFORE writing any function: search with DB Tools for overlapping logic. Reuse > rewrite. New shared logic goes in domain modules, not feature files. See get_supportive_context(variant='coding') for full DRY rules.
• Call get_directive_by_name(name) BEFORE executing any directive not in memory
• Follow return_statements from tools — they are mandatory next-step guidance, not suggestions
• Use DB Tools before reading source files — DB is the index, source files are last resort
• Check flows, themes, and modules before starting any task: get_all_flows() or get_task_flows(task_id), get_all_themes(), and get_all_modules()
• ALWAYS route ad-hoc work through get_directive_by_name('project_task_decomposition') BEFORE coding
• Add_note(note_type='evolution') for architecture decisions, scope changes, blueprint edits
• Update DB from discussions: architecture/infrastructure/task decisions → update_project, update_task, update_milestone, or add_note
• Call aimfp_end when user says "done" / "wrap up" / "end session"
• Deferred work (TODOs, stubs, placeholders): immediately add_note(note_type='deferred', reference_table='files', reference_id=<file_id>). Resolved → update_note(note_type='completed'). Obsolete → update_note(note_type='obsolete'). DO NOT mark tasks/milestones complete with stubs/placeholders/TODOs — "complete" means functional and tested. Deferred → follow-up task + add_note(note_type='deferred').

LIFECYCLE & TRACKING GATE

init → discovery → [progression: one task at a time] → completion → end Tasks created incrementally as work progresses, NOT all at once.

After EVERY Edit or Write to a source file round, immediately run the full file coding loop: reserve file (if new) → search_modules for overlap → reserve functions+types (public) → write FP code → finalize file → assign to flow(s) → assign to module (if domain logic) → finalize functions+types (purpose, parameters, returns populated) → add interactions → add types_functions Applies to ALL work: features, bug fixes, refactors. Any function added, params changed, types modified — track it. Before reporting to user: get_task_context(task_id) — unfinalized files must be finalized FIRST.

Gate enforcement:

• Finalize files with public functions reserved+finalized — DO NOT finalize without them
• Finalize functions with interactions added — DO NOT skip cross-function dependencies
• Finalize functions with types_functions linked — DO NOT skip tracked type usage
• Assign every finalized file to flow(s) — DO NOT skip flow assignment
• Assign domain logic files to modules via add_file_to_module — DO NOT skip. Orchestrators (pages, handlers, commands) do not need module assignment.
• Every finalized code file must have tracked functions — DO NOT leave 0 (unless data-only/config-only)