@polymorphism-tech/morph-spec 9.8.0 → 10.1.1

package/framework/standards/PROVENANCE.json

@@ -1,119 +0,0 @@
-{
-  "version": "1.0.0",
-  "_note": "Standards distilled from an external source. The source is not a dependency at runtime: it lives in another repository and is not needed to use the framework. The same mechanism covers content distilled into a SKILL — an entry declares `standards`, `skills`, or both, and every declared name must resolve. This file exists so drift is detectable instead of silent. Pin `sourceTree` when distilling, and re-pin deliberately after reviewing what changed. See test/framework/standards-provenance.test.js.",
-  "sources": [
-    {
-      "id": "morph-lp-cinematic",
-      "repo": "morph-HUB",
-      "path": "skills/morph-lp-cinematic",
-      "envVar": "MORPH_HUB",
-      "defaultCheckout": "R:/Polymorphism Tech/repos/morph-HUB",
-      "sourceTree": "2987b44241cae479b1aedc63f689cdcd6ef6fb94",
-      "sourceCommit": "c4c9164",
-      "distilledOn": "2026-08-21",
-      "distilledFrom": [
-        "references/build-stack.md",
-        "references/component-recipes.md",
-        "references/premium-finish.md",
-        "references/seo-and-qa.md",
-        "references/image-prompt.md",
-        "references/seedance-scrub-prompt.md",
-        "references/seedance-loop-prompt.md"
-      ],
-      "notDistilled": [
-        "references/last-mile.md",
-        "references/copy-and-messaging.md",
-        "references/section-blueprint.md"
-      ],
-      "notDistilledReason": "Deliberate split: a standard carries knowledge, a skill carries process. Deploy and copy strategy stay with the skill. `references/gates.md` LEFT this list on 2026-09-09: the reason that kept it out was \"a skill carries process\", and the destination is now a skill — see the \"cinematic-lp\" source below, which distils it into morph-media. Review of 2026-09-29 (source c4c9164): only tool-independent facts were ported (the scrub_frames manifest contract for frame-scrub, chained clips for ai-video-generation); the rest was already in the standards or stays with the skill (ffmpeg-to-media_tool swaps, model prices, SKILL.md, gates.md, assets/).",
-      "standards": [
-        "frontend-scroll-driven-frame-scrub",
-        "frontend-scroll-driven-smooth-scroll",
-        "frontend-scroll-driven-scroll-components",
-        "frontend-design-system-premium-finish",
-        "frontend-design-system-ai-image-generation",
-        "frontend-design-system-ai-video-generation",
-        "frontend-seo-meta-schema-audit"
-      ],
-      "skills": []
-    },
-    {
-      "id": "morph-image",
-      "repo": "morph-HUB",
-      "path": "skills/morph-image",
-      "envVar": "MORPH_HUB",
-      "defaultCheckout": "R:/Polymorphism Tech/repos/morph-HUB",
-      "sourceTree": "e55dcf307278583120601c3c5d55118302335f7b",
-      "sourceCommit": "c4c9164",
-      "distilledOn": "2026-09-09",
-      "distilledFrom": [
-        "SKILL.md"
-      ],
-      "notDistilled": [
-        "skill.json",
-        "evals/"
-      ],
-      "notDistilledReason": "Manifest and eval fixtures of the source skill: packaging of the origin, not knowledge. The MCP tool names of the source were also NOT carried over — morph-media is about the authoring decisions, and a tool table pinned to one MCP server would rot on its own.",
-      "standards": [],
-      "skills": [
-        "morph-media"
-      ]
-    },
-    {
-      "id": "cinematic-lp",
-      "repo": "morph-HUB",
-      "path": "skills/cinematic-lp/references",
-      "envVar": "MORPH_HUB",
-      "defaultCheckout": "R:/Polymorphism Tech/repos/morph-HUB",
-      "sourceTree": "3c557425d649ed477bf6645b9297b6d1d72ae4a3",
-      "sourceCommit": "c4c9164",
-      "distilledOn": "2026-09-09",
-      "distilledFrom": [
-        "gates.md"
-      ],
-      "notDistilled": [
-        "build-stack.md",
-        "component-recipes.md",
-        "copy-and-messaging.md",
-        "image-prompt.md",
-        "last-mile.md",
-        "mcp-setup.md",
-        "premium-finish.md",
-        "section-blueprint.md",
-        "seo-and-qa.md",
-        "video-loop-examples.md",
-        "video-loop-prompt.md",
-        "video-scrub-prompt.md"
-      ],
-      "notDistilledReason": "Only the HITL gate mechanics were distilled: the N-option picker, \"rejection goes back to the same step\", and \"show MOVEMENT, never a still\". The rest is either already a standard (the frame-scrub / smooth-scroll / premium-finish family, from the morph-lp-cinematic source above) or build/deploy strategy that belongs to the calling workflow. Review of 2026-09-29 (source c4c9164): gates.md did not change; the changes were in image-prompt.md and mcp-setup.md, both not distilled. Re-pinned only.",
-      "standards": [],
-      "skills": [
-        "morph-media"
-      ]
-    },
-    {
-      "id": "brand-design",
-      "repo": "morph-HUB",
-      "path": "skills/brand-design/references",
-      "envVar": "MORPH_HUB",
-      "defaultCheckout": "R:/Polymorphism Tech/repos/morph-HUB",
-      "sourceTree": "7b637a08e931d8b7ba5be7fc75b851d89cd6e6f4",
-      "sourceCommit": "c4c9164",
-      "distilledOn": "2026-09-09",
-      "distilledFrom": [
-        "image-generation.md"
-      ],
-      "notDistilled": [
-        "brand-book.md",
-        "checklist.md",
-        "example-identidade-visual.md",
-        "phases.md"
-      ],
-      "notDistilledReason": "Only the image-per-phase map and the \"concept, never the final vector\" rule were distilled. The narrative prompt recipes were NOT copied verbatim: they are bound to one brand pipeline, and morph-media carries the prompt STRUCTURE instead, which survives the model changing. Brand book, checklist and phases are the process of another skill. Review of 2026-09-29 (source c4c9164): the image-per-phase table and the \"concept, never the final vector\" rule are unchanged (the text now says \"image model\" instead of Gemini); what was added is morph-assets call mechanics (project_set, @brand, outputPath, models, variants, dryRun), tool-bound and kept out on purpose. Re-pinned only.",
-      "standards": [],
-      "skills": [
-        "morph-media"
-      ]
-    }
-  ]
-}

