@polymorphism-tech/morph-spec 4.5.0 → 4.7.0

package/docs/plans/2026-02-23-infra-architect-refactor.md

@@ -0,0 +1,437 @@
+# infra-architect Refactor Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Introduce a cloud-agnostic `infra-architect` tier-2 squad leader, demote `azure-architect` to tier-3 specialist, and update all references so non-Azure projects aren't burdened with an always-active Azure agent.
+
+**Architecture:** Add a new `infra-architect` agent (tier 2, always_active: true) that owns infrastructure coordination regardless of cloud provider. `azure-architect` becomes a tier-3 specialist under it (always_active: false), activated only when Azure infra work is needed. `bicep-architect` stays tier-3 (already always_active: false... wait, it IS true — fix that too).
+
+**Tech Stack:** Node.js/ESM, `framework/agents.json`, `.claude/agents/`, `src/lib/standards/standards-context-injector.js`, `test/utils/agents-installer.test.js`
+
+---
+
+## Scope Summary
+
+| File | Action |
+|------|--------|
+| `framework/agents.json` | Add `infra-architect` (tier-2), demote `azure-architect` (tier-3), fix `bicep-architect` always_active, update refs, update counts |
+| `framework/agents/infrastructure/infra-architect.md` | CREATE cloud-agnostic squad leader spec |
+| `framework/agents/infrastructure/azure-architect.md` | Remove "always active Core Agent" trigger text |
+| `framework/agents/README.md` | Update squad leader reference |
+| `.claude/agents/morph-azure-architect.md` | DELETE (no longer tier-2, installAgents won't generate it) |
+| `.claude/agents/morph-infra-architect.md` | CREATE new squad leader agent file |
+| `src/lib/standards/standards-context-injector.js` | Add `infra-architect` entry, keep `azure-architect` entry |
+| `test/utils/agents-installer.test.js` | Replace `morph-azure-architect.md` check → `morph-infra-architect.md` |
+
+---
+
+### Task 1: Update `framework/agents.json` — add infra-architect, demote azure-architect
+
+**Files:**
+- Modify: `framework/agents.json`
+
+**Step 1: Add the `infra-architect` agent entry in the tier-2 section (after `dotnet-senior`, before `azure-architect` current slot)**
+
+Insert before the `"azure-architect"` key:
+
+```json
+"infra-architect": {
+  "tier": 2,
+  "role": "domain-leader",
+  "title": "Infrastructure Squad Leader",
+  "domains": ["infrastructure"],
+  "keywords": ["infrastructure", "infra", "cloud", "deployment", "hosting", "ci/cd", "container", "iac", "pipeline"],
+  "always_active": true,
+  "validators": ["architecture"],
+  "relationships": {
+    "reports_to": "standards-architect",
+    "coordinates": ["azure-architect", "bicep-architect", "devops-engineer", "container-specialist", "observability-expert", "azure-identity"],
+    "escalates_to": "standards-architect",
+    "collaborates_with": ["dotnet-senior", "ui-designer"],
+    "team_role": "domain_leader"
+  },
+  "standards": ["core/coding.md", "core/architecture.md"],
+  "teammate": {
+    "role": "Infrastructure Squad Leader",
+    "icon": "🏗️",
+    "spawn_prompt": "You are the Infrastructure Squad Leader. Coordinate infra specialists regardless of cloud provider (azure-architect, devops-engineer, container-specialist, observability-expert). Focus on IaC, CI/CD, containerization, cost optimization. Delegate to azure-architect for Azure-specific work. Escalate to standards-architect on conflicts."
+  }
+},
+```
+
+**Step 2: Demote `azure-architect` from tier-2 to tier-3**
+
+In the `azure-architect` entry change:
+- `"tier": 2` → `"tier": 3`
+- `"role": "domain-leader"` → `"role": "specialist"`
+- `"always_active": true` → `"always_active": false`
+- `"relationships.reports_to": "standards-architect"` → `"infra-architect"`
+- `"relationships.escalates_to": "standards-architect"` → `"infra-architect"`
+- Remove `"collaborates_with": ["dotnet-senior", "blazor-builder", "nextjs-expert"]` (now a specialist, not a leader)
+- Remove `"team_role": "domain_leader"` → `"team_role": "specialist"`
+- Add `"collaborates_with": ["bicep-architect", "devops-engineer", "container-specialist"]`
+
+**Step 3: Fix `bicep-architect` — set `always_active: false`**
+
+`bicep-architect` is currently `always_active: true`, which is wrong (it's Azure Bicep-specific). Change to `false`.
+
+**Step 4: Update tier counts and cross-references**
+
+- `"total_agents": 37` → `38` (infra-architect is new)
+- `"tier_2_leaders": 3` stays at `3` (azure-architect leaves, infra-architect joins — net zero)
+- `"tier_3_specialists": 26` → `27` (azure-architect joins tier-3)
+- `standards-architect.relationships.coordinates`: replace `"azure-architect"` → `"infra-architect"`
+- `dotnet-senior.relationships.collaborates_with`: replace `"azure-architect"` → `"infra-architect"`
+- `event-architect.relationships.collaborates_with`: replace `"azure-architect"` → `"infra-architect"`
+- `nosql-cache-expert.relationships.collaborates_with`: check and replace `"azure-architect"` → `"infra-architect"` if present
+- `blazor-builder.relationships.collaborates_with`: replace `"azure-architect"` → `"infra-architect"` if present
+- `nextjs-expert.relationships.collaborates_with`: replace `"azure-architect"` → `"infra-architect"` if present
+- `hangfire-orchestrator.relationships.collaborates_with`: replace `"azure-architect"` → `"infra-architect"` if present
+- `devops-engineer`, `container-specialist`, `observability-expert`, `azure-identity`: change `reports_to`/`escalates_to` from `"azure-architect"` → stays as `"azure-architect"` IF they are Azure-specific; OR change to `"infra-architect"` since the squad leader is now `infra-architect`
+  - Decision: `devops-engineer`, `container-specialist`, `observability-expert`, `azure-identity` are still sub-specialties that `azure-architect` may coordinate. But the squad leader is `infra-architect`. Change their `reports_to`/`escalates_to` → `"infra-architect"`.
+  - `bicep-architect` stays `reports_to: "azure-architect"` (Bicep is Azure-specific, azure-architect coordinates it)
+
+**Step 5: Validate JSON is well-formed**
+
+Run: `node -e "JSON.parse(require('fs').readFileSync('framework/agents.json','utf8')); console.log('OK')"`
+Expected: `OK`
+
+**Step 6: Verify counts**
+
+Run: `node -e "const d=JSON.parse(require('fs').readFileSync('framework/agents.json','utf8')); const agents=Object.entries(d.agents).filter(([k])=>!k.startsWith('_comment')); const t2=agents.filter(([,v])=>v.tier===2); const t3=agents.filter(([,v])=>v.tier===3); console.log('total',agents.length,'t2',t2.length,'t3',t3.length,'always_active',agents.filter(([,v])=>v.always_active).map(([k])=>k).join(','));"`
+
+Expected: `total 38 t2 3 t3 27 always_active standards-architect,dotnet-senior,infra-architect,...` (azure-architect and bicep-architect should NOT be in the always_active list)
+
+**Step 7: Commit**
+
+```bash
+git add framework/agents.json
+git commit -m "refactor(agents): introduce infra-architect tier-2 squad leader, demote azure-architect to tier-3 specialist"
+```
+
+---
+
+### Task 2: Create `framework/agents/infrastructure/infra-architect.md`
+
+**Files:**
+- Create: `framework/agents/infrastructure/infra-architect.md`
+
+**Step 1: Write the new agent spec file**
+
+```markdown
+---
+name: infra-architect
+description: Infrastructure Squad Leader for cloud-agnostic infrastructure coordination. Use when planning deployments, provisioning any cloud resources, setting up CI/CD pipelines, containerizing applications, or designing infrastructure architecture regardless of cloud provider.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Infrastructure Squad Leader
+
+Cloud-agnostic infrastructure coordinator. Delegates to cloud-specific specialists.
+
+## Responsabilidades
+
+1. **Coordenar especialistas de infra** (azure-architect, devops-engineer, container-specialist, observability-expert)
+2. **Decidir stack de infra** com base no config do projeto (cloud: azure | aws | gcp | self-hosted)
+3. **Garantir IaC** — tudo via código, nada manual
+4. **CI/CD** — pipelines para todos os ambientes
+
+## Quando ativar sub-especialistas
+
+| Cenário | Especialista |
+|---------|-------------|
+| Deploy em Azure | azure-architect |
+| Templates Bicep | bicep-architect (via azure-architect) |
+| Pipelines CI/CD | devops-engineer |
+| Docker / containers | container-specialist |
+| Logs / métricas | observability-expert |
+| Auth Microsoft/Entra | azure-identity |
+
+## Princípio: Infrastructure as Code
+
+> Nunca criar recursos de infra manualmente. Toda infra via código (Bicep, Terraform, Pulumi, Compose).
+
+## Checklist de Infra
+
+- [ ] Cloud provider definido em config.json
+- [ ] IaC templates criados e validados
+- [ ] Ambientes dev/staging/prod separados
+- [ ] Secrets nunca hardcoded
+- [ ] CI/CD pipeline configurado
+- [ ] Observability básica (logs + métricas)
+- [ ] Estimativa de custos documentada
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*
+```
+
+**Step 2: Commit**
+
+```bash
+git add framework/agents/infrastructure/infra-architect.md
+git commit -m "feat(agents): add infra-architect cloud-agnostic squad leader spec"
+```
+
+---
+
+### Task 3: Update `framework/agents/infrastructure/azure-architect.md`
+
+**Files:**
+- Modify: `framework/agents/infrastructure/azure-architect.md`
+
+**Step 1: Remove "always active" claim from Triggers section**
+
+Find and replace:
+```
+## Triggers
+
+Ativado automaticamente em todo projeto MORPH-SPEC (Core Agent).
+```
+→
+```
+## Triggers
+
+Ativado quando o projeto usa Azure como provedor de cloud. Coordenado pelo `infra-architect`.
+```
+
+**Step 2: Verify the file looks correct**
+
+Read the file and confirm the Triggers section no longer claims it's always-on.
+
+**Step 3: Commit**
+
+```bash
+git add framework/agents/infrastructure/azure-architect.md
+git commit -m "fix(agents): azure-architect is no longer always-active, ativado apenas em projetos Azure"
+```
+
+---
+
+### Task 4: Update `framework/agents/README.md`
+
+**Files:**
+- Modify: `framework/agents/README.md`
+
+**Step 1: Update squad leader reference**
+
+Change:
+```
+- infrastructure/ - Infrastructure Squad (led by azure-architect)
+```
+→
+```
+- infrastructure/ - Infrastructure Squad (led by infra-architect)
+```
+
+**Step 2: Commit**
+
+```bash
+git add framework/agents/README.md
+git commit -m "docs(agents): update infra squad leader reference to infra-architect"
+```
+
+---
+
+### Task 5: Update `.claude/agents/` installed agent files
+
+**Files:**
+- Delete: `.claude/agents/morph-azure-architect.md`
+- Create: `.claude/agents/morph-infra-architect.md`
+
+**Step 1: Delete the old tier-2 azure-architect agent file**
+
+`azure-architect` is no longer tier-2, so `installAgents()` won't generate `morph-azure-architect.md`. Delete the stale file.
+
+```bash
+rm ".claude/agents/morph-azure-architect.md"
+```
+
+**Step 2: Create the new infra-architect agent file**
+
+```markdown
+---
+name: Infrastructure Squad Leader
+description: Infrastructure Squad Leader
+model: inherit
+tools: Read, Grep, Glob, Bash
+maxTurns: 20
+skills:
+  - morph-checklist
+memory: local
+---
+
+You are the Infrastructure Squad Leader. Coordinate infra specialists regardless of cloud provider (azure-architect, devops-engineer, container-specialist, observability-expert). Focus on IaC, CI/CD, containerization, and cost optimization. Delegate to azure-architect for Azure-specific work. Escalate to standards-architect on conflicts.
+
+## Standards to Reference
+- core/coding.md
+- core/architecture.md
+```
+
+**Step 3: Verify the correct files exist**
+
+Run: `ls ".claude/agents/" | grep -E "morph-(infra|azure)" `
+Expected: `morph-domain-azure-architect.md`, `morph-infra-architect.md` — no `morph-azure-architect.md`
+
+**Step 4: Commit**
+
+```bash
+git add ".claude/agents/morph-infra-architect.md"
+git rm ".claude/agents/morph-azure-architect.md"
+git commit -m "fix(agents): replace morph-azure-architect with morph-infra-architect as tier-2 squad leader"
+```
+
+---
+
+### Task 6: Update `src/lib/standards/standards-context-injector.js`
+
+**Files:**
+- Modify: `src/lib/standards/standards-context-injector.js:47`
+
+**Step 1: Add `infra-architect` entry and rename existing entry**
+
+The current entry at line 47:
+```js
+'azure-architect': [
+  'infrastructure/azure/azure', // Stack-specific
+  'core/architecture',
+  'backend/dotnet/core'
+],
+```
+
+**After** the `ui-designer` entry (end of tier-2 section), add:
+```js
+'infra-architect': [
+  'core/architecture',
+  'core/coding'
+],
+```
+
+Keep the existing `'azure-architect'` entry as-is (it's now a tier-3 specialist entry, still valid).
+
+**Step 2: Add a comment clarifying the section**
+
+Above `'azure-architect'`: add `// Tier 3: Specialists - Infrastructure Squad`
+
+**Step 3: Verify no syntax errors**
+
+Run: `node -e "require('./src/lib/standards/standards-context-injector.js'); console.log('OK')"`
+Expected: `OK`
+
+**Step 4: Commit**
+
+```bash
+git add src/lib/standards/standards-context-injector.js
+git commit -m "feat(standards): add infra-architect to standards context injector"
+```
+
+---
+
+### Task 7: Update `test/utils/agents-installer.test.js`
+
+**Files:**
+- Modify: `test/utils/agents-installer.test.js`
+
+**Step 1: Find and update the tier-2 file check**
+
+Current (around line 101-105):
+```js
+// Find a tier-2 file (dotnet-senior, azure-architect, or ui-designer)
+...
+  f === 'morph-azure-architect.md' ||
+```
+
+Change `morph-azure-architect.md` → `morph-infra-architect.md`
+
+**Step 2: Run the test suite to verify**
+
+Run: `node --test test/utils/agents-installer.test.js`
+Expected: All tests pass (no failures)
+
+**Step 3: Run the full test suite**
+
+Run: `npm test`
+Expected: Same pass count as before (or +0 failures)
+
+**Step 4: Commit**
+
+```bash
+git add test/utils/agents-installer.test.js
+git commit -m "test(agents-installer): update tier-2 file check to morph-infra-architect"
+```
+
+---
+
+### Task 8: Update agents-installer.js to regenerate correctly
+
+**Files:**
+- Modify: `src/utils/agents-installer.js` (only if the installer hardcodes azure-architect anywhere)
+
+**Step 1: Check for hardcoded references**
+
+Run: `grep -n "azure-architect\|infra-architect" src/utils/agents-installer.js`
+
+If only data-driven (reads from agents.json) — no changes needed.
+If hardcoded references exist — update them to use `infra-architect`.
+
+**Step 2: Verify installAgents() generates the right files by dry-running**
+
+Run: `node -e "
+const {installAgents} = require('./src/utils/agents-installer.js');
+const path = require('path');
+const os = require('os');
+const tmp = require('fs').mkdtempSync(path.join(os.tmpdir(), 'morph-test-'));
+installAgents(process.cwd(), tmp).then(r => { console.log(r.installed); require('fs').rmdirSync(tmp, {recursive:true}); });
+"`
+Expected: Output includes `morph-infra-architect` but NOT `morph-azure-architect` in the tier-1/2 installed list.
+
+**Step 3: Commit if changes were needed**
+
+```bash
+git add src/utils/agents-installer.js
+git commit -m "fix(agents-installer): update hardcoded azure-architect references if present"
+```
+
+---
+
+### Task 9: Final verification
+
+**Step 1: Run the full test suite**
+
+Run: `npm test`
+Expected: All previously passing tests still pass. No new failures.
+
+**Step 2: Verify always_active agents are correct**
+
+Run: `node -e "
+const d = JSON.parse(require('fs').readFileSync('framework/agents.json', 'utf8'));
+const always = Object.entries(d.agents)
+  .filter(([k, v]) => !k.startsWith('_comment') && v.always_active)
+  .map(([k, v]) => k + ' (tier ' + v.tier + ')');
+console.log('Always active:', always.join(', '));
+"`
+Expected: `infra-architect` is listed, `azure-architect` and `bicep-architect` are NOT listed.
+
+**Step 3: Final commit (version bump if needed)**
+
+The change is a `refactor` — no version bump required unless maintainer decides otherwise.
+
+```bash
+git log --oneline -8
+```
+
+---
+
+## Files Changed Summary
+
+| File | Type |
+|------|------|
+| `framework/agents.json` | Modified |
+| `framework/agents/infrastructure/infra-architect.md` | Created |
+| `framework/agents/infrastructure/azure-architect.md` | Modified |
+| `framework/agents/README.md` | Modified |
+| `.claude/agents/morph-azure-architect.md` | Deleted |
+| `.claude/agents/morph-infra-architect.md` | Created |
+| `src/lib/standards/standards-context-injector.js` | Modified |
+| `test/utils/agents-installer.test.js` | Modified |
+| `src/utils/agents-installer.js` | Modified only if hardcoded refs found |

package/docs/plans/2026-02-23-nextjs-code-review-design.md

@@ -0,0 +1,156 @@
+# Next.js Code Review & Scan — Design Doc
+
+> **Date:** 2026-02-23
+> **Status:** Approved
+> **Approach:** Approach 1 — Trio completo (wire + scan script + skill)
+
+---
+
+## Problem
+
+The MORPH-SPEC framework has a two-layer validation architecture for .NET/Blazor (programmatic validators + `code-review` skill) but Next.js is severely under-covered:
+
+- `nextjs-expert.validators = ["packages"]` — only 1 validator; blazor-builder has 6
+- `next-component-validator.js` was created but **never wired** into agents.json
+- No `code-review-nextjs` skill exists
+- `scripts/scan-csharp.mjs` referenced in `code-review` skill but doesn't exist
+- The `scan-nextjs.mjs` would be the **first scan script** in the framework
+
+## Design
+
+### Three layers (full parity with intended .NET design)
+
+```
+Layer 1 (auto)    agents.json → validation-runner.js → validators/*.js
+Layer 2 (CLI)     scripts/scan-nextjs.mjs → validateNextComponent() + additional checks
+Layer 3 (LLM)     code-review-nextjs skill → scan script first, then manual checklist
+```
+
+---
+
+## Layer 1: Wire `nextjs-component` validator
+
+**Change:** `agents.json` — `nextjs-expert.validators`
+
+```json
+// Before
+"validators": ["packages"]
+
+// After
+"validators": ["packages", "nextjs-component"]
+```
+
+**Also register** the validator key in `validation-runner.js`'s validator registry so `nextjs-component` maps to `next-component-validator.js`.
+
+---
+
+## Layer 2: `scripts/scan-nextjs.mjs`
+
+CLI scan script for CRITICAL/HIGH violation detection before manual review.
+
+**Interface:**
+```bash
+node scripts/scan-nextjs.mjs [path]          # defaults to src/
+node scripts/scan-nextjs.mjs src/features/   # specific dir
+node scripts/scan-nextjs.mjs --json          # JSON output for CI
+```
+
+**What it checks (delegates to `validateNextComponent` + adds):**
+1. `'use client'` without interactivity (warning → HIGH)
+2. React hooks without `'use client'` (error → CRITICAL)
+3. PascalCase `.tsx` file names (warning → HIGH)
+4. `useEffect` used for data fetching (`useEffect(() => { fetch(...)` pattern) → CRITICAL
+5. Default exports on non-special files (should use named exports) → MEDIUM
+6. Deep path imports instead of feature index (`from '@/features/users/components/x'` instead of `from '@/features/users'`) → MEDIUM
+
+**Output format** (mirrors intended `scan-csharp.mjs` style):
+```
+🔍 Scanning src/ (42 files)...
+
+CRITICAL (1)
+  components/UserCard.tsx:1  — React hooks used (useState) without 'use client'
+
+HIGH (2)
+  components/UserList.tsx    — 'use client' with no interactivity detected
+  components/UserCard.tsx    — PascalCase filename (should be user-card.tsx)
+
+✅ No issues found in 39 files
+
+Summary: 42 files scanned | 3 issues (1 critical, 2 high, 0 medium)
+Exit code: 1 (errors found)
+```
+
+**Exit codes:** `0` = clean, `1` = errors, `2` = scan failed
+
+---
+
+## Layer 3: `code-review-nextjs` skill
+
+Skill file: `framework/skills/level-0-meta/code-review-nextjs/SKILL.md`
+Reference: `framework/skills/level-0-meta/code-review-nextjs/references/review-example-nextjs.md`
+
+**Structure mirrors `code-review.md`:**
+
+1. Run scan script first (automated CRITICAL/HIGH)
+2. Naming & Style checklist (8 standards ref)
+3. Component Architecture checklist (tier violations, use client discipline)
+4. Data Fetching checklist (TanStack Query v5, no useEffect fetch)
+5. Forms checklist (zodResolver, schema-first, shadcn Form)
+6. State Management checklist (no unnecessary Zustand/Context for server state)
+7. TypeScript checklist (no `any`, z.infer<> usage)
+8. Structure checklist (feature boundary rules, index imports)
+9. Testing checklist (userEvent over fireEvent, MSW over mock fetch)
+10. Quick Pre-Merge Checklist
+
+**Severity levels:**
+- `[CRITICAL]` — breaks app or violates core Next.js rules
+- `[HIGH]` — significant pattern violation, reviewer must fix before merge
+- `[MEDIUM]` — best practice violation, should fix
+- `[LOW]` — style/consistency, nice to fix
+
+---
+
+## Testing Strategy
+
+**End-to-end tests using real temp directory user cases** (not mocks):
+
+### Test cases for `scan-nextjs.mjs`:
+1. **Clean project** — a `src/` with properly written components → 0 issues, exit 0
+2. **Component with `useState` but no `'use client'`** → CRITICAL finding
+3. **Unnecessary `'use client'`** on static component → HIGH finding
+4. **PascalCase filename** `UserCard.tsx` → HIGH finding
+5. **`useEffect` for fetch** → CRITICAL finding
+6. **Mixed project** — some clean, some violations → correct counts, exit 1
+7. **`--json` flag** → valid JSON output with `{ files, issues, exitCode }`
+8. **Empty directory** → 0 files, exit 0
+9. **Non-existent path** → graceful error, exit 2
+
+### Test cases for validation-runner wiring:
+10. **Feature with `nextjs-expert` active** → `nextjs-component` validator runs
+11. **Feature without `nextjs-expert` active** → `nextjs-component` validator doesn't run
+
+---
+
+## Artifacts
+
+| File | Type | Notes |
+|------|------|-------|
+| `framework/agents.json` | Modified | Add `nextjs-component` to validators |
+| `src/lib/validators/validation-runner.js` | Modified | Register `nextjs-component` key |
+| `scripts/scan-nextjs.mjs` | New | CLI scan script |
+| `test/scripts/scan-nextjs.test.mjs` | New | E2E tests with real temp dirs |
+| `framework/skills/level-0-meta/code-review-nextjs/SKILL.md` | New | Code review skill |
+| `framework/skills/level-0-meta/code-review-nextjs/references/review-example-nextjs.md` | New | Filled review example |
+| `.claude/skills/code-review-nextjs.md` | Installed | Via installSkills() |
+
+---
+
+## Out of Scope
+
+- `scan-csharp.mjs` — exists conceptually, not implemented. Follow-up task.
+- AST-based analysis — regex is sufficient for the current check set
+- IDE integration — out of scope for this iteration
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*