@polymorphism-tech/morph-spec 8.34.2 → 8.35.1

package/src/utils/hooks-installer.js

@@ -9,10 +9,11 @@
  */
 
 import { join, dirname } from 'path';
-import { readFile, writeFile, mkdir, copyFile } from 'fs/promises';
+import { readFile } from 'fs/promises';
 import { existsSync, chmodSync, readdirSync } from 'fs';
 import { homedir } from 'os';
 import { execSync } from 'child_process';
+import { realEffects } from '../lib/installers/effects.js';
 
 /**
  * Current hooks schema version — bump when hook definitions change.
@@ -280,9 +281,14 @@ const MORPH_HOOKS = [
  * - Tracks installed version via _morph_managed.hooks_version
  *
  * @param {string} targetPath - Project root directory
+ * @param {object} [options]
+ * @param {ReturnType<import('../lib/installers/effects.js').createEffects>} [options.fx]
+ *   Coletor de efeitos. Esta função é o seam mais barato do caminho de update:
+ *   o objeto de settings INTEIRO já é montado em memória e há UMA escrita, no
+ *   fim. Previsão e execução percorrem a mesma montagem.
  * @returns {Promise<{ installed: number, updated: boolean }>}
  */
-export async function installClaudeHooks(targetPath) {
+export async function installClaudeHooks(targetPath, { fx = realEffects() } = {}) {
   const claudeDir = join(targetPath, '.claude');
   const settingsPath = join(claudeDir, 'settings.local.json');
 
@@ -409,11 +415,9 @@ export async function installClaudeHooks(targetPath) {
   settings._morph_managed.generated_at = new Date().toISOString();
 
   // Ensure .claude directory exists
-  if (!existsSync(claudeDir)) {
-    await mkdir(claudeDir, { recursive: true });
-  }
+  fx.ensureDir(claudeDir);
 
-  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+  fx.writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n');
   return { installed, updated: !alreadyCurrent };
 }
 
@@ -530,19 +534,24 @@ function resolvePythonForStatusline() {
  *
  * @param {string} hooksSourceDir - Path to framework/hooks/claude-code/
  * @param {string} [globalClaudeDirOverride] - Override ~/.claude/ (for testing)
+ * @param {object} [options]
+ * @param {ReturnType<import('../lib/installers/effects.js').createEffects>} [options.fx]
+ *   Coletor de efeitos. Estes são os efeitos FORA do projeto — o relatório do
+ *   `--dry-run` é obrigado a nomeá-los separadamente, porque ninguém os
+ *   adivinha da palavra "update".
  * @returns {Promise<{ installed: boolean, globalDir: string }>}
  */
-export async function installGlobalStatusline(hooksSourceDir, globalClaudeDirOverride = null) {
+export async function installGlobalStatusline(hooksSourceDir, globalClaudeDirOverride = null, { fx = realEffects() } = {}) {
   const globalDir = globalClaudeDirOverride || join(homedir(), '.claude');
-  await mkdir(globalDir, { recursive: true });
+  fx.ensureDir(globalDir);
 
   // Copy statusline scripts to ~/.claude/
   const scripts = ['statusline.sh', 'statusline.py'];
   for (const fname of scripts) {
     const src = join(hooksSourceDir, fname);
     if (existsSync(src)) {
-      await copyFile(src, join(globalDir, fname));
-      if (process.platform !== 'win32') {
+      fx.copyFile(src, join(globalDir, fname));
+      if (process.platform !== 'win32' && !fx.dryRun) {
         try { chmodSync(join(globalDir, fname), 0o755); } catch { /* non-critical */ }
       }
     }
@@ -550,14 +559,6 @@ export async function installGlobalStatusline(hooksSourceDir, globalClaudeDirOve
 
   // Register statusLine in ~/.claude/settings.json (global user settings)
   const settingsPath = join(globalDir, 'settings.json');
-  let settings = {};
-  if (existsSync(settingsPath)) {
-    try {
-      settings = JSON.parse(await readFile(settingsPath, 'utf-8'));
-    } catch {
-      settings = {};
-    }
-  }
 
   // On Windows, Claude Code cannot execute .sh files directly — call Python instead.
   const statuslineCommand = process.platform === 'win32'
@@ -569,14 +570,16 @@ export async function installGlobalStatusline(hooksSourceDir, globalClaudeDirOve
   // `↻` countdown to the 5h rate-limit reset — the only widget that moves on
   // its own — sits frozen through a long turn. Everything else is event-driven
   // and would be fine without this.
-  settings.statusLine = {
-    type: 'command',
-    command: statuslineCommand,
-    padding: 2,
-    refreshInterval: 10
-  };
-
-  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+  // Fusão rasa: só `statusLine` é do morph-spec; tudo o mais no
+  // `~/.claude/settings.json` é do usuário e sobrevive intocado.
+  fx.mergeJson(settingsPath, {
+    statusLine: {
+      type: 'command',
+      command: statuslineCommand,
+      padding: 2,
+      refreshInterval: 10
+    }
+  });
   return { installed: true, globalDir };
 }
 

package/src/utils/skills-installer.js

@@ -14,10 +14,11 @@
  * execute scripts and load references on demand.
  */
 
-import { mkdirSync, copyFileSync, existsSync, readdirSync, statSync, readFileSync, rmSync } from 'fs';
-import { join } from 'path';
+import { existsSync, readdirSync, statSync, readFileSync } from 'fs';
+import { basename, join } from 'path';
 import { fileURLToPath } from 'url';
 import { parseStacks, shouldInstall } from '../lib/stack-filter.js';
+import { realEffects } from '../lib/installers/effects.js';
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 const FRAMEWORK_SKILLS_DIR = join(__dirname, '..', '..', 'framework', 'skills');
@@ -39,24 +40,17 @@ export function shouldInstallSkill(skillContent, projectTags) {
 }
 
 /**
- * Recursively copy a directory tree from src to dest.
- * Creates dest if it doesn't exist. Skips README.md files.
+ * Copy a skill directory tree from src to dest, skipping README.md files.
+ *
+ * UM efeito por skill (não um por arquivo): é assim que o instalador pensa
+ * ("instalar a skill X"), e é o que o relatório do `--dry-run` precisa dizer.
  *
  * @param {string} src - Source directory path
  * @param {string} dest - Destination directory path
+ * @param {ReturnType<import('../lib/installers/effects.js').createEffects>} fx
  */
-function copyDirectory(src, dest) {
-  mkdirSync(dest, { recursive: true });
-  for (const entry of readdirSync(src)) {
-    if (entry === 'README.md') continue;
-    const srcPath = join(src, entry);
-    const destPath = join(dest, entry);
-    if (statSync(srcPath).isDirectory()) {
-      copyDirectory(srcPath, destPath);
-    } else {
-      copyFileSync(srcPath, destPath);
-    }
-  }
+function copySkillDirectory(src, dest, fx) {
+  fx.copyDir(src, dest, { filter: (from) => basename(from) !== 'README.md' });
 }
 
 /**
@@ -82,7 +76,7 @@ function copyDirectory(src, dest) {
  *   previous run with different projectTags", which is exactly the stale
  *   entry a stack change needs cleaned up.
  */
-function installSkillsFromDir(srcDir, destDir, projectTags, installedNow) {
+function installSkillsFromDir(srcDir, destDir, projectTags, installedNow, fx) {
   const entries = readdirSync(srcDir);
   for (const entry of entries) {
     const srcPath = join(srcDir, entry);
@@ -91,15 +85,17 @@ function installSkillsFromDir(srcDir, destDir, projectTags, installedNow) {
     if (stat.isDirectory()) {
       const skillMdPath = join(srcPath, 'SKILL.md');
       if (existsSync(skillMdPath)) {
-        // Directory-based skill — check stack filter before copying
+        // Directory-based skill — check stack filter before copying.
+        // O filtro é PURO e continua sendo o único: previsão e execução
+        // percorrem esta mesma linha.
         const content = readFileSync(skillMdPath, 'utf-8');
         if (!shouldInstallSkill(content, projectTags)) continue;
         const skillDestDir = join(destDir, entry);
-        copyDirectory(srcPath, skillDestDir);
+        copySkillDirectory(srcPath, skillDestDir, fx);
         installedNow.add(entry);
       } else {
         // Level/category directory — recurse
-        installSkillsFromDir(srcPath, destDir, projectTags, installedNow);
+        installSkillsFromDir(srcPath, destDir, projectTags, installedNow, fx);
       }
     } else if (entry.endsWith('.md') && entry !== 'README.md') {
       // Legacy flat .md skill — check stack filter before copying
@@ -107,8 +103,8 @@ function installSkillsFromDir(srcDir, destDir, projectTags, installedNow) {
       if (!shouldInstallSkill(content, projectTags)) continue;
       const skillName = entry.slice(0, -3);
       const skillDir = join(destDir, skillName);
-      mkdirSync(skillDir, { recursive: true });
-      copyFileSync(srcPath, join(skillDir, 'SKILL.md'));
+      fx.ensureDir(skillDir);
+      fx.copyFile(srcPath, join(skillDir, 'SKILL.md'));
       installedNow.add(skillName);
     }
   }
@@ -150,10 +146,12 @@ function collectNamesFromDir(dir, names) {
  * @param {string} projectDir - Target project root directory
  * @param {Object} [options]
  * @param {string[]} [options.projectTags=[]] - Stack tags from config
+ * @param {ReturnType<import('../lib/installers/effects.js').createEffects>} [options.fx]
+ *   Coletor de efeitos; o default executa e registra numa lista descartada.
  */
-export async function installSkills(projectDir, { projectTags = [] } = {}) {
+export async function installSkills(projectDir, { projectTags = [], fx = realEffects() } = {}) {
   const claudeSkillsDir = join(projectDir, '.claude', 'skills');
-  mkdirSync(claudeSkillsDir, { recursive: true });
+  fx.ensureDir(claudeSkillsDir);
 
   // Skill names this call actually (re)installs, given projectTags. Tracked
   // as we go (NOT by re-scanning claudeSkillsDir afterwards) — a disk scan
@@ -164,7 +162,7 @@ export async function installSkills(projectDir, { projectTags = [] } = {}) {
   for (const level of SKILL_LEVELS_TO_INSTALL) {
     const levelDir = join(FRAMEWORK_SKILLS_DIR, level);
     if (!existsSync(levelDir)) continue;
-    installSkillsFromDir(levelDir, claudeSkillsDir, projectTags, installedNow);
+    installSkillsFromDir(levelDir, claudeSkillsDir, projectTags, installedNow, fx);
   }
 
   // Clean-slate: remove any skill dir that is a KNOWN framework skill (still
@@ -176,10 +174,19 @@ export async function installSkills(projectDir, { projectTags = [] } = {}) {
   // `umbraco` in the stack, drop the stack later, and they'd survive every
   // reinstall/update forever. Names outside allSourceSkills (user-added,
   // non-framework skills) are never touched.
-  const allSourceSkills = collectSourceSkillNames();
-  for (const entry of readdirSync(claudeSkillsDir)) {
-    if (!installedNow.has(entry) && allSourceSkills.has(entry)) {
-      rmSync(join(claudeSkillsDir, entry), { recursive: true, force: true });
+  //
+  // Em `dryRun` este laço NÃO emite nada, e a razão está na D6: numa execução
+  // real do `update` ele sempre vê um diretório VAZIO, porque
+  // `cleanFrameworkDirs()` acabou de apagar `.claude/skills/` inteiro. Num dry
+  // ingênuo nada foi apagado, ele veria o diretório POPULADO, e o relatório
+  // preveria remoções que a execução real nunca faz — errado na direção que
+  // assusta o usuário. O clean subsome este laço, provadamente.
+  if (!fx.dryRun) {
+    const allSourceSkills = collectSourceSkillNames();
+    for (const entry of readdirSync(claudeSkillsDir)) {
+      if (!installedNow.has(entry) && allSourceSkills.has(entry)) {
+        fx.remove(join(claudeSkillsDir, entry));
+      }
     }
   }
 

package/src/utils/version-checker.js

@@ -1,7 +1,8 @@
 import { readFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { pathExists, readJson, writeJson } from './file-copier.js';
+import { pathExists, readJson } from './file-copier.js';
+import { realEffects } from '../lib/installers/effects.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -58,14 +59,14 @@ export async function getProjectMorphVersion(projectPath) {
  * @param {string} version - Version to save
  * @returns {Promise<void>}
  */
-export async function saveProjectMorphVersion(projectPath, version) {
+export async function saveProjectMorphVersion(projectPath, version, fx = realEffects()) {
   const versionPath = join(projectPath, '.morph', '.morphversion');
   const versionInfo = {
     morphVersion: version,
     installedAt: new Date().toISOString(),
     cliVersion: version
   };
-  await writeJson(versionPath, versionInfo);
+  fx.writeJson(versionPath, versionInfo);
 }
 
 /**
@@ -91,6 +92,70 @@ export function compareVersions(v1, v2) {
   return 0;
 }
 
+/**
+ * Major de uma versão, ou `null` quando a string não permite decidir.
+ *
+ * Vive aqui, ao lado de `compareVersions`, de propósito: uma segunda
+ * aritmética de versão noutro arquivo é exatamente como duas verdades sobre a
+ * mesma versão nascem.
+ *
+ * @param {string|null|undefined} version
+ * @returns {number|null}
+ */
+export function majorOf(version) {
+  if (typeof version !== 'string') return null;
+  const m = /^\s*v?(\d+)\./.exec(version) ?? /^\s*v?(\d+)\s*$/.exec(version);
+  return m ? Number(m[1]) : null;
+}
+
+/**
+ * Limiar do freio: um salto de DOIS majors ou mais recusa sem `--force`.
+ *
+ * O limiar não é "quantos majors dá para pular com segurança" — é "a partir de
+ * onde o usuário merece ler o relatório antes". Medido: um projeto em 7.x indo
+ * para 9.x recusa; um em 8.x atualiza sem atrito.
+ */
+export const MAJOR_JUMP_LIMIT = 2;
+
+/**
+ * Avalia o salto entre a versão instalada no projeto e a versão de destino.
+ *
+ * Três resultados, e a diferença entre eles é o que a mensagem tem de dizer:
+ *
+ * - `reason: 'unknown-installed'` — a versão instalada é indeterminável.
+ *   Tratada como salto grande, com motivo PRÓPRIO: "não sei quão velho isto é"
+ *   é precisamente quando sobrescrever às cegas é mais perigoso, e tratá-la
+ *   como zero seria a única leitura que libera o pior caso.
+ * - `reason: 'major-jump'` — salto medido de `jump` majors, >= ao limiar.
+ * - `reason: null` — sem freio (mesmo major, um só major de diferença, ou
+ *   destino não superior à instalada).
+ *
+ * @param {string|null} installedVersion
+ * @param {string|null} targetVersion
+ * @param {{ limit?: number }} [options]
+ * @returns {{ refuse: boolean, reason: 'unknown-installed'|'major-jump'|null, jump: number|null }}
+ */
+export function majorJump(installedVersion, targetVersion, { limit = MAJOR_JUMP_LIMIT } = {}) {
+  const installedMajor = majorOf(installedVersion);
+  const targetMajor = majorOf(targetVersion);
+
+  if (installedMajor === null) {
+    return { refuse: true, reason: 'unknown-installed', jump: null };
+  }
+  if (targetMajor === null) {
+    // Sem destino legível não há salto a medir — e inventar um seria decidir
+    // por um número que ninguém mantém.
+    return { refuse: false, reason: null, jump: null };
+  }
+  if (compareVersions(installedVersion, targetVersion) >= 0) {
+    return { refuse: false, reason: null, jump: 0 };
+  }
+
+  const jump = targetMajor - installedMajor;
+  if (jump >= limit) return { refuse: true, reason: 'major-jump', jump };
+  return { refuse: false, reason: null, jump };
+}
+
 /**
  * Detect how the CLI was installed
  * @returns {'global'|'npx'|'unknown'}

package/framework/standards/ai-agents/prompts-in-db.md

@@ -1,214 +0,0 @@
-# Prompts in DB — Editable, versioned agent instructions
-
-> **Scope:** stacks=["dotnet"]
-> **Layer:** 1 (on-keyword)
-> **Keywords:** prompts in db, agent prompts, prompt versioning, prompt hot-reload, editable instructions, prompt management
-> **Read by Claude in:** implement (when an agent's instructions should be runtime-editable)
-
-**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
-
----
-
-## Por que prompts no DB
-
-Hardcoded instructions in source code mean every prompt tweak requires a full build and deploy cycle. With prompts in the database the team can tune agent behavior without touching code, pushing a commit, or triggering CI.
-
-Key benefits:
-
-| Benefit | Explanation |
-|---------|-------------|
-| **No deploy to tune** | Product/ML team edits prompts via a backoffice or SQL — the agent picks up the change on next load |
-| **Versioning and rollback** | Every version is kept as an immutable row; rollback = flip `is_active` |
-| **A/B testing** | Two rows for the same `agent_key`, activate one; compare metrics; flip back if needed |
-| **Audit trail** | `created_at` per version gives a full timeline of what prompt was active when |
-
-The agent receives its `instructions:` value from the repository at construction time — not from a string literal in code.
-
----
-
-## O pattern
-
-```
-┌─────────────────┐       ┌──────────────────┐       ┌──────────────────────┐
-│  Agent Handler  │──────▶│ PromptRepository │──────▶│  agent_prompts table │
-│  (constructs    │       │ (IMemoryCache    │       │  (PostgreSQL)        │
-│   AIAgent)      │◀──────│  TTL: 5 min)     │◀──────│                      │
-└─────────────────┘       └──────────────────┘       └──────────────────────┘
-```
-
-1. The handler (or DI factory) calls `IPromptRepository.GetActivePromptAsync(agentKey, ct)`.
-2. `PromptRepository` checks `IMemoryCache`. On a hit, returns the cached string. On a miss, queries the DB for the single row where `agent_key = @key AND is_active = true`, caches it with a short TTL (e.g. 5 minutes), and returns it.
-3. The handler constructs the agent: `chatClient.AsAIAgent(instructions: prompt, name: "MyAgent")`.
-4. **Agents are cheap to construct** — recreate on every request (or per scoped lifetime). Do NOT attempt to mutate a running agent's instructions.
-
----
-
-## Schema da tabela
-
-The `agent_prompts` table stores one row per prompt version. See the full migration in:
-
-```
-templates/code/sql/ai-agents/agent-prompts-migration.sql.template
-```
-
-Column summary:
-
-| Column | Type | Notes |
-|--------|------|-------|
-| `id` | `uuid` | PK, `gen_random_uuid()` |
-| `agent_key` | `text NOT NULL` | Logical identifier, e.g. `"proposal-agent"` |
-| `version` | `int NOT NULL` | Monotonically increasing per `agent_key` |
-| `content` | `text NOT NULL` | The full system-prompt text |
-| `is_active` | `boolean NOT NULL DEFAULT false` | Only one row active per `agent_key` |
-| `created_at` | `timestamptz NOT NULL DEFAULT now()` | Immutable audit timestamp |
-
-### Unique-partial-index trick
-
-```sql
-CREATE UNIQUE INDEX ix_agent_prompts_active
-    ON {{SCHEMA}}.agent_prompts (agent_key)
-    WHERE is_active;
-```
-
-This index enforces at the database level that only one row per `agent_key` can have `is_active = true`. An attempt to activate a second row for the same key will fail with a unique-constraint violation — no application logic needed to guard this invariant.
-
----
-
-## O repository
-
-Reference implementation:
-
-```
-templates/code/dotnet/ai-agents/PromptRepository.cs.template
-```
-
-Interface contract:
-
-```csharp
-public interface IPromptRepository
-{
-    /// <summary>
-    /// Returns the content of the currently active prompt for the given agent key.
-    /// Throws <see cref="InvalidOperationException"/> if no active prompt exists.
-    /// </summary>
-    Task<string> GetActivePromptAsync(string agentKey, CancellationToken ct = default);
-}
-```
-
-The concrete `PromptRepository`:
-
-- Receives `DbContext` and `IMemoryCache` via primary constructor.
-- Uses a cache key of `$"agent_prompt:{agentKey}"` with a sliding expiration of 5 minutes.
-- On a cache miss, queries `AgentPrompts.Where(p => p.AgentKey == agentKey && p.IsActive)` via EF Core.
-- Throws `InvalidOperationException($"No active prompt found for agent '{agentKey}'.")` when no row matches — fail fast so misconfiguration is immediately visible.
-- Does NOT catch DB exceptions — let the caller decide how to handle transient failures.
-
-DI registration (in `Program.cs` or a bootstrap extension):
-
-```csharp
-builder.Services.AddMemoryCache();
-builder.Services.AddScoped<IPromptRepository, PromptRepository>();
-```
-
----
-
-## Integração com o agente
-
-### Scoped construction (recommended)
-
-```csharp
-public sealed class ProposalAgentHandler(
-    IPromptRepository promptRepo,
-    ModelRegistry modelRegistry)
-{
-    public async Task<string> RunAsync(string userMessage, CancellationToken ct)
-    {
-        var prompt = await promptRepo.GetActivePromptAsync("proposal-agent", ct);
-
-        var agent = modelRegistry
-            .GetChatClient("text-default")
-            .AsAIAgent(instructions: prompt, name: "ProposalAgent");
-
-        var response = await agent.RunAsync(userMessage, ct);
-        return response.Text;
-    }
-}
-```
-
-### Hot-reload semantics
-
-When a new prompt is saved with `is_active = true`:
-
-1. The old active row is set to `is_active = false` (see §Versionamento).
-2. The cache entry expires within the configured TTL (5 min by default).
-3. The next agent construction after expiry picks up the new prompt automatically.
-
-**Do NOT mutate a running agent.** Agents are lightweight value-like objects in MAF — recreate on each scoped lifetime instead of attempting to patch `instructions` on a live instance.
-
-### Keyed singleton (long-lived, explicit refresh)
-
-For agents registered as keyed singletons (e.g. via `builder.AddAIAgent`), hot-reload requires explicit invalidation. In that pattern, call `IMemoryCache.Remove($"agent_prompt:{key}")` from an admin endpoint or background job after saving a new version, then recreate the agent in the factory. This is more complex; prefer scoped construction unless the agent carries expensive state (e.g. an embedded tool pipeline that is costly to rebuild).
-
----
-
-## Versionamento
-
-**Rule: never UPDATE the `content` column.** The content of a prompt row is immutable once written.
-
-To release a new prompt version:
-
-```sql
--- 1. Deactivate the current active version
-UPDATE {{SCHEMA}}.agent_prompts
-   SET is_active = false
- WHERE agent_key = 'proposal-agent' AND is_active = true;
-
--- 2. Insert the new version (version = previous max + 1)
-INSERT INTO {{SCHEMA}}.agent_prompts (agent_key, version, content, is_active)
-VALUES (
-    'proposal-agent',
-    (SELECT COALESCE(MAX(version), 0) + 1 FROM {{SCHEMA}}.agent_prompts WHERE agent_key = 'proposal-agent'),
-    'Your new system prompt text here...',
-    true
-);
-```
-
-This keeps a complete, auditable history. Rollback = deactivate the current row and reactivate any previous row.
-
----
-
-## Anti-patterns
-
-| Anti-pattern | Por quê é problema | Solução |
-|---|---|---|
-| Hardcoded prompt string in production code | Every tune requires a build + deploy | Move to `agent_prompts` table |
-| `UPDATE agent_prompts SET content = '...'` without a version | Destroys history; no rollback | INSERT new row with version+1, flip `is_active` |
-| No cache — DB query on every agent invocation | High latency + DB load under traffic | Use `IMemoryCache` with a short TTL |
-| `appsettings.json` prompts | Still requires a deploy to change; no versioning | Move to DB or environment-variable-agnostic store |
-| Single global `IMemoryCache` key collisions | Two agents with similar keys overwrite each other | Always prefix: `$"agent_prompt:{agentKey}"` |
-| Activating a new row without deactivating the old one | Two active rows for the same key — undefined behavior | The partial unique index prevents this at DB level; always deactivate first in app code |
-
----
-
-## Checklist (verifiable by morph-eval)
-
-- [ ] `agent_prompts` table exists with all required columns (`id`, `agent_key`, `version`, `content`, `is_active`, `created_at`)
-- [ ] Unique partial index `ix_agent_prompts_active` on `(agent_key) WHERE is_active` is present
-- [ ] `IPromptRepository` registered in DI (`AddScoped`)
-- [ ] `IMemoryCache` registered (`builder.Services.AddMemoryCache()`)
-- [ ] No prompt string literals in production agent construction code
-- [ ] `GetActivePromptAsync` throws `InvalidOperationException` (not returns null) when no active prompt found
-- [ ] Versionamento pattern followed: INSERT + flip, never UPDATE content
-- [ ] At least one seed row per `agent_key` in migrations or seed script
-
----
-
-## References
-
-- `ai-agents-setup` — how to construct an `AIAgent` via `AsAIAgent(instructions:)`
-- `ai-agents-providers-model-registry` — how to obtain the `IChatClient` from the Model Registry
-- `backend-database-postgresql-database` — naming conventions, timestamptz, uuid PKs, partial indexes
-
----
-
-*MORPH-SPEC by Polymorphism Tech — ai-agents/prompts-in-db.md v1.0 (2026-05-19)*