@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

package/framework/templates/REGISTRY.json

@@ -55,7 +55,7 @@
       "path": "context/ARCHITECTURE.md",
       "location": "framework",
       "category": "context",
-      "phase": "proposal",
+      "phase": "plan",
       "required": false,
       "description": "Auto-scanned architecture context with entities, endpoints, pages, components, integrations, database tables, and package versions",
       "outputName": "ARCHITECTURE.md",
@@ -179,7 +179,7 @@
       "path": "code/dotnet/contracts/README.md",
       "location": "framework",
       "category": "documentation",
-      "phase": "design",
+      "phase": "implement",
       "required": false,
       "description": "Documentation for contract patterns and usage",
       "outputName": "README.md",
@@ -200,7 +200,7 @@
       "path": "code/dotnet/contracts/contracts-vsa.cs",
       "location": "framework",
       "category": "code",
-      "phase": "design",
+      "phase": "implement",
       "required": false,
       "description": "Feature slice completo: Abstractions, Entity, Errors, e um slice de operação (Request, Response, Validator, Handler, Endpoint). Padrão KanaiyaKatarmal (.NET 10, Minimal APIs, EF Core 10, FluentValidation 12, Scrutor 7).",
       "outputName": "contracts.cs",
@@ -222,7 +222,7 @@
       "path": "code/typescript/contracts.ts",
       "location": "framework",
       "category": "code",
-      "phase": "design",
+      "phase": "implement",
       "required": false,
       "description": "TypeScript type definitions and interfaces",
       "outputName": "contracts.ts",
@@ -538,7 +538,7 @@
       "location": "framework",
       "category": "infrastructure",
       "technology": "github-actions",
-      "phase": "build",
+      "phase": "implement",
       "required": false,
       "description": "Reusable workflow for building .NET applications with restore, build, test, coverage",
       "outputName": "dotnet-build.yml",
@@ -562,7 +562,7 @@
       "location": "framework",
       "category": "infrastructure",
       "technology": "github-actions",
-      "phase": "build",
+      "phase": "implement",
       "required": false,
       "description": "Reusable workflow for building and pushing Docker images to registry",
       "outputName": "docker-build-push.yml",
@@ -584,7 +584,7 @@
       "location": "framework",
       "category": "infrastructure",
       "technology": "github-actions",
-      "phase": "deploy",
+      "phase": "implement",
       "required": false,
       "description": "Reusable workflow for deploying to Coolify via SSH (API is not publicly exposed)",
       "outputName": "deploy-coolify.yml",
@@ -606,7 +606,7 @@
       "location": "framework",
       "category": "infrastructure",
       "technology": "github-actions",
-      "phase": "build",
+      "phase": "implement",
       "required": false,
       "description": "Composite action for building and pushing Docker images",
       "outputName": "action.yml",
@@ -628,7 +628,7 @@
       "location": "framework",
       "category": "infrastructure",
       "technology": "github-actions",
-      "phase": "deploy",
+      "phase": "implement",
       "required": false,
       "description": "Composite action for polling health endpoint until ready",
       "outputName": "action.yml",

package/framework/templates/docs/ui-mockups.md

@@ -18,6 +18,10 @@
 
 ## Tela: {Primary Screen}
 
