---
name: eck:validate
version: "0.7.4"
description: "Validation orchestrator: quality gates, code review, security scan, CI triage, and user acceptance testing against FRD.md criteria."
disable-model-invocation: false
---

# Validate

Validate development quality against FRD.md acceptance criteria and TASKS.md goals. Dispatches to validate-\* sub-skills with mode-calibrated depth, then handles approval, merge, and tracker updates.

---

## Visual Framework

Follow the visual framework defined in the `output:visual-framework` primitive.

---

## Task Registration

| Stage | Subject             | Active Form          | Statusline       |
| ----- | ------------------- | -------------------- | ---------------- |
| 1     | Stage 1: Calibrate  | Calibrating gates    | Calibrate (1/11) |
| 2     | Stage 2: Quality    | Running quality      | Quality (2/11)   |
| 3     | Stage 3: Code       | Reviewing code       | Code (3/11)      |
| 4     | Stage 4: Security   | Scanning security    | Security (4/11)  |
| 5     | Stage 5: Pipeline   | Checking pipeline    | Pipeline (5/11)  |
| 6     | Stage 6: Documents  | Validating documents | Documents (6/11) |
| 7     | Stage 7: Acceptance | Running acceptance   | Accept (7/11)    |
| 8     | Stage 8: Review     | Reviewing validate   | Review (8/11)    |
| 9     | Stage 9: Approval   | Checking approval    | Approve (9/11)   |
| 10    | Stage 10: Merge     | Merging to dev       | Merge (10/11)    |
| 11    | Stage 11: Tracker   | Updating tracker     | Tracker (11/11)  |

## Statusline Stage Updates

At the start of each stage:

```bash
bash $ECK_HOME/update-stage.sh "Name (N/11)"
```

At skill completion (success or error):

```bash
bash $ECK_HOME/update-stage.sh
```

## Usage

```bash
/eck:validate                              # Standard validation
/eck:validate --against TASKS.md          # Load specific plan file
/eck:validate --rigor lite                # Quality gates only
/eck:validate --rigor standard             # Quality + code review + CI
/eck:validate --rigor strict             # All 5 sub-skills
/eck:validate --security                  # Force security scan
/eck:validate --uat                       # Force UAT stage
--force                                   # Override prerequisite gate check (not available at strict rigor)
```

### Flags

| Flag         | Description                                                      |
| ------------ | ---------------------------------------------------------------- |
| `--against`  | Load a specific plan file for UAT                                |
| `--rigor`    | Override development rigor for this run                          |
| `--security` | Force security scan regardless of mode                           |
| `--uat`      | Force UAT stage regardless of mode                               |
| `--force`    | Override prerequisite gate check (not available at strict rigor) |

---

## Context Budget — Agent Dispatch Required

> **Stages 2–6 MUST dispatch their sub-skills via the Agent tool**, not inline invocation. The validate orchestrator has 11 stages with 5 heavy gate stages (quality, code, security, pipeline, documents) that produce verbose output. Inline execution exhausts the context window before reaching Stage 8 (Review). Each Agent dispatch returns only a compact summary, keeping the orchestrator lean enough to complete all stages.

---

## Sub-Skill Dispatch

| Sub-skill         | Invocation                                   | Purpose                                                   |
| ----------------- | -------------------------------------------- | --------------------------------------------------------- |
| validate-quality  | `/<PROJECT_KEY_LOWERCASE>:validate-quality`  | Lint, type checks, test suite                             |
| validate-code     | `/<PROJECT_KEY_LOWERCASE>:validate-code`     | Language-aware code review                                |
| validate-security | `/<PROJECT_KEY_LOWERCASE>:validate-security` | Security review and secret scanning                       |
| validate-ci       | `/<PROJECT_KEY_LOWERCASE>:validate-ci`       | CI failure diagnosis and fix proposals                    |
| validate-docs     | `/<PROJECT_KEY_LOWERCASE>:validate-docs`     | Feature doc quality: traceability, freshness, terminology |
| validate-uat      | `/<PROJECT_KEY_LOWERCASE>:validate-uat`      | User acceptance testing against FRD.md AC-IDs             |
| validate-review   | `/<PROJECT_KEY_LOWERCASE>:validate-review`   | Review gate (mandatory)                                   |
| validate-approval | `/<PROJECT_KEY_LOWERCASE>:validate-approval` | PR approval gate (CI + reviewer)                          |
| validate-merge    | `/<PROJECT_KEY_LOWERCASE>:validate-merge`    | Merge approved PR to integration branch                   |
| deploy-tracker    | `/<PROJECT_KEY_LOWERCASE>:deploy-tracker`    | Update tracker issue status                               |