package/framework/standards/infrastructure/neon/neon-pgrag.md

@@ -1,243 +0,0 @@
-# Neon pgrag Standard
-
-> **Scope:** neon
-> **Layer:** 2 (on keyword)
-> **Keywords:** pgrag, rag, chunking, embedding, reranking, retrieval
-> **Load When:** pgrag or in-database RAG keywords detected
-
-**Verified against:** Neon pgrag (`rag` extension family — experimental, see Core Rules). Last-verified: 2026-05-20.
-
----
-
-Stack: Neon Serverless Postgres
-
-## Core Rules
-
-- pgrag is EXPERIMENTAL -- API may change between Neon releases
-- ALWAYS enable unstable extensions before installing: `SET neon.allow_unstable_extensions='true'`
-- Use pgrag for simple, self-contained RAG pipelines (PDF ingestion, chunking, search)
-- Use application-level custom RAG (a typed MAF tool over pgvector — see standard ai-agents-rag-custom-pgvector) for complex workflows requiring custom logic, multi-model orchestration, or .NET integration
-- NEVER use pgrag local embeddings (384 dims) when your application uses a different embedding model -- dimension mismatch breaks search
-
-## Install pgrag
-
-```sql
--- Enable unstable extensions (required)
-SET neon.allow_unstable_extensions='true';
-
--- Core extension
-CREATE EXTENSION IF NOT EXISTS rag CASCADE;
-
--- Local embedding model (bge-small-en-v1.5, 384 dimensions, 33M params)
-CREATE EXTENSION IF NOT EXISTS rag_bge_small_en_v15 CASCADE;
-
--- Local reranker (jina-reranker-v1-tiny-en, 33M params)
-CREATE EXTENSION IF NOT EXISTS rag_jina_reranker_v1_tiny_en CASCADE;
-```
-
-## Text Extraction
-
-Extract text from binary documents directly in SQL:
-
-```sql
--- Extract text from PDF
-SELECT rag.text_from_pdf(pg_read_binary_file('/path/to/document.pdf'));
-
--- Extract text from DOCX
-SELECT rag.text_from_docx(pg_read_binary_file('/path/to/document.docx'));
-
--- Convert HTML to Markdown
-SELECT rag.markdown_from_html('<h1>Title</h1><p>Content here</p>');
-```
-
-### From a Documents Table
-
-```sql
-CREATE TABLE raw_documents (
-  id SERIAL PRIMARY KEY,
-  filename TEXT NOT NULL,
-  content BYTEA NOT NULL,
-  extracted_text TEXT
-);
-
--- Extract text on insert
-UPDATE raw_documents
-SET extracted_text = rag.text_from_pdf(content)
-WHERE filename LIKE '%.pdf' AND extracted_text IS NULL;
-```
-
-## Chunking Strategies
-
-### Character-Based Chunking
-
-Splits text by character count with overlap for context continuity:
-
-```sql
--- Split into chunks of 1000 chars with 200 char overlap
-SELECT unnest(
-  rag.chunks_by_character_count(
-    'Your long document text here...',
-    1000,   -- max_chars per chunk
-    200     -- overlap chars
-  )
-);
-```
-
-### Token-Based Chunking
-
-Uses the bge-small-en-v1.5 tokenizer for model-aware splitting:
-
-```sql
--- Split into chunks of 512 tokens with 50 token overlap
-SELECT unnest(
-  rag_bge_small_en_v15.chunks_by_token_count(
-    'Your long document text here...',
-    512,    -- max_tokens per chunk
-    50      -- overlap tokens
-  )
-);
-```
-
-## Embedding Generation
-
-### Local Embeddings (bge-small-en-v1.5)
-
-Zero-cost, runs on the database server. Produces 384-dimension vectors:
-
-```sql
--- Embedding for a document passage (includes "passage:" prefix internally)
-SELECT rag_bge_small_en_v15.embedding_for_passage('Neon is a serverless Postgres platform');
-
--- Embedding for a search query (includes "query:" prefix internally)
-SELECT rag_bge_small_en_v15.embedding_for_query('What is Neon?');
-```
-
-### OpenAI Embeddings (text-embedding-3-small)
-
-Remote API call, produces 1536-dimension vectors:
-
-```sql
--- Set API key (per session)
-SET neon.ai_api_key = 'sk-...';
-
--- Generate embedding via OpenAI
-SELECT rag.openai_text_embedding_3_small('Neon is a serverless Postgres platform');
-```
-
-## Full RAG Pipeline Example
-
-```sql
--- 1. Create chunks table
-CREATE TABLE chunks (
-  id SERIAL PRIMARY KEY,
-  document_id INT REFERENCES raw_documents(id),
-  chunk_text TEXT NOT NULL,
-  embedding vector(384)
-);
-
--- 2. Chunk and embed a document
-WITH doc AS (
-  SELECT id, rag.text_from_pdf(content) AS full_text
-  FROM raw_documents WHERE id = 1
-),
-chunked AS (
-  SELECT doc.id AS document_id, unnest(
-    rag.chunks_by_character_count(doc.full_text, 1000, 200)
-  ) AS chunk_text
-  FROM doc
-)
-INSERT INTO chunks (document_id, chunk_text, embedding)
-SELECT document_id, chunk_text,
-  rag_bge_small_en_v15.embedding_for_passage(chunk_text)
-FROM chunked;
-
--- 3. Create HNSW index
-CREATE INDEX idx_chunks_embedding ON chunks
-  USING hnsw (embedding vector_cosine_ops) WITH (m = 16, ef_construction = 64);
-```
-
-## Similarity Search
-
-```sql
--- Find top 10 similar chunks
-SELECT id, chunk_text,
-  1 - (embedding <=> rag_bge_small_en_v15.embedding_for_query('What is Neon?')) AS similarity
-FROM chunks
-ORDER BY embedding <=> rag_bge_small_en_v15.embedding_for_query('What is Neon?')
-LIMIT 10;
-```
-
-## Reranking
-
-Reranking refines initial vector search results using a cross-encoder model for higher accuracy:
-
-```sql
--- Rerank top 10 vector results down to top 5
-WITH vector_matches AS (
-  SELECT id, chunk_text,
-    1 - (embedding <=> rag_bge_small_en_v15.embedding_for_query('What is Neon?')) AS similarity
-  FROM chunks
-  ORDER BY embedding <=> rag_bge_small_en_v15.embedding_for_query('What is Neon?')
-  LIMIT 10
-)
-SELECT id, chunk_text, similarity,
-  rag_jina_reranker_v1_tiny_en.rerank_distance('What is Neon?', chunk_text) AS rerank_score
-FROM vector_matches
-ORDER BY rerank_score ASC
-LIMIT 5;
-```
-
-## LLM Integration in SQL
-
-Send context + question to an LLM directly from SQL:
-
-```sql
--- Set API key
-SET neon.ai_api_key = 'sk-...';
-
--- Ask a question with retrieved context
-WITH context AS (
-  SELECT string_agg(chunk_text, E'\n---\n') AS combined_context
-  FROM (
-    SELECT chunk_text FROM chunks
-    ORDER BY embedding <=> rag_bge_small_en_v15.embedding_for_query('What is Neon?')
-    LIMIT 5
-  ) top_chunks
-)
-SELECT rag.openai_chat_completion(
-  json_build_object(
-    'model', 'gpt-4o',
-    'messages', json_build_array(
-      json_build_object('role', 'system', 'content',
-        'Answer based on the provided context. If unsure, say so.'),
-      json_build_object('role', 'user', 'content',
-        format('Context:\n%s\n\nQuestion: What is Neon?', context.combined_context))
-    )
-  )
-) FROM context;
-```
-
-## When to Use pgrag vs Application-Level RAG
-
-| Factor | pgrag (In-Database) | SK + pgvector (Application) |
-|--------|---------------------|----------------------------|
-| Setup complexity | Minimal -- SQL only | Requires .NET service layer |
-| Embedding model | Local (384d) or OpenAI | Any model via SK connectors |
-| Reranking | Built-in (Jina) | Custom implementation |
-| Custom logic | Limited to SQL | Full C# flexibility |
-| Multi-model orchestration | Not supported | Native SK capability |
-| Production readiness | Experimental | Stable (SK GA) |
-| Cost | Zero for local models | API costs for remote models |
-| Best for | Prototyping, simple RAG, SQL-only environments | Production .NET applications, complex pipelines |
-
-**Recommendation:** Start with pgrag for prototyping and validation. Migrate to custom RAG (a typed MAF vector-search tool over pgvector — see ai-agents-rag-custom-pgvector) for production .NET applications that need custom retrieval logic, multi-model orchestration, or MAF agent integration.
-
-## Common Mistakes
-
-| Wrong | Right | Why |
-|-------|-------|-----|
-| Missing `neon.allow_unstable_extensions` | `SET neon.allow_unstable_extensions='true'` | pgrag won't install without it |
-| Mixing local (384d) and OpenAI (1536d) embeddings | Use one model consistently per column | Dimension mismatch breaks similarity search |
-| No HNSW index on chunks table | Create index after initial data load | Full table scan on every search |
-| Using pgrag in production without testing | Validate with representative data first | Extension is experimental, may change |
-| Storing API key in SQL scripts | Use session variables or environment config | Keys in scripts leak to version control |

