# Workflow State & Rules (STM + Rules + Log)

*This file contains the dynamic state, embedded rules, active plan, and log for the current session.*
*It is read and updated frequently by the AI during its operational loop.*

---

## State

*Holds the current status of the workflow.*

```yaml
Phase: CONSTRUCT # Current workflow phase (ANALYZE, BLUEPRINT, CONSTRUCT, VALIDATE, BLUEPRINT_REVISE)
Status: IN_PROGRESS # Current status (READY, IN_PROGRESS, BLOCKED_*, NEEDS_*, COMPLETED, COMPLETED_ITERATION)
CurrentTaskID: UpdateReadmeDocumentation # Identifier for the main task being worked on
CurrentStep: Step 13 # Identifier for the specific step in the plan being executed
CurrentItem: null # Identifier for the item currently being processed in iteration
```

---

## Plan

*Contains the step-by-step implementation plan generated during the BLUEPRINT phase.*

**Task: ImplementNestedGroupProcessing**

*   `[x] Step 1: (CONSTRUCT Phase) Modify the process_group method in inkscape_transform.py to recursively process nested groups.`
*   `[x] Step 2: (CONSTRUCT Phase) Implement the recursive call to process_group when a nested 'g' element is encountered.`
*   `[x] Step 3: (CONSTRUCT Phase) Update counter/index tracking for nested groups (use format "parent_index.child_index").`
*   `[x] Step 4: (CONSTRUCT Phase) Properly aggregate and return results from nested groups by extending the current group's results.`
*   `[x] Step 5: (CONSTRUCT Phase) Ensure group context (prefixes, suffixes) are correctly passed to nested groups.`
*   `[x] Step 6: (VALIDATE Phase) Verify nested group processing works by testing with a sample SVG file containing nested groups.`

**Task: FixElementPositioningAndLabels**

*   `[x] Step 1: (CONSTRUCT Phase) Fix label prefix inheritance from groups. Modify the process_element function in element_processor.py to correctly set label_prefix when prefix_source is "group".`
*   `[x] Step 2: (CONSTRUCT Phase) Fix element position calculation. Add debugging to track position calculation flow and fix any issues with the transformation or geometry extraction.`
*   `[x] Step 3: (CONSTRUCT Phase) Ensure the label_prefix value is correctly passed to json_builder.create_element_json to properly set the "elementPrefix" field in the JSON output.`
*   `[x] Step 4: (CONSTRUCT Phase) Review and fix any fallback logic related to position calculation that might be causing default (-10,-10) positions for elements.`
*   `[x] Step 5: (VALIDATE Phase) Test the fixes with an SVG file containing nested groups and verify that elements have correct prefix inheritance and position values.`

**Task: ImplementCustomExportLocation**

*   `[x] Step 1: (CONSTRUCT Phase) Modify the ScadaCreator class in scada_exporter.py to accept a custom export directory parameter that will override the default path construction.`
*   `[x] Step 2: (CONSTRUCT Phase) Update the _create_view_files method in scada_exporter.py to use the custom export directory when provided, while maintaining the original behavior when no custom directory is specified.`
*   `[x] Step 3: (CONSTRUCT Phase) Add a new field in the SCADA settings frame in svg_processor_gui.py to allow users to specify a custom export location.`
*   `[x] Step 4: (CONSTRUCT Phase) Add a "Browse" button next to the new field that opens a directory selection dialog.`
*   `[x] Step 5: (CONSTRUCT Phase) Modify the create_scada_view method in svg_processor_gui.py to pass the custom export location to the ScadaCreator.`
*   `[x] Step 6: (CONSTRUCT Phase) Update the config_manager.py to include the custom export location in the default configuration.`
*   `[x] Step 7: (VALIDATE Phase) Test the new feature by exporting a SCADA view to a custom location and verifying that all files are correctly created in the specified directory.`