> **Sub-skill invocation rule:** All sub-skills above MUST be invoked with the project key prefix derived from `PROJECT_KEY` in `.claude/project-constants.md`. For example, if `PROJECT_KEY=WA`, invoke `/wa:validate-quality`, not `/validate-quality`.

---

## Stage 0: Gate Check

> **Pre-execution prerequisite validation — does not appear in Task Registration.**

### Inputs

- Feature slug from `<FEATURE_SLUG>` or `$ARGUMENTS`
- `--force` flag (if present)

### Activities

1. Invoke `core/ops:gate-check` primitive with:
   - `feature_slug`: current feature
   - `required_step`: `develop`
   - `rigor`: current rigor level from `core/mode:read-dev-rigor`
2. If gate check passes: proceed to Stage 1.
3. If gate check fails:
   - **Without `--force`**: Display blocking reason and guidance. STOP.

     ```
     ⚠ Prerequisite not met: develop phase must be complete with passing review gate.
     Current status: <status> | Gate verdict: <verdict>

     Options:
     - Complete /eck:develop first
     - Re-run with --force to override (not available at strict rigor)
     ```

   - **With `--force`** (lite/standard only): Record override in lifecycle.json and proceed.
     At strict rigor, `--force` is rejected with: "Hard block at strict rigor — complete prerequisites first."

### Outputs

- Gate check result (pass/fail/forced)

### Exit Criteria

- Prerequisites verified OR override recorded

---

## Stage 1: Calibrate

```bash
bash $ECK_HOME/update-stage.sh "Calibrate (1/11)"
```

### Inputs

- `$ARGUMENTS` — flags and plan reference
- `docs/{feature}/FRD.md` — acceptance criteria (if exists)
- `docs/{feature}/TASKS.md` — task goals (if exists)
- Development mode via `mode:read-dev-rigor` primitive

### Activities

1. Resolve development mode using the `mode:read-dev-rigor` primitive. Default: `standard`.
2. Check for existing state file:

   ```bash
   FEATURE_ID=$(node $ECK_HOME/update-lifecycle.js read 2>/dev/null | node -e "const d=JSON.parse(require('fs').readFileSync(0,'utf-8'));console.log(d.active_feature||'')" 2>/dev/null)
   [ -z "$FEATURE_ID" ] && FEATURE_ID=$(node $ECK_HOME/manage-features.js resolve "$ARGUMENTS" 2>/dev/null | jq -r '.id // empty')
   FEATURE_SLUG=$(node $ECK_HOME/manage-features.js read "$FEATURE_ID" 2>/dev/null | jq -r '.slug // empty')
   cat "$CLAUDE_PROJECT_DIR/docs/${FEATURE_ID}-${FEATURE_SLUG}/VALIDATE-STATE.md" 2>/dev/null || echo "No state file"
   ```

   If found, offer resume via AskUserQuestion:

   ```
   Found VALIDATE-STATE.md from a previous session.
   Options:
     1 - Resume from where you left off
     2 - Start fresh (discard previous state)
   ```

   If resume: load state, skip completed gates, resume from the last incomplete stage.

3. Load `docs/{feature}/FRD.md` if it exists. Extract AC-IDs for UAT checklist.
4. If `--against` was specified, load the named plan file. Otherwise check for `docs/{feature}/TASKS.md` or `.claude/TASKS.md`.
5. If FRD.md not found, fall back to TASKS.md goals:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${YELLOW}[>]${RESET} No FRD.md found — using TASKS.md goals for UAT"
printf '%b\n' "    ${DIM}Run /eck:spec for AC-ID-based validation.${RESET}"
```

6. Determine verification depth:

| Mode         | Gates That Run                                                                               |
| ------------ | -------------------------------------------------------------------------------------------- |
| **lite**     | validate-quality (tests only)                                                                |
| **standard** | validate-quality, validate-code, validate-security (conditional), validate-ci, validate-docs |
| **strict**   | validate-quality, validate-code, validate-security, validate-ci, validate-docs, validate-uat |

At **standard**, validate-security runs conditionally — only if changes touch auth/API/data/secrets (mirroring the develop-phase security behavior). At **strict**, it always runs.

The `--security` flag forces validate-security in any mode. The `--uat` flag adds validate-uat to any mode.

### Outputs

- Resolved mode and gate configuration
- FRD.md AC-IDs loaded (if available)
- TASKS.md goals loaded (if available)

### Exit Criteria

- Development mode resolved
- Gate set determined
- At least one plan or spec file loaded (or fallback acknowledged)

### Display Calibration Summary

```bash
source $ECK_HOME/colors.sh