package/src/commands/project/worktree-reap.js

@@ -1,34 +0,0 @@
-import chalk from 'chalk';
-import { reapAgentWorktrees } from '../../lib/worktree/agent-reaper.js';
-
-const label = (item) => item.path ?? item.branch ?? item.hex;
-
-function printReport(out) {
-  const mode = out.dryRun ? ' (simulação)' : '';
-  console.log(chalk.bold(`\nWorktrees de sub-agent${mode} — graça de ${out.graceMinutes} min\n`));
-  if (out.busy) console.log(chalk.yellow('  ⏳ outro reaper está em execução; nada foi feito\n'));
-
-  for (const item of out.wouldReap ?? []) console.log(chalk.cyan(`  → removeria: ${label(item)}`));
-  for (const item of out.reaped) console.log(chalk.green(`  ✓ removido: ${label(item)}${item.backup ? chalk.gray(` (backup: ${item.backup})`) : ''}`));
-  for (const item of out.preserved) {
-    console.log(chalk.yellow(`  ⚠ preservado: ${label(item)} — ${item.reason}${item.detail ? `: ${item.detail}` : ''}`));
-  }
-  if (out.active) console.log(chalk.gray(`  ${out.active} agente(s) ainda ativo(s), intocado(s)`));
-  const nothing = !out.reaped.length && !out.preserved.length && !out.active && !(out.wouldReap ?? []).length;
-  if (nothing && !out.busy) console.log(chalk.green('  ✓ nenhuma worktree de sub-agent sobrando'));
-  console.log();
-}
-
-export async function worktreeReapCommand(options = {}) {
-  const grace = options.grace === undefined ? undefined : Number(options.grace);
-  if (grace !== undefined && !(Number.isFinite(grace) && grace >= 0)) {
-    console.error(chalk.red(`--grace precisa ser um número de minutos >= 0 (recebi "${options.grace}")`));
-    process.exit(2);
-  }
-
-  const out = await reapAgentWorktrees(options.cwd || process.cwd(), { dryRun: options.dryRun === true, graceMinutes: grace });
-  if (options.json) console.log(JSON.stringify(out));
-  else if (out.ok) printReport(out);
-  else console.log(chalk.gray(`  fora de um repositório git — nada a fazer (${out.error})`));
-  return out;
-}

