chore: initial monorepo scaffold + WDS Phase 1+2 artifacts

- Nx 22.7 monorepo (pnpm 11.1, TypeScript 5.9, Node 24) - apps/api: NestJS 11 (CJS conforme CODING-RULES.md PGD-DB-004) - apps/web: React 19 + Vite 8 (ESM) - libs/shared/api-interface: Zod contract base - Docker Compose dev: Postgres 18, Valkey 8, MinIO, Mailpit - WDS artifacts: - design-artifacts/A-Product-Brief/ (5 docs canônicos + 16 dialogs) - design-artifacts/B-Trigger-Map/ (hub + 4 personas + feature impact) - Stack canon: STACK.md v2.2 + CODING-RULES.md v2.0 + brand.md - AGENTS.md + README.md como entrada para devs/agentes Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-27 14:34:20 +00:00
commit 17c08e6392
3631 changed files with 855518 additions and 0 deletions
--- a/.agents/skills/bmad-story-automator/steps-v/step-v-01-check.md
+++ b/.agents/skills/bmad-story-automator/steps-v/step-v-01-check.md
@@ -0,0 +1,178 @@
+---
+name: 'step-v-01-check'
+description: 'Validate orchestration state document integrity and session health'
+nextStep: './step-v-02-report.md'
+outputFolder: '{output_folder}/story-automator'
+rules: '../data/orchestrator-rules.md'
+stateFilePattern: '{outputFolder}/orchestration-*.md'
+outputFile: '{outputFolder}/orchestration-{epic_id}-{timestamp}.md'
+validateState: '../scripts/story-automator'
+listSessions: '../scripts/story-automator'
+deriveProjectSlug: '../scripts/story-automator'
+tmuxCommands: '../data/tmux-commands.md'
+---
+
+# Validation Step 1: Check State Integrity
+
+**Goal:** Validate an orchestration state document for structural integrity and session health.
+
+## MANDATORY EXECUTION RULES
+
+- 🛑 **DO NOT BE LAZY** - CHECK EVERY FIELD AND SESSION
+- 📖 Validate ALL required fields, not just a sample
+- 🚫 DO NOT skip any validation checks
+- ✅ Report ALL issues found, not just the first one
+
+---
+
+## Do
+
+### 1. Load Rules
+Load `{rules}` once for context on expected state structure.
+
+### 2. Request State Document
+```
+**Which orchestration would you like to validate?**
+
+Found state documents in `{outputFolder}`:
+[List all orchestration-*.md files with: name, status, last updated]
+
+Pattern: `{stateFilePattern}`
+
+Enter filename or number to select:
+```
+
+**Wait.**
+
+### 3. Load and Parse State
+Load the selected state document (resolved as `{state_path}` for this run). Extract frontmatter:
+- `epic`, `epicName`, `storyRange`
+- `status`, `currentStory`, `currentStep`
+- `stepsCompleted`, `lastUpdated`
+- `projectContext`, `aiCommand`, `agentConfig`, `overrides`
+- `activeSessions`, `completedSessions`
+
+### 3a. Helper CLI Contract Check (Required)
+
+Before running validation commands, verify helper interfaces in parallel:
+```bash
+tmp_help_validate=$(mktemp)
+tmp_help_sessions=$(mktemp)
+tmp_help_slug=$(mktemp)
+
+("{validateState}" validate-state --help >"$tmp_help_validate" 2>&1) &
+pid_validate=$!
+("{listSessions}" list-sessions --help >"$tmp_help_sessions" 2>&1) &
+pid_sessions=$!
+("{deriveProjectSlug}" derive-project-slug --help >"$tmp_help_slug" 2>&1) &
+pid_slug=$!
+
+wait "$pid_validate"; status_validate=$?
+wait "$pid_sessions"; status_sessions=$?
+wait "$pid_slug"; status_slug=$?
+
+if [ "$status_validate" -ne 0 ] || [ "$status_sessions" -ne 0 ] || [ "$status_slug" -ne 0 ]; then
+  rm -f "$tmp_help_validate" "$tmp_help_sessions" "$tmp_help_slug"
+  echo "validation helper CLI contract changed"
+  exit 1
+fi
+
+rm -f "$tmp_help_validate" "$tmp_help_sessions" "$tmp_help_slug"
+```
+
+If any check fails: **STOP and report "validation helper CLI contract changed"**.
+
+### 4. Run Structure + Session Baseline in Parallel
+
+Run structure validation and session inventory concurrently, then aggregate results.
+
+```bash
+tmp_validation=$(mktemp)
+tmp_sessions=$(mktemp)
+
+("{validateState}" validate-state --state "{state_path}" > "$tmp_validation") &
+validation_pid=$!
+
+project_slug_json=$("{deriveProjectSlug}" derive-project-slug --project-root "{project-root}") || {
+  rm -f "$tmp_validation" "$tmp_sessions"
+  echo "derive-project-slug failed"
+  exit 1
+}
+project_slug=$(printf '%s' "$project_slug_json" | jq -r '.slug')
+("{listSessions}" list-sessions --slug "$project_slug" > "$tmp_sessions") &
+sessions_pid=$!
+
+wait "$validation_pid"; validation_status=$?
+wait "$sessions_pid"; sessions_status=$?
+
+if [ "$validation_status" -ne 0 ] || [ "$sessions_status" -ne 0 ]; then
+  rm -f "$tmp_validation" "$tmp_sessions"
+  echo "state validation or session inventory failed"
+  exit 1
+fi
+
+validation=$(cat "$tmp_validation")
+sessions=$(cat "$tmp_sessions")
+rm -f "$tmp_validation" "$tmp_sessions"
+```
+
+### 5. Validate Structure + Session Consistency (Single Diff Pass)
+
+**Required Fields Check:**
+
+| Field | Present | Valid |
+|-------|---------|-------|
+| epic | ✅/❌ | non-empty string |
+| epicName | ✅/❌ | non-empty string |
+| storyRange | ✅/❌ | array |
+| status | ✅/❌ | valid enum |
+| lastUpdated | ✅/❌ | ISO date |
+| aiCommand or agentConfig | ✅/❌ | at least one runtime command source is present |
+
+**Valid status values:** INITIALIZING, READY, IN_PROGRESS, PAUSED, COMPLETE, ABORTED
+
+**Record issues:**
+- Missing required fields
+- Invalid field values
+- Malformed YAML
+
+Single-pass structure issue extraction (compact output):
+```bash
+field_issues=$(echo "$validation" | jq -r '.issues[]? | select(.type=="missing_field" or .type=="invalid_value" or .type=="yaml_error") | "\(.type): \(.field // .message)"')
+```
+
+Using `{tmuxCommands}` semantics and `sessions` output, compare state vs live sessions in one pass:
+```bash
+state_sessions=$(echo "$validation" | jq -r '.activeSessions[]?.sessionId // empty' | sort -u)
+live_sessions=$(echo "$sessions" | jq -r '.sessions[]?.name // empty' | sort -u)
+
+orphaned_refs=$(comm -23 <(echo "$state_sessions") <(echo "$live_sessions"))
+untracked_live=$(comm -13 <(echo "$state_sessions") <(echo "$live_sessions"))
+```
+
+**Session consistency checks:**
+
+| Check | Result |
+|-------|--------|
+| Active sessions in state but not in T-Mux | Orphaned references |
+| T-Mux sessions not in state | Untracked sessions |
+| Status=IN_PROGRESS but no active sessions | Stale state |
+
+### 6. Carry Forward Validation Context
+
+Carry forward to `{nextStep}`:
+- `state_path`
+- `validation`
+- `sessions`
+- `orphaned_refs`
+- `untracked_live`
+- Any structure/session issues identified
+
+### 7. Auto-Proceed
+
+Display: "**Structure and session baseline complete. Proceeding to progress validation and final report...**"
+
+---
+
+## Then
+→ Load and execute `{nextStep}`
--- a/.agents/skills/bmad-story-automator/steps-v/step-v-02-report.md
+++ b/.agents/skills/bmad-story-automator/steps-v/step-v-02-report.md
@@ -0,0 +1,115 @@
+---
+name: 'step-v-02-report'
+description: 'Validate story progress consistency and present final validation report'
+outputFile: '{output_folder}/story-automator/orchestration-{epic_id}-{timestamp}.md'
+---
+
+# Validation Step 2: Progress Consistency + Final Report
+
+**Goal:** Validate story-progress consistency using the selected state document and present a consolidated validation report.
+
+## MANDATORY EXECUTION RULES
+
+- 🛑 **DO NOT BE LAZY** - CHECK EVERY STORY IN RANGE
+- 📖 Validate ALL progress checks, not just samples
+- 🚫 DO NOT skip stalled/skipped-step checks
+- ✅ Include structure/session findings from step-v-01 in final report
+
+---
+
+## Do
+
+### 1. Load Validation Context from Step 1
+
+Use carried-forward context:
+- `state_path`
+- `validation`
+- `sessions`
+- `orphaned_refs`
+- `untracked_live`
+- Prior structure/session issues
+
+Load the selected state document again (resolved as `{state_path}` for this run) to verify progress details.
+
+### 2. Validate Story Progress Thoroughly
+
+Run a single prefilter pass first and keep parent context compact:
+```bash
+# Focused extraction before deep checks
+progress_focus=$(rg -n "done|in_progress|blocked|review|create|dev|automate|commit|ERROR|WARN|FAIL" "$state_path" | head -n 200)
+if [ -z "$progress_focus" ]; then
+  progress_focus=$(tail -n 200 "$state_path")
+fi
+```
+
+Return only compact progress fields to the final report synthesis:
+- `story_count`
+- `progress_rows`
+- `inconsistency_count`
+- `stalled_count`
+- `critical_issues[]`
+
+For each story in `storyRange`:
+- Check progress table has an entry for the story
+- Verify task sequence is coherent (`create -> dev -> automate -> review -> commit`)
+- Flag impossible regressions (for example, `review=done` while `dev` missing)
+- Detect potentially stuck stories (same `currentStep` for too long without action-log movement)
+
+Deterministic checks (example pattern):
+```bash
+# Example only: derive summary values from state/action log without loading full logs
+story_count=$(echo "$validation" | jq -r '.storyRangeCount // 0')
+progress_rows=$(rg -n "^[[:space:]]*\\|[[:space:]]*[0-9]+\\.[0-9]+" "$state_path" | wc -l | tr -d ' ')
+```
+
+If `story_count >= 4`, run per-story consistency checks in parallel and return compact rows only:
+```bash
+story_ids=$(echo "$validation" | jq -r '.storyRange[]?')
+tmp_progress=$(mktemp)
+printf "%s\n" "$story_ids" | xargs -I{} -P 4 sh -c \
+  'id="$1"; file="$2"; rg -n -F "| ${id} |" "$file" | head -n 1 | sed "s/^/${id}|/"' _ "{}" "$state_path" \
+  > "$tmp_progress"
+progress_rows=$(wc -l < "$tmp_progress" | tr -d ' ')
+rm -f "$tmp_progress"
+```
+
+### 3. Consolidate Findings
+
+Create final status buckets:
+- **Structure:** from `validation`
+- **Sessions:** from `sessions`, `orphaned_refs`, `untracked_live`
+- **Progress:** from step-2 checks above
+
+Mark severity:
+- **CRITICAL:** malformed state / irrecoverable sequence corruption
+- **WARNING:** stale or inconsistent but recoverable
+- **INFO:** healthy or minor notes
+
+### 4. Present Final Validation Report
+
+```
+**Validation Report: {epicName}**
+
+**Structure:** ✅ Valid / ⚠️ Issues found
+**Sessions:** ✅ Healthy / ⚠️ Anomalies detected
+**Progress:** ✅ Consistent / ⚠️ Inconsistencies found
+
+[If issues:]
+**Issues Found:**
+1. {issue description}
+2. {issue description}
+
+**Recommendations:**
+- {recommendation}
+```
+
+### 5. Complete
+
+Display: "**Validation complete.** Review the issues above and use the edit workflow to apply fixes if needed."
+
+**End validation.**
+
+---
+
+## Then
+→ End workflow (validation completed in 2 steps)