**Task: UpdateReadmeDocumentation**
*   `[x] Step 1: (CONSTRUCT Phase) Review existing README.md sections and identify areas for improvement, consolidation, and expansion based on project_config.md and actual application features.`
*   `[x] Step 2: (CONSTRUCT Phase) Restructure README.md for better flow and readability. Consolidate duplicated sections (e.g., "Technical Details", "License", "Acknowledgments").`
*   `[x] Step 3: (CONSTRUCT Phase) Expand "Overview" to clearly state the problem the application solves and its benefits.`
*   `[x] Step 4: (CONSTRUCT Phase) Enhance "Features" section: Ensure all key functionalities are listed and briefly described. Refer to `project_config.md` for core features.`
*   `[x] Step 5: (CONSTRUCT Phase) Update "Installation" section: Verify prerequisites, source installation, and PyInstaller build instructions. Add notes on virtual environments for all OS if not sufficiently covered.`
*   `[x] Step 6: (CONSTRUCT Phase) Improve "Usage" section: Make it a step-by-step guide for a new user. Ensure clarity on configuring project settings and element mappings. Add screenshots or ASCII diagrams if helpful (consider limitations).`
*   `[x] Step 7: (CONSTRUCT Phase) Detail "Configuration File (`config.json`)" section: Explain key configuration options and their purpose. Mention `config_manager.py`'s role in handling this.`
*   `[x] Step 8: (CONSTRUCT Phase) Refine "Technical Details" section:
    *   `[x] Ensure "Project Structure" accurately reflects the current module organization. Describe the role of each key file/directory (e.g. `app_runner.py`, `gui/`, `processing/`, `utils.py`, `config_manager.py`).`
    *   `[x] Clarify "SVG Processing Workflow" and "SCADA Export Process".`
    *   `[x] Elaborate on "JSON Element Structure", "Label Prefix System", "Matrix Transformations", and "Rotation Handling".`
    *   `[x] Add a subsection on "Error Handling" strategy as defined in `project_config.md`.`
    *   `[x] Add a subsection on "Threading" for UI responsiveness as defined in `project_config.md`.`
*   `[x] Step 9: (CONSTRUCT Phase) Update "Testing" section: If `pytest` is used, provide clear instructions. Mention any specific test configurations or environments.`
*   `[x] Step 10: (CONSTRUCT Phase) Enhance "Troubleshooting" section: Add common issues and solutions. Refer to logs for debugging.`
*   `[x] Step 11: (CONSTRUCT Phase) Add "Dependencies" section: List all dependencies from `requirements.txt` with brief explanations of their roles (lxml for XML, numpy for math, Pillow for images, svg.path for paths).`
*   `[x] Step 12: (CONSTRUCT Phase) Add "Contributing" section: Briefly outline how others can contribute (e.g., reporting bugs, suggesting features, submitting PRs). Mention coding standards if any are implicitly followed.`
*   `[x] Step 13: (CONSTRUCT Phase) Add/Update "License" section: Prompt user for actual license type if "[Specify Your License Here]" is still present.`
*   `[ ] Step 14: (CONSTRUCT Phase) Review and refine "Acknowledgments". (Skipping as per user request to move to final step)`
*   `[ ] Step 15: (CONSTRUCT Phase) Perform a final review of the entire `README.md` for clarity, consistency, grammar, and formatting.`
*   `[ ] Step 16: (VALIDATE Phase) Confirm with the user that the updated README.md is comprehensive and accurate.`

---

## Rules

*Embedded rules governing the AI's autonomous operation.*

**# --- Core Workflow Rules ---**

RULE_WF_PHASE_ANALYZE:
  **Constraint:** Goal is understanding request/context. NO solutioning or implementation planning.

RULE_WF_PHASE_BLUEPRINT:
  **Constraint:** Goal is creating a detailed, unambiguous step-by-step plan. NO code implementation.

RULE_WF_PHASE_CONSTRUCT:
  **Constraint:** Goal is executing the `## Plan` exactly. NO deviation. If issues arise, trigger error handling or revert phase.

RULE_WF_PHASE_VALIDATE:
  **Constraint:** Goal is verifying implementation against `## Plan` and requirements using tools. NO new implementation.