package/src/commands/state/handoff.js

@@ -1,65 +0,0 @@
-import chalk from 'chalk';
-import { buildHandoff, writeHandoff } from '../../lib/generators/handoff-generator.js';
-import { resolveFeatureTree } from '../../lib/worktree/feature-truth.js';
-
-// With a live worktree the root copy is a stale birth skeleton: build and write in the
-// owning tree (`resolveFeatureTree`) unless `--here` forces the cwd.
-export function handoffCommand(featureName, options = {}) {
-  const cwd = process.cwd();
-
-  const owner = options.here ? { source: 'cwd', tree: cwd, branch: null, worktree: null } : resolveFeatureTree(featureName, cwd);
-
-  if (owner.source === 'none') {
-    if (options.json) {
-      console.log(JSON.stringify({ error: 'feature-not-found', feature: featureName }));
-    } else {
-      console.error(chalk.red(`\n❌ Feature not found: ${featureName}\n`));
-    }
-    process.exit(1);
-  }
-
-  if (owner.source === 'branch-only') {
-    // The handoff points at files on disk; a truth materialized in no tree is refused.
-    const hint = `morph-spec worktree setup ${featureName}  (ou: git checkout ${owner.branch})`;
-    if (options.json) {
-      console.log(JSON.stringify({ error: 'feature-not-in-tree', feature: featureName, branch: owner.branch, hint }));
-    } else {
-      console.error(chalk.red(`\n❌ "${featureName}" está commitada em \`${owner.branch}\`, mas não está materializada em árvore nenhuma.`));
-      console.error(chalk.gray(`   ${hint}\n`));
-    }
-    process.exit(1);
-  }
-
-  const tree = owner.tree;
-  const result = buildHandoff(featureName, tree, { worktree: owner.worktree });
-  if (!result) {
-    if (options.json) {
-      console.log(JSON.stringify({ error: 'feature-not-found', feature: featureName, tree }));
-    } else {
-      console.error(chalk.red(`\n❌ Feature not found: ${featureName}\n`));
-    }
-    process.exit(1);
-  }
-
-  const path = writeHandoff(featureName, tree, { worktree: owner.worktree });
-  if (!path) {
-    if (options.json) {
-      console.log(JSON.stringify({ error: 'write-failed', feature: featureName, tree }));
-    } else {
-      console.error(chalk.red(`\n❌ Could not write handoff.md for ${featureName}\n`));
-    }
-    process.exit(1);
-  }
-
-  if (options.json) {
-    console.log(JSON.stringify({ path, feature: featureName, tree, source: owner.source, ...result.meta }));
-    return;
-  }
-
-  console.log(chalk.green(`\n✅ Handoff gerado: ${path}`));
-  if (tree !== cwd) {
-    console.log(chalk.yellow(`   resolvido para ${tree} — a cópia da raiz é esqueleto de nascimento, não a verdade.`));
-  }
-  console.log(chalk.gray(`   fase ${result.meta.phase} · fatias ${result.meta.slicesDone}/${result.meta.slicesTotal} · ${result.meta.generatedAt}`));
-  console.log(chalk.gray('   A próxima sessão lê este documento antes de continuar (ponteiros, não cópias).\n'));
-}