@polymorphism-tech/morph-spec 6.0.0 → 7.1.0

package/framework/templates/code/sql/ai-agents/pgvector-embeddings-migration.sql.template

@@ -0,0 +1,91 @@
+-- TEMPLATE: pgvector-embeddings-migration.sql
+-- PURPOSE: Creates the kb_embeddings table for custom RAG — chunk storage with pgvector.
+-- READS STANDARD: ai-agents-rag-custom-pgvector
+-- PLACEHOLDERS:
+--   {{SCHEMA}}  — target schema (default: public)
+-- LAST-VERIFIED: 2026-05-19
+--
+-- PREREQUISITES:
+--   - pgvector extension enabled in Neon (see infrastructure-neon-pgvector).
+--   - NpgsqlDataSourceBuilder.UseVector() called in the project's DB setup.
+--
+-- DIMENSION NOTE:
+--   embedding vector(1536) matches text-embedding-3-small (default 1536 dimensions).
+--   If the project uses a different embedding model, adjust the dimension to match.
+--   NEVER mix embedding models on a single column — vectors live in different spaces.
+
+-- ============================================================
+-- 1. EXTENSION
+-- ============================================================
+
+CREATE EXTENSION IF NOT EXISTS vector;
+
+-- ============================================================
+-- 2. TABLE
+-- ============================================================
+
+CREATE TABLE {{SCHEMA}}.kb_embeddings (
+    id          uuid         PRIMARY KEY DEFAULT gen_random_uuid(),
+    tenant_id   uuid         NOT NULL,
+    source      text         NOT NULL,   -- document identifier or source URL
+    chunk_index int          NOT NULL,   -- position of this chunk within the source document
+    content     text         NOT NULL,   -- chunk text returned to the agent as context
+    embedding   vector(1536) NOT NULL,   -- vector dimension must match embedding model
+    metadata    jsonb        NOT NULL DEFAULT '{}',
+    created_at  timestamptz  NOT NULL DEFAULT now()
+);
+
+COMMENT ON TABLE  {{SCHEMA}}.kb_embeddings               IS 'RAG knowledge base — chunk text and pgvector embeddings for semantic search.';
+COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.tenant_id     IS 'Tenant partition. Every query MUST filter on this column. Never query across tenants.';
+COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.source        IS 'Document identifier or URL. Used for citation and re-indexing detection.';
+COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.chunk_index   IS 'Zero-based position of this chunk within the source document.';
+COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.content       IS 'Chunk text returned to the agent. Plain text, no markup.';
+COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.embedding     IS 'Float vector. Dimension MUST match the embedding model declared in model-registry.json.';
+COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.metadata      IS 'Arbitrary JSON metadata (section headers, page numbers, doc type, etc.). Used for filtering.';
+
+-- ============================================================
+-- 3. INDEXES
+-- ============================================================
+
+-- HNSW index for cosine similarity — production-grade recall, no training data required.
+-- vector_cosine_ops: use <=> operator (cosine distance, ascending = most similar first).
+-- m=16, ef_construction=64 are pgvector defaults. Tune per infrastructure-neon-pgvector §HNSW Parameters.
+CREATE INDEX ix_kb_embeddings_hnsw
+    ON {{SCHEMA}}.kb_embeddings
+    USING hnsw (embedding vector_cosine_ops)
+    WITH (m = 16, ef_construction = 64);
+
+-- Index for the mandatory tenant_id filter (applied in every search query).
+CREATE INDEX ix_kb_embeddings_tenant
+    ON {{SCHEMA}}.kb_embeddings (tenant_id);
+
+-- Composite index for source-level operations (re-indexing, deletion by document).
+CREATE INDEX ix_kb_embeddings_source
+    ON {{SCHEMA}}.kb_embeddings (tenant_id, source);
+
+-- ============================================================
+-- 4. ROW-LEVEL SECURITY (multi-tenant)
+-- ============================================================
+
+-- RLS enforces tenant isolation at the database level as a second line of defence.
+-- The application already filters on tenant_id in every query; RLS is the backstop.
+--
+-- See templates/code/sql/postgresql-rls-policy.sql for the policy pattern that
+-- binds app.current_tenant_id (a session-level setting) to the RLS policy.
+--
+-- Uncomment and adapt once RLS is wired in the project:
+--
+-- ALTER TABLE {{SCHEMA}}.kb_embeddings ENABLE ROW LEVEL SECURITY;
+--
+-- CREATE POLICY kb_embeddings_tenant_isolation
+--     ON {{SCHEMA}}.kb_embeddings
+--     USING (tenant_id = current_setting('app.current_tenant_id')::uuid);
+
+-- ============================================================
+-- ROLLBACK
+-- ============================================================
+
+-- DROP INDEX IF EXISTS {{SCHEMA}}.ix_kb_embeddings_hnsw;
+-- DROP INDEX IF EXISTS {{SCHEMA}}.ix_kb_embeddings_tenant;
+-- DROP INDEX IF EXISTS {{SCHEMA}}.ix_kb_embeddings_source;
+-- DROP TABLE IF EXISTS {{SCHEMA}}.kb_embeddings CASCADE;