echo ""
printf '%b\n' "${ORANGE}${BOLD}Validate Calibration${RESET}"
echo ""
printf '%b\n' "Mode: {MODE}"
printf '%b\n' "FRD.md: {LOADED | not found}"
printf '%b\n' "AC-IDs: {COUNT} criteria for UAT"
printf '%b\n' "Plan File: {PLAN_FILE or none}"
printf '%b\n' "Gates Enabled: {N} of 5"
echo ""

printf '%b\n' "${BOLD}Gates${RESET}"
printf '%b\n' "${GREEN}[x]${RESET} validate-quality"
printf '%b\n' "${GREEN}[x]${RESET} validate-code      ${DIM}(skipped in lite)${RESET}"
printf '%b\n' "${GREEN}[x]${RESET} validate-security  ${DIM}(conditional in standard, always in strict, or --security)${RESET}"
printf '%b\n' "${GREEN}[x]${RESET} validate-ci        ${DIM}(skipped in lite)${RESET}"
printf '%b\n' "${DIM}[-]${RESET} validate-uat       ${DIM}(strict or --uat)${RESET}"
```

---

## Stage 2: Quality

**Always runs regardless of mode.**

```bash
bash $ECK_HOME/update-stage.sh "Quality (2/11)"
```

### Inputs

- Development mode (lite → tests only)

### Activities

1. **MUST** dispatch `/<PROJECT_KEY_LOWERCASE>:validate-quality` via the **Agent tool** to keep orchestrator context lean. Pass `--tests-only` when mode is `lite`.

   The Agent prompt should instruct the subagent to:
   - Run the validate-quality sub-skill
   - Return a **compact summary only**: per-gate verdict (PASS/FAIL) and error count per gate
   - Do NOT return full test output, lint output, or typecheck output

   Example Agent dispatch:

   ```
   Agent tool — prompt:
   "Run /{PK}:validate-quality {flags}. Return ONLY a compact summary:
   - review:test: PASS or FAIL (N failures)
   - review:lint: PASS or FAIL (N errors)
   - review:typecheck: PASS or FAIL (N errors)
   Do not include full test output or lint listings."
   ```

2. Parse the agent's returned summary to collect results for each gate:

| Gate               | Check                            |
| ------------------ | -------------------------------- |
| `review:test`      | Test suite passes                |
| `review:lint`      | No lint errors                   |
| `review:typecheck` | No type errors (skipped in lite) |

3. If **all enabled gates fail**, STOP:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${RED}[!]${RESET} All quality gates failed. Halting validation."
printf '%b\n' "    ${DIM}Fix test, lint, and typecheck errors before re-running.${RESET}"
```

Reset statusline and exit.

### Outputs

- Per-gate pass/fail results

### Stage Exit Verification

Before proceeding to Stage 3, **MUST** verify:

- [ ] Quality gate results are captured (pass/fail per gate)
- [ ] At least one enabled gate passes

**Rigor behavior:**

- **strict**: STOP on failure, no override
- **standard**: STOP on failure, `--force` available
- **lite**: Warn and continue

If verification fails at current rigor level (read via `mode:read-dev-rigor`): apply rigor behavior above.

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${RED}[!]${RESET} Stage exit verification failed: all quality gates failed"
```

If all enabled gates fail: STOP. Do NOT proceed to code review.

### Exit Criteria

- At least one gate passes (or execution halted)

### Display Results

```bash
source $ECK_HOME/colors.sh