RULE_WF_TRANSITION_01:
  **Trigger:** Explicit user command (`@analyze`, `@blueprint`, `@construct`, `@validate`).
  **Action:** Update `State.Phase` accordingly. Log phase change.

RULE_WF_TRANSITION_02:
  **Trigger:** AI determines current phase constraint prevents fulfilling user request OR error handling dictates phase change (e.g., RULE_ERR_HANDLE_TEST_01).
  **Action:** Log the reason. Update `State.Phase` (e.g., to `BLUEPRINT_REVISE`). Set `State.Status` appropriately (e.g., `NEEDS_PLAN_APPROVAL`). Report to user.

RULE_ITERATE_01: # Triggered by RULE_MEM_READ_STM_01 when State.Status == READY and State.CurrentItem == null, or after VALIDATE phase completion.
  **Trigger:** `State.Status == READY` and `State.CurrentItem == null` OR after `VALIDATE` phase completion.
  **Action:**
    1. Check `## Items` section for more items.
    2. If more items:
    3. Set `State.CurrentItem` to the next item.
    4. Clear `## Log`.
    5. Set `State.Phase = ANALYZE`, `State.Status = READY`.
    6. Log "Starting processing item [State.CurrentItem]".
    7. If no more items:
    8. Trigger `RULE_ITERATE_02`.

RULE_ITERATE_02:
  **Trigger:** `RULE_ITERATE_01` determines no more items.
  **Action:**
    1. Set `State.Status = COMPLETED_ITERATION`.
    2. Log "Tokenization iteration completed."

**# --- Initialization & Resumption Rules ---**

RULE_INIT_01:
  **Trigger:** AI session/task starts AND `workflow_state.md` is missing or empty.
  **Action:**
    1. Create `workflow_state.md` with default structure.
    2. Read `project_config.md` (prompt user if missing).
    3. Set `State.Phase = ANALYZE`, `State.Status = READY`.
    4. Log "Initialized new session."
    5. Prompt user for the first task.

RULE_INIT_02:
  **Trigger:** AI session/task starts AND `workflow_state.md` exists.
  **Action:**
    1. Read `project_config.md`.
    2. Read existing `workflow_state.md`.
    3. Log "Resumed session."
    4. Check `State.Status`: Handle READY, COMPLETED, BLOCKED_*, NEEDS_*, IN_PROGRESS appropriately (prompt user or report status).

RULE_INIT_03:
  **Trigger:** User confirms continuation via RULE_INIT_02 (for IN_PROGRESS state).
  **Action:** Proceed with the next action based on loaded state and rules.

**# --- Memory Management Rules ---**

RULE_MEM_READ_LTM_01:
  **Trigger:** Start of a new major task or phase.
  **Action:** Read `project_config.md`. Log action.
RULE_MEM_READ_STM_01:
  **Trigger:** Before *every* decision/action cycle.
  **Action:**
    1. Read `workflow_state.md`.
    2. If `State.Status == READY` and `State.CurrentItem == null`:
    3. Log "Attempting to trigger RULE_ITERATE_01".
    4. Trigger `RULE_ITERATE_01`.

RULE_MEM_UPDATE_STM_01:
  **Trigger:** After *every* significant action or information receipt.
  **Action:** Immediately update relevant sections (`## State`, `## Plan`, `## Log`) in `workflow_state.md` and save.

RULE_MEM_UPDATE_LTM_01:
  **Trigger:** User command (`@config/update`) OR end of successful VALIDATE phase for significant change.
  **Action:** Propose concise updates to `project_config.md` based on `## Log`/diffs. Set `State.Status = NEEDS_LTM_APPROVAL`. Await user confirmation.

RULE_MEM_VALIDATE_01:
  **Trigger:** After updating `workflow_state.md` or `project_config.md`.
  **Action:** Perform internal consistency check. If issues found, log and set `State.Status = NEEDS_CLARIFICATION`.

**# --- Tool Integration Rules (Cursor Environment) ---**

