maestro-flow 0.3.14 → 0.3.16

package/.codex/skills/spec-setup/SKILL.md

@@ -22,11 +22,7 @@ No arguments. Scans the codebase and generates spec files in `.workflow/specs/`.
 
 ### Step 1: Validate Preconditions
 
-```bash
-test -d .workflow || exit 1  # E001: not initialized
-```
-
-Verify project contains source files to scan (E002 if empty).
+Verify `.workflow/` exists (E001) and project contains source files (E002).
 
 ### Step 2: Scan Codebase
 
@@ -55,20 +51,7 @@ Create `.workflow/specs/` directory and write:
 
 ### Step 5: Display Report
 
-```
-=== SPEC SETUP COMPLETE ===
-Created:
-  - .workflow/specs/coding-conventions.md    (category: coding)
-  - .workflow/specs/architecture-constraints.md (category: arch)
-  - .workflow/specs/learnings.md             (category: learning)
-  {optional files if created}
-
-Next: Run Skill({ skill: "spec-add", args: "<category> <content>" }) to add entries
-Categories: coding, arch, quality, debug, test, review, learning
-Extended:   bug, pattern, decision, rule, validation (stored in closest core category file)
-Remove:  /spec-remove <entry-id>
-Wiki:    maestro wiki list --type spec (entries auto-indexed in wiki graph)
-```
+List created files with categories. Show next steps: `/spec-add <category> <content>`, available categories (core + extended), `/spec-remove`, wiki graph commands.
 
 </execution>
 

package/.codex/skills/team-coordinate/SKILL.md

@@ -91,20 +91,9 @@ Workers can use CLI tools for analysis and code operations:
 
 ### Orchestration Mode
 
-User just provides task description.
-
 **Invocation**: `Skill(skill="team-coordinate", args="task description")`
 
-**Lifecycle**:
-```
-User provides task description
-  -> coordinator Phase 1: task analysis (detect capabilities, build dependency graph)
-  -> coordinator Phase 2: generate role-specs + initialize session
-  -> coordinator Phase 3: create task chain from dependency graph
-  -> coordinator Phase 4: spawn first batch workers (background) -> STOP
-  -> Worker executes -> callback -> coordinator advances next step
-  -> Loop until pipeline complete -> Phase 5 report + completion action
-```
+**Lifecycle**: Phase 1 (task analysis, dependency graph) -> Phase 2 (generate role-specs, init session) -> Phase 3 (create task chain) -> Phase 4 (spawn workers, STOP) -> callback loop -> Phase 5 (report + completion).
 
 **User Commands** (wake paused coordinator):
 
@@ -116,134 +105,41 @@ User provides task description
 | `feedback <text>` | Inject feedback into active pipeline |
 | `improve [dimension]` | Auto-improve weakest quality dimension |
 
-### Coordinator Spawn Template
-
-#### v2 Worker Spawn (all roles)
+### Worker Spawn Template
 
-When coordinator spawns workers, use `team-worker` agent with role-spec path:
-
-```
-spawn_agent({
-  agent_type: "team_worker",
-  task_name: "<task-id>",
-  fork_turns: "none",
-  message: `## Role Assignment
-role: <role>
-role_spec: <session-folder>/role-specs/<role>.md
-session: <session-folder>
-session_id: <session-id>
-requirement: <task-description>
-inner_loop: <true|false>
-
-Read role_spec file to load Phase 2-4 domain instructions.
-
-## Task Context
-task_id: <task-id>
-title: <task-title>
-description: <task-description>
-pipeline_phase: <pipeline-phase>
-
-## Upstream Context
-<prev_context>`
-})
-```
+Spawn via `team-worker` agent with role-spec path. Message includes: role, role_spec path, session folder, session_id, requirement, inner_loop flag, task context (id, title, description, pipeline_phase), and upstream context from prior tasks.
 
-After spawning, use `wait_agent({ timeout_ms: 1800000 })` to collect results (30 min). If `result.timed_out`, send STATUS_CHECK via followup_task (wait 3 min), then FINALIZE with interrupt (wait 3 min), then mark timed_out and close agents. Use `close_agent({ target: <name> })` each worker.
+After spawning: `wait_agent` (30 min timeout). On timeout: STATUS_CHECK via followup_task (3 min) -> FINALIZE with interrupt (3 min) -> mark timed_out, close agent.
 