echo ""
printf '%b\n' "${ORANGE}${BOLD}Quality Gates${RESET}"
echo ""
printf '%b\n' "${GREEN}[x]${RESET} review:test        PASS"
printf '%b\n' "${GREEN}[x]${RESET} review:lint        PASS"
printf '%b\n' "${RED}[!]${RESET} review:typecheck   FAIL  {N} errors"
```

---

## Stage 3: Code Review

**Skipped in lite mode.**

```bash
bash $ECK_HOME/update-stage.sh "Code (3/11)"
```

### Inputs

- Changed files from development
- Code review configuration

### Activities

1. **MUST** dispatch `/<PROJECT_KEY_LOWERCASE>:validate-code` via the **Agent tool** to keep orchestrator context lean.

   The Agent prompt should instruct the subagent to:
   - Run the validate-code sub-skill
   - Return a **compact summary only**: finding counts by severity (CRITICAL, WARNING, INFO) and one-line descriptions for any CRITICAL findings
   - Do NOT return full file-level review output

   Example Agent dispatch:

   ```
   Agent tool — prompt:
   "Run /{PK}:validate-code. Return ONLY a compact summary:
   - CRITICAL: N (one-line each if any)
   - WARNING: N
   - INFO: N
   Do not include full review output."
   ```

2. Parse the agent's returned summary to collect findings by severity: CRITICAL, WARNING, INFO.

### Outputs

- Finding counts by severity

### Exit Criteria

- Code review completed (or skipped in lite mode)

### Display Findings

```bash
source $ECK_HOME/colors.sh

echo ""
printf '%b\n' "${ORANGE}${BOLD}Code Review${RESET}"
echo ""
printf '%b\n' "${RED}[!]${RESET} CRITICAL   {N}"
printf '%b\n' "${YELLOW}[>]${RESET} WARNING    {N}"
printf '%b\n' "${CYAN}[*]${RESET} INFO       {N}"
# Or if no findings:
printf '%b\n' "${GREEN}[x]${RESET} Code review: no findings"
```

---

## Stage 4: Security

**Runs in standard mode (conditional) or strict mode (always), or when `--security` flag is specified.**

At standard, runs only if changes touch auth/API/data/secrets (mirroring develop-phase security behavior). At strict, always runs.

```bash
bash $ECK_HOME/update-stage.sh "Security (4/11)"
```

### Inputs

- Codebase and changed files
- Security scan configuration

### Activities

1. **MUST** dispatch `/<PROJECT_KEY_LOWERCASE>:validate-security` via the **Agent tool** to keep orchestrator context lean. This is a PR-level security review using three complementary layers:
   - Built-in `/security-review` — AI-powered analysis of PR diff for high-confidence vulnerabilities
   - `validation:secret-check` — scans for hardcoded secrets (complements built-in which excludes secrets-on-disk)
   - Dependency audit (`npm audit` / `pip-audit`) — CVE scanning (complements built-in which excludes library vulns)

   The Agent prompt should instruct the subagent to:
   - Run the validate-security sub-skill
   - Return a **compact summary only**: finding counts by severity, one-line per CRITICAL finding, and whether a deploy block is needed
   - Do NOT return full scan output or dependency trees

   Example Agent dispatch:

   ```
   Agent tool — prompt:
   "Run /{PK}:validate-security. Return ONLY a compact summary:
   - CRITICAL: N (one-line each if any)
   - WARNING: N
   - Deploy block: YES/NO
   Do not include full scan output or dependency listings."
   ```

2. Parse the agent's returned summary. If any CRITICAL finding, record a **deploy block**.

### Outputs

- Security findings by severity
- Deploy block flag (if CRITICAL found)

### Exit Criteria

- Security scan completed
- Deploy block recorded if applicable

### Display Security Findings

```bash
source $ECK_HOME/colors.sh

echo ""
printf '%b\n' "${ORANGE}${BOLD}Security Scan${RESET}"
echo ""
printf '%b\n' "${RED}[!]${RESET} CRITICAL  {file}  {description}"
printf '%b\n' "    ${DIM}{remediation}${RESET}"
printf '%b\n' "${YELLOW}[>]${RESET} WARNING   {file}  {description}"
printf '%b\n' "    ${DIM}{remediation}${RESET}"
```

---

## Stage 5: Pipeline

**Skipped in lite mode. Runs only if CI configuration is detected.**

```bash
bash $ECK_HOME/update-stage.sh "Pipeline (5/11)"
```

### Inputs

- CI configuration files (.github/workflows/, .gitlab-ci.yml, etc.)

### Activities

1. Check for CI configuration files.
2. If no CI config found:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${DIM}[-]${RESET} No CI configuration detected — skipping pipeline check."
```

