@polymorphism-tech/morph-spec 4.8.1 → 4.8.4

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

@@ -1,439 +0,0 @@
-# infra-architect Refactor Implementation Plan
-
-**Status:** COMPLETE
-
-> **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

@@ -1,157 +0,0 @@
-# Next.js Code Review & Scan — Design Doc
-
-**Status:** COMPLETE (see implementation plan)
-
-> **Date:** 2026-02-23
-> **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*