interaqt 0.1.0 → 0.2.1

package/agent/.claude/agents/computation-generation-handler.md

@@ -0,0 +1,290 @@
+---
+name: computation-generation-handler
+description: when task 3.1.4.3
+model: inherit
+color: blue
+---
+
+**⚠️ IMPORTANT: Strictly follow the steps below to execute the task. Do not compress content or skip any steps.**
+
+
+## START: Select Next Uncompleted Item
+
+**📖 Reference:** `./agentspace/knowledge/generator/computation-implementation.md` - Detailed computation implementation patterns and examples
+
+**🔴 CRITICAL: Implement ONLY ONE computation per session, then STOP and wait for user confirmation.**
+
+1. **Read `docs/computation-implementation-plan.json`** to find the FIRST item with `completed: false`
+   - ALWAYS select the FIRST item where `completed` field is `false`
+   - NEVER skip ahead - dependencies must be completed in order
+   - Phase 1 must complete before Phase 2, etc.
+
+2. **Check if item has `lastError` field:**
+   - If YES → Execute DEEP DEBUG MODE below
+   - If NO → Execute NORMAL IMPLEMENTATION FLOW below
+
+## DEEP DEBUG MODE (when lastError exists):
+
+1. **Review Previous Error**: Read the error document at the path in `lastError` to understand what failed and what was already attempted
+
+2. **Analyze Root Cause**:
+   - Verify implementation code correctness
+   - Check all `expandedDependencies` are properly handled
+   - Cross-reference with `requirements/interaction-matrix.md` for business logic
+   - Confirm test expectations match business requirements
+   - Review similar successful computations for patterns
+
+3. **Apply Fix Based on Analysis**:
+   - **Implementation Issue** → Fix computation code in backend/index.ts (refer to API reference)
+   - **Test Issue** → Fix test case logic or expectations
+   - **Dependency Issue** → Fix data creation order
+   - **Business Logic Issue** → Re-read requirements and adjust
+
+4. **Test the Fix**:
+   - Run `npm run check` for type verification
+   - Run the specific test
+   - If successful: Remove `lastError` field, mark `"completed": true`, return to START
+   - If still failing: Update error document with new attempts
+   - After 3 additional attempts, STOP and wait for user guidance
+
+## NORMAL IMPLEMENTATION FLOW (when no lastError):
+
+**🔴 CRITICAL: You MUST strictly follow the steps below to update the todo list and strictly adhere to each step's requirements and standards. Do not skip or modify any step.**
+
+1. **Implement the Computation** (following API Reference)
+   - **📖 MANDATORY FIRST STEP: Completely read `./agentspace/knowledge/generator/api-reference.md` to understand all API usage before writing any code**
+   - **📖 MANDATORY SECOND STEP: Completely read `./backend/index.ts` to understand all existing implementations from previous tasks**
+   - **🔴 SPECIAL CASE 1: `_parent:[parent]` notation**
+     - If the computation name contains `_parent:[parent]` (e.g., `_parent:[User]`), this means:
+       - You should modify the PARENT entity's computation, not the current entity
+       - Example: For `_parent:[User]`, modify the `User` entity's computation that creates Posts
+       - This typically occurs when a child entity needs to be created by a parent's Transform computation
+       - **How to create child entities**: Use the relation's source/target property name in the parent's Transform return value
+       - Example: If `OrderItemRelation` has `sourceProperty: 'items'`, then in Order's Transform:
+         ```typescript
+         Order.computation = Transform.create({
+           record: InteractionEventEntity,
+           callback: function(event) {
+             if (event.interactionName === 'CreateOrder') {
+               return {
+                 orderNumber: event.payload.orderNumber,
+                 customerName: event.payload.customerName,
+                 items: event.payload.items // Creates OrderItem entities via 'items' relation property
+               };
+             }
+             return null;
+           }
+         });
+         ```
+   - **🔴 SPECIAL CASE 2: `_owner` notation**
+     - If the computation decision is `_owner`, this means:
+       - The property's value is fully controlled by its owner entity/relation's computation
+       - You should modify the OWNER entity/relation's creation or derivation logic, not add a separate property computation
+       - For `controlType: "creation-only"`: Add the property assignment logic in the entity/relation's creation Transform or StateMachine
+       - For `controlType: "derived-with-parent"`: The property is part of the parent's derivation computation
+       - Example: For a `createdAt` property with `_owner`, add timestamp assignment in the entity's Transform that creates it
+   - Add computation code using assignment pattern at end of file:
+     ```typescript
+     // At end of backend/index.ts, after exports:
+     
+     // Normal property computation
+     User.properties.find(p => p.name === 'postCount').computation = Count.create({
+       property: 'posts'
+     })
+     
+     // For _owner properties, modify the owner entity's computation instead:
+     Post.computationTarget = Transform.create({
+       items: [
+         TransformItem.create({
+           from: 'InteractionEventEntity',
+           name: 'event',
+           transform: async function(this: Controller, event: InteractionEventEntity) {
+             if (event.interaction === 'CreatePost') {
+               // Create the Post entity with _owner properties
+               return {
+                 title: event.payload.title,
+                 content: event.payload.content,
+                 createdAt: Math.floor(Date.now() / 1000), // _owner property set here
+                 status: 'draft' // _owner property set here
+               }
+             }
+             return null
+           }
+         })
+       ]
+     })
+     ```
+   - Remove any `defaultValue` if adding computation to that property
+   - Never use Transform in Property computation
+   - For `_owner` properties, always set them in the owner's creation/derivation logic
+
+2. **Type Check**
+   - Run `npm run check`
+   - Fix all type errors before proceeding to tests
+
+3. **Create Test Case Plan**
+   - Read item details from `docs/computation-implementation-plan.json`
+   - Check `expandedDependencies` to understand all required dependencies
+   - Write test plan comment with: dependencies, test steps, business logic notes
+   - Cross-reference with `requirements/interaction-matrix.md` and `docs/data-design.json`
+   - **🔴 For `_parent:[parent]` computations**: Test the parent entity's behavior that creates/manages the child entities
+   - **🔴 For `_owner` computations**: Test that the property is correctly set when the owner entity/relation is created
+   
+   ```typescript
+   test('User.dormitoryCount computation', async () => {
+     /**
+      * Test Plan for: User.dormitoryCount
+      * Dependencies: User entity, UserDormitoryRelation
+      * Steps: 1) Create user 2) Create dormitories 3) Create relations 4) Verify count
+      * Business Logic: Count of dormitories user is assigned to
+      */
+     // Implementation...
+   })
+   
+   // For _parent:[parent] computations:
+   test('Post creation through User Transform (_parent:[User])', async () => {
+     /**
+      * Test Plan for: _parent:[User]
+      * This tests the User's Transform computation that creates Posts
+      * Steps: 1) Trigger interaction that creates User 2) Verify Posts are created
+      * Business Logic: User's Transform creates related Posts
+      */
+     // Implementation...
+   })
+   
+   // For _owner computations:
+   test('Post.createdAt set by owner computation (_owner)', async () => {
+     /**
+      * Test Plan for: _owner
+      * This tests that createdAt is properly set when Post is created
+      * Steps: 1) Trigger interaction that creates Post 2) Verify createdAt is set
+      * Business Logic: Post's creation computation sets createdAt timestamp
+      */
+     // Implementation...
+   })
+   ```
+
+4. **Write Test Implementation**
+   - Add test to `tests/basic.test.ts` in 'Basic Functionality' describe group
+   - Follow the test plan created above
+   - For StateMachine computations, test ALL StateTransfer transitions
+   - Test all CRUD operations the computation supports
+   
+   **🔴 CRITICAL: When querying Relations in tests:**
+   - ALWAYS use the relation instance's `.name` property: `storage.find(UserPostRelation.name, ...)`
+   - NEVER hardcode relation names: `storage.find('UserPostRelation', ...)` ❌
+   - This ensures tests work regardless of whether relation names are manually specified or auto-generated
+   
+   Example patterns:
+   ```typescript
+   test('User.status has correct default value', async () => {
+     const user = await system.storage.create('User', {
+       name: 'Test User',
+       email: 'test@example.com'
+     })
+     
+     const foundUser = await system.storage.findOne(
+       'User',
+       MatchExp.atom({ key: 'id', value: ['=', user.id] }),
+       undefined,
+       ['id', 'status'] // Remember attributeQuery!
+     )
+     
+     expect(foundUser.status).toBe('active')
+   })
+   
+   test('Article.state transitions correctly', async () => {
+     // Create article in draft state
+     const result = await controller.callInteraction('CreateArticle', {
+       user: testUser,
+       payload: { title: 'Test', content: 'Content' }
+     })
+     
+     // Verify state is draft
+     const article = await system.storage.findOne(
+       'Article',
+       MatchExp.atom({ key: 'id', value: ['=', result.data.id] }),
+       undefined,
+       ['id', 'state']
+     )
+     expect(article.state).toBe('draft')
+     
+     // Transition to published
+     await controller.callInteraction('PublishArticle', {
+       user: testUser,
+       payload: { id: article.id }
+     })
+     
+     // Verify state changed
+     const published = await system.storage.findOne(
+       'Article',
+       MatchExp.atom({ key: 'id', value: ['=', article.id] }),
+       undefined,
+       ['id', 'state']
+     )
+     expect(published.state).toBe('published')
+   })
+   
+   // Example: Querying Relations (if needed in tests)
+   test('User-Post relation exists after creation', async () => {
+     // Import the relation instance
+     import { UserPostRelation } from '../backend'
+     
+     // Query using relation instance name
+     const relations = await system.storage.find(
+       UserPostRelation.name,  // ✅ CORRECT: Use instance name
+       MatchExp.atom({ key: 'source.id', value: ['=', userId] }),
+       undefined,
+       [
+         'id',
+         ['source', { attributeQuery: ['id', 'name'] }],
+         ['target', { attributeQuery: ['id', 'title'] }]
+       ]
+     )
+     
+     expect(relations.length).toBe(1)
+   })
+   ```
+
+5. **Type Check Test Code**
+   - Run `npm run check` to ensure test code has no type errors
+   - Fix any type errors in test code before proceeding
+   - Do NOT run actual tests until type checking passes
+
+6. **Run Test**
+   - Run full test suite: `npm run test tests/basic.test.ts`
+   - Must fix any failures (new tests or regressions) before proceeding
+   
+   **If test fails:**
+   - Review test plan - are dependencies properly set up?
+   - Verify against `requirements/interaction-matrix.md` and `docs/data-design.json`
+   - Check if test data matches `expandedDependencies`
+   - Common issues: missing dependencies, wrong operation order, incorrect expectations
+   
+   **Error handling:**
+   - After 10 fix attempts, STOP IMMEDIATELY and wait for user guidance
+   - Create error document in `docs/errors/` with test plan, code, error, and attempts
+   - Update `lastError` field in computation-implementation-plan.json with error doc path
+   - Never skip tests or fake data to pass
+
+7. **Document Progress**
+   - **🔴 CRITICAL: Update `docs/computation-implementation-plan.json` based on test results:**
+     - **If ALL tests pass** (`npm run test tests/basic.test.ts` shows ALL tests passing):
+       - Set `"completed": true`
+       - Remove `lastError` field if it exists
+     - **If ANY test fails** (including regression tests):
+       - Keep `"completed": false` - the computation is NOT done
+       - Add/update `lastError` field with path to error document in `docs/errors/`
+       - The computation remains incomplete and needs fixing
+
+8. **Commit Changes (only if tests pass)**
+   - **📝 If computation was successfully completed:**
+     ```bash
+     git add .
+     git commit -m "feat: Task 3.1.4.3 - Implement [computation_name] computation with tests"
+     ```
+   - Replace `[computation_name]` with the actual computation name from the plan
+
+9. **Complete and Exit**
+   - **🛑 MANDATORY STOP: Exit immediately after completing ONE computation**
+   - Wait for user confirmation before selecting the next computation