3. If CI configured, **MUST** dispatch `/<PROJECT_KEY_LOWERCASE>:validate-ci` via the **Agent tool** to keep orchestrator context lean.

   The Agent prompt should instruct the subagent to:
   - Check latest pipeline status and diagnose any failures
   - Return a **compact summary only**: CI status (pass/fail/pending), root cause classification if failed, and one-line fix proposal
   - Do NOT return full CI logs or workflow output

   Example Agent dispatch:

   ```
   Agent tool — prompt:
   "Run /{PK}:validate-ci. Return ONLY a compact summary:
   - CI status: PASS/FAIL/PENDING
   - Root cause: (one-line if failed)
   - Fix proposal: (one-line if failed)
   Do not include full CI logs."
   ```

### Outputs

- CI status (pass/fail/skipped)

### Exit Criteria

- Pipeline check completed (or skipped)

### Display Pipeline Result

```bash
source $ECK_HOME/colors.sh

echo ""
printf '%b\n' "${ORANGE}${BOLD}Pipeline Check${RESET}"
echo ""
printf '%b\n' "${RED}[!]${RESET} CI failure detected: {root cause classification}"
printf '%b\n' "${YELLOW}[>]${RESET} Fix proposal: {proposed fix}"
# Or on pass:
printf '%b\n' "${GREEN}[x]${RESET} CI: all pipelines passing"
```

---

## Stage 6: Documents

**Runs in standard and strict modes. Skipped in lite mode.**

```bash
bash $ECK_HOME/update-stage.sh "Documents (6/11)"
```

### Inputs

- Feature doc artifacts from `docs/{feature}/`
- Changed file list from git history
- Terminology glossary from `.claude/context/standards/terminology-glossary.md`

### Activities

1. **MUST** dispatch `/<PROJECT_KEY_LOWERCASE>:validate-docs` via the **Agent tool** to keep orchestrator context lean. The sub-skill dispatches `technical-writer` agent for content review and uses `traceability:coverage-report` primitive for AC-ID coverage.

   The Agent prompt should instruct the subagent to:
   - Run the validate-docs sub-skill
   - Return a **compact summary only**: per-check verdict (PASS/FAIL), composite score, and one-line per finding
   - Do NOT return full document content or traceability matrices

   Example Agent dispatch:

   ```
   Agent tool — prompt:
   "Run /{PK}:validate-docs. Return ONLY a compact summary:
   - AC-ID traceability: PASS/FAIL
   - Doc freshness: PASS/FAIL
   - Terminology: PASS/FAIL
   - Artifact consistency: PASS/FAIL
   - Score: N%
   List only findings, one line each. Do not include full document content."
   ```

2. Checks performed:
   - **AC-ID traceability**: coverage matrix from FRD.md through commits
   - **Doc freshness**: changed code files have corresponding doc updates
   - **Terminology compliance**: no deprecated terms from glossary in feature docs
   - **Artifact consistency**: cross-references between FRD.md, TASKS.md, and review artifacts

### Outputs

- Documentation quality score and per-check verdicts
- Finding list with file:line locations

### Exit Criteria

- Documentation validation completed (or skipped in lite mode)

### Display Results

```bash
source $ECK_HOME/colors.sh

echo ""
printf '%b\n' "${ORANGE}${BOLD}Documentation Quality${RESET}"
echo ""
printf '%b\n' "${GREEN}[x]${RESET} AC-ID traceability    PASS"
printf '%b\n' "${GREEN}[x]${RESET} Doc freshness         PASS"
printf '%b\n' "${GREEN}[x]${RESET} Terminology            PASS"
printf '%b\n' "${GREEN}[x]${RESET} Artifact consistency   PASS"
echo ""
printf '%b\n' "Score: {composite}%"
```

---

## Stage 7: Acceptance

**Runs in strict mode, or when `--uat` flag is specified.**

```bash
bash $ECK_HOME/update-stage.sh "Acceptance (7/11)"
```

### Inputs

- `docs/{feature}/FRD.md` — AC-IDs (primary UAT source)
- `docs/{feature}/TASKS.md` — goals (fallback)

### Activities

1. **MUST** invoke `/<PROJECT_KEY_LOWERCASE>:validate-uat` with FRD.md AC-IDs as the UAT checklist.
2. If FRD.md was loaded, the checklist uses AC-IDs directly:

