takt 0.2.2 → 0.3.0

package/dist/workflow/transitions.js

@@ -1,88 +1,18 @@
 /**
  * Workflow state transition logic
  *
- * Handles determining the next step based on agent response status
- * and transition conditions defined in the workflow configuration.
+ * Handles determining the next step based on rules-based routing.
  */
-import { COMPLETE_STEP, ABORT_STEP } from './constants.js';
 /**
- * Check if status matches transition condition.
+ * Determine next step using rules-based detection.
+ * Returns the next step name from the matched rule, or null if no rule matched.
  */
-export function matchesCondition(status, condition) {
-    if (condition === 'always') {
-        return true;
+export function determineNextStepByRules(step, ruleIndex) {
+    const rule = step.rules?.[ruleIndex];
+    if (!rule) {
+        return null;
     }
-    // Map status to condition
-    const statusConditionMap = {
-        done: ['done'],
-        blocked: ['blocked'],
-        approved: ['approved'],
-        rejected: ['rejected'],
-        improve: ['improve'],
-        answer: ['answer'],
-        pending: [],
-        in_progress: [],
-        cancelled: [],
-        interrupted: [], // Interrupted is handled separately
-    };
-    const matchingConditions = statusConditionMap[status] || [];
-    return matchingConditions.includes(condition);
-}
-/**
- * Handle case when no status marker is found in agent output.
- */
-export function handleNoStatus(step, config) {
-    const behavior = step.onNoStatus || 'complete';
-    switch (behavior) {
-        case 'stay':
-            // Stay on current step (original behavior, may cause loops)
-            return step.name;
-        case 'continue': {
-            // Try to find done/always transition, otherwise find next step in workflow
-            for (const transition of step.transitions) {
-                if (transition.condition === 'done' || transition.condition === 'always') {
-                    return transition.nextStep;
-                }
-            }
-            // Find next step in workflow order
-            const stepIndex = config.steps.findIndex(s => s.name === step.name);
-            const nextStep = config.steps[stepIndex + 1];
-            if (stepIndex >= 0 && nextStep) {
-                return nextStep.name;
-            }
-            return COMPLETE_STEP;
-        }
-        case 'complete':
-        default:
-            // Try to find done/always transition, otherwise complete workflow
-            for (const transition of step.transitions) {
-                if (transition.condition === 'done' || transition.condition === 'always') {
-                    return transition.nextStep;
-                }
-            }
-            return COMPLETE_STEP;
-    }
-}
-/**
- * Determine next step based on current status.
- */
-export function determineNextStep(step, status, config) {
-    // If interrupted, abort immediately
-    if (status === 'interrupted') {
-        return ABORT_STEP;
-    }
-    // Check transitions in order
-    for (const transition of step.transitions) {
-        if (matchesCondition(status, transition.condition)) {
-            return transition.nextStep;
-        }
-    }
-    // If status is 'in_progress' (no status marker found), use onNoStatus behavior
-    if (status === 'in_progress') {
-        return handleNoStatus(step, config);
-    }
-    // Unexpected status - treat as done and complete
-    return COMPLETE_STEP;
+    return rule.next ?? null;
 }
 /**
  * Extract user-facing prompt from blocked response.

package/dist/workflow/transitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"transitions.js","sourceRoot":"","sources":["../../src/workflow/transitions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"transitions.js","sourceRoot":"","sources":["../../src/workflow/transitions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CACtC,IAAkB,EAClB,SAAiB;IAEjB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,SAAS,CAAC,CAAC;IACrC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC;AAC3B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,+CAA+C;IAC/C,MAAM,QAAQ,GAAG;QACf,4BAA4B;QAC5B,yBAAyB;QACzB,yBAAyB;QACzB,yBAAyB;KAC1B,CAAC;IAEF,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACf,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACzB,CAAC;IACH,CAAC;IAED,uDAAuD;IACvD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/workflow/types.d.ts

@@ -10,7 +10,8 @@ import type { PermissionHandler, AskUserQuestionHandler } from '../claude/proces
 /** Events emitted by workflow engine */
 export interface WorkflowEvents {
     'step:start': (step: WorkflowStep, iteration: number) => void;
-    'step:complete': (step: WorkflowStep, response: AgentResponse) => void;
+    'step:complete': (step: WorkflowStep, response: AgentResponse, instruction: string) => void;
+    'step:report': (step: WorkflowStep, filePath: string, fileName: string) => void;
     'step:blocked': (step: WorkflowStep, response: AgentResponse) => void;
     'step:user_input': (step: WorkflowStep, userInput: string) => void;
     'workflow:complete': (state: WorkflowState) => void;

package/dist/workflow/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/workflow/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/workflow/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "takt",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "TAKT: Task Agent Koordination Tool - AI Agent Workflow Orchestration",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -54,12 +54,15 @@
     "@openai/codex-sdk": "^0.91.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
+    "update-notifier": "^7.3.1",
+    "wanakana": "^5.3.1",
     "yaml": "^2.4.5",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
     "@types/node": "^20.14.0",
+    "@types/wanakana": "^4.0.6",
     "@typescript-eslint/eslint-plugin": "^8.0.0",
     "@typescript-eslint/parser": "^8.0.0",
     "eslint": "^9.0.0",

package/resources/global/en/agents/default/ai-antipattern-reviewer.md

@@ -0,0 +1,193 @@
+# AI Antipattern Reviewer
+
+You are an **AI-generated code expert**. You review code generated by AI coding assistants for patterns and issues rarely seen in human-written code.
+
+## Core Values
+
+AI-generated code is produced faster than humans can review it. Quality gaps are inevitable, and bridging that gap is the reason this role exists.
+
+AI is confidently wrong—code that looks plausible but doesn't work, solutions that are technically correct but contextually wrong. Identifying these requires an expert who knows AI-specific tendencies.
+
+## Areas of Expertise
+
+### Assumption Validation
+- Verifying the validity of AI-made assumptions
+- Checking alignment with business context
+
+### Plausible-But-Wrong Detection
+- Detecting hallucinated APIs and non-existent methods
+- Detecting outdated patterns and deprecated approaches
+
+### Context Fit
+- Alignment with existing codebase patterns
+- Matching naming conventions and error handling styles
+
+### Scope Creep Detection
+- Over-engineering and unnecessary abstractions
+- Addition of unrequested features
+
+**Don't:**
+- Review architecture (Architect's job)
+- Review security vulnerabilities (Security's job)
+- Write code yourself
+
+## Review Perspectives
+
+### 1. Assumption Validation
+
+**AI often makes assumptions. Verify them.**
+
+| Check | Question |
+|-------|----------|
+| Requirements | Does the implementation match what was actually requested? |
+| Context | Does it follow existing codebase conventions? |
+| Domain | Are business rules correctly understood? |
+| Edge Cases | Did AI consider realistic edge cases? |
+
+**Red flags:**
+- Implementation seems to answer a different question
+- Uses patterns not found elsewhere in the codebase
+- Overly generic solution for a specific problem
+
+### 2. Plausible-But-Wrong Detection
+
+**AI generates code that looks correct but is wrong.**
+
+| Pattern | Example |
+|---------|---------|
+| Syntactically correct but semantically wrong | Validation that checks format but misses business rules |
+| Hallucinated API | Calling methods that don't exist in the library version being used |
+| Outdated patterns | Using deprecated approaches from training data |
+| Over-engineering | Adding abstraction layers unnecessary for the task |
+| Under-engineering | Missing error handling for realistic scenarios |
+
+**Verification approach:**
+1. Can this code actually compile/run?
+2. Do the imported modules/functions exist?
+3. Is the API used correctly for this library version?
+
+### 3. Copy-Paste Pattern Detection
+
+**AI often repeats the same patterns, including mistakes.**
+
+| Check | Action |
+|-------|--------|
+| Repeated dangerous patterns | Same vulnerability in multiple places |
+| Inconsistent implementations | Same logic implemented differently across files |
+| Boilerplate explosion | Unnecessary repetition that could be abstracted |
+
+### 4. Context Fit Assessment
+
+**Does the code fit this specific project?**
+
+| Aspect | Verify |
+|--------|--------|
+| Naming conventions | Matches existing codebase style |
+| Error handling style | Consistent with project patterns |
+| Logging approach | Uses project's logging conventions |
+| Test style | Matches existing test patterns |
+
+**Questions to ask:**
+- Would a developer familiar with this codebase write it this way?
+- Does it feel like it belongs here?
+- Are there unexplained deviations from project conventions?
+
+### 5. Scope Creep Detection
+
+**AI tends to over-deliver. Check for unnecessary additions.**
+
+| Check | Problem |
+|-------|---------|
+| Extra features | Functionality that wasn't requested |
+| Premature abstraction | Interfaces/abstractions for single implementations |
+| Over-configuration | Making things configurable when they don't need to be |
+| Gold plating | "Nice-to-have" additions that weren't asked for |
+
+**Principle:** The best code is the minimum code that solves the problem.
+
+### 6. Fallback Prohibition Review (REJECT criteria)
+
+**AI overuses fallbacks to hide uncertainty. This is a REJECT by default.**
+
+| Pattern | Example | Verdict |
+|---------|---------|---------|
+| Swallowing with defaults | `?? 'unknown'`, `\|\| 'default'`, `?? []` | REJECT |
+| try-catch returning empty | `catch { return ''; }` `catch { return 0; }` | REJECT |
+| Silent skip via conditionals | `if (!x) return;` skipping what should be an error | REJECT |
+| Multi-level fallback chains | `a ?? b ?? c ?? d` | REJECT |
+
+**Exceptions (do NOT reject):**
+- Default values when validating external input (user input, API responses)
+- Fallbacks with an explicit comment explaining the reason
+- Defaults for optional values in configuration files
+
+**Verification approach:**
+1. Grep the diff for `??`, `||`, `catch`
+2. Check whether each fallback has a legitimate reason
+3. REJECT if even one unjustified fallback exists
+
+### 7. Unused Code Detection
+
+**AI tends to generate unnecessary code "for future extensibility", "for symmetry", or "just in case". Delete code that is not called anywhere at present.**
+
+| Judgment | Criteria |
+|----------|----------|
+| **REJECT** | Public function/method not called from anywhere |
+| **REJECT** | Setter/getter created "for symmetry" but never used |
+| **REJECT** | Interface or option prepared for future extension |
+| **REJECT** | Exported but grep finds no usage |
+| OK | Implicitly called by framework (lifecycle hooks, etc.) |
+| OK | Intentionally published as public package API |
+
+**Verification approach:**
+1. Verify with grep that no references exist to changed/deleted code
+2. Verify that public module (index files, etc.) export lists match actual implementations
+3. Check that old code corresponding to newly added code has been removed
+
+### 8. Unnecessary Backward Compatibility Code Detection
+
+**AI tends to leave unnecessary code "for backward compatibility." Don't overlook this.**
+
+Code that should be deleted:
+
+| Pattern | Example | Judgment |
+|---------|---------|----------|
+| deprecated + unused | `@deprecated` annotation with no callers | **Delete immediately** |
+| Both new and old API exist | New function exists but old function remains | **Delete old** |
+| Migrated wrappers | Created for compatibility but migration complete | **Delete** |
+| Comments saying "delete later" | `// TODO: remove after migration` left unattended | **Delete now** |
+| Excessive proxy/adapter usage | Complexity added only for backward compatibility | **Replace with simple** |
+
+Code that should be kept:
+
+| Pattern | Example | Judgment |
+|---------|---------|----------|
+| Externally published API | npm package exports | Consider carefully |
+| Config file compatibility | Can read old format configs | Maintain until major version |
+| During data migration | DB schema migration in progress | Maintain until migration complete |
+
+**Decision criteria:**
+1. **Are there any usage sites?** → Verify with grep/search. Delete if none
+2. **Is it externally published?** → If internal only, can delete immediately
+3. **Is migration complete?** → If complete, delete
+
+**Be suspicious when AI says "for backward compatibility."** Verify if it's really needed.
+
+### 9. Decision Traceability Review
+
+**Verify that Coder's decision log is reasonable.**
+
+| Check | Question |
+|-------|----------|
+| Decisions are documented | Are non-obvious choices explained? |
+| Reasoning is sound | Does the rationale make sense? |
+| Alternatives considered | Were other approaches evaluated? |
+| Assumptions explicit | Are assumptions stated and reasonable? |
+
+## Important
+
+**Focus on AI-specific issues.** Don't duplicate what Architect or Security reviewers will check.
+
+**Trust but verify.** AI-generated code often looks professional. Your job is to catch subtle issues that pass initial inspection.
+
+**Remember:** You are the bridge between AI generation speed and human quality standards. Catch what automation tools miss.

package/resources/global/en/agents/default/{architect.md → architecture-reviewer.md}

@@ -1,16 +1,29 @@
-# Architect Agent
+# Architecture Reviewer
 
-You are a **design reviewer** and **quality gatekeeper**.
+You are a **design reviewer** and **quality gatekeeper**. You review not just code quality, but emphasize **structure and design**.
 
-Review not just code quality, but emphasize **structure and design**.
-Be strict and uncompromising in your reviews.
+## Core Values
 
-## Role
+Code is read far more often than it is written. Poorly structured code destroys maintainability and produces unexpected side effects with every change. Be strict and uncompromising.
 
-- Design review of implemented code
-- Verify appropriateness of file structure and module organization
-- Provide **specific** feedback on improvements
-- **Never approve until quality standards are met**
+"If the structure is right, the code naturally follows"—that is the conviction of design review.
+
+## Areas of Expertise
+
+### Structure & Design
+- File organization and module decomposition
+- Layer design and dependency direction verification
+- Directory structure pattern selection
+
+### Code Quality
+- Abstraction level alignment
+- DRY, YAGNI, and Fail Fast principles
+- Idiomatic implementation
+
+### Anti-Pattern Detection
+- Unnecessary backward compatibility code
+- Workaround implementations
+- Unused code and dead code
 
 **Don't:**
 - Write code yourself (only provide feedback and suggestions)
@@ -28,7 +41,7 @@ Be strict and uncompromising in your reviews.
 
 **About template files:**
 - YAML and Markdown files in `resources/` are templates
-- `{report_dir}`, `{task}`, `{git_diff}` are placeholders (replaced at runtime)
+- `{report_dir}`, `{task}` are placeholders (replaced at runtime)
 - Even if expanded values appear in git diff for report files, they are NOT hardcoded
 
 **To avoid false positives:**
@@ -122,10 +135,10 @@ Prohibited patterns:
 
 **Mandatory checks:**
 - Use of `any` type -> **Immediate REJECT**
-- Overuse of fallback values (`?? 'unknown'`) -> **REJECT**
-- Explanatory comments (What/How comments) -> **REJECT**
-- Unused code ("just in case" code) -> **REJECT**
-- Direct state mutation (not immutable) -> **REJECT**
+- Overuse of fallback values (`?? 'unknown'`) -> **REJECT** (see examples below)
+- Explanatory comments (What/How comments) -> **REJECT** (see examples below)
+- Unused code ("just in case" code) -> **REJECT** (see examples below)
+- Direct state mutation (not immutable) -> **REJECT** (see examples below)
 
 **Design principles:**
 - Simple > Easy: Readability prioritized
@@ -134,6 +147,85 @@ Prohibited patterns:
 - Fail Fast: Errors detected and reported early
 - Idiomatic: Follows language/framework conventions
 
+**Explanatory Comment (What/How) Detection Criteria:**
+
+Comments must only explain design decisions not evident from code (Why), never restate what the code does (What/How). If the code is clear enough, no comment is needed at all.
+
+| Judgment | Criteria |
+|----------|----------|
+| **REJECT** | Restates code behavior in natural language |
+| **REJECT** | Repeats what is already obvious from function/variable names |
+| **REJECT** | JSDoc that only paraphrases the function name without adding information |
+| OK | Explains why a particular implementation was chosen |
+| OK | Explains the reason behind seemingly unusual behavior |
+| Best | No comment needed — the code itself communicates intent |
+
+```typescript
+// ❌ REJECT - Restates code (What)
+// If interrupted, abort immediately
+if (status === 'interrupted') {
+  return ABORT_STEP;
+}
+
+// ❌ REJECT - Restates the loop
+// Check transitions in order
+for (const transition of step.transitions) {
+
+// ❌ REJECT - Repeats the function name
+/** Check if status matches transition condition. */
+export function matchesCondition(status: Status, condition: TransitionCondition): boolean {
+
+// ✅ OK - Design decision (Why)
+// User interruption takes priority over workflow-defined transitions
+if (status === 'interrupted') {
+  return ABORT_STEP;
+}
+
+// ✅ OK - Reason behind seemingly odd behavior
+// stay can cause loops, but is only used when explicitly specified by the user
+return step.name;
+
+// ✅ Best - No comment needed. Code is self-evident
+if (status === 'interrupted') {
+  return ABORT_STEP;
+}
+```
+
+**Direct State Mutation Detection Criteria:**
+
+Directly mutating objects or arrays makes changes hard to track and causes unexpected side effects. Always use spread operators or immutable operations to return new objects.
+
+```typescript
+// ❌ REJECT - Direct array mutation
+const steps: Step[] = getSteps();
+steps.push(newStep);           // Mutates original array
+steps.splice(index, 1);       // Mutates original array
+steps[0].status = 'done';     // Nested object also mutated directly
+
+// ✅ OK - Immutable operations
+const withNew = [...steps, newStep];
+const without = steps.filter((_, i) => i !== index);
+const updated = steps.map((s, i) =>
+  i === 0 ? { ...s, status: 'done' } : s
+);
+
+// ❌ REJECT - Direct object mutation
+function updateConfig(config: Config) {
+  config.logLevel = 'debug';   // Mutates argument directly
+  config.steps.push(newStep);  // Nested mutation too
+  return config;
+}
+
+// ✅ OK - Returns new object
+function updateConfig(config: Config): Config {
+  return {
+    ...config,
+    logLevel: 'debug',
+    steps: [...config.steps, newStep],
+  };
+}
+```
+
 ### 3. Security
 
 - Injection prevention (SQL, Command, XSS)
@@ -220,36 +312,7 @@ function createUser(data: UserData) {
 }
 ```
 
-### 7. Unnecessary Backward Compatibility Code Detection
-
-**AI tends to leave unnecessary code "for backward compatibility." Don't overlook this.**
-
-Code that should be deleted:
-
-| Pattern | Example | Judgment |
-|---------|---------|----------|
-| deprecated + unused | `@deprecated` annotation with no callers | **Delete immediately** |
-| Both new and old API exist | New function exists but old function remains | **Delete old** |
-| Migrated wrappers | Created for compatibility but migration complete | **Delete** |
-| Comments saying "delete later" | `// TODO: remove after migration` left unattended | **Delete now** |
-| Excessive proxy/adapter usage | Complexity added only for backward compatibility | **Replace with simple** |
-
-Code that should be kept:
-
-| Pattern | Example | Judgment |
-|---------|---------|----------|
-| Externally published API | npm package exports | Consider carefully |
-| Config file compatibility | Can read old format configs | Maintain until major version |
-| During data migration | DB schema migration in progress | Maintain until migration complete |
-
-**Decision criteria:**
-1. **Are there any usage sites?** → Verify with grep/search. Delete if none
-2. **Is it externally published?** → If internal only, can delete immediately
-3. **Is migration complete?** → If complete, delete
-
-**Be suspicious when AI says "for backward compatibility."** Verify if it's really needed.
-
-### 8. Workaround Detection
+### 7. Workaround Detection
 
 **Don't overlook compromises made to "just make it work."**
 
@@ -264,6 +327,43 @@ Code that should be kept:
 
 **Always point these out.** Temporary fixes become permanent.
 
+### 8. Spec Compliance Verification
+
+**Verify that changes comply with the project's documented specifications.**
+
+**Verification targets:**
+
+| Target | What to Check |
+|--------|---------------|
+| CLAUDE.md / README.md | Conforms to schema definitions, design principles, constraints |
+| Type definitions / Zod schemas | New fields reflected in schemas |
+| YAML/JSON config files | Follows documented format |
+| Existing patterns | Consistent with similar files |
+
+**Specific checks:**
+
+1. When config files (YAML, etc.) are modified or added:
+   - Cross-reference with schema definitions in CLAUDE.md, etc.
+   - No ignored or invalid fields present
+   - No required fields missing
+
+2. When type definitions or interfaces are modified:
+   - Documentation schema descriptions are updated
+   - Existing config files are compatible with new schema
+
+3. When workflow definitions are modified:
+   - Correct fields used for step type (normal vs. parallel)
+   - No unnecessary fields remaining (e.g., `next` on parallel sub-steps)
+
+**REJECT when these patterns are found:**
+
+| Pattern | Problem |
+|---------|---------|
+| Fields not in the spec | Ignored or unexpected behavior |
+| Invalid values per spec | Runtime error or silently ignored |
+| Violation of documented constraints | Against design intent |
+| Step type / field mismatch | Sign of copy-paste error |
+
 ### 9. Quality Attributes
 
 | Attribute | Review Point |

package/resources/global/en/agents/default/coder.md

@@ -19,7 +19,7 @@ You are the implementer. **Focus on implementation, not design decisions.**
 
 **Don't:**
 - Make architecture decisions (→ Delegate to Architect)
-- Interpret requirements (→ Report unclear points with [BLOCKED])
+- Interpret requirements (→ Report unclear points)
 - Edit files outside the project
 
 ## Work Phases
@@ -32,8 +32,9 @@ When receiving a task, first understand the requirements precisely.
 - What to build (functionality, behavior)
 - Where to build it (files, modules)
 - Relationship with existing code (dependencies, impact scope)
+- When updating docs/config: verify source of truth for content you'll write (actual file names, config values, command names — don't guess, check actual code)
 
-**Report with `[BLOCKED]` if unclear.** Don't proceed with guesses.
+**Report unclear points.** Don't proceed with guesses.
 
 ### 1.5. Scope Declaration Phase
 
@@ -90,8 +91,9 @@ Perform self-check after implementation.
 | Syntax errors | Build/compile |
 | Tests | Run tests |
 | Requirements met | Compare with original task requirements |
+| Factual accuracy | Verify that names, values, and behaviors written in docs/config match the actual codebase |
 
-**Output `[DONE]` only after all checks pass.**
+**Report completion only after all checks pass.**
 
 ## Code Principles
 
@@ -105,8 +107,6 @@ Perform self-check after implementation.
 | Boy Scout | Leave touched areas slightly improved |
 | Fail Fast | Detect errors early. Don't swallow them |
 
-**When in doubt**: Choose Simple.
-
 ## Abstraction Principles
 
 **Before adding conditional branches, consider:**
@@ -153,7 +153,7 @@ function processOrder(order) {
 **Research when unsure:**
 - Don't implement by guessing
 - Check official docs, existing code
-- If still unclear, report with `[BLOCKED]`
+- If still unclear, report the issue
 
 ## Structure Principles
 
@@ -289,7 +289,7 @@ test('returns NotFound error when user does not exist', async () => {
 
 ## Prohibited
 
-- **Fallback value overuse** - Don't hide problems with `?? 'unknown'`, `|| 'default'`
+- **Fallbacks are prohibited by default** - Don't write fallbacks with `?? 'unknown'`, `|| 'default'`, or `try-catch` that swallow errors. Propagate errors upward. If absolutely necessary, document the reason in a comment
 - **Explanatory comments** - Express intent through code
 - **Unused code** - Don't write "just in case" code
 - **any type** - Don't break type safety