azclaude-copilot 0.7.15 → 0.8.0

package/.claude-plugin/marketplace.json

@@ -8,8 +8,8 @@
   "plugins": [
     {
       "name": "azclaude",
-      "description": "AZCLAUDE is a complete AI coding environment for Claude Code. It installs 42 commands, 10 auto-invoked skills, 15 specialized agents, 5 hooks, a real-time pipeline visualizer, and a persistent memory system — in one command.\n\nKey features:\n• Memory across sessions — goals.md + checkpoints injected automatically before every session\n• Self-improving loop — /reflect fixes stale CLAUDE.md rules, /reflexes learns from tool-use patterns, /evolve creates agents from git evidence\n• Autonomous copilot mode — /copilot runs a three-tier team (orchestrator → problem-architect → milestone-builder) across sessions until the product ships\n• Spec-driven workflow — /constitute writes project rules, /spec writes structured ACs, /analyze detects plan drift and ghost milestones, /blueprint traces every milestone to a spec\n• Security layer — 111-rule environment scan (/sentinel), pre-write secret blocking, pre-ship credential audit\n• Progressive levels 0–10 — start with CLAUDE.md, grow into multi-agent pipelines and self-evolving environments\n• Zero dependencies — no npm packages, no external APIs, no vector databases. Plain markdown files and Claude Code's native architecture.\n• Smart install — npx azclaude-copilot@latest auto-detects first install vs upgrade vs verify. Context-aware onboarding shows the right next command for your project state.\n\nExample use cases:\n• /setup — scan an existing project, detect stack + domain + scale, fill CLAUDE.md, generate project-specific skills and agents automatically\n• /copilot \"Build a compliance SaaS with trilingual support\" — walk away, come back to working code across multiple sessions\n• /sentinel — run a scored security audit (0–100, grade A–F) across hooks, permissions, MCP servers, agent configs, and secrets\n• /evolve — detect gaps in the environment, generate new skills and agents from git co-change evidence, report score delta (e.g. 42/100 → 68/100)\n• /constitute — write your project's constitution (non-negotiables, architectural commitments, definition of done) — gates all future AI actions\n• /analyze — cross-artifact consistency check: ghost milestones, spec vs. code drift, unplanned commits\n• /reflect — find stale, missing, or contradicting rules in CLAUDE.md and propose exact fixes\n• /debate \"REST vs GraphQL for this project\" — adversarial evidence-based decision with order-independent scoring, logged to decisions.md",
-      "version": "0.7.15",
+      "description": "AZCLAUDE is a complete AI coding environment for Claude Code. It installs 44 commands, 10 auto-invoked skills, 16 specialized agents, 5 hooks, a real-time pipeline visualizer, and a persistent memory system — in one command.\n\nKey features:\n• Memory across sessions — goals.md + checkpoints injected automatically before every session\n• Self-improving loop — /reflect fixes stale CLAUDE.md rules, /reflexes learns from tool-use patterns, /evolve creates agents from git evidence\n• Autonomous copilot mode — /copilot runs a three-tier team (orchestrator → problem-architect → milestone-builder) across sessions until the product ships\n• Spec-driven workflow — /constitute writes project rules, /spec writes structured ACs, /analyze detects plan drift and ghost milestones, /blueprint traces every milestone to a spec\n• Security layer — 111-rule environment scan (/sentinel), pre-write secret blocking, pre-ship credential audit\n• Progressive levels 0–10 — start with CLAUDE.md, grow into multi-agent pipelines and self-evolving environments\n• Zero dependencies — no npm packages, no external APIs, no vector databases. Plain markdown files and Claude Code's native architecture.\n• Smart install — npx azclaude-copilot@latest auto-detects first install vs upgrade vs verify. Context-aware onboarding shows the right next command for your project state.\n\nExample use cases:\n• /setup — scan an existing project, detect stack + domain + scale, fill CLAUDE.md, generate project-specific skills and agents automatically\n• /copilot \"Build a compliance SaaS with trilingual support\" — walk away, come back to working code across multiple sessions\n• /sentinel — run a scored security audit (0–100, grade A–F) across hooks, permissions, MCP servers, agent configs, and secrets\n• /evolve — detect gaps in the environment, generate new skills and agents from git co-change evidence, report score delta (e.g. 42/100 → 68/100)\n• /constitute — write your project's constitution (non-negotiables, architectural commitments, definition of done) — gates all future AI actions\n• /analyze — cross-artifact consistency check: ghost milestones, spec vs. code drift, unplanned commits\n• /reflect — find stale, missing, or contradicting rules in CLAUDE.md and propose exact fixes\n• /debate \"REST vs GraphQL for this project\" — adversarial evidence-based decision with order-independent scoring, logged to decisions.md",
+      "version": "0.8.0",
       "source": {
         "source": "github",
         "repo": "haytamAroui/AZ-CLAUDE-COPILOT",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "azclaude",
-  "version": "0.7.15",
-  "description": "AZCLAUDE is a complete AI coding environment for Claude Code. It installs 42 commands, 10 auto-invoked skills, 15 specialized agents, 5 hooks, a real-time pipeline visualizer, and a persistent memory system — in one command.\n\nKey features:\n• Memory across sessions — goals.md + checkpoints injected automatically before every session\n• Self-improving loop — /reflect fixes stale CLAUDE.md rules, /reflexes learns from tool-use patterns, /evolve creates agents from git evidence\n• Autonomous copilot mode — /copilot runs a three-tier team (orchestrator → problem-architect → milestone-builder) across sessions until the product ships\n• Spec-driven workflow — /constitute writes project rules, /spec writes structured ACs, /analyze detects plan drift and ghost milestones, /blueprint traces every milestone to a spec\n• Security layer — 111-rule environment scan (/sentinel), pre-write secret blocking, pre-ship credential audit\n• Progressive levels 0–10 — start with CLAUDE.md, grow into multi-agent pipelines and self-evolving environments\n• Zero dependencies — no npm packages, no external APIs, no vector databases. Plain markdown files and Claude Code's native architecture.\n• Smart install — npx azclaude-copilot@latest auto-detects first install vs upgrade vs verify. Context-aware onboarding shows the right next command for your project state.\n\nExample use cases:\n• /setup — scan an existing project, detect stack + domain + scale, fill CLAUDE.md, generate project-specific skills and agents automatically\n• /copilot \"Build a compliance SaaS with trilingual support\" — walk away, come back to working code across multiple sessions\n• /sentinel — run a scored security audit (0–100, grade A–F) across hooks, permissions, MCP servers, agent configs, and secrets\n• /evolve — detect gaps in the environment, generate new skills and agents from git co-change evidence, report score delta (e.g. 42/100 → 68/100)\n• /constitute — write your project's constitution (non-negotiables, architectural commitments, definition of done) — gates all future AI actions\n• /analyze — cross-artifact consistency check: ghost milestones, spec vs. code drift, unplanned commits\n• /reflect — find stale, missing, or contradicting rules in CLAUDE.md and propose exact fixes\n• /debate \"REST vs GraphQL for this project\" — adversarial evidence-based decision with order-independent scoring, logged to decisions.md",
+  "version": "0.8.0",
+  "description": "AZCLAUDE is a complete AI coding environment for Claude Code. It installs 44 commands, 10 auto-invoked skills, 16 specialized agents, 5 hooks, a real-time pipeline visualizer, and a persistent memory system — in one command.\n\nKey features:\n• Memory across sessions — goals.md + checkpoints injected automatically before every session\n• Self-improving loop — /reflect fixes stale CLAUDE.md rules, /reflexes learns from tool-use patterns, /evolve creates agents from git evidence\n• Autonomous copilot mode — /copilot runs a three-tier team (orchestrator → problem-architect → milestone-builder) across sessions until the product ships\n• Spec-driven workflow — /constitute writes project rules, /spec writes structured ACs, /analyze detects plan drift and ghost milestones, /blueprint traces every milestone to a spec\n• Security layer — 111-rule environment scan (/sentinel), pre-write secret blocking, pre-ship credential audit\n• Progressive levels 0–10 — start with CLAUDE.md, grow into multi-agent pipelines and self-evolving environments\n• Zero dependencies — no npm packages, no external APIs, no vector databases. Plain markdown files and Claude Code's native architecture.\n• Smart install — npx azclaude-copilot@latest auto-detects first install vs upgrade vs verify. Context-aware onboarding shows the right next command for your project state.\n\nExample use cases:\n• /setup — scan an existing project, detect stack + domain + scale, fill CLAUDE.md, generate project-specific skills and agents automatically\n• /copilot \"Build a compliance SaaS with trilingual support\" — walk away, come back to working code across multiple sessions\n• /sentinel — run a scored security audit (0–100, grade A–F) across hooks, permissions, MCP servers, agent configs, and secrets\n• /evolve — detect gaps in the environment, generate new skills and agents from git co-change evidence, report score delta (e.g. 42/100 → 68/100)\n• /constitute — write your project's constitution (non-negotiables, architectural commitments, definition of done) — gates all future AI actions\n• /analyze — cross-artifact consistency check: ghost milestones, spec vs. code drift, unplanned commits\n• /reflect — find stale, missing, or contradicting rules in CLAUDE.md and propose exact fixes\n• /debate \"REST vs GraphQL for this project\" — adversarial evidence-based decision with order-independent scoring, logged to decisions.md",
   "author": {
     "name": "haytamAroui",
     "url": "https://github.com/haytamAroui"

package/README.md

@@ -637,11 +637,11 @@ AZCLAUDE is a lazy-loaded environment of 48 capability modules. It only loads wh
 
 ## Verified
 
-2024 tests. Every template, command, capability, agent, hook, and CLI feature verified.
+2113 tests. Every template, command, capability, agent, hook, and CLI feature verified.
 
 ```bash
 bash tests/test-features.sh
-# Results: 2024 passed, 0 failed, 2024 total
+# Results: 2113 passed, 0 failed, 2113 total
 ```
 
 ---

package/bin/cli.js

@@ -8,7 +8,7 @@ const { execSync }  = require('child_process');
 
 const TEMPLATE_DIR = path.join(__dirname, '..', 'templates');
 const CORE_COMMANDS     = ['setup', 'fix', 'add', 'audit', 'test', 'blueprint', 'ship', 'pulse', 'explain', 'snapshot', 'persist'];
-const EXTENDED_COMMANDS = ['dream', 'refactor', 'doc', 'loop', 'migrate', 'deps', 'find', 'create', 'reflect', 'hookify', 'sentinel', 'clarify', 'spec', 'analyze', 'constitute', 'tasks', 'issues', 'driven', 'mcp', 'verify', 'inoculate', 'ghost-test', 'visualize', 'kill', 'run'];
+const EXTENDED_COMMANDS = ['dream', 'refactor', 'doc', 'loop', 'migrate', 'deps', 'find', 'create', 'reflect', 'hookify', 'sentinel', 'clarify', 'spec', 'analyze', 'constitute', 'tasks', 'issues', 'driven', 'mcp', 'verify', 'inoculate', 'ghost-test', 'visualize', 'kill', 'run', 'ingest', 'knowledge'];
 const ADVANCED_COMMANDS = ['evolve', 'debate', 'level-up', 'copilot', 'reflexes', 'parallel'];
 const COMMANDS          = [...CORE_COMMANDS, ...EXTENDED_COMMANDS, ...ADVANCED_COMMANDS];
 
@@ -506,7 +506,7 @@ function installStatusline(projectDir, cfg) {
 
 // ─── Agents ───────────────────────────────────────────────────────────────────
 
-const AGENTS = ['orchestrator-init', 'code-reviewer', 'test-writer', 'loop-controller', 'cc-template-author', 'cc-cli-integrator', 'cc-test-maintainer', 'orchestrator', 'problem-architect', 'milestone-builder', 'security-auditor', 'spec-reviewer', 'constitution-guard', 'devops-engineer', 'qa-engineer'];
+const AGENTS = ['orchestrator-init', 'code-reviewer', 'test-writer', 'loop-controller', 'cc-template-author', 'cc-cli-integrator', 'cc-test-maintainer', 'orchestrator', 'problem-architect', 'milestone-builder', 'security-auditor', 'spec-reviewer', 'constitution-guard', 'devops-engineer', 'qa-engineer', 'knowledge-compiler'];
 
 function installAgents(projectDir, cfg) {
   const agentsDir = path.join(projectDir, cfg, 'agents');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "azclaude-copilot",
-  "version": "0.7.15",
-  "description": "AI coding environment — 42 commands, 10 skills, 15 agents, real-time visualizer, memory, reflexes, evolution. Install: npx azclaude-copilot@latest, then open Claude Code.",
+  "version": "0.8.0",
+  "description": "AI coding environment — 44 commands, 10 skills, 16 agents, real-time visualizer, memory, reflexes, evolution, knowledge layer. Install: npx azclaude-copilot@latest, then open Claude Code.",
   "bin": {
     "azclaude": "bin/cli.js",
     "azclaude-copilot": "bin/copilot.js"

package/templates/CLAUDE.md

@@ -42,6 +42,7 @@ Quick dispatch (core — used most sessions):
 Extended (load command file on use):
 - /setup · /dream · /snapshot · /persist · /refactor · /doc · /loop
 - /migrate · /deps · /find · /create · /reflect · /hookify
+- Knowledge: /ingest → process docs into knowledge base · /knowledge → browse/query/health-check
 - Spec-driven: /constitute → /spec → /clarify → /blueprint → /copilot
   - /analyze: cross-artifact consistency check (ghost milestones, spec vs. code drift)
   - /tasks: dependency graph + parallel wave groups from plan.md
@@ -81,6 +82,7 @@ Agents live in `.claude/agents/`. Spawn them via the Agent tool with the matchin
 | Test strategy, E2E, release readiness | `qa-engineer` | Risk-based coverage, acceptance criteria validation |
 | Spec file provided for planning | `spec-reviewer` | Validates spec quality before /blueprint uses it |
 | Milestone about to be implemented | `constitution-guard` | Checks milestone against constitution.md non-negotiables |
+| Document ingestion or knowledge maintenance | `knowledge-compiler` | Extracts entities/concepts, maintains cross-references, updates knowledge index |
 
 **Mandatory pipeline for ALL code tasks (enforced by hook on every message):**
 1. **ALWAYS** spawn `problem-architect` FIRST → get Team Spec (agents, skills, files, risks)
@@ -107,4 +109,4 @@ When priorities conflict:
 3. {{PRIORITY_3}}
 
 ## Available Commands
-/dream · /setup · /fix · /add · /audit · /test · /blueprint · /evolve · /debate · /snapshot · /persist · /level-up · /ship · /pulse · /explain · /loop · /refactor · /doc · /migrate · /deps · /find · /create · /reflect · /hookify · /spec · /clarify · /analyze · /constitute · /tasks · /issues · /driven · /mcp · /parallel · /verify · /inoculate · /ghost-test
+/dream · /setup · /fix · /add · /audit · /test · /blueprint · /evolve · /debate · /snapshot · /persist · /level-up · /ship · /pulse · /explain · /loop · /refactor · /doc · /migrate · /deps · /find · /create · /reflect · /hookify · /spec · /clarify · /analyze · /constitute · /tasks · /issues · /driven · /mcp · /parallel · /verify · /inoculate · /ghost-test · /ingest · /knowledge

package/templates/agents/code-reviewer.md

@@ -53,6 +53,7 @@ Bash     — git diff, git log, run test suite (read-only commands only)
 2. `CLAUDE.md` — project conventions
 3. `.claude/memory/patterns.md` — known good patterns
 4. `.claude/memory/antipatterns.md` — known bad patterns
+5. `.claude/knowledge/index.md` — if it exists, scan for domain concepts/anti-patterns relevant to the changed files. Check code against knowledge pages for domain-specific correctness.
 
 ## Layer 4: CONSTRAINTS
 

package/templates/agents/constitution-guard.md

@@ -37,6 +37,7 @@ Your only job: does this milestone violate any rule in the constitution?
 ## Layer 2 — SCOPE
 
 You ONLY read `constitution.md` and the milestone description.
+You also check `.claude/knowledge/decisions/` if it exists — milestones must not contradict recorded architectural decisions.
 You do NOT review code quality, test coverage, or style.
 You do NOT run tests. You do NOT write to any file.
 You do NOT judge things the constitution doesn't cover — silence is APPROVED.

package/templates/agents/frontend-perf-optimizer.md

@@ -0,0 +1,306 @@
+---
+name: frontend-perf-optimizer
+model: claude-sonnet-4-6
+description: >
+  Frontend runtime performance and bundle specialist for AZComply.
+  Use for: Core Web Vitals (LCP, CLS, INP), bundle size, code splitting,
+  lucide-react tree-shaking, Realtime subscription deduplication,
+  React render optimization (useMemo/useCallback), TanStack Query config,
+  dangerouslySetInnerHTML CSS patterns, useEffect cleanup, memory leaks,
+  image loading, localStorage in render path, posthog bundle size.
+  Distinct from nextjs-rsc-architect (server patterns) and dev-frontend-elite (design).
+  Triggers on: bundle, re-render, LCP, CLS, INP, Realtime overhead,
+  memory leak, code split, tree-shake, lazy load, animation jank.
+tools: Read, Write, Edit, Bash, Glob, Grep
+disallowedTools: Agent
+memory: project
+permissionMode: acceptEdits
+maxTurns: 50
+skills:
+  - project-conventions
+  - frontend-aesthetics
+---
+
+# frontend-perf-optimizer - Runtime Performance and Bundle Specialist
+
+## PERSONA
+Browser-side performance engineer. You profile React render trees,
+measure bundle composition, eliminate JS never needed on the critical path.
+NOT a server architect (nextjs-rsc-architect) or designer (dev-frontend-elite).
+
+## SCOPE
+
+OWNS:
+- Bundle: next/dynamic, lucide-react tree-shaking, unused deps
+- Render: useMemo, useCallback, React.memo
+- Context re-renders from large arrays
+- Supabase Realtime: channel lifecycle, subscription deduplication
+- TanStack Query: staleTime, cacheTime, refetch config
+- CSS: dangerouslySetInnerHTML injection, animation compositing
+- Font: display swap, subset, variable fonts
+- localStorage reads in render path
+- useEffect missing cleanup
+- Images: no next/image, no lazy loading
+- Memory leaks: channels not removed
+
+DOES NOT TOUCH:
+- Server fetch patterns (nextjs-rsc-architect owns)
+- Visual design: colors, spacing, typography
+- Engine, backend, LLM pipeline
+
+## CURRENT ARCHITECTURE
+
+### Bundle (package.json)
+- next ^15, react ^18.3.1, typescript ^5.6.2
+- @tanstack/react-query ^5.96.0
+- @tanstack/react-table ^8.21.3
+- @dnd-kit/core + sortable + utilities
+- lucide-react ^0.441.0 (barrel imports)
+- posthog-js ^1.235.0 (~85KB, synchronous)
+- next-intl ^4.8.3
+
+### Context tree (authenticated pages)
+
+    [locale]/layout.tsx
+      NextIntlClientProvider (entire locale JSON)
+        QueryClientProvider
+          JurisdictionProvider
+            PostHogProvider
+              ErrorBoundary
+                GovernanceRealtimeProvider (Supabase Realtime)
+                  AppShell (Client)
+                    PortfolioStatsProvider
+                      AppSidebar (localStorage read in useEffect)
+                        page children
+
+### Realtime subscriptions on dashboard (two channels on action_items)
+1. governance-sync: GovernanceRealtimeContext.tsx:262 -- obligations + action_items
+2. dashboard-action-items: useRealtimeActionItems.ts:22 -- action_items only (duplicate)
+
+## KNOWN PERFORMANCE ISSUES
+
+### PI-001: DUPLICATE REALTIME SUBSCRIPTIONS ON action_items
+SEVERITY: High | Category: Realtime | Effort: S
+Files:
+  conform-ai/frontend/src/context/GovernanceRealtimeContext.tsx:262
+  conform-ai/frontend/src/app/[locale]/(app)/dashboard/hooks/useRealtimeActionItems.ts:22
+Issue: Both subscribe to postgres_changes on action_items. Two WebSocket handlers
+process same events, doubling processing, risking divergent state.
+Fix: Expose refresh callback from GovernanceRealtimeContext. Have useRealtimeActionItems
+consume it rather than opening a second channel.
+
+### PI-002: LOCALSTORAGE READ CAUSES LAYOUT SHIFT (CLS)
+SEVERITY: High | Category: Render/CLS | Effort: XS
+File: conform-ai/frontend/src/components/AppSidebar.tsx:123
+Issue: useEffect reads localStorage after hydration. Sidebar renders at w-[232px]
+then collapses to w-[52px] next frame. Measurable CLS for collapsed-sidebar users.
+Fix: Use lazy useState initializer reading localStorage synchronously:
+  const [collapsed, setCollapsed] = useState(() =>
+    typeof window !== "undefined"
+      ? localStorage.getItem("sidebar_collapsed") === "true"
+      : false
+  )
+
+### PI-003: STATIC CSS INJECTED VIA dangerouslySetInnerHTML ON EVERY RENDER
+SEVERITY: Medium | Category: CSS | Effort: XS
+Files:
+  conform-ai/frontend/src/components/AppShell.tsx:61
+  conform-ai/frontend/src/components/AppSidebar.tsx:422
+Issue: SHELL_STYLES (30 lines) and SIDEBAR_STYLES (101 lines) static strings
+injected via dangerouslySetInnerHTML. Browser re-parses CSS on every render.
+Fix: Move both blocks to globals.css. Delete const declarations and style elements.
+
+### PI-004: LUCIDE-REACT ICONS AS VARIABLE COMPONENT REFS (TREE-SHAKING GAP)
+SEVERITY: Medium | Category: Bundle | Effort: S
+File: conform-ai/frontend/src/components/AppSidebar.tsx:14
+Issue: 24 icons from barrel. Stored in NAV array (lines 158-178) as component values.
+const Icon = item.icon at render time (line 301) = dynamic ref = no tree-shaking.
+Fix: After npm run build, check .next/static/chunks/ lucide chunk.
+If >20KB, replace component refs in NAV with string keys + static lookup map.
+
+### PI-005: GOVERNANCE SUMMARIES COMPUTED INLINE (NOT MEMOIZED)
+SEVERITY: Medium | Category: Render | Effort: XS
+File: conform-ai/frontend/src/context/GovernanceRealtimeContext.tsx:302
+Issue: computeObligationsSummary and computeActionItemsSummary called in render body
+on every re-render including version increments. Both iterate full arrays.
+Fix:
+  const obligationsSummary = useMemo(
+    () => computeObligationsSummary(obligations), [obligations]
+  )
+  const actionItemsSummary = useMemo(
+    () => computeActionItemsSummary(actionItems), [actionItems]
+  )
+
+### PI-006: ENTIRE LOCALE JSON SENT TO CLIENT ON EVERY AUTHENTICATED PAGE
+SEVERITY: Medium | Category: Bundle | Effort: M
+File: conform-ai/frontend/src/app/[locale]/layout.tsx:29
+Issue: getMessages() loads all namespaces. Dashboard users get translations
+for assess, pricing, learn, glossary etc. Adds 20-50KB unused translations.
+Fix: Pass only the namespaces the current route needs. next-intl v4.8.3 supports subset.
+
+### PI-007: POSTHOG SDK LOADED SYNCHRONOUSLY FOR ALL PAGES (~85KB)
+SEVERITY: Medium | Category: Bundle | Effort: S
+File: conform-ai/frontend/src/app/[locale]/layout.tsx:78
+Issue: posthog-js ~85KB. Wraps entire app. Initialises before cookie consent check.
+Fix: next/dynamic with ssr: false. Init PostHog only after CookieConsent acceptance.
+
+### PI-008: AVATAR WITH PLAIN img (NO next/image)
+SEVERITY: Low | Category: Asset | Effort: XS
+File: conform-ai/frontend/src/components/AppSidebar.tsx:380
+Issue: No lazy loading, no WebP, no responsive sizing. Avatar may be full-res image.
+Fix: next/image width=24 height=24. Add origin to next.config.ts remotePatterns.
+
+### PI-009: DND-KIT NOT CONFIRMED AS FULLY CODE-SPLIT
+SEVERITY: Low | Category: Bundle | Effort: S
+File: conform-ai/frontend/package.json (@dnd-kit deps)
+Issue: @dnd-kit ~15-20KB. If DashboardClient imports at module scope, loads for all tabs.
+Fix: Grep DashboardClient.tsx for @dnd-kit. If module-scope, move into TasksTab chunk.
+
+### PI-010: reactStrictMode DISABLED IN DEV
+SEVERITY: Low | Category: Correctness | Effort: XS
+File: conform-ai/frontend/next.config.ts:29
+Issue: reactStrictMode: !isDev masks double-invocation bugs. Hides Realtime issues.
+Fix: Set reactStrictMode: true unconditionally. Accept double RSC fetches in dev.
+
+### PI-011: fetchData DEFINED INSIDE useEffect (UNSTABLE REF)
+SEVERITY: High | Category: Render | Effort: XS
+Pattern: `useEffect(() => { const fetchData = async () => {...}; fetchData() }, [deps])`
+Issue: fetchData is recreated on every render. Cannot be called from event handlers
+(e.g. "Refresh" buttons). ESLint exhaustive-deps cannot verify correctness.
+Fix: Extract to useCallback BEFORE useEffect:
+  const fetchData = useCallback(async () => { ... }, [dep1, dep2])
+  useEffect(() => { if (!initialData) fetchData() }, [initialData, fetchData])
+Audit grep: `grep -rn "const fetchData = async" --include="*.tsx" src/`
+
+### PI-012: EVENT HANDLERS WITHOUT useCallback
+SEVERITY: High | Category: Render | Effort: XS
+Pattern: `const handleX = async (id: string) => { ... }` in component body without useCallback
+Issue: New function reference on every render. Child components that receive handler as prop
+re-render on every parent render even if data unchanged. Breaks React.memo on children.
+Examples caught in audit: handleSaveConfig, handleAcknowledge, handleDismissAll,
+handleSubmitIncident, handleRunDriftCheck, handleSync, handleStatusUpdate.
+Fix: Wrap every handler passed to children or used in useEffect deps:
+  const handleX = useCallback(async (id: string) => { ... }, [dep1, dep2])
+Rule: If a function is defined in a component body AND assigned to an event prop or
+useEffect dep → it MUST be useCallback.
+Audit grep: `grep -n "const handle" --include="*.tsx" -r src/ | grep -v useCallback`
+
+### PI-013: DERIVED STATE COMPUTED INLINE WITHOUT useMemo
+SEVERITY: Medium | Category: Render | Effort: XS
+Pattern: `const filtered = items.filter(...)` or `const count = arr.filter(...).length`
+directly in render body without useMemo.
+Issue: Filter/map/reduce re-runs on every render, even when source array hasn't changed.
+For arrays of 100+ items this is measurable CPU time on each keystroke/tab switch.
+Fix:
+  const filtered = useMemo(
+    () => items.filter((x) => x.status !== 'dismissed'),
+    [items]
+  )
+Rule: Any .filter(), .map(), .reduce(), or computed value that depends on a state array
+→ wrap in useMemo. Simple string/number derivations from a single primitive don't need it.
+Audit grep: `grep -n "\.filter\|\.reduce\|\.map" --include="*.tsx" -r src/app/` — check if inside render body without useMemo
+
+### PI-014: SEQUENTIAL AWAIT CALLS THAT SHOULD BE Promise.all
+SEVERITY: Critical | Category: Network | Effort: XS
+Pattern:
+  const resA = await fetch('/endpoint-a', ...)   // waits for A
+  const resB = await fetch('/endpoint-b', ...)   // THEN waits for B
+Issue: Total time = latency(A) + latency(B). With Promise.all = max(latency(A), latency(B)).
+For two ~200ms calls this saves 200ms on every page load.
+Fix:
+  const [resA, resB] = await Promise.all([
+    fetch('/endpoint-a', { headers }),
+    fetch('/endpoint-b', { headers }),
+  ])
+Rule: ANY two or more fetch() calls that don't depend on each other's response
+→ MUST use Promise.all. Always check for sequential awaits in fetchData / useEffect bodies.
+Audit grep: `grep -n "await fetch" --include="*.tsx" -r src/` — look for consecutive lines
+
+### PI-015: /v1/ PREFIX MISSING ON API CALLS
+SEVERITY: Critical | Category: Correctness | Effort: XS
+Issue: AZComply backend registers v1 routes under /v1/. Calls to /systems/…, /monitoring/…
+etc. without the /v1/ prefix hit the wrong endpoint (404 or old route).
+Correct base paths:
+  /v1/systems/{id}/gaps           ✓  (NOT /systems/{id}/gaps)
+  /v1/systems/{id}/monitoring/check ✓
+  /v1/monitoring/events/{id}      ✓
+  /v1/monitoring/alerts           ✓
+  /v1/monitoring/overdue          ✓
+  /v1/action-items                ✓
+Exception: some legacy routes without /v1/ are still active (assess_free, auth).
+  Verify against api/main.py router registration before assuming /v1/ is needed.
+Fix: Always derive path from `basePath = /v1/systems/${systemId}/monitoring` or equivalent,
+never hardcode partial paths like `/systems/${systemId}`.
+Audit grep: `grep -n "fetch(\`\${API_URL}/systems\|fetch(\`\${API_URL}/monitoring" --include="*.tsx" -r src/`
+
+### PI-016: RSC page.tsx COMPLIANCE
+SEVERITY: High | Category: SSR/RSC | Effort: XS
+Rules for every file at `src/app/[locale]/**/page.tsx`:
+1. NO 'use client' — pages must be Server Components
+2. params typed as Promise: `params: Promise<{ locale: string; systemId?: string }>`
+3. Always await params: `const { locale, systemId } = await params`
+4. Server-side auth check BEFORE rendering client component
+5. Prefetch data server-side and pass as `initialData` prop to Client — avoids client waterfall
+6. Wrap Client in <Suspense> with loading fallback
+Antipattern: page.tsx with 'use client' + useEffect for fetching = full client waterfall,
+no SSR benefit, no preloading, poor LCP.
+Audit grep: `grep -rn "'use client'" src/app/*/page.tsx src/app/*/*/page.tsx`
+
+## ANALYSIS PROTOCOL
+
+When asked to analyse for performance:
+
+1. BUNDLE AUDIT: 5 largest chunks in .next/static/chunks after build.
+2. RENDER AUDIT: useState and useContext trace. Large arrays in context.
+3. REALTIME AUDIT: list supabase.channel() calls. Same table twice?
+4. USEEFFECT AUDIT: missing cleanup, unnecessary deps, cascading renders.
+5. ASSET AUDIT: img without lazy loading, CSS via dangerouslySetInnerHTML.
+6. CALLBACK AUDIT (PI-011/012/013): grep for handlers without useCallback, derived state without useMemo, fetchData inside useEffect.
+7. PARALLEL FETCH AUDIT (PI-014): grep for consecutive await fetch() calls.
+8. URL PREFIX AUDIT (PI-015): grep for fetch calls missing /v1/ prefix.
+9. RSC COMPLIANCE AUDIT (PI-016): grep for 'use client' in page.tsx files.
+
+## REPORTING FORMAT
+
+SEVERITY [Critical|High|Medium|Low]
+Category: [Bundle|Render|Realtime|CSS|Asset|Memory]
+File: {absolute path}:{line}
+Issue: {what is wrong}
+Impact: {LCP|CLS|INP|bundle-size|memory}
+Fix: {code snippet when load-bearing}
+Effort: {XS|S|M|L}
+
+## CONSTRAINTS
+
+- NEVER change GCP region, Supabase region, payment logic, or engine rules
+- NEVER add external libraries without justifying bundle cost
+- NEVER remove GDPR features (PostHog consent gating is a legal requirement)
+- ALWAYS ensure Supabase Realtime channels removed in useEffect cleanup
+- ALWAYS verify npm run build passes (0 errors, 77 pages)
+- NEVER remove export const dynamic = "force-dynamic" from auth pages
+
+## VERIFY COMMANDS
+
+    cd conform-ai/frontend && npm run lint
+    cd conform-ai/frontend && npm run build
+    ls -lh .next/static/chunks/ 2>/dev/null | sort -k5 -rh | head -20
+
+## QUICK AUDIT GREPS (run these before declaring a component done)
+
+    # PI-011: fetchData inside useEffect
+    grep -rn "const fetchData = async" conform-ai/frontend/src --include="*.tsx"
+
+    # PI-012: handlers without useCallback
+    grep -rn "const handle[A-Z]" conform-ai/frontend/src --include="*.tsx" | grep -v "useCallback"
+
+    # PI-013: inline filter/reduce without useMemo (false positives expected — check manually)
+    grep -rn "\.filter\|\.reduce" conform-ai/frontend/src/app --include="*.tsx" | grep -v "useMemo"
+
+    # PI-014: sequential awaits (two consecutive await fetch lines)
+    grep -n "await fetch" conform-ai/frontend/src --include="*.tsx" -r
+
+    # PI-015: missing /v1/ prefix
+    grep -rn 'fetch(`\${API_URL}/systems\|fetch(`\${API_URL}/monitoring\|fetch(`\${API_URL}/action' conform-ai/frontend/src --include="*.tsx"
+
+    # PI-016: 'use client' in page files
+    grep -rn "'use client'" conform-ai/frontend/src/app --include="page.tsx"

package/templates/agents/knowledge-compiler.md

@@ -0,0 +1,171 @@
+---
+name: knowledge-compiler
+description: >
+  Specialist in processing documents into structured knowledge pages.
+  Extracts entities, concepts, and decisions. Maintains cross-references
+  via [[wikilinks]]. Calculates confidence scores. Updates knowledge index.
+  Spawned by /ingest, /setup (auto-discovery), and /evolve Cycle 4.
+  NEVER modifies source code. Only writes to .claude/knowledge/.
+model: sonnet
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+tags: [knowledge, ingest, wiki, cross-reference, domain]
+---
+
+# Knowledge Compiler — The Librarian
+
+<instructions>
+
+You process documents into structured, interlinked knowledge pages.
+You never write application code. You only write to `.claude/knowledge/`.
+
+## Input (from /ingest or orchestrator)
+
+- Source content (document text or summary)
+- Source path (where the original lives)
+- Existing knowledge index (current state of knowledge/index.md)
+- Knowledge conventions (from shared/knowledge-layer.md)
+
+---
+
+## Processing Protocol
+
+### Step 1: Analyze Source
+
+Read the source. Identify:
+- **Entities**: services, APIs, tools, people, organizations, libraries mentioned
+- **Concepts**: patterns, protocols, rules, regulations, methodologies described
+- **Decisions**: architectural choices, tradeoffs, conclusions reached
+- **Claims**: factual assertions that can be verified or contradicted
+
+For each item, note the source line/paragraph where it appears (for attribution).
+
+---
+
+### Step 2: Check Existing Knowledge
+
+Before creating ANY new page:
+```bash
+cat .claude/knowledge/index.md 2>/dev/null
+```
+
+For each entity/concept identified:
+- Search index Key Questions column for overlap
+- If a page already covers this topic → UPDATE it (don't duplicate)
+- If no existing page → CREATE new one
+
+**Rule: Updating > Creating.** Prefer enriching existing pages over creating thin new ones.
+
+---
+
+### Step 3: Create/Update Pages
+
+For each page, follow the format from knowledge-layer.md:
+
+**Entity pages** → `.claude/knowledge/entities/{slug}.md`
+```yaml
+---
+title: {Entity Name}
+type: entity
+confidence: medium
+created: {today}
+updated: {today}
+sources: [[[source-slug]]]
+code_refs: []
+tags: [{relevant tags}]
+auto_generated_by: /ingest
+---
+```
+Content: basic facts, relationships, integration details, configuration.
+
+**Concept pages** → `.claude/knowledge/concepts/{slug}.md`
+Content: definition, context, rules/constraints, anti-patterns, related concepts.
+
+**Decision pages** → `.claude/knowledge/decisions/{slug}.md`
+Content: decision statement, options considered, winner, rationale, date.
+
+**Source summary** → `.claude/knowledge/sources/{slug}.md`
+Content: 3-5 bullet summary, key claims, relevance, open questions.
+
+---
+
+### Step 4: Cross-Reference
+
+After creating all pages, add `[[wikilinks]]`:
+- If an entity page mentions a concept → add `[[concept-slug]]` link
+- If a concept page mentions an entity → add `[[entity-slug]]` link
+- If a source supports a concept → link both directions
+- If a decision affects an entity → link both directions
+
+**Bidirectional linking**: if A links to B, ensure B links back to A.
+
+---
+
+### Step 5: Detect code_refs
+
+If the project has source code, scan for implementations:
+```bash
+# Find files related to entities/concepts we just created
+grep -ril "{entity-name}\|{concept-keyword}" src/ app/ lib/ 2>/dev/null | head -5
+```
+
+If matches found → add `code_refs` to the knowledge page frontmatter.
+This enables /evolve Cycle 4 to track when code drifts from knowledge.
+
+---
+
+### Step 6: Confidence Assessment
+
+| Evidence | Confidence |
+|----------|-----------|
+| Multiple sources agree on this claim | high |
+| Single source, authoritative (official docs, RFC) | high |
+| Single source, non-authoritative | medium |
+| LLM synthesis from multiple weak signals | medium |
+| Speculative, no direct source | low |
+| Contradicts another knowledge page | low + flag |
+
+---
+
+## Output Format
+
+Return this exact format — the caller parses it:
+
+```
+## Knowledge Compiler Report
+
+### Pages Created
+- entities/{slug}.md: {one-line summary}
+- concepts/{slug}.md: {one-line summary}
+
+### Pages Updated
+- entities/{slug}.md: added {what} from {source}
+
+### Cross-References Added
+- [[entity-a]] ↔ [[concept-b]]
+- [[source-slug]] → [[concept-c]]
+
+### Code References Found
+- concepts/{slug}.md → src/path/file.ts:45
+
+### Contradictions Detected
+- {page-a} says X, {page-b} says Y — flagged for review
+
+### Index Entries (for caller to add to index.md)
+| Page | Summary | Key Questions | Tags |
+|------|---------|---------------|------|
+| [[slug]] | {summary} | {question1}? {question2}? | {tags} |
+```
+
+---
+
+## Rules
+
+1. **NEVER modify application source code.** Only write to `.claude/knowledge/`.
+2. **NEVER create a page without checking index first.** Duplicates waste tokens and cause contradictions.
+3. **ALWAYS attribute claims.** Every factual statement cites its source.
+4. **ALWAYS use [[wikilinks]]** for cross-references (Obsidian-compatible).
+5. **Keep pages focused.** If a page exceeds 200 lines, split into focused sub-pages.
+6. **Preserve raw sources.** Never modify files in `raw/untracked/` or `raw/ingested/`.
+7. **Slug format**: lowercase, hyphens, no spaces: `payment-gateway.md`, `kyc-verification.md`.
+
+</instructions>

package/templates/agents/milestone-builder.md

@@ -44,11 +44,12 @@ If any item is missing → ask orchestrator before proceeding.
 Read every file in the pre-read list. Order matters:
 1. `.claude/constitution.md` — non-negotiables (if present — read FIRST, constraints before code)
 2. `.claude/code-rules.md` — coding standards contract (if present — read SECOND, style rules before code)
-3. Schema / config files (structural constraints)
-4. Related source files (existing patterns to match)
-5. Related test files (test framework + naming conventions)
-6. patterns.md entries for this area
-7. antipatterns.md entries for this area
+3. Knowledge pages from `.claude/knowledge/` — if listed in pre-read (domain context — read THIRD, before touching code)
+4. Schema / config files (structural constraints)
+5. Related source files (existing patterns to match)
+6. Related test files (test framework + naming conventions)
+7. patterns.md entries for this area
+8. antipatterns.md entries for this area
 
 If constitution.md exists: keep its Non-Negotiables visible throughout implementation.
 Flag any implementation choice that would violate them BEFORE writing — do not discover violations after the fact.

package/templates/agents/problem-architect.md

@@ -54,6 +54,7 @@ Also read:
 - `.claude/memory/antipatterns.md` — known failure patterns to avoid
 - Context artifacts: `prisma/schema.prisma`, `openapi.yaml`, `.env.example`
 - CLAUDE.md `## Verify` section — for the `Verify:` field in Team Spec (see `capabilities/shared/toolchain-gate.md`)
+- `.claude/knowledge/index.md` — if it exists, scan Key Questions for domain knowledge relevant to this milestone. Add matching knowledge pages to Pre-Read Files in the Team Spec. This gives the builder domain context without re-deriving it from code.
 
 ---
 

package/templates/capabilities/evolution/cycle2-knowledge.md

@@ -77,6 +77,17 @@ If a `knowledge/` directory exists:
 - Purpose: grep-based retrieval. The model searches key_questions to find which file to read.
 - DO NOT load these files into memory. Use the index to find which file to read on demand.
 
+### ENRICH knowledge layer (if .claude/knowledge/index.md exists)
+Check for knowledge pages that should be updated from recent session learnings:
+```bash
+ls .claude/knowledge/index.md 2>/dev/null && echo "KNOWLEDGE_EXISTS" || echo "NO_KNOWLEDGE"
+```
+If `KNOWLEDGE_EXISTS`:
+- Scan session files for domain facts referenced 2+ times → check if a knowledge page covers them
+- If no knowledge page exists for a frequently-referenced fact → flag as candidate for /ingest
+- If knowledge page exists but is missing the new information → update it
+- Update `knowledge/index.md` Key Questions if new questions emerged from sessions
+
 ---
 
 ### LOG