```
UAT Checklist — please confirm each criterion:

AC-1: {criterion description} — does this work as expected?
AC-2: {criterion description} — does this work as expected?
...

For each item, respond: pass / fail / partial
```

3. If no FRD.md, fall back to TASKS.md goals.
4. **MUST** present checklist via AskUserQuestion. Do NOT auto-complete UAT results — every item requires explicit user confirmation.
5. Record results:

| Outcome | Condition                        |
| ------- | -------------------------------- |
| PASS    | All items confirmed as pass      |
| PARTIAL | One or more items marked partial |
| FAIL    | One or more items marked fail    |

### Outputs

- UAT results with per-criterion status
- AC-ID coverage: "X of N criteria passed"

### Exit Criteria

- User confirmed each UAT item
- UAT verdict recorded

### Display UAT Results

```bash
source $ECK_HOME/colors.sh

echo ""
printf '%b\n' "${ORANGE}${BOLD}UAT Results${RESET}"
echo ""
printf '%b\n' "${GREEN}[x]${RESET} AC-1: {criterion}: pass"
printf '%b\n' "${YELLOW}[>]${RESET} AC-2: {criterion}: partial"
printf '%b\n' "${RED}[!]${RESET} AC-3: {criterion}: fail"
echo ""
printf '%b\n' "${BOLD}Verdict: {X} of {N} criteria passed${RESET}"
```

---

## Stage 8: Review (8/11)

> **Mandatory — cannot be skipped or deselected.**

```bash
bash $ECK_HOME/update-stage.sh "Review (8/11)"
```

### Inputs

- All stage artifacts produced by prior stages
- Feature slug
- Rigor level

### Activities

1. **MUST** dispatch to `<PK>:validate-review` sub-skill. Do NOT skip the review gate.
2. Review skill validates mandatory artifacts, runs quality checks, computes verdict.
3. Review skill **MUST** record verdict via `update-lifecycle.js gate-verdict`.
4. On PASS or CONDITIONAL:
   - Display: "✓ Validate gate PASSED. Proceeding to approval and merge."
   - Proceed to Stage 9.
5. On FAIL:
   - Step status set to "gated" (yellow in statusline)
   - Display: "✗ Validate gate FAILED. Fix issues and re-run /eck:validate."
   - STOP (do not display next-stage guidance)

### Outputs

- `docs/{feature}/VALIDATE-REVIEW.md` verdict artifact
- lifecycle.json updated with gate verdict

### Exit Criteria

- Review gate verdict recorded
- On PASS/CONDITIONAL: proceed to Stage 9
- On FAIL: step marked "gated" and skill stops

### Validation Report (pre-review)

Before dispatching the review sub-skill, display the aggregated report:

```bash
source $ECK_HOME/colors.sh

echo ""
printf '%b\n' "${ORANGE}${BOLD}Validation Complete${RESET}"
echo ""

printf '%b\n' "${ORANGE}${BOLD}Validate Report${RESET}"
echo ""
printf '%b\n' "Gates: {N} / {total} passed"
printf '%b\n' "Code Review: {N} critical, {N} warning"
printf '%b\n' "Security: {PASS | BLOCKED | SKIPPED}"
printf '%b\n' "UAT: {X of N passed | SKIPPED}"
echo ""
printf '%b\n' "${BOLD}Verdict: {PASS | PASS WITH WARNINGS | FAIL}${RESET}"
echo ""
```

### Verdict Rules

| Verdict                | Condition                                                       |
| ---------------------- | --------------------------------------------------------------- |
| **PASS**               | All gates pass, no CRITICAL findings, UAT pass (if run)         |
| **PASS WITH WARNINGS** | No CRITICAL findings, but WARNING-level findings or partial UAT |
| **FAIL**               | Any gate fails, any CRITICAL security finding, or UAT fail      |

### Reset Statusline

```bash
bash $ECK_HOME/update-stage.sh
```

---

## Stage 9: Approval

**Only runs when Stage 8 Review verdict is PASS or CONDITIONAL.**

```bash
bash $ECK_HOME/update-stage.sh "Approve (9/11)"
```

### Inputs

- Open PR from develop phase
- CI status and reviewer approvals

### Activities

1. **MUST** invoke `/<PROJECT_KEY_LOWERCASE>:validate-approval` and wait for completion.