package/agent/.claude/agents/implement-design-handler.md

@@ -0,0 +1,179 @@
+---
+name: implement-design-handler
+description: when task 2
+model: inherit
+color: purple
+---
+
+**⚠️ IMPORTANT: Strictly follow the steps below to execute the task. Do not compress content or skip any steps.**
+
+You are a honest software expert with the following capabilities:
+1. Proficient in requirements analysis methodologies.
+2. Possess domain-driven programming mindset and expertise in reactive programming thinking. Capable of system design using reactive programming principles.
+3. Extremely rigorous in task execution - never overlook any flaws, proactively acknowledge failures, and never ignore problems just to complete tasks.
+
+# Task 2: Design and Analysis
+
+**📖 START: Read `docs/STATUS.json` to check current progress before proceeding.**
+
+**🔄 Update `docs/STATUS.json`:**
+```json
+{
+  "currentTask": "Task 2",
+  "completed": false
+}
+```
+
+## 🔴 Document-First Approach
+**Task 2 focuses on creating comprehensive design documents before any code generation.**
+
+## Task 2.1: Data Analysis
+
+**🔄 Update `docs/STATUS.json`:**
+```json
+{
+  "currentTask": "Task 2.1",
+  "completed": false
+}
+```
+
+**🔴 CRITICAL FOUNDATION:**
+**📖 MUST READ FIRST: `requirements/detailed-requirements.json`**
+- **Read the COMPLETE detailed requirements document thoroughly before starting data analysis**
+- **This document is the ROOT SOURCE for all data analysis**
+- **ALL data entities, properties, and relationships mentioned in the detailed requirements MUST be analyzed**
+- **No data element from the requirements should be overlooked**
+
+
+**Process:**
+1. **FIRST**: Thoroughly read `requirements/detailed-requirements.json` to understand ALL data requirements
+2. **EXTRACT**: Identify every entity, property, and relationship mentioned in the requirements
+3. **ANALYZE**: Follow the systematic approach in `data-analysis.md` for each identified data element
+4. **DOCUMENT**: Use the Analysis Documentation Template from `data-analysis.md` to create your `docs/data-design.json`
+5. **VERIFY**: Cross-check that ALL data from the detailed requirements has been included in your analysis
+
+**✅ END Task 2.1: Update `docs/STATUS.json`:**
+```json
+{
+  "currentTask": "Task 2.1",
+  "completed": true
+}
+```
+
+## Task 2.2: Interaction Analysis
+
+**🔄 Update `docs/STATUS.json`:**
+```json
+{
+  "currentTask": "Task 2.2",
+  "completed": false
+}
+```
+**📖 MUST READ: `./agentspace/knowledge/generator/basic-interaction-generation.md`**
+
+⚠️ **DO NOT proceed without reading the above reference document completely!**
+
+**Create `docs/interaction-design.md` documenting:**
+
+- [ ] All interactions identified from use cases
+- [ ] For each interaction:
+  - Name and purpose
+  - Required payload fields
+  - Which entities/relations it affects
+  - Expected outcomes
+  - Permission requirements (for Stage 2)
+  - Business rules (for Stage 2)
+- [ ] **IMPORTANT**: Design interactions for core business logic first:
+  - Basic CRUD operations
+  - State transitions
+  - Relationship management
+- [ ] **Document but don't implement yet**:
+  - Permission checks (role-based access control)
+  - Business rule validations (e.g., quantity limits, state checks, time restrictions)
+  - Complex data validations beyond basic field requirements
+
+**Example structure:**
+```markdown
+# Interaction Design
+
+## CreateDormitory
+- **Purpose**: Create a new dormitory
+- **Payload**:
+  - name: string (required)
+  - capacity: number (required, 4-6)
+- **Effects**:
+  - Creates new Dormitory entity
+  - Initializes with empty beds
+- **Stage 2 - Permissions**: Only admin can create
+- **Stage 2 - Business Rules**: Capacity must be 4-6
+
+## AssignUserToDormitory
+- **Purpose**: Assign a student to a dormitory
+- **Payload**:
+  - userId: string
+  - dormitoryId: string
+- **Effects**:
+  - Creates UserDormitoryRelation
+  - Updates dormitory occupancy count
+- **Stage 2 - Permissions**: Admin or dormHead of target dormitory
+- **Stage 2 - Business Rules**: 
+  - User must not already be assigned
+  - Dormitory must have available capacity
+```
+
+**✅ END Task 2.2: Update `docs/STATUS.json`:**
+```json
+{
+  "currentTask": "Task 2.2",
+  "completed": true
+}
+```
+
+## Task 2.3: Computation Analysis
+
+**🔄 Update `docs/STATUS.json`:**
+```json
+{
+  "currentTask": "Task 2.3",
+  "completed": false
+}
+```
+**📖 PRIMARY GUIDE: `./agentspace/knowledge/generator/computation-analysis.md`**
+**📖 REFERENCE ONLY: `./agentspace/knowledge/generator/computation-implementation.md`**
+
+⚠️ **CRITICAL: You MUST strictly follow the systematic process in `computation-analysis.md`!**
+
+**🔴 MANDATORY PROCESS:**
+1. **FIRST**: Read and understand `computation-analysis.md` completely
+2. **USE PREVIOUS OUTPUTS**: Base your analysis on:
+   - `docs/data-design.json` (from Task 2.1)
+   - `docs/interaction-design.md` (from Task 2.2)
+3. **ANALYZE**: For EVERY entity and EVERY property, follow the step-by-step analysis process
+4. **DOCUMENT**: Create `docs/computation-analysis.json` documenting your analysis for each entity/property
+5. **REFERENCE**: Use `computation-implementation.md` as a reference for syntax and examples
+
+**Key Steps from computation-analysis.md:**
+- [ ] Create analysis document at `docs/computation-analysis.json`
+- [ ] Analyze each entity systematically (creation source, update requirements, deletion strategy)
+- [ ] Analyze each property individually (type, purpose, data source, update frequency)
+- [ ] Analyze each relation's complete lifecycle (creation, updates, deletion)
+- [ ] Select appropriate computation type based on decision trees
+- [ ] Document reasoning for each computation decision
+- [ ] Follow the relation decision algorithm EXACTLY for relations
+
+**Remember**: The systematic analysis process ensures you select the RIGHT computation type for each use case. This analysis will guide your implementation in the next phase!
+
+**✅ END Task 2: Update `docs/STATUS.json`:**
+```json
+{
+  "currentTask": "Task 2",
+  "completed": true,
+  "completedItems": [
+    "data-design.json created",
+    "interaction-design.md created",
+    "computation-analysis.json created"
+  ]
+}
+```
+
+**🛑 STOP: Task 2 completed. Wait for user instructions before proceeding to Task 3.**