-**Inner Loop roles** (role has 2+ serial same-prefix tasks): Set `inner_loop: true`. The team-worker agent handles the loop internally.
-
-**Single-task roles**: Set `inner_loop: false`.
+**Inner Loop**: Set `inner_loop: true` for roles with 2+ serial same-prefix tasks. Single-task roles: `inner_loop: false`.
 
 ### Model Selection Guide
 
-Roles are **dynamically generated** at runtime. Select model/reasoning_effort based on the generated role's `responsibility_type`:
-
-| responsibility_type | model | reasoning_effort | Rationale |
-|---------------------|-------|-------------------|-----------|
-| exploration | (default) | medium | Read-heavy, less reasoning needed |
-| analysis | (default) | high | Deep analysis requires full reasoning |
-| implementation | (default) | high | Code generation needs precision |
-| synthesis | (default) | medium | Aggregation over generation |
-| review | (default) | high | Quality assessment needs deep reasoning |
+Map each role's `responsibility_type` (from `team-session.json#roles`) to reasoning effort:
 
-Map each generated role's `responsibility_type` (from `team-session.json#roles`) to the table above.
+| responsibility_type | reasoning_effort |
+|---------------------|-------------------|
+| exploration | medium |
+| analysis | high |
+| implementation | high |
+| synthesis | medium |
+| review | high |
 
-Override model/reasoning_effort in spawn_agent when cost optimization is needed:
-```
-spawn_agent({
-  agent_type: "team_worker",
-  task_name: "<task-id>",
-  fork_turns: "none",
-  model: "<model-override>",
-  reasoning_effort: "<effort-level>",
-  message: "..."
-})
-```
+Override via `model`/`reasoning_effort` params in spawn_agent for cost optimization.
 
 ### v4 Agent Coordination
 