+**Protótipo:** 1-design/prototipos/{tela}.html
+
+O protótipo renderizado é a fonte visual da tela; os prints `{tela}-1280.png` e `{tela}-390.png` ficam ao lado dele, e sem os três arquivos o Gate uiux pausa. O layout em texto abaixo é opcional.
+
 ### Desktop Layout
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "9.0.0",
+  "version": "9.1.0",
   "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
   "keywords": [
     "claude-code",

package/src/commands/context/context-refresh.js

@@ -1,22 +1,6 @@
-/**
- * CLI handler for `morph-spec context refresh`
- *
- * Scans the project filesystem for architectural patterns and generates
- * a rich .morph/context/README.md that Claude reads at session start.
- *
- * @module context-refresh
- */
-
 import { scanArchitecture, renderArchitectureContext } from '../../lib/generators/architecture-scanner.js';
 import { logger } from '../../utils/logger.js';
 
-/**
- * @param {Object} options - Commander options
- * @param {string} [options.path] - Target project path
- * @param {boolean} [options.verbose] - Show detailed output
- * @param {boolean} [options.json] - Output raw JSON
- * @param {boolean} [options.quiet] - Suppress output (for programmatic use)
- */
 export async function contextRefreshCommand(options = {}) {
   const projectPath = options.path || process.cwd();
 

package/src/commands/dashboard/dashboard.js

@@ -8,19 +8,14 @@ import { registerProject } from '../../lib/projects/registry.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-/** Where the hash of the package.json that produced node_modules is kept. */
 export const DEPS_STAMP = '.morph-deps-stamp';
 
-/** Hash of the dashboard's package.json — the dependency set it declares. */
 export function depsHash(dashboardDir) {
   return createHash('sha256').update(readFileSync(join(dashboardDir, 'package.json'))).digest('hex');
 }
 
-/**
- * Does the dashboard need an `npm install`? Not only when node_modules is
- * missing: an install made before a dependency was added fails at import time,
- * so node_modules must have been produced by THIS package.json.
- */
+// An install made before a dependency was added fails at import time, so
+// node_modules must have been produced by THIS package.json, not merely exist.
 export function needsInstall(dashboardDir) {
   const stamp = join(dashboardDir, 'node_modules', DEPS_STAMP);
   if (!existsSync(stamp)) return true;
@@ -48,7 +43,6 @@ export async function dashboardCommand(options = {}) {
     writeFileSync(join(dashboardDir, 'node_modules', DEPS_STAMP), depsHash(dashboardDir));
   }
 
-  // Opening the dashboard in a project puts it in the portfolio.
   registerProject(process.cwd(), 'dashboard');
 
   console.log(chalk.cyan(`\n  Starting morph-spec dashboard at http://localhost:${port}\n`));

package/src/commands/e2e/e2e.js

@@ -1,22 +1,6 @@
-/**
- * `morph-spec e2e up|status|down` — lifecycle of the verification stack.
- *
- * The stack is deliberately NOT torn down between verifies: cold-starting a
- * .NET container per task is the difference between a loop people run and one
- * they disable. `up` brings it (or reuses it), `status` says whether what is
- * running still matches the working tree, and `down` releases it — which
- * `morph-spec finish` also does as part of teardown.
- *
- * Every subcommand acts in the TREE THAT OWNS THE FEATURE: run from the
- * primary root for a feature that lives in a worktree, the compose file, the
- * bind mount and the stamp are all the worktree's — the root's copy is a
- * different checkout of different code.
- *
- * All the real logic lives in framework/hooks/shared/e2e-check.js, shared with
- * the `verify` e2e node so the two can never drift.
- *
- * @module commands/e2e
- */
+// The stack is deliberately NOT torn down between verifies: a cold .NET start per task is the
+// difference between a loop people run and one they disable. Every subcommand acts in the tree
+// that owns the feature.
 
 import chalk from 'chalk';
 import { execFileSync } from 'child_process';
@@ -46,22 +30,10 @@ import { createHeavyGate, HeavyBusyError } from '../../lib/heavy/gate.js';
 import { afterHeavyRun } from '../../lib/heavy/cleanup.js';
 import { readHeavyConfig } from '../../../framework/hooks/shared/heavy-config.js';
 
-/** Exit code for a usage error, matching `verify`'s convention. */
 const EXIT_USAGE = 2;
 const EXIT_BUSY = 3;
 
-// ============================================================================
-// Shared context
-// ============================================================================
-
-/**
- * Everything the three subcommands need, resolved once — against the tree
- * that owns the feature (its live worktree when it has one, the root
- * otherwise).
- *
- * Returns null (after printing) when that tree has no compose file — a usage
- * error here, unlike in the verify node where it is a graded skip.
- */
+// No compose file is a usage error here, unlike in the verify node where it is a graded skip.
 function resolveContext(featureName, { json = false } = {}) {
   const root = resolvePrimaryRoot(process.cwd());
   const found = findWorktreeForFeature(featureName, root);
@@ -95,49 +67,24 @@ function resolveContext(featureName, { json = false } = {}) {
   };
 }
 
-/**
- * Compose environment: the port block this feature owns, plus any credentials
- * from the gitignored auth env file.
- *
- * The port block comes from `buildComposeEnv` rather than being assembled here
- * so this command and the `e2e` node inside `verify` agree by construction —
- * isolation that exists only in the command nobody runs is no isolation at all.
- */
+// The port block comes from `buildComposeEnv`, so this command and the verify node agree by
+// construction.
 function buildEnv({ cwd, config, featureName, projectName, gitCommonDir }) {
-  // COMPOSE_PROJECT_NAME is part of the port layout now; the explicit key stays
-  // as the fail-open floor for a repo with no git common dir (no block → no
-  // layout), where the project name is still what isolates the containers.
+  // The explicit key is the floor for a repo with no git common dir (no port layout).
   return {
     COMPOSE_PROJECT_NAME: projectName,
     ...buildComposeEnv({ cwd, config, featureName, gitCommonDir }),
   };
 }
 
-// ============================================================================
-// up
-// ============================================================================
-
-/**
- * `morph-spec e2e up <feature> [--fresh]`
- *
- * `--fresh` is destructive on purpose: it tears the previous stack down WITH
- * its named volumes and forces the auth seed to run again. A rebuild that
- * preserved the database would hand the next suite the previous run's rows,
- * and a storageState captured against that database would keep authenticating
- * a user that no longer exists.
- *
- * Exit codes: 0 = stack healthy · 1 = failed to come up (or auth broke, or the
- * compose cannot be isolated inside a worktree) · 2 = usage (no compose file /
- * no docker).
- */
+// `--fresh` drops the named volumes and reruns the auth seed: a preserved database would hand the
+// next suite stale rows and a storageState for a user that no longer exists.
 export async function e2eUpCommand(featureName, options = {}) {
   const ctx = resolveContext(featureName, options);
   if (!ctx) process.exit(EXIT_USAGE);
 
-  // Isolation BEFORE the docker check: `COMPOSE_PROJECT_NAME` isolates
-  // container names but not host ports, and a compose that hardcodes them (or
-  // names its containers) collides with the sibling worktree no matter what we
-  // inject. Same rule as the verify node — see decideIsolation().
+  // Isolation BEFORE the docker check: a compose that hardcodes host ports or container names
+  // collides with a sibling worktree whatever we inject.
   const lint = lintComposeIsolation(readComposeText(ctx.cwd, ctx.composeFile));
   const isolation = decideIsolation({ findings: lint.findings, insideWorktree: ctx.insideWorktree });
   if (isolation.status === 'fail') {
@@ -189,8 +136,7 @@ export async function e2eUpCommand(featureName, options = {}) {
       ? prepareAuth(ctx.cwd, { config: ctx.config, env: ctx.env, forceSeed: Boolean(options.fresh) })
       : { status: 'skip', reason: null };
 
-  // Same warnings[] contract as the verify e2e node: a seedCommand that never
-  // runs because `mode` switches it off is reported, never swallowed.
+  // A seedCommand that `mode` switches off is reported, never swallowed.
   const warnings = [];
   if (isolation.status === 'warn') warnings.push(isolation.reason);
   if (auth.warning) warnings.push(auth.warning);
@@ -225,32 +171,13 @@ export async function e2eUpCommand(featureName, options = {}) {
   process.exit(failed ? 1 : 0);
 }
 
-// ============================================================================
-// status
-// ============================================================================
-
-/**
- * Where the app actually landed.
- *
- * The orchestrator hands this to the verifier instead of letting it guess
- * `localhost:3000` — each feature owns a port block, so the default port is the
- * one address most likely to be wrong. Mirrors what `playwright.config.ts` is
- * asked to do, deliberately: one rule, two readers.
- *
- * @param {Record<string,string>} env
- * @returns {string}
- */
+// Handed to the verifier so it never guesses `localhost:3000`: each feature owns a port block.
+// Mirrors what `playwright.config.ts` does: one rule, two readers.
 export function resolveBaseUrl(env = {}) {
   return env.PLAYWRIGHT_BASE_URL ?? `http://localhost:${env.PORT ?? 3000}`;
 }
 
-/**
- * `morph-spec e2e status <feature> [--json]`
- *
- * Answers the question that matters before trusting a green run: is what is
- * running still built from the code on disk? Exit 0 when up AND fresh, 1
- * otherwise — so it can gate a script.
- */
+// Exit 0 only when up AND built from the code on disk, so it can gate a script.
 export async function e2eStatusCommand(featureName, options = {}) {
   const ctx = resolveContext(featureName, options);
   if (!ctx) process.exit(EXIT_USAGE);
@@ -309,17 +236,8 @@ export async function e2eStatusCommand(featureName, options = {}) {
   process.exit(status.up && status.healthy && fresh ? 0 : 1);
 }
 
-// ============================================================================
-// down
-// ============================================================================
-
-/**
- * `morph-spec e2e down <feature> [--volumes]`
- *
- * Teardown is best-effort by design — a stack that will not come down must
- * never block `finish`. The freshness stamp goes regardless: a stamp that
- * outlives its containers would let the next `up` reuse a stack that is gone.
- */
+// Best-effort: a stack that will not come down must never block `finish`. The freshness stamp
+// goes regardless, or the next `up` would reuse a stack that is gone.
 export async function e2eDownCommand(featureName, options = {}) {
   const ctx = resolveContext(featureName, options);
   if (!ctx) process.exit(EXIT_USAGE);
@@ -348,10 +266,6 @@ export async function e2eDownCommand(featureName, options = {}) {
   process.exit(0);
 }
 
-// ============================================================================
-// Shared helpers
-// ============================================================================
-
 function readConfig(cwd) {
   try {
     const path = join(cwd, '.morph', 'config', 'config.json');
@@ -370,7 +284,6 @@ function readComposeText(cwd, composeFile) {
   }
 }
 
-/** Same resolution (and same fail-open) as verify-runner's. */
 function resolveGitCommonDir(cwd) {
   try {
     const common = execFileSync('git', ['rev-parse', '--git-common-dir'], {

package/src/commands/graph/affected.js

@@ -1,23 +1,9 @@
-/**
- * `morph-spec graph affected <símbolo>` — blast radius saneado.
- *
- * O valor medido não é recall: contra o grep, o grafo achou ZERO arquivos a
- * mais. É precisão — 58% menos ruído em 12 símbolos do ProspectPRO (1.092
- * arquivos no grep, 266 usos reais) e a classificação da relação. `IHandler`
- * aparece em 193 arquivos no grep e tem 2 usos reais: é implementada por 98.
- *
- * @module graph-affected
- */
 import chalk from 'chalk';
 import { loadGraph, getFreshness, describeStale } from '../../lib/graph/graph-loader.js';
 import { buildIndex, resolveLabel, affected } from '../../lib/graph/sanitize.js';
 
 const FALLBACK_HINT = 'Sem resposta do grafo, caia para grep/Glob — o grafo é um subconjunto estrito do grep, então cair para grep não perde recall.';
 
-/**
- * @param {string} symbol
- * @param {{path?: string, json?: boolean, prod?: boolean, usesOnly?: boolean}} [options]
- */
 export async function graphAffectedCommand(symbol, options = {}) {
   const projectPath = options.path || process.cwd();
   const loaded = loadGraph(projectPath);

package/src/commands/graph/build.js

@@ -1,11 +1,3 @@
-/**
- * `morph-spec graph build` (extração completa) e `graph refresh` (incremental).
- *
- * Fail-open: sem graphify no PATH, explica o que fazer e sai 1 — sem stack
- * trace. Um projeto sem grafo continua funcionando por grep.
- *
- * @module graph-build
- */
 import chalk from 'chalk';
 import { readFileSync, existsSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -33,26 +25,9 @@ function readProjectTags(projectPath) {
   }
 }
 
-/**
- * O `.graphifyignore` com que o graphify vai rodar.
- *
- * Na raiz: escrito ou migrado (writeGraphifyignore). Numa worktree o arquivo é
- * do checkout e nunca é reescrito — seria uma mudança na branch da feature.
- * Ausente ali (a raiz ainda não o versionou), as regras — as da raiz
- * (`ignoreTextOf`), ou as geradas — entram só durante a rodada e saem depois
- * (`cleanup`): um `?? .graphifyignore` deixado na worktree faz o `finish` e
- * o `worktree remove --if-clean` recusarem com worktree-dirty (medido), e pôr
- * o arquivo no exclude do common dir esconderia também o da raiz. O arquivo leva
- * `TEMP_IGNORE_MARKER` na 1ª linha: se este processo morrer antes do
- * `cleanup`, a sobra é reconhecida pelo conteúdo — a próxima rodada a reusa e o
- * `finish` a apaga (`dropLeftoverIgnore`). O graphify não herda o da raiz: o
- * ignore dele para na raiz de VCS mais próxima, que numa worktree é ela mesma
- * (detect.py `_load_graphifyignore`).
- *
- * @param {string} projectPath
- * @param {string[]} tags
- * @returns {{written: boolean, migrated?: boolean, outdated?: object, temporary?: boolean, path: string, cleanup: () => void}}
- */
+// Numa worktree o arquivo do checkout nunca é reescrito; ausente, as regras entram só durante
+// a rodada (uma sobra suja a worktree e o `finish` recusa). `TEMP_IGNORE_MARKER` na 1ª linha
+// deixa a próxima rodada e o `finish` reconhecerem a sobra de um processo morto.
 function prepareIgnore(projectPath, tags) {
   const none = () => {};
   if (!isSecondaryWorktree(projectPath)) return { ...writeGraphifyignore(projectPath, tags), cleanup: none };
@@ -71,9 +46,6 @@ function prepareIgnore(projectPath, tags) {
   };
 }
 
-/**
- * @param {{path?: string, json?: boolean, refresh?: boolean}} [options]
- */
 export async function graphBuildCommand(options = {}) {
   const projectPath = options.path || process.cwd();
   const refresh = options.refresh === true;
@@ -93,19 +65,14 @@ export async function graphBuildCommand(options = {}) {
     process.exit(1);
   }
 
-  // O ignore precisa existir ANTES da extração, senão o grafo nasce com o
-  // ruído que a ADR-004 existe para tirar.
+  // O ignore precisa existir ANTES da extração, senão o grafo nasce com o ruído.
   const ignore = prepareIgnore(projectPath, readProjectTags(projectPath));
   if (ignore.outdated && !options.json) {
     console.error(chalk.yellow(`\n⚠ ${describeOutdatedIgnore(ignore.outdated)}`));
   }
 
-  // Na árvore principal o refresh em background (framework/hooks/shared/
-  // graph-refresh.js) escreve o mesmo graph.json: dois graphify ao mesmo tempo
-  // disputam o arquivo e todos os núcleos. Numa worktree ninguém mais escreve
-  // o graph.json dela — o background só toca a raiz —, e esperar o lock da
-  // raiz ali prometeria "o grafo chega ao HEAD" sobre um refresh que nunca a
-  // alcança. Sem git não há lock, e o comando segue sozinho.
+  // Na raiz o refresh em background escreve o mesmo graph.json: dois graphify disputam o arquivo
+  // e os núcleos. Numa worktree só este comando escreve o grafo dela, e sem git não há lock.
   const primary = isPrimaryTree(projectPath);
   const lock = primary ? acquireRefreshLock(projectPath) : null;
   const running = primary && !lock ? readRefreshLock(projectPath) : null;
@@ -127,24 +94,18 @@ export async function graphBuildCommand(options = {}) {
     ? ['update', projectPath]
     : ['extract', projectPath, '--code-only'];
 
-  // Capturamos o output em vez de herdar o terminal porque precisamos
-  // inspecioná-lo: o graphify sai 1 tanto quando quebra quanto quando não há
-  // código para indexar, e essas duas coisas não podem virar a mesma mensagem.
-  // HEAD e regras lidos ANTES: são o que o graphify leu.
+  // Output capturado: o graphify sai 1 tanto ao quebrar quanto sem código para indexar, e as duas
+  // coisas não podem virar a mesma mensagem. HEAD e regras lidos ANTES: são o que o graphify leu.
   const head = readHead(projectPath);
   const ignoreHash = ignoreRulesHash(projectPath);
   let run;
   let empty = false;
   try {
     run = runGraphify(projectPath, args, { timeout: null });
-    // Projeto sem código é o estado normal logo depois de um `init`, não uma
-    // falha: o graphify diz "found 0 code" / "graph is empty", sai 1 e não
-    // escreve graph.json. Tratar isso como erro faria todo init greenfield
-    // terminar em vermelho.
+    // Projeto sem código (logo depois de um `init`) não é falha: o graphify sai 1 sem graph.json.
     empty = run.status !== 0 && (/found 0 code/i.test(run.output) || /graph is empty/i.test(run.output));
-    // O registro é o que torna "untouched" em dia: sem ele, um refresh que não
-    // mudou a topologia deixa o carimbo no commit antigo e o grafo parece
-    // velho para sempre (framework/hooks/shared/graph-freshness.js).
+    // Sem o registro, um refresh que não mudou a topologia deixa o carimbo no commit antigo
+    // e o grafo parece velho para sempre.
     if (!empty) {
       recordRefreshRun(projectPath, {
         head, exit: run.status ?? null, ignoreHash, unavailable: Boolean(run.unavailable),

package/src/commands/graph/explain.js

@@ -1,25 +1,9 @@
-/**
- * `morph-spec graph explain <símbolo>` — vizinhança com citação arquivo:linha.
- *
- * É o comando preferido nas personas: no eval, `explain` foi consistentemente
- * mais preciso que `query`, que trunca por budget e traz ruído.
- *
- * Cada aresta carrega a procedência (`via`), então dá para ver o que o
- * saneamento recuperou — `coalesced` são exatamente as arestas que o graphify
- * cru perde.
- *
- * @module graph-explain
- */
 import chalk from 'chalk';
 import { loadGraph, getFreshness, describeStale } from '../../lib/graph/graph-loader.js';
 import { buildIndex, resolveLabel, neighborhood, isTestPath } from '../../lib/graph/sanitize.js';
 
 const FALLBACK_HINT = 'Sem resposta do grafo, caia para grep/Glob.';
 
-/**
- * @param {string} symbol
- * @param {{path?: string, json?: boolean}} [options]
- */
 export async function graphExplainCommand(symbol, options = {}) {
   const projectPath = options.path || process.cwd();
   const loaded = loadGraph(projectPath);

package/src/commands/graph/status.js

@@ -1,12 +1,3 @@
-/**
- * `morph-spec graph status` — existência, tamanho, frescor e saúde do
- * saneamento.
- *
- * Ausência de grafo NÃO é erro (ADR-002): exit 0 com `available: false`. Um
- * projeto sem grafo é um estado válido, e o framework segue por grep.
- *
- * @module graph-status
- */
 import chalk from 'chalk';
 import {
   loadGraph, getFreshness, describeStale, refreshState, staleCause,
@@ -24,9 +15,7 @@ function summarizeSanitize(index) {
   return counts;
 }
 
-/**
- * @param {{path?: string, json?: boolean}} [options]
- */
+// Ausência de grafo não é erro: exit 0 com `available: false`, e o framework segue por grep.
 export async function graphStatusCommand(options = {}) {
   const projectPath = options.path || process.cwd();
   const installed = detectGraphifyVersion();