modu-ai
diff --git a/‎.claude/agents/moai/manager-spec.md‎
Lines changed: 47 additions & 1 deletion b/‎.claude/agents/moai/manager-spec.md‎
Lines changed: 47 additions & 1 deletion
diff --git a/‎.claude/output-styles/moai/moai.md‎
Lines changed: 3 additions & 1 deletion b/‎.claude/output-styles/moai/moai.md‎
Lines changed: 3 additions & 1 deletion
diff --git a/‎.claude/rules/moai/core/agent-common-protocol.md‎
Lines changed: 39 additions & 0 deletions b/‎.claude/rules/moai/core/agent-common-protocol.md‎
Lines changed: 39 additions & 0 deletions
@@ -110,12 +110,55 @@ OUT OF SCOPE: Code implementation (manager-ddd/tdd), Git operations (manager-git
 
 [HARD] Use MultiEdit for simultaneous 3-file creation (60% faster than sequential):
 
-**spec.md**: YAML frontmatter (8 fields: id, version, status, created, updated, author, priority, issue_number), HISTORY section, EARS requirements, exclusions.
+**spec.md**: YAML frontmatter (9 required fields, see schema below), HISTORY section, EARS requirements, exclusions.
 
 **plan.md**: Implementation plan, milestones (priority-based, no time estimates), technical approach, risks.
 
 **acceptance.md**: Given-When-Then scenarios (minimum 2), edge cases, quality gate criteria, Definition of Done.
 
+#### [HARD] SPEC Frontmatter Canonical Schema
+
+[HARD] Every `spec.md` YAML frontmatter MUST contain ALL 9 required fields below. Missing any one is a schema violation and blocks creation. This schema is non-negotiable — aligns with plan-auditor expectations and prevents the 2026-04-21 mass-SPEC-drift incident (30 SPECs generated with inconsistent fields).
+
+```yaml
+---
+id: SPEC-{DOMAIN}-{NUM}                 # Required. Format: SPEC-[A-Z]+-[0-9]+
+version: "0.1.0"                         # Required. Semantic version as quoted string
+status: draft                            # Required. Enum: draft|approved|completed|superseded|archived
+created_at: YYYY-MM-DD                   # Required. ISO date. NEVER use `created` (legacy, rejected)
+updated_at: YYYY-MM-DD                   # Required. ISO date. NEVER use `updated` (legacy, rejected)
+author: <name or role>                   # Required. String. Recommended: agent name or user identifier
+priority: High|Medium|Low|Critical       # Required. Enum (Title case). Alt: P0|P1|P2|P3 (uppercase)
+labels: [domain1, domain2, ...]          # Required. YAML array of lowercase tags. Empty array [] allowed only if justified.
+issue_number: null                       # Required. Integer | null. GitHub Issue number when created.
+---
+```
+
+Optional fields (include when applicable):
+- `depends_on: [SPEC-X-001, SPEC-Y-002]` — SPEC IDs this one blocks on
+- `related_specs: [SPEC-Z-001]` — Non-blocking references
+- `superseded_by: SPEC-NEW-001` — When status=superseded
+- `partially_superseded_by: [SPEC-A-001]` — Partial supersession
+- `issue_number: 123` — After GitHub Issue creation
+- `merged_pr: [N, M]` — Post-merge provenance
+- `merged_commit: <hash>` — Post-merge provenance
+
+[HARD] Field name aliases REJECTED (common errors caught by plan-auditor):
+- `created` → must be `created_at`
+- `updated` → must be `updated_at`
+- `spec_id` → must be `id`
+- `title` in frontmatter → put title in H1 heading, not frontmatter
+
+Pre-write validation (you MUST verify before calling Write/MultiEdit):
+1. All 9 required fields present
+2. `id` matches regex `^SPEC-[A-Z][A-Z0-9]+-[0-9]{3}$`
+3. `status` is one of the 5 enum values
+4. `priority` is Title-case or P-prefixed uppercase
+5. `created_at` / `updated_at` are ISO YYYY-MM-DD (not `created` / `updated`)
+6. `labels` is a YAML array (not comma-separated string)
+7. `version` is a quoted string (not unquoted float like `0.1`)
+8. If any check fails: halt, report the missing/invalid field, do NOT write the file
+
 ### Step 5: Verification Checklist
 
 - [ ] Directory format: `.moai/specs/SPEC-{ID}/`
@@ -124,6 +167,9 @@ OUT OF SCOPE: Code implementation (manager-ddd/tdd), Git operations (manager-git
 - [ ] EARS format compliant
 - [ ] Exclusions section present
 - [ ] No implementation details in spec.md
+- [ ] Frontmatter 9-field canonical schema validated (see Step 4)
+- [ ] `created_at` / `updated_at` used (NOT `created` / `updated`)
+- [ ] `labels` array present (non-empty unless documented reason)
 
 ### Step 6: Expert Consultation (Conditional)
 
 
@@ -74,7 +74,8 @@ Trigger conditions (any one activates Stage 1):
 - Potential conflict with current state (uncommitted changes, partial branches)
 
 Process:
-1. Ask via `AskUserQuestion` (max 4 options, user language, no emoji)
+0. First: `ToolSearch(query: "select:AskUserQuestion")` — preload deferred tool schema before every AskUserQuestion call (see `.claude/rules/moai/core/askuser-protocol.md` §ToolSearch Preload Procedure)
+1. Ask via `AskUserQuestion` (max 4 questions per round, max 4 options per question, user language, no emoji, first option marked `(권장)`/`(Recommended)`)
 2. Build on previous answers; continue rounds until 100% intent clarity
 3. Consolidate into a short report
 4. Obtain explicit final confirmation before Stage 2
@@ -310,6 +311,7 @@ Rules:
 - [HARD] Parallel tool calls when no dependencies
 - [HARD] File paths include `file:line` for navigation
 - [HARD] No time estimates ("2-3 days" forbidden); use priority labels
+- [HARD] **free-form interrogative prose in response body is prohibited as a question channel.** All user-facing questions MUST go through `AskUserQuestion` (which automatically provides an `Other` option for free-form answers when needed). Anti-pattern: embedding `?` questions or `- A: / - B:` option lists in response prose instead of calling `AskUserQuestion`. Canonical reference: `.claude/rules/moai/core/askuser-protocol.md`
 
 ---
 
 
@@ -4,6 +4,10 @@ Shared protocol for all MoAI agent definitions. This rule is automatically loade
 
 ## User Interaction Boundary
 
+`AskUserQuestion` is the **only** user-facing question channel. The boundary is asymmetric by design.
+
+### Subagent Prohibitions
+
 [HARD] Subagents MUST NOT prompt the user. AskUserQuestion is reserved exclusively for the MoAI orchestrator.
 
 Rules for subagents:
@@ -17,6 +21,41 @@ Rationale:
 - Attempting to prompt inside a subagent produces a dead channel — no response arrives
 - This rule preserves the orchestrator's single-point-of-contact with the user (see CLAUDE.md Section 8)
 
+### Orchestrator Obligations
+
+The MoAI orchestrator MUST follow these obligations when using AskUserQuestion:
+
+- [HARD] The orchestrator MUST preload AskUserQuestion via `ToolSearch(query: "select:AskUserQuestion")` before each call — AskUserQuestion is a deferred tool and its schema is not loaded at session start
+- [HARD] All user-facing questions MUST go through AskUserQuestion — free-form prose questions in response text are prohibited
+- Collect all user preferences before delegating to subagents via Agent()
+- On receiving a blocker report from a subagent: run an AskUserQuestion round, inject the user's responses into a fresh subagent prompt, and re-delegate
+
+Canonical reference: see `.claude/rules/moai/core/askuser-protocol.md` for full preload sequence, Socratic interview structure, and anti-pattern catalog.
+
+### Blocker Report Format
+
+When a subagent requires user input not provided in the spawn prompt, it MUST return a structured blocker report:
+
+```markdown
+## Missing Inputs
+
+The following parameters are required but were not provided:
+
+| Parameter | Type | Expected Values | Rationale |
+|-----------|------|-----------------|-----------|
+| [name]    | [type] | [values]      | [why needed] |
+
+**Blocker**: Cannot proceed without the above inputs. Please re-delegate with these values injected into the prompt.
+```
+
+### Re-delegation Procedure
+
+On receiving a blocker report, the orchestrator:
+1. Invokes `ToolSearch(query: "select:AskUserQuestion")`
+2. Runs an AskUserQuestion round to collect the missing inputs from the user
+3. Constructs a fresh subagent prompt with the user's answers injected
+4. Re-delegates to the subagent
+
 ## Language Handling
 
 [HARD] All agents receive and respond in user's configured conversation_language.