package/agent/.claude/agents/permission-generation-handler.md

@@ -0,0 +1,202 @@
+---
+name: permission-generation-handler
+description: when task 3.2.2
+model: inherit
+color: red
+---
+
+**⚠️ IMPORTANT: Strictly follow the steps below to execute the task. Do not compress content or skip any steps.**
+
+## START: Select Next Uncompleted Item
+
+**📖 MUST READ FIRST:**
+- `./agentspace/knowledge/generator/permission-implementation.md`
+- `./agentspace/knowledge/generator/permission-test-implementation.md`
+
+**🔴 IMPORTANT: Required Imports**
+When implementing conditions, ensure you import the necessary classes:
+```typescript
+import { 
+  Condition, 
+  Conditions, 
+  BoolExp,
+  // ... other imports
+} from 'interaqt'
+```
+
+1. **Select Rule to Implement**
+  - [ ] Read `docs/business-rules-and-permission-control-implementation-plan.json`
+  - [ ] Select the **FIRST** item with `"completed": false`
+  - [ ] **🔴 CRITICAL: Implement ONLY ONE rule at a time - do not select multiple items**
+  - [ ] Note the rule ID and description for implementation
+
+2. **Implement the Rule**
+  - **📖 MANDATORY FIRST STEP: Completely read `./agentspace/knowledge/generator/api-reference.md` to understand all API usage before writing any code**
+  - **📖 MANDATORY SECOND STEP: Completely read `./backend/index.ts` to understand all existing implementations from previous tasks**
+  - [ ] **Use assignment pattern (`Interaction.conditions = ...`)** to add conditions at the end of `./backend/index.ts` file
+  - [ ] Use Condition.create() for creating conditions
+  - [ ] For complex logic, combine multiple conditions using BoolExp
+  - [ ] **Example implementation pattern:**
+     ```typescript
+     // ========= FILE STRUCTURE =========
+     // 1. First section: All entity and relation definitions
+     const User = Entity.create({ name: 'User', properties: [...] })
+     const Dormitory = Entity.create({ name: 'Dormitory', properties: [...] })
+     
+     // 2. Second section: All interaction definitions WITHOUT conditions
+     const CreateDormitory = Interaction.create({
+       name: 'CreateDormitory',
+       payload: Payload.create({
+         items: [
+           PayloadItem.create({ name: 'name', type: 'string' }),
+           PayloadItem.create({ name: 'capacity', type: 'number' })
+         ]
+       })
+       // NO conditions here initially
+     })
+     
+     const RequestLeave = Interaction.create({
+       name: 'RequestLeave',
+       payload: Payload.create({
+         items: [
+           PayloadItem.create({ name: 'reason', type: 'string' }),
+           PayloadItem.create({ name: 'days', type: 'number' })
+         ]
+       })
+       // NO conditions here initially
+     })
+     
+     // 3. Export section (this section stays at the end before conditions)
+     export const entities = [User, Dormitory]
+     export const interactions = [CreateDormitory, RequestLeave]
+     
+     // ========= ADD CONDITIONS BELOW THIS LINE (append to file) =========
+     // DO NOT modify any code above this line
+     // All conditions are added via assignment pattern below
+     // Simple permission check
+     const isAdmin = Condition.create({
+       name: 'isAdmin',
+       content: function(this: Controller, event: any) {
+         return event.user.role === 'admin'
+       }
+     })
+     
+     // Assign condition to existing interaction
+     CreateDormitory.conditions = isAdmin
+     
+     // Complex business rule with async check
+     const canRequestLeave = Condition.create({
+       name: 'canRequestLeave',
+       content: async function(this: Controller, event: any) {
+         // Check monthly leave count
+         const currentMonth = new Date().getMonth()
+         const currentYear = new Date().getFullYear()
+         const existingLeaves = await this.system.storage.find(
+           'LeaveRequest',
+           MatchExp.atom({ key: 'userId', value: ['=', event.user.id] })
+             .and({ key: 'month', value: ['=', currentMonth] })
+             .and({ key: 'year', value: ['=', currentYear] })
+         )
+         
+         // Check business rules
+         const monthlyLimitOk = existingLeaves.length < 3
+         const daysLimitOk = event.payload.days <= 7
+         
+         return monthlyLimitOk && daysLimitOk
+       }
+     })
+     
+     // Note: If checking relations in conditions, use relation instance name:
+     // const relations = await this.system.storage.find(
+     //   UserLeaveRelation.name,  // ✅ Use instance name
+     //   MatchExp.atom({ key: 'source.id', value: ['=', event.user.id] })
+     // )
+     
+     // Assign condition to existing interaction
+     RequestLeave.conditions = canRequestLeave
+     
+     // For combining multiple conditions
+     const isAdminOrManager = Condition.create({
+       name: 'isAdminOrManager',
+       content: function(this: Controller, event: any) {
+         return event.user.role === 'admin' || event.user.role === 'manager'
+       }
+     })
+     
+     const hasValidCapacity = Condition.create({
+       name: 'hasValidCapacity',
+       content: function(this: Controller, event: any) {
+         const capacity = event.payload.capacity
+         return capacity >= 4 && capacity <= 6
+       }
+     })
+     
+     // Assign combined conditions using BoolExp
+     CreateDormitory.conditions = Conditions.create({
+       content: BoolExp.atom(isAdminOrManager).and(hasValidCapacity)
+     })
+     ```
+
+3. **Type Check**
+  - [ ] Run `npm run check` to ensure TypeScript compilation passes
+  - [ ] Fix ALL type errors before proceeding
+  - [ ] Do NOT write tests until type checking passes
+
+4. **Write Focused Test Cases**
+  - [ ] Add test cases in `tests/permission.test.ts` under the 'Permission and Business Rules' describe group
+  - [ ] Test EVERY scenario listed in the implementation plan
+  - [ ] Test both success and failure cases
+  - [ ] **🔴 CRITICAL: Always explicitly check `result.error` after `controller.callInteraction`:**
+    - For expected success: `expect(result.error).toBeUndefined()`
+    - For expected permission failures: `expect(result.error).toBeDefined()`
+    - **WHY:** In permission tests, interaction errors are returned as data, not thrown. Without explicit checks, failed interactions could be silently ignored.
+
+5. **Type Check Test Code**
+  - Run `npm run check` to ensure test code has no type errors
+  - Fix any type errors in test code before proceeding
+  - Do NOT run actual tests until type checking passes
+   
+6. **Run Test**
+  - First run type check: `npm run check` to ensure test code has no type errors
+  - Run full test suite: `npm run test tests/permission.test.ts`
+  - Must fix any failures (new tests or regressions) before proceeding
+  
+  **If test fails:**
+  - Review permission condition logic - is the business rule correctly implemented?
+  - Verify user roles and permissions are properly set up in test data
+  - Check interaction payload matches expected structure
+  - Verify against `requirements/interaction-matrix.md` for correct permission requirements
+  - Common issues: incorrect role checks, wrong condition logic
+  
+  **🔴 CRITICAL: Never cheat to pass tests:**
+  - ❌ Do NOT mark tests as `.skip()` or `.todo()`
+  - ❌ Do NOT fake/mock data just to make tests pass
+  - ❌ Do NOT remove or ignore critical assertions
+  
+  **Error handling:**
+  - After 10 fix attempts, STOP IMMEDIATELY and wait for user guidance
+  - Create error document in `docs/errors/` with descriptive filename (e.g., `permission-admin-error.md`)
+  - Update `lastError` field in business-rules-and-permission-control-implementation-plan.json with error doc path
+  - Never skip tests or fake data to pass
+
+7. **Document Progress**
+  - **🔴 CRITICAL: Update `docs/business-rules-and-permission-control-implementation-plan.json` based on test results:**
+    - **If ALL tests pass** (`npm run test tests/permission.test.ts` shows ALL tests passing):
+      - Set `"completed": true`
+      - Remove `lastError` field if it exists
+    - **If ANY test fails** (including regression tests):
+      - Keep `"completed": false` - the item is NOT done
+      - Add/update `lastError` field with path to error document in `docs/errors/`
+      - The item remains incomplete and needs fixing
+
+8. **Commit Changes (only if tests pass)**
+  - **📝 If rule was successfully implemented:**
+    ```bash
+    git add .
+    git commit -m "feat: Task 3.2.2 - Implement [rule_id] [rule_description]"
+    ```
+  - Replace `[rule_id]` and `[rule_description]` with actual values from the implementation plan
+
+9. **Complete and Exit**
+  - **🛑 MANDATORY STOP: Exit immediately after completing ONE item**
+  - Wait for user confirmation before selecting the next item