package/framework/templates/docs/onboarding.md

@@ -94,10 +94,10 @@ morph-spec doctor
 │   ├── context/                   # Project context & overrides
 │   └── features/{feature}/        # Feature outputs
 │       ├── 0-proposal/
-│       ├── 1-ui/
-│       ├── 2-design/
-│       ├── 4-tasks/
-│       └── 5-implement/
+│       ├── 1-design/              # optional (UI-heavy features)
+│       ├── 2-plan/
+│       ├── 3-implement/
+│       └── 4-review/
 └── .claude/
     ├── commands/                  # Slash commands
     ├── skills/                    # Workflow skills

package/framework/templates/tasks.template.json

@@ -0,0 +1,17 @@
+{
+  "version": "1.0",
+  "feature": "{{featureName}}",
+  "tasks": [
+    {
+      "id": "T1",
+      "title": "Example task title",
+      "description": "What this task accomplishes and why",
+      "dependencies": [],
+      "effort": "M",
+      "doneCriteria": "Verifiable acceptance condition stated in one sentence",
+      "status": "pending",
+      "outputs": [],
+      "group": "backend"
+    }
+  ]
+}

package/package.json

@@ -1,83 +1,89 @@
-{
-  "name": "@polymorphism-tech/morph-spec",
-  "version": "6.0.0",
-  "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
-  "keywords": [
-    "claude-code",
-    "claude",
-    "ai-coding",
-    "ai-first",
-    "spec-driven",
-    "nlh",
-    "natural-language-harness",
-    "autonomy",
-    "dotnet",
-    "dotnet10",
-    "nextjs",
-    "vsa",
-    "vertical-slice",
-    "framework",
-    "morph",
-    "polymorphism"
-  ],
-  "main": "src/index.js",
-  "bin": {
-    "morph-spec": "bin/morph-spec.js"
-  },
-  "files": [
-    "bin/",
-    "src/",
-    "framework/",
-    "claude-plugin.json",
-    "docs/QUICKSTART.md",
-    "docs/CHEATSHEET.md",
-    "README.md",
-    "LICENSE",
-    "CLAUDE.md"
-  ],
-  "type": "module",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "scripts": {
-    "start": "node bin/morph-spec.js",
-    "generate": "node scripts/generate-refs.js",
-    "test": "node --test --test-concurrency=1",
-    "test:coverage": "c8 --reporter=text --reporter=html --reporter=lcov node --test --test-concurrency=1",
-    "test:coverage:summary": "c8 --reporter=text-summary node --test --test-concurrency=1",
-    "docs": "jsdoc -c jsdoc.json",
-    "docs:watch": "jsdoc -c jsdoc.json --watch",
-    "docs:serve": "npx http-server docs/api -p 8080 -o",
-    "release": "node scripts/release.js",
-    "postinstall": "node src/scripts/global-install.js"
-  },
-  "dependencies": {
-    "chalk": "^5.3.0",
-    "commander": "^12.0.0",
-    "fs-extra": "^11.2.0",
-    "glob": "^13.0.6",
-    "handlebars": "^4.7.8",
-    "inquirer": "^9.2.0",
-    "minimatch": "^9.0.5",
-    "ora": "^8.0.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/lucasPolymorphism/morph-spec-framework.git"
-  },
-  "author": "Polymorphism Tech <contact@polymorphism.com.br>",
-  "license": "SEE LICENSE IN LICENSE",
-  "homepage": "https://polymorphism.com.br/morph-spec",
-  "bugs": {
-    "email": "support@polymorphism.com.br"
-  },
-  "private": false,
-  "publishConfig": {
-    "access": "public"
-  },
-  "devDependencies": {
-    "c8": "^11.0.0",
-    "docdash": "^2.0.2",
-    "jsdoc": "^4.0.5"
-  }
-}
+{
+  "name": "@polymorphism-tech/morph-spec",
+  "version": "7.1.0",
+  "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
+  "keywords": [
+    "claude-code",
+    "claude",
+    "ai-coding",
+    "ai-first",
+    "spec-driven",
+    "nlh",
+    "natural-language-harness",
+    "autonomy",
+    "dotnet",
+    "dotnet10",
+    "nextjs",
+    "vsa",
+    "vertical-slice",
+    "framework",
+    "morph",
+    "polymorphism"
+  ],
+  "main": "src/index.js",
+  "bin": {
+    "morph-spec": "bin/morph-spec.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "framework/",
+    "claude-plugin.json",
+    "docs/QUICKSTART.md",
+    "docs/CHEATSHEET.md",
+    "README.md",
+    "LICENSE",
+    "CLAUDE.md"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "start": "node bin/morph-spec.js",
+    "generate": "node scripts/generate-refs.js",
+    "generate:check": "node scripts/generate-refs.js --check",
+    "generate-standards": "node scripts/generate-standards-registry.js",
+    "generate-standards:check": "node scripts/generate-standards-registry.js --check",
+    "validate": "node scripts/validate-framework.js",
+    "freshness": "node scripts/check-freshness.js",
+    "verify": "npm run generate:check && npm run generate-standards:check && npm run validate && npm run freshness && npm test",
+    "test": "node scripts/run-tests.mjs",
+    "test:coverage": "c8 --reporter=text --reporter=html --reporter=lcov node scripts/run-tests.mjs",
+    "test:coverage:summary": "c8 --reporter=text-summary node scripts/run-tests.mjs",
+    "docs": "jsdoc -c jsdoc.json",
+    "docs:watch": "jsdoc -c jsdoc.json --watch",
+    "docs:serve": "npx http-server docs/api -p 8080 -o",
+    "release": "node scripts/release.js",
+    "postinstall": "node src/scripts/global-install.js"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "fs-extra": "^11.2.0",
+    "glob": "^13.0.6",
+    "handlebars": "^4.7.8",
+    "inquirer": "^9.2.0",
+    "minimatch": "^9.0.5",
+    "ora": "^8.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lucasPolymorphism/morph-spec-framework.git"
+  },
+  "author": "Polymorphism Tech <contact@polymorphism.com.br>",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://polymorphism.com.br/morph-spec",
+  "bugs": {
+    "email": "support@polymorphism.com.br"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "c8": "^11.0.0",
+    "docdash": "^2.0.2",
+    "jsdoc": "^4.0.5"
+  }
+}

