@polymorphism-tech/morph-spec 8.17.0 → 8.19.0

package/src/lib/git/default-branch.js

@@ -71,3 +71,68 @@ export function hasOriginRemote(cwd = process.cwd()) {
     return false;
   }
 }
+
+/**
+ * Resolve HEAD's full commit SHA. Fail-open: null when cwd isn't a git repo,
+ * or the repo has no commits yet (unborn HEAD) — never throws.
+ *
+ * Shared by `morph-spec verify` (the `verification` stamp) and
+ * `morph-spec gate-check` (signals + staleness-vs-code checks) — both need
+ * the exact commit a result covers, mirroring the same fail-open pattern
+ * `reviewStaleness()` in approve.js uses for the same `git rev-parse HEAD` call.
+ *
+ * @param {string} [cwd]
+ * @returns {string|null}
+ */
+export function getHeadSha(cwd = process.cwd()) {
+  try {
+    return execFileSync('git', ['rev-parse', 'HEAD'], { cwd, stdio: 'pipe' }).toString().trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parse `git diff --shortstat` output ("3 files changed, 45 insertions(+), 2
+ * deletions(-)") into counts. Any line missing (e.g. only insertions, no
+ * deletions) contributes 0 for that field. Empty input (no diff) is all-zero,
+ * not an error.
+ *
+ * @param {string} text
+ * @returns {{ filesChanged: number, insertions: number, deletions: number }}
+ */
+function parseShortstat(text) {
+  const files = /(\d+) files? changed/.exec(text || '');
+  const ins = /(\d+) insertions?\(\+\)/.exec(text || '');
+  const del = /(\d+) deletions?\(-\)/.exec(text || '');
+  return {
+    filesChanged: files ? Number(files[1]) : 0,
+    insertions: ins ? Number(ins[1]) : 0,
+    deletions: del ? Number(del[1]) : 0,
+  };
+}
+
+/**
+ * `git diff --shortstat <baseRef>` against the CURRENT WORKING TREE (tracked
+ * edits — staged, unstaged, and everything committed since baseRef —
+ * deliberately not `baseRef...HEAD`, so a gate-check mid-implement still sees
+ * uncommitted work). Same as plain `git diff`, this does NOT count brand-new
+ * UNTRACKED files (never `git add`-ed) — a real, known gap if a gate check
+ * runs before `git add`; not fixed here since covering it needs `--no-index`
+ * or `git add -N` bookkeeping this shared helper doesn't own. Fail-open: null
+ * when `baseRef` is falsy, cwd isn't a git repo, or the diff itself fails
+ * (e.g. baseRef doesn't resolve).
+ *
+ * @param {string|null} baseRef - typically `detectDefaultBranch(cwd)`
+ * @param {string} [cwd]
+ * @returns {{ filesChanged: number, insertions: number, deletions: number }|null}
+ */
+export function getDiffStat(baseRef, cwd = process.cwd()) {
+  if (!baseRef) return null;
+  try {
+    const out = execFileSync('git', ['diff', '--shortstat', baseRef], { cwd, stdio: 'pipe' }).toString().trim();
+    return parseShortstat(out);
+  } catch {
+    return null;
+  }
+}

package/src/lib/risk-detector.js

@@ -8,6 +8,7 @@
  * Signals checked (in order):
  *   - designSystemDivergence: boolean — conflicting design sources detected
  *   - standardsViolations: string[]   — violations of mandate.md proibições
+ *   - verificationStatus: string      — último `morph-spec verify` ('fail' pausa)
  *   - evalScore: number               — morph-eval score (pause if < 9)
  *   - taskCount: number               — total tasks (pause if > 20)
  */
@@ -52,6 +53,17 @@ export function shouldPauseGate(config, signals) {
     };
   }
 
+  // Verify vermelho no momento do gate = a barreira determinística (build/
+  // testes/validadores) está falhando — código antes do juiz vale também
+  // para a decisão de pausa. Só 'fail' pausa: ausência de stamp não é sinal
+  // (features antigas não têm o campo).
+  if (signals.verificationStatus === 'fail') {
+    return {
+      pause: true,
+      reason: 'último morph-spec verify está VERMELHO — rode verify e corrija antes de aprovar o gate',
+    };
+  }
+
   if (typeof signals.evalScore === 'number' && signals.evalScore < MIN_EVAL_SCORE) {
     return {
       pause: true,
@@ -80,6 +92,7 @@ export function getRiskSignals(signals) {
   if (Array.isArray(signals.standardsViolations) && signals.standardsViolations.length > 0) {
     out.push(`standards violations: ${signals.standardsViolations.join(', ')}`);
   }
+  if (signals.verificationStatus === 'fail') out.push('verify vermelho');
   if (typeof signals.evalScore === 'number' && signals.evalScore < MIN_EVAL_SCORE) {
     out.push(`eval score ${signals.evalScore}/10`);
   }

package/src/lib/stack-filter.js

@@ -16,10 +16,15 @@ export function parseStacks(content) {
 
   const fm = fmMatch[1];
 
-  // Try inline format: stacks: [dotnet, blazor]
+  // Try inline format: stacks: [dotnet, blazor] — quotes stripped like the
+  // list branch below; `["umbraco"]` sem isso parseava como a string literal
+  // `"umbraco"` (com aspas) e nunca casava tag nenhuma.
   const inlineMatch = fm.match(/^stacks:\s*\[([^\]]*)\]/m);
   if (inlineMatch) {
-    const items = inlineMatch[1].split(',').map(s => s.trim()).filter(Boolean);
+    const items = inlineMatch[1]
+      .split(',')
+      .map(s => s.replace(/["']/g, '').trim())
+      .filter(Boolean);
     return items.length > 0 ? items : ['*'];
   }
 

package/src/scripts/setup-infra.js

@@ -264,14 +264,23 @@ export async function setupInfra(targetPath, { _exec = execSync, reinstall = fal
     await writeFile(contextReadmePath, readmeContent);
   }
 
-  // --- 5. Copy framework/templates → .morph/framework/templates ---
-  log('Step 5: Copying framework templates...');
-  const frameworkTemplatesSrc = join(FRAMEWORK_DIR, 'templates');
-  const templatesDest = join(frameworkDestDir, 'templates');
-  if (await pathExists(frameworkTemplatesSrc)) {
-    await copyDirectory(frameworkTemplatesSrc, templatesDest);
-  } else {
-    await ensureDir(templatesDest);
+  // --- 5. framework/templates is intentionally NOT copied to
+  // .morph/framework/templates anymore (R3 perf plan, Task 2). Template
+  // resolution is layered (template-registry.js, architecture-scanner.js
+  // resolveTemplatePath): a project-local .morph/framework/templates/{path}
+  // is still checked FIRST as an explicit override, then falls back to the
+  // npm package's own framework/templates/ — which is what every template
+  // actually rendered from until now anyway, since the installed copy was
+  // never read as anything but that override. Pre-populating it was a
+  // byte-for-byte redundant 348KB copy on every install/update.
+  log('Step 5: Skipping framework templates copy (resolved from package; local override still supported)...');
+  // Cópia legada de instalação pré-R3: se existir, ela SOMBREIA os templates
+  // do pacote (override-first). O `morph-spec update` reconcilia (remove cópia
+  // stale por fronteira de versão); aqui só avisamos — init não conhece a
+  // versão anterior do projeto para decidir com segurança.
+  const legacyTemplatesDir = join(frameworkDestDir, 'templates');
+  if (await pathExists(legacyTemplatesDir)) {
+    log('  ⚠ .morph/framework/templates/ existe (instalação antiga) e tem precedência sobre os templates do pacote — rode `morph-spec update` para reconciliar, ou apague se não for customização sua.');
   }
 
   // --- 6. Copy framework/standards → .morph/framework/standards ---
@@ -324,6 +333,16 @@ export async function setupInfra(targetPath, { _exec = execSync, reinstall = fal
     await copyFile(morphMdSrc, morphMdDest);
   }
 
+  // --- 8b2. Copy framework/docs/CLI.md → .morph/framework/CLI.md ---
+  // Referência completa dos comandos (flags, semântica, exemplos) — o
+  // CLAUDE.md residente carrega só a tabela compacta e aponta para cá.
+  log('Step 8b2: Copying CLI.md (command reference)...');
+  const cliMdSrc = join(FRAMEWORK_DIR, 'docs', 'CLI.md');
+  const cliMdDest = join(frameworkDestDir, 'CLI.md');
+  if (await pathExists(cliMdSrc)) {
+    await copyFile(cliMdSrc, cliMdDest);
+  }
+
   // --- 8c. Copy framework/phases.json → .morph/framework/phases.json ---
   log('Step 8c: Copying phases.json...');
   const phasesSrc = join(FRAMEWORK_DIR, 'phases.json');

package/src/utils/skills-installer.js

@@ -75,8 +75,14 @@ function copyDirectory(src, dest) {
  *
  * @param {string} srcDir - Source directory to walk
  * @param {string} destDir - Destination base directory (.claude/skills/)
+ * @param {string[]} projectTags - Stack tags from config
+ * @param {Set<string>} installedNow - Accumulator: skill names this call
+ *   actually (re)installed. NOT derived by re-scanning destDir afterwards —
+ *   a disk scan can't distinguish "installed this run" from "leftover from a
+ *   previous run with different projectTags", which is exactly the stale
+ *   entry a stack change needs cleaned up.
  */
-function installSkillsFromDir(srcDir, destDir, projectTags) {
+function installSkillsFromDir(srcDir, destDir, projectTags, installedNow) {
   const entries = readdirSync(srcDir);
   for (const entry of entries) {
     const srcPath = join(srcDir, entry);
@@ -90,9 +96,10 @@ function installSkillsFromDir(srcDir, destDir, projectTags) {
         if (!shouldInstallSkill(content, projectTags)) continue;
         const skillDestDir = join(destDir, entry);
         copyDirectory(srcPath, skillDestDir);
+        installedNow.add(entry);
       } else {
         // Level/category directory — recurse
-        installSkillsFromDir(srcPath, destDir, projectTags);
+        installSkillsFromDir(srcPath, destDir, projectTags, installedNow);
       }
     } else if (entry.endsWith('.md') && entry !== 'README.md') {
       // Legacy flat .md skill — check stack filter before copying
@@ -102,6 +109,7 @@ function installSkillsFromDir(srcDir, destDir, projectTags) {
       const skillDir = join(destDir, skillName);
       mkdirSync(skillDir, { recursive: true });
       copyFileSync(srcPath, join(skillDir, 'SKILL.md'));
+      installedNow.add(skillName);
     }
   }
 }
@@ -147,28 +155,33 @@ export async function installSkills(projectDir, { projectTags = [] } = {}) {
   const claudeSkillsDir = join(projectDir, '.claude', 'skills');
   mkdirSync(claudeSkillsDir, { recursive: true });
 
+  // Skill names this call actually (re)installs, given projectTags. Tracked
+  // as we go (NOT by re-scanning claudeSkillsDir afterwards) — a disk scan
+  // can't tell "installed this run" apart from "leftover from a previous
+  // run with different projectTags", which is exactly the stale entry a
+  // stack change (or a re-run that narrows the stack) needs cleaned up.
+  const installedNow = new Set();
   for (const level of SKILL_LEVELS_TO_INSTALL) {
     const levelDir = join(FRAMEWORK_SKILLS_DIR, level);
     if (!existsSync(levelDir)) continue;
-    installSkillsFromDir(levelDir, claudeSkillsDir, projectTags);
-  }
-
-  // Collect installed morph-* skill names
-  const installed = new Set();
-  for (const entry of readdirSync(claudeSkillsDir)) {
-    if (existsSync(join(claudeSkillsDir, entry, 'SKILL.md'))) {
-      installed.add(entry);
-    }
+    installSkillsFromDir(levelDir, claudeSkillsDir, projectTags, installedNow);
   }
 
-  // Cleanup orphan morph-* skill dirs that exist in source but were filtered out
+  // Clean-slate: remove any skill dir that is a KNOWN framework skill (still
+  // present in framework/skills/core/) but did NOT get (re)installed this
+  // run — i.e. it was filtered out by a `stacks:` mismatch (project.stack
+  // changed, or a re-run narrowed the tags). Previously scoped to `morph-`
+  // prefixed names only, which silently exempted every non-`morph-` skill
+  // (the Umbraco pair) from ever being cleaned up: install once with
+  // `umbraco` in the stack, drop the stack later, and they'd survive every
+  // reinstall/update forever. Names outside allSourceSkills (user-added,
+  // non-framework skills) are never touched.
   const allSourceSkills = collectSourceSkillNames();
   for (const entry of readdirSync(claudeSkillsDir)) {
-    if (!entry.startsWith('morph-')) continue;
-    if (!installed.has(entry) && allSourceSkills.has(entry)) {
+    if (!installedNow.has(entry) && allSourceSkills.has(entry)) {
       rmSync(join(claudeSkillsDir, entry), { recursive: true, force: true });
     }
   }
 
-  return { installed: installed.size };
+  return { installed: installedNow.size };
 }

package/src/lib/standards/digest-builder.js

@@ -1,72 +0,0 @@
-/**
- * Validator Prompt Builder
- *
- * Generates read-only validation task prompts for Tier-4 validator agents
- * from agents.json hook_behavior configuration.
- *
- * Used by dispatch-agents.js in --mode validate.
- */
-
-import { readFileSync, existsSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-const AGENTS_JSON_PATH = join(__dirname, '../../../framework/agents.json');
-
-let _agentsCache = null;
-
-/** Load and cache agents.json */
-function loadAgents() {
-  if (_agentsCache) return _agentsCache;
-  if (!existsSync(AGENTS_JSON_PATH)) return { agents: {} };
-  try {
-    _agentsCache = JSON.parse(readFileSync(AGENTS_JSON_PATH, 'utf8'));
-    return _agentsCache;
-  } catch {
-    return { agents: {} };
-  }
-}
-
-/**
- * Build a read-only validation task prompt for Tier-4 validator agents.
- * Uses hook_behavior.validates[] from agents.json.
- *
- * @param {string} agentId - Agent ID (must be tier 4 with hook_behavior)
- * @param {string} [taskId] - Optional task ID being validated
- * @returns {string} Validator task prompt or ''
- */
-export function buildValidatorPrompt(agentId, taskId) {
-  const agents = loadAgents();
-  const agentData = agents.agents?.[agentId];
-  if (!agentData?.hook_behavior) return '';
-
-  const validates = agentData.hook_behavior.validates || [];
-  const severity = agentData.hook_behavior.severity || 'error';
-  const blocksOnFail = agentData.hook_behavior.blocks_on_fail ?? true;
-  const taskSuffix = taskId ? ` for task ${taskId}` : '';
-
-  const lines = [
-    `You are ${agentData.title || agentId} (Tier 4 Validator). Mode: READ-ONLY validation${taskSuffix}.`,
-    `DO NOT edit any files. Review the current implementation for the following violations:`,
-    ``,
-    `Checks (severity: ${severity}):`,
-    ...validates.map(v => `  - ${v}`),
-    ``,
-    `Output a single JSON line: { "passed": boolean, "issues": [{ "file": "path/to/file", "line": 0, "message": "description", "rule": "rule-name" }] }`,
-    blocksOnFail
-      ? `BLOCKING: if any issues found, implementation must be fixed before task can complete.`
-      : `NON-BLOCKING: issues are warnings only — task completion is not blocked.`,
-  ];
-
-  return lines.join('\n');
-}
-
-/**
- * Invalidate module-level caches.
- * Used in tests to ensure a fresh load of agents.json.
- */
-export function clearCache() {
-  _agentsCache = null;
-}