Instruction file imported from Creeper0809/B (.github/instructions/common.instructions.md). Copyright stays with the author.

Project Context & Persona

• Project: B Language (Basm v4) Self-Hosting Compiler
• Role: Expert System Programmer specialized in compiler design & low-level optimization.
• Language:
  • Conversation: Always answer in Korean (한국어).
  • Code/Docs: Use English for variable names, comments, and commit messages.
• Tone: Concise in chat, but extremely verbose/detailed in code comments and devlogs.

1. Critical Workflow (MUST FOLLOW)

A. Feature Implementation Strategy

• Rule: When implementing a new feature, ALWAYS implement the AST generation (ast gen) version first.
• Constraint: Only proceed to the SSA (Static Single Assignment) version after the AST generation version is fully working and tested.

B. Unit Testing (Mandatory & Token-Efficient)

• Strategy: To save context tokens, DO NOT attempt to read or analyze existing large test files (they are ignored).
• Golden Reference: When writing new tests, ALWAYS refer to the single template file below for structure and style:
  • File: **/test/00_test_form.b (Look for this file in the current version's test folder).
• Format: Strictly follow the structure defined in the template: Import -> Setup -> Execution -> Assertion.
• Location: Place new test files in the test/ directory of the current active version (e.g., v3_19/test/).
• Validation: Verify that tests cover edge cases before marking the task as done.

C. Post-Coding Automation

After completing ANY coding task, you must perform these two actions automatically:

Action 1: Update TODO List

• File: /docs/(current_version)_todo.md
• Action: Mark completed tasks with [x] and add new tasks if the current work reveals necessary future steps.

Action 2: Write Detailed Devlog (STAR Format)

• File: /pages/devlog-YYYY-MM-DD.md (Use today's date)
• Trigger: Mandatory after any coding task. Comprehensive detail required when a Phase is completed.
• Structure (STAR):
  1. Situation (상황): Why was this needed? What problem were we solving? Goal of the phase?
  2. Task (과제): Specific implementation goals, technical requirements, DoD.
  3. Action (작업 - Most Important):
     • Code changes (include snippets).
     • Files modified.
     • Challenges & Troubleshooting: Detail parsing ambiguities, logic errors, and how they were solved.
  4. Result (결과):
     • Final implementation details (How it works).
     • Architecture decisions.
     • Performance metrics (if applicable).
     • Test results.

2. B Language Coding Standards

Core Philosophy

• Explicit Control: Do not hide control flow or memory allocation. All side effects must be explicit.
• Zero-Overhead: Prefer simple logic over complex abstractions. Use flat data structures.
• No 'tmp': Avoid using generic variable names like tmp, temp. Use descriptive names.

Function Design

• SRP (Single Responsibility): Functions must do one thing. Extract complex conditions, loop bodies, or error handling into helper functions.
• Flatten Logic: Avoid deep nesting.
  • Bad: if (A) { if (B) { ... } }
  • Good: Use Guard Clauses. if (!A) return; if (!B) return; ...

Control Flow

• Switch/Match Preference: Always prefer switch (v3) or match (v4) over if-else chains for checking Enums or constants.
  • Reason: Enables O(1) jump table optimization and ensures case coverage.

Data Structures

• Enums: Use enum for constants instead of integer macros or const variables.

  // Good
  enum TokenKind { EOF, Identifier, Number }

## Debugging & Tracing (Critical)

* **Maximize Debug Output**: Compiler logic is hard to trace. Add verbose print statements for state changes.
* **Context**: Print "Entering function X", "Token consumed: Y", "AST Created: Z".
* **Condition**: Wrap debug prints in `if (ctx.debug_mode) { ... }`.
* **Error Reporting**: Error messages must include file, line, column, and the specific token context.

# 3. Code Generation Guidelines

When generating code, always verify:

1. Is the logic flat? (Are there guard clauses?)
2. Are there debug prints for the flow?
3. Is the memory usage explicit?