package/src/commands/project/init.js

@@ -483,6 +483,19 @@ export async function initCommand(options) {
 
     logger.blank();
 
+    // Populate Claude Code persistent memory so future sessions enter contextualized
+    try {
+      const { installProjectMemory } = await import('../../lib/installers/memory-installer.js');
+      const memResult = await installProjectMemory(targetPath, {
+        projectName: config.project?.name ?? targetPath.split(/[\\/]/).pop(),
+        frameworkVersion: config.frameworkVersion ?? cliVersion,
+        stack: config.project?.stack,
+      });
+      logger.dim(`  ✓ Claude Code memory populated (${memResult.projectMemoryPath})`);
+    } catch (err) {
+      logger.dim(`  ⚠ Memory install skipped: ${err.message}`);
+    }
+
     // Suggest tutorial for first-time users
     if (integrationsCreated) {
       logger.blank();
@@ -490,6 +503,9 @@ export async function initCommand(options) {
     }
 
     logger.blank();
+    logger.warn('IMPORTANT: Restart your Claude Code session for morph-* skills to be available.');
+    logger.dim('Skills installed in .claude/skills/ are only registered at session start.');
+    logger.blank();
 
   } catch (error) {
     spinner.fail('Installation failed');

package/src/commands/validation/validate-feature.js

@@ -69,7 +69,7 @@ const PHASE_OUTPUTS = {
  */
 const PHASE_FOLDERS = {
   proposal: '0-proposal',
-  uiux: '1-ui',
+  uiux: '1-design',
   plan: '2-plan',
   implement: '3-implement',
   review: '4-review',

package/src/core/paths/output-schema.js

@@ -27,16 +27,16 @@ export const OUTPUT_SCHEMA = {
   stackScan:      { filename: 'stack-scan.md',         phaseDir: '0-proposal',  phase: 'proposal',  protected: false },
   migrationPlan:  { filename: 'migration-plan.md',     phaseDir: '0-proposal',  phase: 'proposal',  protected: false },
 
-  // 1-ui/ (optional)
-  uiDesignSystem: { filename: 'design-system.md',      phaseDir: '1-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
-  uiMockups:      { filename: 'mockups.md',            phaseDir: '1-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
-  uiComponents:   { filename: 'components.md',         phaseDir: '1-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
-  uiFlows:        { filename: 'flows.md',              phaseDir: '1-ui',        phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
+  // 1-design/ (optional)
+  uiDesignSystem: { filename: 'design-system.md',      phaseDir: '1-design',    phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
+  uiMockups:      { filename: 'mockups.md',            phaseDir: '1-design',    phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
+  uiComponents:   { filename: 'components.md',         phaseDir: '1-design',    phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
+  uiFlows:        { filename: 'flows.md',              phaseDir: '1-design',    phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
 
   // 2-plan/
   spec:           { filename: 'spec.md',               phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
   mandate:        { filename: 'mandate.md',            phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
-  tasks:          { filename: 'tasks.md',              phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
+  tasks:          { filename: 'tasks.json',            phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
   decisions:      { filename: 'decisions.md',          phaseDir: '2-plan',      phase: 'plan',      protected: false },
 
   // 3-implement/

package/src/core/state/state-manager.js

@@ -34,7 +34,7 @@ export function derivePhase(featurePath) {
     ['4-review', 'review'],
     ['3-implement', 'implement'],
     ['2-plan', 'plan'],
-    ['1-ui', 'uiux'],
+    ['1-design', 'uiux'],
     ['0-proposal', 'proposal'],
   ];
   for (const [folder, phase] of phaseMap) {