@polymorphism-tech/morph-spec 8.44.0 → 8.46.0

package/framework/templates/docs/clarifications.md

@@ -1,253 +0,0 @@
-# Clarifications - {{FEATURE_NAME_TITLE}}
-
-**Feature**: {{FEATURE_NAME}}
-**Date**: {{DATE}}
-**Phase**: CLARIFY (Phase 3)
-**Status**: {{#if status}}{{status}}{{else}}In Progress{{/if}}
-
----
-
-## Purpose
-
-This document addresses ambiguities, edge cases, and questions identified during the design review. All clarifications should be incorporated back into `spec.md` after approval.
-
----
-
-## Questions & Answers
-
-{{#each questions}}
-### Q{{this.id}}: {{this.category}} - {{this.title}}
-
-**Question:**
-{{this.question}}
-
-**Context:**
-{{this.context}}
-
-**Answer:**
-{{this.answer}}
-
-**Impact:**
-{{this.impact}}
-
-**Spec Updates Required:**
-{{#each this.specUpdates}}
-- {{this}}
-{{/each}}
-
-**Priority:** {{this.priority}}
-**Resolved:** {{#if this.resolved}}✅ Yes{{else}}❌ No{{/if}}
-**Resolved By:** {{#if this.resolvedBy}}{{this.resolvedBy}}{{else}}_Pending_{{/if}}
-
----
-{{/each}}
-
-## Edge Cases Identified
-
-{{#each edgeCases}}
-### EC{{@index}}: {{this.title}}
-
-**Scenario:**
-{{this.scenario}}
-
-**Current Behavior:**
-{{this.currentBehavior}}
-
-**Expected Behavior:**
-{{this.expectedBehavior}}
-
-**Proposed Solution:**
-{{this.proposedSolution}}
-
-**Acceptance Criteria:**
-{{#each this.acceptanceCriteria}}
-- [ ] {{this}}
-{{/each}}
-
-**Affected Components:**
-{{#each this.affectedComponents}}
-- {{this}}
-{{/each}}
-
----
-{{/each}}
-
-## Assumptions Validated
-
-{{#each assumptions}}
-### A{{@index}}: {{this.title}}
-
-**Assumption:**
-{{this.description}}
-
-**Validation:**
-{{#if this.validated}}✅ Confirmed{{else}}❌ Invalid{{/if}}
-
-**Notes:**
-{{this.notes}}
-
-**Action Required:**
-{{#if this.action}}{{this.action}}{{else}}_None_{{/if}}
-
----
-{{/each}}
-
-## Business Rules Clarified
-
-{{#each businessRules}}
-### BR{{@index}}: {{this.title}}
-
-**Rule:**
-{{this.rule}}
-
-**Rationale:**
-{{this.rationale}}
-
-**Examples:**
-{{#each this.examples}}
-- {{this}}
-{{/each}}
-
-**Exceptions:**
-{{#if this.exceptions}}
-{{#each this.exceptions}}
-- {{this}}
-{{/each}}
-{{else}}
-_None_
-{{/if}}
-
----
-{{/each}}
-
-## Data Validation Rules
-
-{{#each dataValidations}}
-### DV{{@index}}: {{this.field}} Validation
-
-**Field:** {{this.field}}
-**Entity:** {{this.entity}}
-
-**Validation Rules:**
-{{#each this.rules}}
-- {{this}}
-{{/each}}
-
-**Error Messages:**
-{{#each this.errorMessages}}
-- {{this.condition}}: "{{this.message}}"
-{{/each}}
-
-**Impact on UX:**
-{{this.uxImpact}}
-
----
-{{/each}}
-
-## Performance & Scalability Clarifications
-
-{{#each performanceClarifications}}
-### PC{{@index}}: {{this.title}}
-
-**Concern:**
-{{this.concern}}
-
-**Clarification:**
-{{this.clarification}}
-
-**Solution:**
-{{this.solution}}
-
-**Performance Target:**
-{{this.target}}
-
----
-{{/each}}
-
-## Security & Authorization Clarifications
-
-{{#each securityClarifications}}
-### SC{{@index}}: {{this.title}}
-
-**Security Concern:**
-{{this.concern}}
-
-**Clarification:**
-{{this.clarification}}
-
-**Implementation:**
-{{this.implementation}}
-
-**Affected Roles:**
-{{#each this.affectedRoles}}
-- {{this}}
-{{/each}}
-
----
-{{/each}}
-
-## Integration & External Dependencies
-
-{{#each integrationClarifications}}
-### IC{{@index}}: {{this.title}}
-
-**External System:**
-{{this.externalSystem}}
-
-**Question:**
-{{this.question}}
-
-**Clarification:**
-{{this.clarification}}
-
-**API Endpoint/Method:**
-{{this.apiDetails}}
-
-**Error Handling:**
-{{this.errorHandling}}
-
----
-{{/each}}
-
-## Summary
-
-**Total Questions:** {{#if totalQuestions}}{{totalQuestions}}{{else}}0{{/if}}
-**Resolved:** {{#if resolvedCount}}{{resolvedCount}}{{else}}0{{/if}}
-**Pending:** {{#if pendingCount}}{{pendingCount}}{{else}}0{{/if}}
-
-**Edge Cases Identified:** {{#if edgeCaseCount}}{{edgeCaseCount}}{{else}}0{{/if}}
-**Business Rules Documented:** {{#if businessRuleCount}}{{businessRuleCount}}{{else}}0{{/if}}
-**Assumptions Validated:** {{#if assumptionCount}}{{assumptionCount}}{{else}}0{{/if}}
-
----
-
-## Next Steps
-
-1. [ ] Resolve all pending questions
-2. [ ] Update `spec.md` with all clarifications
-3. [ ] Update `contracts.cs` if data model changes are needed
-4. [ ] Document breaking changes in `decisions.md`
-5. [ ] Get stakeholder approval on all clarifications
-6. [ ] Advance to Phase 4 (Tasks)
-
----
-
-## Spec Updates Log
-
-**Changes to be made to `spec.md`:**
-
-{{#each specUpdates}}
-### Update {{@index}}
-
-**Section:** {{this.section}}
-**Type:** {{this.type}}
-**Description:** {{this.description}}
-**From Clarification:** {{this.clarificationId}}
-
----
-{{/each}}
-
----
-
-*Generated by MORPH-SPEC v{{FRAMEWORK_VERSION}}*
-*All clarifications must be incorporated into spec.md before advancing to Phase 4*

package/framework/templates/docs/onboarding.md

@@ -1,122 +0,0 @@
-# Onboarding Guide — {{PROJECT_NAME}}
-
-> Generated by MORPH-SPEC on {{DATE}}
-
----
-
-## Project Overview
-
-- **Project:** {{PROJECT_NAME}}
-- **Stack:** {{STACK}}
-- **Architecture:** {{ARCHITECTURE}}
-
----
-
-## Active Agents
-
-The following agents are configured for this project:
-
-{{AGENTS_LIST}}
-
----
-
-## Available MCPs & Plugins
-
-{{AVAILABLE_MCPS}}
-
----
-
-## Standards
-
-The following standards are enforced in this project:
-
-{{STANDARDS_SUMMARY}}
-
-Standards are located in:
-- `.morph/framework/standards/` — Framework standards (universal)
-- `.morph/context/` — Project-specific overrides
-
----
-
-## Configured Workflow
-
-{{WORKFLOW_SUMMARY}}
-
-### Available Workflows
-
-| Workflow | Description | Phases |
-|----------|-------------|--------|
-| fast-track | Simple, well-defined features | 0→1→2→4→5 |
-| standard | Most features | 0→1→(1.5)→2→3→4→5 |
-| full-morph | Complex features with sync | 0→1→1.5→2→3→4→5→6 |
-| design-impl | Pre-planned work | 2→4→5 |
-| ui-refresh | Visual redesigns | 1.5→2→5 |
-
----
-
-## Key Commands
-
-```bash
-# Start a feature
-# Just ask Claude Code to implement something
-
-# Check feature progress
-morph-spec status <feature>
-
-# Validate feature outputs
-morph-spec validate-feature <feature>
-
-# Approve the current gate and scaffold the next phase folder
-morph-spec advance <feature>
-
-# Archive a finished feature (after Gate 3)
-morph-spec archive <feature>
-
-# Health check
-morph-spec doctor
-```
-
-> **Task tracking lives in `tasks.json`.** During the implement phase Claude records
-> progress by writing `tasks.json` directly (only the `status`, `outputs`, and `notes`
-> fields). State is synced automatically by the `state-sync` hook — there is no CLI
-> command to mark a task done.
-
----
-
-## Project Structure
-
-```
-{{PROJECT_NAME}}/
-├── CLAUDE.md                      # Claude Code instructions
-├── .morph/
-│   ├── config/
-│   │   └── config.json            # Project configuration
-│   ├── framework/
-│   │   ├── agents.json            # Agent definitions
-│   │   ├── standards/             # Framework standards
-│   │   └── templates/             # Output templates
-│   ├── context/                   # Project context & overrides
-│   └── features/{feature}/        # Feature outputs
-│       ├── 0-proposal/
-│       ├── 1-design/              # optional (UI-heavy features)
-│       ├── 2-plan/
-│       ├── 3-implement/
-│       └── 4-review/
-└── .claude/
-    ├── commands/                  # Slash commands
-    ├── skills/                    # Workflow skills
-    └── settings.local.json        # Hooks & permissions
-```
-
----
-
-## Getting Started
-
-1. **Ask Claude Code** to implement a feature
-2. **Follow the phases** — the framework guides you automatically
-3. **Approve at pauses** — design and task breakdowns need your approval
-4. **Check progress** with `morph-spec status <feature>`
-
----
-
-*Generated by MORPH-SPEC v{{VERSION}} — Polymorphism Tech*

package/framework/templates/docs/schema-analysis.md

@@ -1,119 +0,0 @@
-# Schema Analysis - {{FEATURE_NAME_TITLE}}
-
-**Feature**: {{FEATURE_NAME}}
-**Date**: {{DATE}}
-**Method**: {{#if method}}{{method}}{{else}}Manual Code Analysis{{/if}}
-**Analyzed By**: {{AUTHOR}}
-
----
-
-## Summary
-
-**Tables Analyzed**: {{#if tableCount}}{{tableCount}}{{else}}0{{/if}}
-**Code Files Scanned**: {{#if fileCount}}{{fileCount}}{{else}}0{{/if}}
-**MCP Tools Used**: {{#if mcpUsed}}{{mcpUsed}}{{else}}No (manual analysis){{/if}}
-
----
-
-## Tables Analyzed
-
-{{#each tables}}
-### Table: {{this.name}}
-
-**Source:**
-{{#if this.mcpSource}}- MCP: {{this.mcpSource}}{{/if}}
-{{#if this.codeSource}}- Code: {{this.codeSource}}{{/if}}
-
-**Columns:**
-| Column Name | Type | Nullable | Default | Notes |
-|------------|------|----------|---------|-------|
-{{#each this.columns}}
-| {{this.name}} | {{this.type}} | {{#if this.nullable}}YES{{else}}NO{{/if}} | {{#if this.default}}{{this.default}}{{else}}-{{/if}} | {{#if this.notes}}{{this.notes}}{{else}}-{{/if}} |
-{{/each}}
-
-**Relationships:**
-{{#each this.relationships}}
-- {{this.description}}
-{{/each}}
-
-**Indexes:**
-{{#each this.indexes}}
-- {{this.description}}
-{{/each}}
-
----
-{{/each}}
-
-## ⚠️ CRITICAL FINDINGS
-
-### Field Name Mismatches (MUST FIX)
-
-{{#if fieldMismatches}}
-{{#each fieldMismatches}}
-- ❌ {{this.description}}
-{{/each}}
-{{else}}
-✅ No field name mismatches found
-{{/if}}
-
-### Type Mismatches
-
-{{#if typeMismatches}}
-{{#each typeMismatches}}
-- ⚠️ {{this.description}}
-{{/each}}
-{{else}}
-✅ No type mismatches found
-{{/if}}
-
-### Relationship Corrections
-
-{{#if relationshipIssues}}
-{{#each relationshipIssues}}
-- ⚠️ {{this.description}}
-{{/each}}
-{{else}}
-✅ All relationships correctly identified
-{{/if}}
-
----
-
-## Recommendations for contracts.cs
-
-Based on real schema analysis:
-
-\`\`\`csharp
-{{#each dtoRecommendations}}
-// {{this.tableName}} → {{this.dtoName}}
-public record {{this.dtoName}}(
-{{#each this.fields}}
-    {{this.type}} {{this.name}}{{#if this.nullable}}?{{/if}}{{#unless @last}},{{/unless}}  // {{#if this.comment}}{{this.comment}}{{/if}}
-{{/each}}
-);
-
-{{/each}}
-\`\`\`
-
----
-
-## Analysis Notes
-
-{{#if notes}}
-{{notes}}
-{{else}}
-_No additional notes._
-{{/if}}
-
----
-
-## Next Steps
-
-- [ ] Verify schema analysis with stakeholders
-- [ ] Generate `contracts.cs` using real field names
-- [ ] Update `spec.md` data model section with findings
-- [ ] Document any schema migrations needed in `decisions.md`
-
----
-
-*Generated by MORPH-SPEC v{{FRAMEWORK_VERSION}}*
-*Schema analysis helps prevent DTO field name mismatches and ensures contracts match real database schema*

package/framework/templates/docs/user-stories.md

@@ -1,34 +0,0 @@
-# User Stories: {{featureName}}
-
-> Generated: {{date}} | Feature: {{featureName}} | Status: Draft
-
----
-
-## Story 1: [Actor] [Action]
-
-**Feature:** {{featureName}}
-**Priority:** High / Medium / Low
-
-### Optimal Path
-1. [Step 1]
-2. [Step 2]
-3. [Step 3 — success state]
-
-### Edge Cases
-- [Edge case] → [Expected behavior]
-- [Error condition] → [Expected error handling]
-
-### Acceptance Criteria
-- [ ] [Measurable criterion 1]
-- [ ] [Measurable criterion 2]
-- [ ] Edge: [edge case criterion]
-
----
-
-## Story 2: [Actor] [Action]
-
-[Repeat structure above]
-
----
-
-*Generated by MORPH-SPEC — complete before implementation begins*

package/src/commands/state/score.js

@@ -1,147 +0,0 @@
-import chalk from 'chalk';
-import { existsSync, readFileSync } from 'fs';
-import { join } from 'path';
-import { getFeature, updateFeature } from '../../core/state/state-manager.js';
-import { assertOwnerTree, ownerTreeRefusalLines } from '../../lib/worktree/feature-truth.js';
-
-/** Fixed --dims order: a,c,q,t (mirrors the morph-eval dimension weights). */
-const DIM_KEYS = ['architecture', 'contracts', 'codeQuality', 'testCoverage'];
-
-/**
- * taskScores keys are pinned to `^T\d+$` by feature.schema.json, and tasks.schema.json
- * pins the same shape for the task ids themselves. Anything else — a dotted `T3.2`
- * above all — is split on the dot by `updateFeature` and lands as a NESTED key that
- * neither the schema nor the gate-check proxy can see.
- */
-const TASK_ID_PATTERN = /^T\d+$/;
-
-const USAGE_LINE = 'Usage: morph-spec score <feature> <task> <score> [--dims a,c,q,t]   e.g. morph-spec score my-feature T1 9.2 --dims "9,10,9,9"';
-
-function parseScoreValue(raw, label) {
-  // `Number('')` and `Number('   ')` are 0 — finite and inside 0-10, so the range check
-  // below waves them through and a blank value gets recorded as a real zero. Refuse the
-  // empty shape BEFORE Number() so no score can ever be fabricated.
-  const text = raw === undefined || raw === null ? '' : String(raw).trim();
-  if (text === '') {
-    const got = raw === undefined ? 'no value was passed' : `got "${raw}"`;
-    console.error(chalk.red(`\n❌ Missing ${label}: ${got} — a blank value is refused, never recorded as 0`));
-    console.error(chalk.gray(`   ${USAGE_LINE}\n`));
-    process.exit(1);
-  }
-  const value = Number(text);
-  if (!Number.isFinite(value) || value < 0 || value > 10) {
-    console.error(chalk.red(`\n❌ Invalid ${label}: "${raw}" — expected a number between 0 and 10\n`));
-    process.exit(1);
-  }
-  return value;
-}
-
-function assertTaskIdShape(taskId) {
-  const id = taskId === undefined || taskId === null ? '' : String(taskId);
-  if (TASK_ID_PATTERN.test(id)) return;
-  console.error(chalk.red(`\n❌ Invalid task id: "${id}" — expected the pattern T<n> (T1, T7, T12)`));
-  console.error(chalk.gray(
-    `   taskScores keys are pinned by feature.schema.json (propertyNames.pattern "^T\\d+$").\n` +
-    `   A dotted id is split on the "." and written as a nested key, invisible to the gate-check proxy.\n` +
-    `   ${USAGE_LINE}\n`
-  ));
-  process.exit(1);
-}
-
-/**
- * `morph-spec score <feature> <task> <score> [--dims a,c,q,t]` — record a
- * task eval score under `taskScores` in the authoritative feature.json.
- *
- * The timestamp is stamped server-side (`updatedAt`), the write is atomic
- * (state-manager), attempts auto-increment and bestScore is kept — this
- * replaces the fragile manual Edit of feature.json from the skills.
- */
-export async function scoreCommand(featureName, taskId, scoreArg, options = {}) {
-  try {
-    // Argument validation runs before any state read or write: a refusal must never
-    // leave a fabricated or nested taskScores entry behind.
-    assertTaskIdShape(taskId);
-    const score = parseScoreValue(scoreArg, 'score');
-
-    const feature = getFeature(featureName);
-    if (!feature) {
-      console.error(chalk.red(`\n❌ Feature not found: ${featureName}\n`));
-      process.exit(1);
-    }
-
-    const owner = assertOwnerTree(featureName, process.cwd());
-    if (owner.blocked) {
-      for (const { tone, text } of ownerTreeRefusalLines(featureName, owner.tree, owner.branch, `morph-spec score ${featureName} ${taskId} ${scoreArg}`)) {
-        console.error(chalk[tone](text));
-      }
-      process.exit(1);
-    }
-
-    if (feature.taskVerifications?.[taskId]?.status === 'fail') {
-      console.error(chalk.yellow(`⚠️  Último verify de ${taskId} está VERMELHO — score sendo gravado sobre código que não passou no verify determinístico`));
-    }
-
-    let dimensions;
-    if (options.dims) {
-      // Commander captures --dims as variadic (`<dims...>`), so an UNQUOTED
-      // comma list typed in PowerShell — `--dims 9.5,9,9,9` — that arrives as
-      // 4 separate argv tokens (confirmed: Commander binds only the first
-      // token to a non-variadic option and silently drops the rest) is not
-      // lost. Accept either shape: one comma-joined string (the documented,
-      // quoted form) or N separate tokens — split on both separators so a
-      // mix of the two never matters either.
-      const raw = Array.isArray(options.dims) ? options.dims.join(' ') : String(options.dims);
-      const parts = raw.split(/[,\s]+/).filter(Boolean);
-      if (parts.length !== DIM_KEYS.length) {
-        console.error(chalk.red(
-          `\n❌ --dims expects ${DIM_KEYS.length} values in order a,c,q,t (architecture,contracts,code-quality,test-coverage) — got ${parts.length} (${JSON.stringify(parts)}).\n` +
-          `   Quote the value under PowerShell to keep it as one argument: --dims "9.5,9,9,9"\n`
-        ));
-        process.exit(1);
-      }
-      dimensions = {};
-      DIM_KEYS.forEach((key, i) => {
-        dimensions[key] = parseScoreValue(parts[i], `--dims ${key}`);
-      });
-    }
-
-    // Non-fatal sanity check: warn when the task id is unknown to tasks.json.
-    const tasksPath = join(process.cwd(), '.morph', 'features', featureName, '2-plan', 'tasks.json');
-    if (existsSync(tasksPath)) {
-      try {
-        const tasks = JSON.parse(readFileSync(tasksPath, 'utf8')).tasks || [];
-        if (!tasks.some(t => t.id === taskId)) {
-          console.error(chalk.yellow(`⚠️  Task "${taskId}" not found in tasks.json — recording anyway`));
-        }
-      } catch {
-        // unreadable tasks.json — the score is still worth recording
-      }
-    }
-
-    const prev = feature.taskScores?.[taskId];
-    const entry = {
-      lastScore: score,
-      bestScore: prev?.bestScore != null ? Math.max(prev.bestScore, score) : score,
-      attempts: (prev?.attempts ?? 0) + 1,
-      ...(dimensions ? { dimensions } : {}),
-      updatedAt: new Date().toISOString(),
-    };
-
-    await updateFeature(featureName, `taskScores.${taskId}`, entry);
-
-    if (options.json) {
-      console.log(JSON.stringify({ feature: featureName, task: taskId, ...entry }, null, 2));
-      return;
-    }
-
-    console.log(chalk.green(`\n✅ Score recorded: ${featureName}/${taskId} → ${entry.lastScore}`));
-    console.log(chalk.gray(`   best: ${entry.bestScore} | attempts: ${entry.attempts} | updatedAt: ${entry.updatedAt}`));
-    if (dimensions) {
-      console.log(chalk.gray(`   dims: arch=${dimensions.architecture} contracts=${dimensions.contracts} quality=${dimensions.codeQuality} tests=${dimensions.testCoverage}`));
-    }
-    console.log('');
-  } catch (error) {
-    console.error(chalk.red(`\n❌ Error recording score: ${error.message}\n`));
-    process.exit(1);
-  }
-}