-#### Message Semantics
-
-| Intent | API | Example |
-|--------|-----|---------|
-| Queue supplementary info (don't interrupt) | `send_message` | Send upstream task findings to a running downstream worker |
-| Not used in this skill | `followup_task` | No resident agents -- all workers are one-shot |
-| Check running agents | `list_agents` | Verify agent health during resume |
-
-**Note**: Since roles are dynamically generated, the coordinator must resolve task prefixes and role names from `team-session.json#roles` at runtime. There are no hardcoded role-specific examples.
+**Message Semantics**: `send_message` to queue supplementary info to downstream workers (non-interrupting). `list_agents` for health checks. `followup_task` not used (all workers are one-shot).
 
-#### fork_turns Strategy
+**fork_turns**: Default `"none"`. Use `"all"` only when task requires deep familiarity with full conversation context (decided per-task in Phase 4).
 
-`fork_turns: "none"` is the default. Consider `fork_turns: "all"` only when:
-- Runtime analysis reveals the task requires deep familiarity with the full conversation context
-- The dynamically-generated role-spec indicates the worker needs project-wide understanding
-- The coordinator has already accumulated significant context about the codebase
+**Agent Health Check**: On resume/complete, reconcile `team-session.json.active_workers` with `list_agents({})`. Reset orphaned tasks (in_progress but agent gone) to pending.
 
-This decision should be made per-task during Phase 4 based on the role's `responsibility_type`.
-
-#### Agent Health Check
-
-Use `list_agents({})` in handleResume and handleComplete:
-
-```
-// Reconcile session state with actual running agents
-const running = list_agents({})
-// Compare with team-session.json active_workers
-// Reset orphaned tasks (in_progress but agent gone) to pending
-```
-
-#### Named Agent Targeting
-
-Workers are spawned with `task_name: "<task-id>"` enabling direct addressing:
-- `send_message({ target: "<TASK-ID>", message: "..." })` -- queue upstream context without interrupting
-- `close_agent({ target: "<TASK-ID>" })` -- cleanup by name
+**Named Targeting**: Workers spawned with `task_name: "<task-id>"` for `send_message`/`close_agent` by name.
 
 ### Completion Action
 
-When pipeline completes (all tasks done), coordinator presents an interactive choice:
-
-```
-request_user_input({
-  questions: [{
-    question: "Team pipeline complete. What would you like to do?",
-    header: "Completion",
-    multiSelect: false,
-    options: [
-      { label: "Archive & Clean (Recommended)", description: "Archive session, clean up team" },
-      { label: "Keep Active", description: "Keep session for follow-up work" },
-      { label: "Export Results", description: "Export deliverables to target directory, then clean" }
-    ]
-  }]
-})
-```
-
-#### Action Handlers
-
-| Choice | Steps |
-|--------|-------|
-| Archive & Clean | Update session status="completed" -> output final summary with artifact paths |
-| Keep Active | Update session status="paused" -> output: "Resume with: Skill(skill='team-coordinate', args='resume')" |
-| Export Results | request_user_input(target path) -> copy artifacts to target -> Archive & Clean |
+Present interactive choice via `request_user_input`: **Archive & Clean** (recommended -- mark completed, output summary), **Keep Active** (mark paused, output resume command), **Export Results** (prompt target path, copy artifacts, then archive).
 
 ### Specs Reference
 
@@ -310,15 +206,7 @@ request_user_input({
 
 ### Session Resume
 
-Coordinator supports `resume` / `continue` for interrupted sessions:
-
-1. Scan `.workflow/.team/TC-*/team-session.json` for active/paused sessions
-2. Multiple matches -> request_user_input for selection
-3. Audit task states -> reconcile session state <-> task status
-4. Reset in_progress -> pending (interrupted tasks)
-5. Rebuild team and spawn needed workers only
-6. Create missing tasks, set dependencies
-7. Kick first executable task -> Phase 4 coordination loop
+Scan `TC-*/team-session.json` for active/paused sessions (prompt if multiple). Reconcile state: reset interrupted tasks to pending, rebuild team, spawn needed workers, resume Phase 4 loop.
 </context>
 
 <error_codes>

package/.codex/skills/team-coordinate/roles/coordinator/commands/monitor.md

@@ -62,27 +62,14 @@ Parse `$ARGUMENTS` to determine handler:
 Worker completed a task. Verify completion, update state, auto-advance.
 
 ```
-Receive result from wait_agent for [<role>]
-  +- Find matching active worker by role (from session.roles)
-  +- Is this a progress update (not final)? (Inner Loop intermediate task completion)
-  |   +- YES -> Update session state, do NOT remove from active_workers -> STOP
-  +- Task status = completed?
-  |   +- YES -> remove from active_workers -> update session
-  |   |   +- Close agent: close_agent({ target: <agentId> })
-  |   |   +- -> handleSpawnNext
-  |   +- NO -> progress message, do not advance -> STOP
-  +- No matching worker found
-      +- Scan all active workers for completed tasks
-      +- Found completed -> process each -> handleSpawnNext
-      +- None completed -> STOP
+Match worker by role -> route:
+  progress_update (not final) -> update state, keep in active_workers -> STOP
+  completed -> remove from active_workers, close_agent, -> handleSpawnNext
+  not_completed -> log progress -> STOP
+  no_match -> scan all workers for completions -> process any found -> handleSpawnNext, else STOP
 ```
 
-**Fast-advance reconciliation**: A worker may have already spawned its successor via fast-advance. When processing any callback or resume:
-1. Read recent `fast_advance` messages from team_msg (type="fast_advance")
-2. For each fast_advance message: add the spawned successor to `active_workers` if not already present
-3. Check if the expected next task is already `in_progress` (fast-advanced)
-4. If yes -> skip spawning that task (already running)
-5. If no -> normal handleSpawnNext
+**Fast-advance reconciliation**: On any callback/resume, sync `fast_advance` messages from team_msg into `active_workers`. Skip spawning tasks already `in_progress` via fast-advance.
 
 ---
 
@@ -90,17 +77,8 @@ Receive result from wait_agent for [<role>]
 
 Read-only status report with progress milestones. No pipeline advancement.
 
-1. Read tasks.json for pipeline state
-2. Read worker progress from message bus:
-   ```javascript
-   const progressMsgs = mcp__maestro-tools__team_msg({
-     operation: "list", session_id: sessionId, type: "progress", last: 50
-   })
-   const blockerMsgs = mcp__maestro-tools__team_msg({
-     operation: "list", session_id: sessionId, type: "blocker", last: 10
-   })
-   ```
-3. Aggregate latest milestone per active worker
+1. Read tasks.json + team_msg (type="progress", last=50) + team_msg (type="blocker", last=10)
+2. Aggregate latest milestone per active worker
 
 **Output format**:
 
@@ -136,29 +114,17 @@ Then STOP.
 
 ### Handler: handleResume
 
-**Agent Health Check** (v4):
-```
-// Verify actual running agents match session state
-const runningAgents = list_agents({})
-// For each active_agent in tasks.json:
-//   - If agent NOT in runningAgents -> agent crashed
-//   - Reset that task to pending, remove from active_agents
-// This prevents stale agent references from blocking the pipeline
-```
+**Agent Health Check** (v4): Cross-check `list_agents()` against session `active_workers`. Any agent not actually running -> reset task to pending, remove from active_workers.
 
 Check active worker completion, process results, advance pipeline.
 
 ```
-Load active_workers from session
-  +- No active workers -> handleSpawnNext
-  +- Has active workers -> check each:
-      +- status = completed -> mark done, log
-      +- status = in_progress -> still running, log
-      +- other status -> worker failure -> reset to pending
-      After processing:
-        +- Some completed -> handleSpawnNext
-        +- All still running -> report status -> STOP
-        +- All failed -> handleSpawnNext (retry)
+Load active_workers -> route:
+  none -> handleSpawnNext
+  has workers -> classify each: completed | in_progress | failed(reset to pending)
+    some completed -> handleSpawnNext
+    all running -> report status -> STOP
+    all failed -> handleSpawnNext (retry)
 ```
 
 ---
@@ -168,155 +134,61 @@ Load active_workers from session
 Find all ready tasks, spawn team_worker agents, update session, STOP.
 
 ```
-Collect task states from tasks.json
-  +- completedSubjects: status = completed
-  +- inProgressSubjects: status = in_progress
-  +- readySubjects: pending + all deps in completedSubjects
-
-Ready tasks found?
-  +- NONE + work in progress -> report waiting -> STOP
-  +- NONE + nothing in progress -> PIPELINE_COMPLETE -> handleComplete
-  +- HAS ready tasks -> for each:
-      +- Is task role an Inner Loop role AND that role already has an active_worker?
-      |   +- YES -> SKIP spawn (existing worker will pick it up via inner loop)
-      |   +- NO -> normal spawn below
-      +- Update tasks.json entry status -> "in_progress"
-      +- team_msg log -> task_unblocked (session_id=<session-id>)
-      +- Spawn team_worker (see spawn call below)
-      +- Add to session.active_workers
-      Update session file -> output summary -> STOP
+Classify tasks: completed | in_progress | ready (pending + all deps completed)
+
+Ready tasks -> route:
+  none + in_progress exists -> report waiting -> STOP
+  none + nothing in_progress -> PIPELINE_COMPLETE -> handleComplete
+  has ready -> for each:
+    skip if Inner Loop role already has active_worker
+    else: set status="in_progress", log task_unblocked, spawn team_worker, add to active_workers
+  Update session -> output summary -> STOP
 ```
 
-**Cross-Agent Supplementary Context** (v4):
+**Cross-Agent Supplementary Context** (v4): When spawning later-phase workers, use `send_message` (not `followup_task`) to deliver upstream results to already-running downstream workers as non-interrupting supplementary context.
 
-When spawning workers in a later pipeline phase, send upstream results as supplementary context to already-running workers:
+**Spawn worker call** (one per ready task):
 
 ```
-// Example: Send upstream task results to running downstream workers
-send_message({
-  target: "<running-agent-task-name>",
-  message: `## Supplementary Context\n${upstreamFindings}`
-})
-// Note: send_message queues info without interrupting the agent's current work
+spawn_agent({ agent_type: "team_worker", task_name: taskId, message: <role-assignment> })
 ```
 
-Use `send_message` (not `followup_task`) for supplementary info that enriches but doesn't redirect the agent's current task.
-
-**Spawn worker call** (one per ready task):
-
+**Role assignment message template**:
 ```
-const agentId = spawn_agent({
-  agent_type: "team_worker",
-  task_name: taskId,  // e.g., "EXPLORE-001" — enables named targeting
-  message: `## Role Assignment
-role: <role>
-role_spec: <session-folder>/role-specs/<role>.md
-session: <session-folder>
-session_id: <session-id>
-team_name: <team-name>
-requirement: <task-description>
-inner_loop: <true|false>
-
-Read role_spec file to load Phase 2-4 domain instructions.
-
+## Role Assignment
+role: <role> | role_spec: <session-folder>/role-specs/<role>.md
+session: <session-folder> | session_id: <session-id> | team_name: <team-name>
+requirement: <task-description> | inner_loop: <true|false>
+Read role_spec for Phase 2-4 instructions.
 ## Progress Milestones
-session_id: ${sessionId}
-Report progress via team_msg at natural phase boundaries.
-Report blockers immediately via team_msg type="blocker".
-Report completion via team_msg type="task_complete" after report_agent_job_result.`
-})
-// Collect results — use task_name for stable targeting (v4):
-const result = wait_agent({ timeout_ms: 1800000 })  // 30 min
-
-// Drain progress from message bus (before processing results)
-const progressMsgs = mcp__maestro-tools__team_msg({
-  operation: "list", session_id: sessionId, type: "progress", last: 100
-})
-for (const msg of (progressMsgs.result?.messages || [])) {
-  console.log(`[coordinator] trace: ${msg.summary}`)
-}
-
-if (result.timed_out) {
-  // Status probe before closing
-  followup_task({ target: taskId, message: "STATUS_CHECK: Report current progress, findings so far, and estimated remaining work." })
-  const status = wait_agent({ timeout_ms: 180000 })  // 3 min
-  if (status.timed_out) {
-    followup_task({ target: taskId, message: "FINALIZE: Output all current findings immediately. Time limit reached.", interrupt: true })
-    const forced = wait_agent({ timeout_ms: 180000 })  // 3 min
-    if (forced.timed_out) {
-      const lastProgress = (progressMsgs.result?.messages || [])
-        .filter(m => m.data?.task_id === taskId).pop()
-      state.tasks[taskId].status = 'timed_out'
-      state.tasks[taskId].error = lastProgress
-        ? `Timed out at ${lastProgress.data.phase} (${lastProgress.data.progress_pct}%)`
-        : 'Timed out with no progress reported'
-      close_agent({ target: taskId })
-    }
-    // else: forced output received, process result
-  }
-  // else: status received, continue processing
-} else {
-  // Process result, update tasks.json
-  close_agent({ target: taskId })  // Use task_name, not agentId
-}
+Report progress via team_msg at phase boundaries. Blockers via type="blocker". Completion via type="task_complete" after report_agent_job_result.
 ```
 
+**Result collection**: `wait_agent({ timeout_ms: 1800000 })` (30 min), drain progress from team_msg.
+
+**Timeout escalation**: STATUS_CHECK (3 min) -> FINALIZE with interrupt (3 min) -> mark timed_out with last progress context, close_agent. Normal completion -> process result, close_agent (use task_name, not agentId).
+
 ---
 
 ### Handler: handleComplete
 
-**Cleanup Verification** (v4):
-```
-// Verify all agents are properly closed
-const remaining = list_agents({})
-// If any team agents still running -> close_agent each
-// Ensures clean session shutdown
-```
+**Cleanup Verification** (v4): `list_agents()` -> close any still-running team agents.
 
 Pipeline complete. Execute completion action based on session configuration.
 
 ```
-All tasks completed (no pending, no in_progress)
-  +- Generate pipeline summary:
-  |   - Deliverables list with paths
-  |   - Pipeline stats (tasks completed, duration)
-  |   - Discussion verdicts (if any)
-  |
-  +- Read session.completion_action:
-      |
-      +- "interactive":
-      |   request_user_input({
-      |     questions: [{
-      |       question: "Team pipeline complete. What would you like to do?",
-      |       header: "Completion",
-      |       multiSelect: false,
-      |       options: [
-      |         { label: "Archive & Clean (Recommended)", description: "Archive session, clean up team" },
-      |         { label: "Keep Active", description: "Keep session for follow-up work" },
-      |         { label: "Export Results", description: "Export deliverables to target directory" }
-      |       ]
-      |     }]
-      |   })
-      |   +- "Archive & Clean":
-      |   |   Update session status="completed"
-      |   |   Clean up session
-      |   |   Output final summary with artifact paths
-      |   +- "Keep Active":
-      |   |   Update session status="paused"
-      |   |   Output: "Resume with: Skill(skill='team-coordinate', args='resume')"
-      |   +- "Export Results":
-      |       request_user_input for target directory
-      |       Copy deliverables to target
-      |       Execute Archive & Clean flow
-      |
-      +- "auto_archive":
-      |   Execute Archive & Clean without prompt
-      |
-      +- "auto_keep":
-          Execute Keep Active without prompt
-```
+Generate summary: deliverables + stats + verdicts
+
+Route by session.completion_action:
+  "interactive" -> request_user_input with options:
+    "Archive & Clean" -> status="completed", cleanup, output artifact paths
+    "Keep Active"     -> status="paused", output resume command
+    "Export Results"   -> prompt for target dir, copy deliverables, then Archive & Clean
+  "auto_archive" -> Archive & Clean without prompt
+  "auto_keep"    -> Keep Active without prompt
 
-**Fallback**: If completion action fails, default to Keep Active (session status="paused"), log warning.
+Fallback: default to Keep Active on failure.
+```
 
 ---
 
@@ -327,25 +199,11 @@ Handle mid-pipeline capability gap discovery. A worker reports `capability_gap`
 **CONSTRAINT**: Maximum 5 worker roles per session. handleAdapt MUST enforce this limit.
 
 ```
-Parse capability_gap message:
-  +- Extract: gap_description, requesting_role, suggested_capability
-  +- Validate gap is genuine:
-      +- Check existing roles in session.roles -> does any role cover this?
-      |   +- YES -> redirect to that role -> STOP
-      |   +- NO -> genuine gap, proceed to role-spec generation
-  +- CHECK ROLE COUNT LIMIT (MAX 5 ROLES):
-      +- Count current roles in session.roles
-      +- If count >= 5:
-          +- Attempt to merge new capability into existing role
-          +- If merge NOT possible -> PAUSE, report to user
-  +- Generate new role-spec:
-      1. Read specs/role-spec-template.md
-      2. Fill template with: frontmatter (role, prefix, inner_loop, message_types) + Phase 2-4 content
-      3. Write to <session-folder>/role-specs/<new-role>.md
-      4. Add to session.roles[]
-  +- Create new task(s) (add to tasks.json)
-  +- Update team-session.json
-  +- Spawn new team_worker -> STOP
+Extract: gap_description, requesting_role, suggested_capability
+Validate: existing role covers gap? -> redirect -> STOP
+Enforce MAX 5 ROLES: count >= 5 -> attempt merge, else PAUSE for user
+Generate role-spec from template -> write to role-specs/<new-role>.md -> add to session.roles
+Create task(s) in tasks.json -> update session -> spawn team_worker -> STOP
 ```
 
 ---
@@ -363,14 +221,8 @@ When a worker has unexpected status (not completed, not in_progress):
 When coordinator detects a fast-advanced task has failed:
 
 ```
-handleCallback / handleResume detects:
-  +- Task is in_progress (was fast-advanced by predecessor)
-  +- No active_worker entry for this task
-  +- Resolution:
-      1. Update tasks.json -> reset task to pending
-      2. Remove stale active_worker entry (if any)
-      3. Log via team_msg (type: error)
-      4. -> handleSpawnNext (will re-spawn the task normally)
+Detect: task in_progress with no active_worker (stale fast-advance)
+-> reset to pending, remove stale entry, log error, -> handleSpawnNext
 ```
 
 ### Fast-Advance State Sync
@@ -383,16 +235,10 @@ On every coordinator wake (handleCallback, handleResume, handleCheck):
 ### Consensus-Blocked Handling
 
 ```
-handleCallback receives message with consensus_blocked flag
-  +- Route by severity:
-      +- severity = HIGH
-      |   +- Create REVISION task (same role, incremented suffix)
-      |   +- Max 1 revision per task. If already revised -> PAUSE, escalate to user
-      +- severity = MEDIUM
-      |   +- Proceed with warning, log to wisdom/issues.md
-      |   +- Normal handleSpawnNext
-      +- severity = LOW
-          +- Proceed normally, treat as consensus_reached with notes
+Route by consensus_blocked severity:
+  HIGH   -> create REVISION task (max 1 per task, else PAUSE + escalate)
+  MEDIUM -> proceed with warning, log to wisdom/issues.md, -> handleSpawnNext
+  LOW    -> proceed normally, treat as consensus_reached with notes
 ```
 
 ## Phase 4: Validation