`/<PROJECT_KEY_LOWERCASE>:validate-approval` polls for CI status and reviewer approvals.

2. Check CI Status:

| CI Result | Action                                              |
| --------- | --------------------------------------------------- |
| Passing   | Continue to Stage 10                                |
| Failing   | Invoke `/validate-ci` for diagnosis, then STOP      |
| Pending   | Display waiting status, suggest checking back later |

On CI failure:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${RED}[!]${RESET} CI failed — invoking validate-ci for diagnosis"
printf '%b\n' "    ${DIM}Address failures and re-run /eck:validate.${RESET}"
```

Then reset the statusline and STOP.

On CI pending:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${YELLOW}[>]${RESET} CI in progress — check back when complete"
printf '%b\n' "    ${DIM}Re-run /eck:validate once CI passes.${RESET}"
```

Then reset the statusline and STOP.

3. Display approval status:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${GREEN}[x]${RESET} CI: passing"
printf '%b\n' "${GREEN}[x]${RESET} Reviewer: approved"
```

### Outputs

- CI and reviewer approval status confirmed

### Exit Criteria

- CI passing and reviewer approved, or skill stops with guidance to re-run when ready

4. **STOP — Do NOT proceed to Stage 10 automatically.**

Display merge readiness and instruct the user:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' ""
printf '%b\n' "${GREEN}[x]${RESET} Validation complete — PR is approved and CI passing."
printf '%b\n' "    ${DIM}Run /{PROJECT_KEY_LOWERCASE}:validate-merge to merge the PR.${RESET}"
```

Then reset the statusline and **STOP the skill**. The user must explicitly invoke `/<PROJECT_KEY_LOWERCASE>:validate-merge` to proceed.

---

## Stage 10: Merge

> **This stage is NOT reached by the orchestrator.** It exists only as documentation for the `validate-merge` sub-skill. The orchestrator STOPS after Stage 9.

**Only runs when invoked directly via `/<PROJECT_KEY_LOWERCASE>:validate-merge`.**

```bash
bash $ECK_HOME/update-stage.sh "Merge (10/11)"
```

### Inputs

- Approved PR from Stage 9
- Merge strategy from project configuration (`project-constants.md`)

### Activities

1. **MUST** invoke `/<PROJECT_KEY_LOWERCASE>:validate-merge` and wait for completion.

`/<PROJECT_KEY_LOWERCASE>:validate-merge` uses the merge strategy configured for the project's development mode (merge commit, squash, or ff-only).

2. Display merge confirmation:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${GREEN}[x]${RESET} Merged: {BRANCH_NAME} -> {DEV_BRANCH}"
printf '%b\n' "    ${DIM}Strategy: {MERGE_STRATEGY}${RESET}"
```

On failure:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${RED}[!]${RESET} validate-merge failed — merge halted"
printf '%b\n' "    ${DIM}Address the error and re-run /eck:validate.${RESET}"
```

Then reset the statusline and STOP.

### Outputs

- PR merged to integration branch (`<DEV_BRANCH>`)

### Exit Criteria

- Merge successful, or error displayed and skill stops

---

## Stage 11: Tracker

```bash
bash $ECK_HOME/update-stage.sh "Tracker (11/11)"
```

### Inputs

- Child issue keys from TASKS.md or FRD.md
- Merge result from Stage 10

### Activities

1. Invoke `/<PROJECT_KEY_LOWERCASE>:deploy-tracker --status done` to update tracker issue statuses.
   - On success: display `[x] Tracker issues updated to Done`
   - On failure: display `[!] deploy-tracker failed — update tracker manually`. Non-blocking.

### Outputs

- Tracker issues updated with "Done" status

### Exit Criteria

- `/<PROJECT_KEY_LOWERCASE>:deploy-tracker` completed (success or failure logged)

### Completion Display

After Stage 11 completes successfully:

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${GREEN}✓${RESET} Validate complete. Code merged to dev. Next: /eck:deploy"
```

---

## Registry Update

**Reference:** `ops:registry-update` primitive for the canonical read-modify-write procedure.

If registry does not exist, log warning and skip this step.

Append a `sync_history` entry to `$ECK_HOME/registry.yaml`:

```yaml
- date: "{DATE}"
  action: "validate"
  performed_by: "/eck:validate"
  summary: "Validation {PASS|FAIL}: {tests|lint|types|security} — {N} passed, {N} failed"
