@polymorphism-tech/morph-spec 8.46.0 → 9.0.0

package/framework/templates/examples/spec-examples.md

@@ -1,91 +0,0 @@
-# Spec Template Reference
-
-> **Layer:** 3 | **Load:** on-demand | **Keywords:** spec, specification, template
-
-**The canonical template is `docs/spec.md` of the template system** (REGISTRY id `spec`),
-resolved from the installed package — see `framework/templates/README.md`.
-
-This file contains extended examples for each spec section.
-
----
-
-## Example: Entity (Pseudo-code)
-
-```csharp
-class ProcessingJob {
-  Guid Id
-  string OriginalPhotoUrl     // Azure Blob URL, max 500 chars
-  string? ProcessedPhotoUrl   // Nullable, populated after processing
-  ProcessingStatus Status     // Enum: Pending, Processing, Completed, Failed
-  DateTime CreatedAt
-  ICollection<ExecutionLog> Logs  // 1:N relationship
-}
-
-enum ProcessingStatus {
-  Pending = 0, Processing = 1, Completed = 2,  // Normal flow
-  Failed = 100                                   // Error states (high values)
-}
-```
-
-## Example: Command (Pseudo-code)
-
-```csharp
-UploadPhotoCommand {
-  Input: IFormFile photo, string? email
-  Output: Guid jobId
-
-  Handler:
-    1. Validate file (size <= 10MB, type in [.jpg, .png])
-    2. Upload to Azure Blob Storage
-    3. Create ProcessingJob entity (status = Pending)
-    4. Enqueue Hangfire background job
-    5. Return jobId
-}
-```
-
-## Example: API Endpoints
-
-```csharp
-PhotoProcessingController {
-  POST /api/upload        → multipart/form-data → { jobId: Guid }
-  GET  /api/status/{id}   → jobId → { status, progress, createdAt }
-  GET  /api/download/{id} → jobId → Redirect to Blob URL or 404
-}
-```
-
-## Example: Flow
-
-```
-Upload Flow (Actor: User)
-1. User selects photo → System validates (size, type) → If invalid: show error
-2. User sees preview → clicks "Upload"
-3. System creates ProcessingJob → uploads to Blob → enqueues Hangfire job → returns jobId
-4. System navigates to /processing/{jobId} → polls every 5s
-End State: User on progress page, job processing in background
-```
-
-## Example: ADR
-
-### ADR-001: Use Hangfire for Background Jobs
-**Status:** Accepted
-**Context:** Need background processing for AI photo transformation (30-120s).
-**Decision:** Hangfire (self-hosted).
-**Alternatives:**
-1. Azure Functions — serverless, auto-scaling, but cold start + $10/mo for 50k jobs
-2. Hangfire — zero cost, simpler, but scales with app
-3. Quartz.NET — more features, but steeper learning curve
-**Trade-offs:** Simplicity vs Features (Hangfire sufficient for MVP)
-
-## Example: Cost Estimate
-
-| Resource | SKU | Monthly | Justification |
-|----------|-----|---------|---------------|
-| Blob Storage | LRS | $0.02 | Store photos, low redundancy OK |
-| Azure SQL | Basic | $4.99 | < 100k jobs/month |
-| Container App | Consumption | $0.49 | Scale to zero |
-| Hangfire | Self-hosted | $0.00 | In-process |
-| **Total** | | **~$5.50** | |
-
----
-
-*MORPH-SPEC by Polymorphism Tech*

package/framework/templates/feature/decisions.md