RULE_TOOL_LINT_01:
  **Trigger:** Relevant source file saved during CONSTRUCT phase.
  **Action:** Instruct Cursor terminal to run lint command. Log attempt. On completion, parse output, log result, set `State.Status = BLOCKED_LINT` if errors.

RULE_TOOL_FORMAT_01:
  **Trigger:** Relevant source file saved during CONSTRUCT phase.
  **Action:** Instruct Cursor to apply formatter or run format command via terminal. Log attempt.

RULE_TOOL_TEST_RUN_01:
  **Trigger:** Command `@validate` or entering VALIDATE phase.
  **Action:** Instruct Cursor terminal to run test suite. Log attempt. On completion, parse output, log result, set `State.Status = BLOCKED_TEST` if failures, `TESTS_PASSED` if success.

RULE_TOOL_APPLY_CODE_01:
  **Trigger:** AI determines code change needed per `## Plan` during CONSTRUCT phase.

RULE_PROCESS_ITEM_01:
  **Trigger:** `State.Phase == CONSTRUCT` and `State.CurrentItem` is not null and current step in `## Plan` requires item processing.
  **Action:**
    1. **Get Item Text:** Based on `State.CurrentItem`, extract the corresponding 'Text to Tokenize' from the `## Items` section.
    2. **Summarize (Placeholder):**  Use a placeholder to generate a summary of the extracted text.  For example, "Summary of [text] is [placeholder summary]".
    3. **Estimate Token Count:**
       a. Read `Characters Per Token (Estimate)` from `project_config.md`.
       b. Get the text content of the item from the `## Items` section. (Placeholder: Implement logic to extract text based on `State.CurrentItem` from the `## Items` table.)
       c. Calculate `estimated_tokens = length(text_content) / 4`.
    4. **Summarize (Placeholder):** Use a placeholder to generate a summary of the extracted text.  For example, "Summary of [text] is [placeholder summary]". (Placeholder: Replace with actual summarization tool/logic)
    5. **Store Results:** Append a new row to the `## TokenizationResults` table with:
       *   `Item ID`: `State.CurrentItem`
       *   `Summary`: The generated summary. (Placeholder: Implement logic to store the summary.)
       *   `Token Count`: `estimated_tokens`.
    6. Log the processing actions, results, and estimated token count to the `## Log`. (Placeholder: Implement logging.)

  **Action:** Generate modification. Instruct Cursor to apply it. Log action.

**# --- Error Handling & Recovery Rules ---**

RULE_ERR_HANDLE_LINT_01:
  **Trigger:** `State.Status` is `BLOCKED_LINT`.
  **Action:** Analyze error in `## Log`. Attempt auto-fix if simple/confident. Apply fix via RULE_TOOL_APPLY_CODE_01. Re-run lint via RULE_TOOL_LINT_01. If success, reset `State.Status`. If fail/complex, set `State.Status = BLOCKED_LINT_UNRESOLVED`, report to user.

RULE_ERR_HANDLE_TEST_01:
  **Trigger:** `State.Status` is `BLOCKED_TEST`.
  **Action:** Analyze failure in `## Log`. Attempt auto-fix if simple/localized/confident. Apply fix via RULE_TOOL_APPLY_CODE_01. Re-run failed test(s) or suite via RULE_TOOL_TEST_RUN_01. If success, reset `State.Status`. If fail/complex, set `State.Phase = BLUEPRINT_REVISE`, `State.Status = NEEDS_PLAN_APPROVAL`, propose revised `## Plan` based on failure analysis, report to user.

RULE_ERR_HANDLE_GENERAL_01:
  **Trigger:** Unexpected error or ambiguity.
  **Action:** Log error/situation to `## Log`. Set `State.Status = BLOCKED_UNKNOWN`. Report to user, request instructions.

---

## Log

*A chronological log of significant actions, events, tool outputs, and decisions.*
*(This section will be populated by the AI during operation)*

*   `[2023-11-18 13:45:00] Initialized new session. State set to ANALYZE/READY.`
*   `