```

Set `last_modified_at` to current ISO-8601 date.
Recompute `project_summary` per the `ops:registry-update` primitive.
Use atomic write: write to `registry.yaml.tmp`, then rename to `registry.yaml`.

---

## Lifecycle Integration

### Entry Protocol (Stage 1)

At the start of Stage 1, after calibration, run:

```bash
echo "$(date +%s)" > /tmp/eck-skill-start-$$

FEATURE_ID=$(node $ECK_HOME/update-lifecycle.js read 2>/dev/null | node -e "const d=JSON.parse(require('fs').readFileSync(0,'utf-8'));console.log(d.active_feature||'')" 2>/dev/null)
[ -z "$FEATURE_ID" ] && FEATURE_ID=$(node $ECK_HOME/manage-features.js resolve "$ARGUMENTS" 2>/dev/null | jq -r '.id // empty')
FEATURE_SLUG=$(node $ECK_HOME/manage-features.js read "$FEATURE_ID" 2>/dev/null | jq -r '.slug // empty')
node $ECK_HOME/update-lifecycle.js register "$FEATURE_ID" --branch "$(git branch --show-current 2>/dev/null)"
node $ECK_HOME/update-lifecycle.js start "$FEATURE_ID" "validate"
node $ECK_HOME/update-lifecycle.js activate "$FEATURE_ID"
```

### Exit Protocol (after Stage 11)

```bash
START_TS=$(cat /tmp/eck-skill-start-$$ 2>/dev/null || echo "0")
END_TS=$(date +%s)
DURATION=$((END_TS - START_TS))

# Use "done" for PASS/PASS WITH WARNINGS, "fail" for FAIL
node $ECK_HOME/update-lifecycle.js done "$FEATURE_ID" "validate"

node $ECK_HOME/log-activity.js \
  --skill "eck:validate" --feature "$FEATURE_ID" --outcome "success" \
  --duration "$DURATION" --summary "{SUMMARY_TEXT}" --step "validate"

```

On FAIL verdict (Stage 8), replace `done` with `fail` and outcome with `"failed"`. The exit protocol runs immediately after Stage 8 on FAIL, or after Stage 11 on PASS/CONDITIONAL.

---

## Error Handling

Each sub-skill failure is isolated. If a sub-skill errors, report it and continue to the next gate.

```bash
printf '%b\n' "${RED}[!]${RESET} {sub-skill} failed: {error message}"
printf '%b\n' "    ${DIM}Gate recorded as FAIL. Continuing to next stage.${RESET}"
```

| Scenario                                   | Behavior                                                                |
| ------------------------------------------ | ----------------------------------------------------------------------- |
| validate-quality errors                    | Record gate as FAIL; continue                                           |
| validate-code errors                       | Record gate as FAIL; continue                                           |
| validate-security CRITICAL finding         | Record deploy block; do not halt                                        |
| validate-ci errors                         | Record gate as FAIL; continue                                           |
| UAT user confirms failure                  | Record UAT as FAIL; include in verdict                                  |
| UAT auto-completion attempted              | Reject — present checklist to user again                                |
| Unexpected failure or user-initiated pause | Write state to `VALIDATE-STATE.md` using the `ops:state-save` primitive |

On unexpected failure or user-initiated pause (`/eck:pause`), write stage state to `docs/{feature}/VALIDATE-STATE.md`. The `/eck:pause` command will write this state file automatically when invoked during a validate session.

At completion (success or error), always reset the statusline:

```bash
bash $ECK_HOME/update-stage.sh
```

---

## Related Documents

- `/eck:develop` — develop orchestrator (lifecycle predecessor)
- `/eck:deploy` — deploy orchestrator (lifecycle successor)
- `validate-security` — security review dispatched by this orchestrator
- `validate-code` — language-aware code review
- `validate-quality` — lint, type checks, test suite
- `validate-ci` — CI failure diagnosis and fix proposals
- `validate-docs` — feature documentation quality (traceability, freshness, terminology)
- `validate-uat` — user acceptance testing against FRD.md
- `validate-approval` — PR approval gate (CI + reviewer check)
- `validate-merge` — merge approved PR to integration branch
- `deploy-tracker` — update tracker issue status
- `/audit-doc-drift` — documentation drift detection (run separately for project-level doc quality)
- `scaffold/project/context/standards/terminology-glossary.md` — canonical term reference