@@ -1,124 +0,0 @@
-# Architecture Decision Records - {{titleCase FEATURE_NAME}}
-
-## ADR-001: {Decision Title}
-
-**Date:** {{DATE}}
-**Status:** Proposed | Accepted | Deprecated | Superseded
-**Deciders:** MORPH Agents, Developer
-**Alcance:** feature
-
-### Context
-
-{Describe the context and problem that led to this decision}
-
-### Decision
-
-{Describe the decision made}
-
-### Consequences
-
-**Pros:**
-- {Positive consequence 1}
-- {Positive consequence 2}
-
-**Cons:**
-- {Negative consequence 1}
-
-**Risks:**
-- {Identified risk}
-
-### Alternatives Considered
-
-#### Option A: {Name}
-- Pros: {advantages}
-- Cons: {disadvantages}
-- **Rejected because:** {reason}
-
-#### Option B: {Name}
-- Pros: {advantages}
-- Cons: {disadvantages}
-- **Rejected because:** {reason}
-
----
-
-{{#if (eq STACK "nextjs-neon")}}
-## ADR-002: Database Access Strategy
-
-**Date:** {{DATE}}
-**Status:** Accepted
-
-### Context
-
-Need to decide how the .NET API accesses Neon PostgreSQL.
-
-### Decision
-
-Use Dapper with Npgsql for direct SQL queries. No EF Core.
-
-### Consequences
-
-**Pros:**
-- Full control over SQL queries
-- Better performance (no ORM overhead)
-- Direct access to PostgreSQL features (jsonb, pgvector, functions)
-- RLS policies apply naturally through connection
-
-**Cons:**
-- No automatic migrations (use Neon CLI / dotnet ef instead)
-- Manual SQL query writing
-- No change tracking
-
----
-
-## ADR-003: Auth Strategy
-
-**Date:** {{DATE}}
-**Status:** Accepted
-
-### Context
-
-Need authentication for both Next.js frontend and .NET API.
-
-### Decision
-
-Use Neon Auth (Better Auth) for authentication. Auth data lives in the Neon database. JWT validated by .NET API middleware.
-
-### Consequences
-
-**Pros:**
-- Auth data in same database — no external provider, no sync delays
-- RLS policies work with Neon Auth JWT via auth.user_id() / pg_session_jwt
-- Built-in social login, email/password via @neondatabase/auth SDK
-- Branch isolation — each Neon branch gets isolated auth data
-- No webhooks needed — query neon_auth schema directly
-
-**Cons:**
-- Neon Auth is currently in Beta
-- JWT must be forwarded to .NET API for backend auth
-{{/if}}
-
----
-
-## Template for New ADRs
-
-```markdown
-## ADR-XXX: {Title}
-
-**Date:**
-**Status:** Proposed | Accepted | Deprecated | Superseded
-**Alcance:** feature | projeto — `projeto` when the rule holds beyond this feature: `morph-spec finish` copies it to `.morph/specs/adrs/`, the folder brainstorming and plan read instead of archived decisions.md
-
-### Context
-{Why is this decision needed?}
-
-### Decision
-{What was decided?}
-
-### Consequences
-**Pros:** {list}
-**Cons:** {list}
-```
-
----
-
-*Generated by MORPH Framework*

package/framework/templates/feature/recap.md

@@ -1,145 +0,0 @@
-# Feature Recap: {{titleCase FEATURE_NAME}}
-
-## Summary
-
-| Field | Value |
-|-------|-------|
-| **Feature ID** | {{FEATURE_NAME}} |
-| **Completed** | {{DATE}} |
-| **Total Tasks** | {X} |
-| **Time Spent** | {X}h |
-| **Agents Used** | {list} |
-{{#if STACK}}| **Stack** | {{STACK}} |{{/if}}
-
----
-
-## Tasks Completed
-
-| ID | Title | Category | Duration |
-|----|-------|----------|----------|
-| T001 | {title} | {{#if (eq STACK "nextjs-neon")}}Database{{else}}{category}{{/if}} | {X}min |
-| T002 | {title} | {{#if (eq STACK "nextjs-neon")}}Backend{{else}}{category}{{/if}} | {X}min |
-| T003 | {title} | {{#if (eq STACK "nextjs-neon")}}Frontend{{else}}{category}{{/if}} | {X}min |
-
----
-
-{{#if (eq STACK "nextjs-neon")}}
-## Validation Results
-
-| Validator | Status | Details |
-|-----------|--------|---------|
-| contract-compliance | Pass/Fail | {details} |
-| architecture | Pass/Fail | {details} |
-| design-system | Pass/Fail | {details} |
-| coding-standards | Pass/Fail | {details} |
-
----
-
-{{/if}}
-## What Was Delivered
-
-### Functionality
-- {Functionality 1 delivered}
-- {Functionality 2 delivered}
-- {Functionality 3 delivered}
-
-{{#if (eq STACK "nextjs-neon")}}
-### Database (Neon PostgreSQL)
-- Tables: {list}
-- RLS Policies: {count} policies
-- Migrations: {count} files
-
-### Backend API (.NET)
-- Endpoints: {count} endpoints
-- Services: {list}
-
-### Frontend (Next.js)
-- Pages: {list}
-- Components: {list}
-{{/if}}
-
----
-
-## Files Created
-
-```
-{{#if (eq STACK "nextjs-neon")}}
-migrations/{files}
-backend/src/{files}
-frontend/src/{files}
-{{else}}
-{list of created files}
-{{/if}}
-```
-
-## Files Modified
-
-```
-{list of modified files}
-```
-
----
-
-## Architecture Decisions
-
-| Decision | Rationale |
-|----------|-----------|
-| {Decision 1} | {Reason} |
-| {Decision 2} | {Reason} |
-
-See full ADRs in `decisions.md`
-
----
-
-## Test Coverage
-
-| Type | Files | Coverage |
-|------|-------|----------|
-| {{#if (eq STACK "nextjs-neon")}}Backend Unit{{else}}Unit Tests{{/if}} | {X} | {X}% |
-| {{#if (eq STACK "nextjs-neon")}}Frontend Component{{else}}Integration Tests{{/if}} | {X} | {X}% |
-
----
-
-## Lessons Learned
-
-### What Went Well
-- {Positive point 1}
-- {Positive point 2}
-
-### What Could Be Improved
-- {Improvement point 1}
-- {Improvement point 2}
-
-### Recommendations for Future
-- {Recommendation 1}
-- {Recommendation 2}
-
----
-
-## Metrics
-
-| Metric | Value |
-|--------|-------|
-| Tasks Completed | {X}/{X} |
-| Checkpoints Passed | {X} |
-{{#if (eq STACK "nextjs-neon")}}| Validation Passes | {X}/{X} |
-{{else}}| Code Reviews | {X} |
-{{/if}}| Bugs Found | {X} |
-| Bugs Fixed | {X} |
-
----
-
-## Related Resources
-
-- **Proposal:** `proposal.md`
-- **Spec:** `spec.md`
-{{#if (eq STACK "nextjs-neon")}}- **Contracts (.NET):** `contracts.cs`
-- **Contracts (TS):** `contracts.ts`
-{{else}}- **Contracts:** `contracts.cs`
-{{/if}}- **Tasks:** `tasks.json`
-- **Decisions:** `decisions.md`
-- **PR:** {link}
-
----
-
-*Generated by MORPH Framework on {{DATE}}*

package/framework/templates/project/validate.js

@@ -1,97 +0,0 @@
-#!/usr/bin/env node
-
-const validator = process.argv[2];
-const isJson = process.argv.includes('--json');
-
-if (!validator) {
-  console.error('Usage: node bin/validate.js <validator> [--json]');
-  process.exit(1);
-}
-
-const { execSync } = await import('child_process');
-const { existsSync } = await import('fs');
-const { join } = await import('path');
-
-const cwd = process.cwd();
-
-const results = {
-  validator,
-  errors: 0,
-  warnings: 0,
-  passed: true,
-  issues: [],
-};
-
-function runCommand(cmd, options = {}) {
-  try {
-    const stdout = execSync(cmd, { cwd, stdio: ['pipe', 'pipe', 'pipe'], ...options }).toString();
-    return { success: true, stdout, stderr: '' };
-  } catch (err) {
-    return {
-      success: false,
-      stdout: err.stdout?.toString() || '',
-      stderr: err.stderr?.toString() || err.message,
-    };
-  }
-}
-
-const hasFrontend = existsSync(join(cwd, 'src/frontend')) || existsSync(join(cwd, 'frontend'));
-const hasBackend  = existsSync(join(cwd, 'src/backend'))  || existsSync(join(cwd, 'backend'));
-const hasSln      = existsSync(join(cwd, 'src/backend/backend.sln')) ||
-                    existsSync(join(cwd, 'src/backend/Backend.sln'));
-
-const frontendDir = existsSync(join(cwd, 'src/frontend')) ? 'src/frontend' : 'frontend';
-const backendDir  = existsSync(join(cwd, 'src/backend'))  ? 'src/backend'  : 'backend';
-
-switch (validator) {
-  case 'architecture': {
-    if (hasBackend && hasSln) {
-      const slnFile = hasSln ? (
-        existsSync(join(cwd, 'src/backend/backend.sln')) ? 'backend.sln' : 'Backend.sln'
-      ) : '.';
-      const result = runCommand(`dotnet build ${slnFile} --no-restore -warnaserror`, { cwd: join(cwd, backendDir) });
-      if (!result.success) {
-        results.errors++;
-        results.passed = false;
-        results.issues.push({ level: 'error', message: `dotnet build failed: ${result.stderr.split('\n')[0]}` });
-      }
-    }
-    break;
-  }
-
-  case 'nextjs-component':
-  case 'packages':
-  case 'design-system': {
-    if (hasFrontend) {
-      const result = runCommand('npx tsc --noEmit', { cwd: join(cwd, frontendDir) });
-      if (!result.success) {
-        results.errors++;
-        results.passed = false;
-        results.issues.push({ level: 'error', message: `TypeScript errors found. Run: npx tsc --noEmit` });
-      }
-    }
-    break;
-  }
-
-  case 'ui-contrast':
-  case 'css': {
-    results.issues.push({ level: 'info', message: `${validator} requires manual review` });
-    break;
-  }
-
-  default:
-    results.issues.push({ level: 'warning', message: `Unknown validator: ${validator}` });
-    break;
-}
-
-if (isJson) {
-  console.log(JSON.stringify(results, null, 2));
-} else {
-  const icon = results.passed ? '✅' : '❌';
-  console.log(`${icon} Validator: ${validator} — ${results.passed ? 'PASSED' : `FAILED (${results.errors} errors)`}`);
-  for (const issue of results.issues) {
-    console.log(`  [${issue.level}] ${issue.message}`);
-  }
-}
-
-process.exit(results.passed ? 0 : 1);

package/framework/templates/tasks.template.json

@@ -1,17 +0,0 @@
-{
-  "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/src/commands/state/usecase.js

@@ -1,143 +0,0 @@
-/**
- * `morph-spec usecase reserve [--count <n>] [--feature <name>] [--json]` —
- * atomically mint the next N `UC-{nn}` numbers, shared across every worktree
- * of this repo. See `usecase-registry.js` for why this exists (worktrees only
- * ever see their own tree, so an independent max+1 scan collides).
- *
- * `--feature` is more than an audit label: `usecase-promoter.js`'s collision
- * guard uses the reservation record to tell a legitimate cross-feature
- * correction (never reserved — reusing a published number by design) from an
- * accidental collision (both features reserved the same id). Passing it is
- * how `morph-plan` gets that protection; omitting it degrades to "reserved,
- * no owner recorded" — still collision-free, just unable to name the
- * conflicting feature if one ever surfaces.
- *
- * `morph-spec usecase check <feature>` — see `usecaseCheckCommand` below.
- */
-
-import chalk from 'chalk';
-import { existsSync, readdirSync } from 'fs';
-import { join } from 'path';
-import { resolveGitCommonDir } from '../../../framework/hooks/shared/git-paths.js';
-import { reserveUseCases } from '../../lib/specs/usecase-registry.js';
-import { checkUseCases } from '../../lib/specs/usecase-check.js';
-import { checkLifecycle } from '../../lib/specs/acervo-lifecycle.js';
-import { parseTasksJsonLenient } from '../../lib/tasks/tasks-json-parser.js';
-import { isValidFeatureName } from '../project/worktree.js';
-import { printLifecycleWarnings } from '../tasks/dag.js';
-
-/**
- * Best-effort feature-name inference when `--feature` is omitted: only when
- * exactly one active feature exists is the guess unambiguous. Anything else
- * (zero, or more than one) is left null rather than guessed wrong — a wrong
- * guess would poison the collision guard's provenance record.
- */
-function inferActiveFeature(cwd) {
-  const featuresDir = join(cwd, '.morph', 'features');
-  try {
-    if (!existsSync(featuresDir)) return null;
-    const entries = readdirSync(featuresDir, { withFileTypes: true }).filter((e) => e.isDirectory());
-    return entries.length === 1 ? entries[0].name : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * @param {{ count?: string, feature?: string, json?: boolean, cwd?: string }} [options]
- */
-export function usecaseReserveCommand(options = {}) {
-  const cwd = options.cwd || process.cwd();
-  const count = Number.parseInt(options.count, 10);
-  const n = Number.isInteger(count) && count > 0 ? count : 1;
-  const feature = options.feature || inferActiveFeature(cwd) || null;
-
-  let gitCommonDir = null;
-  try { gitCommonDir = resolveGitCommonDir(cwd); } catch { gitCommonDir = null; }
-
-  let result;
-  try {
-    result = reserveUseCases(cwd, { feature, count: n, gitCommonDir });
-  } catch (error) {
-    if (options.json) {
-      console.log(JSON.stringify({ reserved: false, error: error.message }));
-      process.exit(1);
-    }
-    console.error(chalk.red(`\n❌ ${error.message}\n`));
-    process.exit(1);
-  }
-
-  const warning = gitCommonDir
-    ? null
-    : 'projeto fora de um repositório git — numeração protegida só localmente; paralelismo entre worktrees NÃO está garantido.';
-
-  if (options.json) {
-    console.log(JSON.stringify({ reserved: true, ...result, feature, warning }));
-    process.exit(0);
-  }
-
-  console.log(chalk.green(`\n✅ Reservado: ${result.numbers.join(' ')}`));
-  if (feature) console.log(chalk.gray(`   feature: ${feature}`));
-  if (warning) console.log(chalk.yellow(`⚠️  ${warning}\n`));
-  else console.log('');
-  process.exit(0);
-}
-
-/**
- * `morph-spec usecase check <feature> [--json]` — the use-case half of `dag`,
- * runnable before `tasks.json` exists: the feature's use cases and the
- * revocations its `spec.md` declares, against the acervo's lifecycle. With a
- * `tasks.json`, also the task → use case plumbing `dag` checks.
- *
- * Exit 1 only for what `dag` also refuses (a task pointing at a use case that
- * does not exist, a tasks.json that does not validate); lifecycle findings are
- * warnings.
- *
- * @param {string} feature
- * @param {{ json?: boolean, cwd?: string }} [options]
- */
-export async function usecaseCheckCommand(feature, options = {}) {
-  const cwd = options.cwd || process.cwd();
-  const fail = (error) => {
-    if (options.json) console.log(JSON.stringify({ feature, error }));
-    else console.error(chalk.red(`\n❌ ${error}\n`));
-    process.exit(1);
-  };
-
-  if (!isValidFeatureName(feature)) fail(`nome de feature inválido: "${feature}"`);
-  const featureDir = join(cwd, '.morph', 'features', feature);
-  if (!existsSync(featureDir)) fail(`feature não encontrada: .morph/features/${feature}`);
-
-  const tasksPath = join(featureDir, '2-plan', 'tasks.json');
-  let tasksData = null;
-  if (existsSync(tasksPath)) {
-    try {
-      ({ data: tasksData } = await parseTasksJsonLenient(tasksPath));
-    } catch (error) {
-      fail(`tasks.json inválido: ${error.message}`);
-    }
-  }
-
-  const useCases = tasksData ? checkUseCases(tasksData, join(featureDir, '2-plan', 'usecases')) : null;
-  const lifecycle = checkLifecycle({ cwd, featureDir, tasksData });
-  const broken = useCases?.errors.length > 0;
-
-  if (options.json) {
-    console.log(JSON.stringify({ feature, useCases, lifecycle }, null, 2));
-    process.exit(broken ? 1 : 0);
-  }
-
-  if (broken) {
-    console.error(chalk.red(`\n❌ Use cases — ${useCases.errors.length} erro(s)\n`));
-    for (const e of useCases.errors) console.error(chalk.red(`  ${e}`));
-  }
-  if (useCases?.warnings.length) {
-    console.error(chalk.yellow(`\n⚠ Use cases — ${useCases.warnings.length} aviso(s)`));
-    for (const w of useCases.warnings) console.error(chalk.yellow(`  ${w}`));
-  }
-  printLifecycleWarnings(lifecycle);
-  if (!broken && !useCases?.warnings.length && !lifecycle.warnings.length) {
-    console.log(chalk.green(`\n✅ ${feature}: use cases e acervo sem achados\n`));
-  }
-  process.exit(broken ? 1 : 0);
-}