@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

package/src/commands/state/report-check.js

@@ -1,29 +1,5 @@
-/**
- * `morph-spec report-check <feature> [slice...] [--json]` — the deterministic
- * half of the missing-report protocol.
- *
- * The slice report file is the sub-agent's authoritative return value; the
- * final message is a courtesy. This command answers what the orchestrator
- * needs when it resumes control, from evidence rather than from the agent's
- * own word: **did the WORK land, independently of whether the REPORT did?**
- *
- *   verdict                          action
- *   ─────────────────────────────    ──────────────────
- *   ok                               proceed
- *   report-stale                     refresh-from-evidence
- *   report-incomplete                resume | complete-degraded
- *   work-landed-report-missing       accept-degraded
- *   no-work-no-report                redispatch
- *   report-missing-evidence-unknown  redispatch   (conservative default)
- *
- * The observed evidence is keyed by the dispatch: the agent whose `agentId`
- * wrote the report owns the window, and its writes after the report make the
- * report stale. A report written inline (no sub-agent) is judged by its
- * markers only.
- *
- * Exit 0 only for `ok`. The output also carries `tree` (see tree-state.js),
- * information only — it never changes the verdict.
- */
+// Judged from observed evidence, never the agent's word: did the WORK land, independently of
+// the REPORT? The `tree` block is information only and never changes the verdict.
 
 import chalk from 'chalk';
 import { existsSync, readFileSync, statSync } from 'fs';
@@ -54,7 +30,7 @@ export function inspectReviewReports(cwd, feature) {
   return out;
 }
 
-/** Who reviews and on which model: the verifier routes to opus on prompt/model or media; security is dispatched only when required. */
+// The verifier routes to opus on prompt/model or media; security is dispatched only when required.
 function reviewDispatch(cwd, feature, slices) {
   let changedFiles = [];
   try { changedFiles = changedPathsAgainst(detectDefaultBranch(cwd), cwd); } catch { changedFiles = []; }
@@ -74,20 +50,12 @@ function reviewDispatch(cwd, feature, slices) {
   };
 }
 
-/**
- * Two clocks: the report's mtime comes from the filesystem, the event's `ts`
- * from the telemetry hook. Two seconds absorb their skew and are far less
- * than any real work done after reporting.
- */
+// Two clocks: the report mtime comes from the filesystem, the event `ts` from the hook. Two
+// seconds absorb their skew and are far less than any real work done after reporting.
 export const STALE_TOLERANCE_MS = 2000;
 
 const slash = (p) => String(p || '').replace(/\\/g, '/');
 
-/**
- * The event target relative to the tree that logged it, the same shape as the
- * slice's `arquivos:`. `Write`/`Edit` targets are absolute; a target outside
- * that tree comes back as it was.
- */
 function toTreeRelative(target, treePath) {
   const norm = slash(target);
   const root = slash(treePath).replace(/\/+$/, '');
@@ -98,7 +66,6 @@ function toTreeRelative(target, treePath) {
 
 const reportSuffix = (feature, sliceId) => `.morph/features/${feature}/3-implement/reports/${sliceId}.md`.toLowerCase();
 
-/** Every successful Write/Edit of every tree of this repo, oldest first. */
 function loadWrites(cwd) {
   let trees = [];
   try { trees = loadTelemetryAllTrees(cwd); } catch { trees = []; }
@@ -115,14 +82,8 @@ function loadWrites(cwd) {
   return { available: trees.some((t) => t.events.length > 0), writes: dedupeEvents(events) };
 }
 
-/**
- * Evidence OBSERVED in the telemetry, never the agent's own word.
- *
- * The dispatch that owns the slice is the sub-agent that wrote its report —
- * the latest such write carrying an `agentId`; an orchestrator edit made
- * afterwards does not hide it. Without a report, any write to one of the
- * slice's files says the work landed.
- */
+// The owning dispatch is the latest sub-agent write of the report; a later orchestrator edit
+// does not hide it. Without a report, any write to one of the slice files says the work landed.
 function observedEvidence(telemetry, feature, slice) {
   if (!telemetry.available) return { available: false };
   const suffix = reportSuffix(feature, slice.id);
@@ -150,7 +111,6 @@ function observedEvidence(telemetry, feature, slice) {
   };
 }
 
-/** Is the report older than the last work its own dispatch observed? */
 function isReportStale(reportFsPath, observed) {
   if (!observed?.agentId || !observed.lastWriteAt) return false;
   try {
@@ -160,7 +120,6 @@ function isReportStale(reportFsPath, observed) {
   }
 }
 
-/** Combine report state + evidence into a verdict and the action it implies. */
 function decide(report, observed, stale) {
   if (report.exists && report.complete) {
     // Structural integrity answers "is the report complete?", never "is it
@@ -200,11 +159,7 @@ function snapshotPath(cwd, feature) {
   return join(cwd, '.morph', 'features', feature, '4-review', 'tree-before-eval.json');
 }
 
-/**
- * The tree block, compared with the snapshot taken before the review agents were
- * dispatched when there is one. `beforeEval` takes a new snapshot after the
- * comparison, so the output still shows what changed since the previous one.
- */
+// `beforeEval` snapshots after comparing, so the output still shows what changed since the last one.
 function treeFor(cwd, feature, beforeEval, slices = []) {
   const path = snapshotPath(cwd, feature);
   let snapshot = null;
@@ -218,11 +173,6 @@ function treeFor(cwd, feature, beforeEval, slices = []) {
   return { tree, beforeEval: { at: next.at, files: Object.keys(next.files).length }, reviewModels };
 }
 
-/**
- * @param {string} feature
- * @param {string[]|undefined} sliceIds - audits only these slices; none audits every slice
- * @param {{ json?: boolean, cwd?: string, beforeEval?: boolean }} [options]
- */
 export function reportCheckCommand(feature, sliceIds, options = {}) {
   const cwd = options.cwd || process.cwd();
   const emit = (obj, code) => {

package/src/commands/state/retype.js

@@ -5,28 +5,8 @@ import { getFeature, setApprovalGate, updateFeature } from '../../core/state/sta
 import { WORK_TYPES, isValidWorkType, POLICY_APPROVER_PREFIX } from '../../core/work-types.js';
 import { renderPlanSkeleton } from '../../lib/plan/plan-template.js';
 
-/**
- * `morph-spec retype <feature> <newType>` — mid-flight work-type change with
- * asymmetric gate rules that preserve GENUINE human/auto approvals and only
- * ever undo policy stamps:
- *
- *  - Blocked outright once Gate 3 (review) is approved — the feature already
- *    shipped its pipeline, retyping it retroactively would be revisionist.
- *  - Downgrade (fewer skipped gates → more skipped gates, e.g. feature/bug
- *    → chore/hotfix) is blocked once the plan gate carries a genuine
- *    (non-policy) approval — the plan was already accepted under the old
- *    type's scrutiny; retyping around it would erase that judgment call.
- *  - Upgrade (more skipped gates → fewer, e.g. chore/hotfix → feature/bug)
- *    is always allowed before review: it only ever ADDS scrutiny.
- *
- * Applying a retype resets exactly the gates that were stamped
- * `policy:{oldType}` and the NEW type no longer skips (so the human is asked
- * again), stamps `policy:{newType}` on any of the new type's skippedGates
- * that aren't already approved (a prior genuine approval is left standing —
- * that's the "preserves human approvals" half of the contract), scaffolds
- * any phase folders the new type needs that don't exist yet, and appends an
- * audit entry to `workTypeHistory`.
- */
+// Retype only ever undoes `policy:` stamps: blocked once review is approved; a downgrade
+// is blocked once the plan carries a genuine approval; an upgrade only adds scrutiny.
 export async function retypeCommand(featureName, newType, options = {}) {
   try {
     if (!isValidWorkType(newType)) {
@@ -69,8 +49,7 @@ export async function retypeCommand(featureName, newType, options = {}) {
 
     const now = new Date().toISOString();
 
-    // Reset gates that were stamped policy:{oldType} and the new type no
-    // longer skips — a genuine (non-policy) approval is never touched.
+    // A genuine (non-policy) approval is never reset.
     const resetGates = [];
     for (const [gate, data] of Object.entries(feature.approvalGates || {})) {
       const isPolicyStamped = String(data?.approvedBy || '').startsWith(POLICY_APPROVER_PREFIX);
@@ -80,8 +59,7 @@ export async function retypeCommand(featureName, newType, options = {}) {
       }
     }
 
-    // Stamp the new type's skipped gates — but only the ones not already
-    // approved (preserves a prior genuine approval untouched).
+    // A gate already approved keeps its genuine approval.
     const stampedGates = [];
     for (const gate of newWorkType.skippedGates) {
       if (!feature.approvalGates?.[gate]?.approved) {

package/src/commands/validation/index.js

@@ -1,5 +1,2 @@
-/**
- * Validation Commands
- */
 export { validateFeatureCommand } from './validate-feature.js';
 export { verifyCommand } from './verify.js';

package/src/commands/validation/mutate.js

@@ -15,7 +15,7 @@ import { groupByNode, loadPlan } from '../../lib/mutation/plan.js';
 import { dotnetSubset, jsSubset, mutatedTypesOf, testFilesCiting, testProjectDirsOf } from '../../lib/mutation/subset.js';
 import { isFinished } from '../../dashboard/scanner/feature-status.js';
 import { dotnetAdapter, genericAdapter, spawnExec } from '../../lib/mutation/adapters.js';
-import { runMutation } from '../../lib/mutation/runner.js';
+import { noSubsetReason, runMutation } from '../../lib/mutation/runner.js';
 import { renderSection, summarize } from '../../lib/mutation/report.js';
 import { readJournal, restoreSnapshot } from '../../lib/mutation/snapshot.js';
 
@@ -23,11 +23,8 @@ const EXIT = { ok: 0, failed: 1, usage: 2, busy: 3, unsafe: 4 };
 const KEEP_RUNS = 2;
 const DEFAULT_JOBS = 2;
 
-/**
- * One heavy slot per worker: the first waits like any heavy node, the others
- * are taken only if free right now. The run uses as many workers as it got,
- * so a busy machine degrades to sequential instead of queueing.
- */
+// One heavy slot per worker: the first waits, the others are taken only if free now,
+// so a busy machine degrades to sequential instead of queueing.
 export function workerGate({ root, feature, jobs }) {
   const config = readHeavyConfig(root);
   const gates = [createHeavyGate({ projectPath: root, label: 'mutate', feature, config })];
@@ -104,8 +101,7 @@ function testDirsOf(node, root, { projectsOnly = false } = {}) {
   return testProjectDirsOf(root, projectsOnly ? targets.filter((t) => !/\.slnx?$/i.test(t)) : targets, cwd);
 }
 
-function subsetFor({ node, group, root, options }) {
-  if (options.subset === false) return { usable: false, reason: '--no-subset' };
+function subsetFor({ node, group, root }) {
   const mutatedFiles = group.regions.map((r) => r.file);
   if (node.runner === 'dotnet') {
     const base = detectDefaultBranch(root);
@@ -196,6 +192,12 @@ export async function mutateCommand(featureArg, options = {}) {
     return fail(`${named}\nNó e2e: true declarado: ${e2eIds}. ${e2eManualProtocol(feature, uncited[0].e2e[0])}`, EXIT.usage);
   }
 
+  const subsets = groups.map((group) => subsetFor({ node: group.node, group, root }));
+  const noSubset = subsets.findIndex((s) => !s.usable);
+  if (noSubset >= 0) {
+    return fail(`suíte "${groups[noSubset].node.id}": ${noSubsetReason(subsets[noSubset].reason)}.`, EXIT.usage);
+  }
+
   if (!options.allowDirty) {
     const dirty = gitOut(root, ['status', '--porcelain', '--', ...new Set(regions.map((r) => r.file))]).trim();
     if (dirty) return fail(`há alteração não commitada nos arquivos a mutar:\n${dirty}\nCommite o fix ANTES de mutar (ou use --allow-dirty sabendo que o snapshot é o único caminho de volta).`, EXIT.usage);
@@ -210,13 +212,11 @@ export async function mutateCommand(featureArg, options = {}) {
   const exec = options.exec ?? spawnExec;
 
   const merged = { wallMs: 0, mutants: [], timings: [], restore: { files: [], ok: true, treeClean: true }, binary: { proof: 'unavailable', projects: [] }, baseline: {}, method: { schemata: 0, rebuild: 0, subset: {} } };
-  const subsets = [];
   try {
     for (const [index, group] of groups.entries()) {
       const workDir = join(base, runId, `g${index}`);
       mkdirSync(workDir, { recursive: true });
-      const subset = subsetFor({ node: group.node, group, root, options });
-      subsets.push(subset);
+      const subset = subsets[index];
       const timeoutMs = options.timeoutMs ?? group.node.timeoutMs ?? 900_000;
       const make = group.node.runner === 'dotnet' ? dotnetAdapter : genericAdapter;
       const adapter = make({ node: group.node, root, workDir, exec, subset, timeoutMs });

package/src/commands/validation/plan-check.js

@@ -5,7 +5,7 @@ import { atomicWriteJson } from '../../core/state/state-manager.js';
 import { isGateApproved } from '../../../framework/hooks/shared/state-reader.js';
 import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
 import { parsePlan } from '../../lib/plan/plan-parser.js';
-import { buildChecks, knownPersonas, parallelGroups, planHash, validatePlan } from '../../lib/plan/checks.js';
+import { buildChecks, knownPersonas, parallelGroups, planHash, planRuleOptions, validatePlan } from '../../lib/plan/checks.js';
 import { knownSurfaces } from '../../lib/specs/screen-checklist.js';
 import { revocationWarnings } from '../../lib/specs/adr-index.js';
 import { assertOwnerTree, ownerTreeRefusalLines } from '../../lib/worktree/feature-truth.js';
@@ -25,7 +25,9 @@ export function runPlanCheck(featureName, cwd = process.cwd()) {
 
   const text = readFileSync(planPath, 'utf8');
   const plan = parsePlan(text);
-  const { errors, warnings } = validatePlan(plan, { personas: knownPersonas(cwd), surfaces: knownSurfaces(cwd) });
+  const { errors, warnings } = validatePlan(plan, {
+    personas: knownPersonas(cwd), surfaces: knownSurfaces(cwd), ...planRuleOptions(cwd, featureName),
+  });
   warnings.push(...revocationWarnings(cwd, plan));
   const groups = errors.length === 0 ? parallelGroups(plan.slices) : [];
   const hash = planHash(text);

package/src/commands/validation/tests-audit.js

@@ -0,0 +1,7 @@
+import { auditTests, renderTestsAudit } from '../../lib/tests-audit/audit.js';
+
+export function testsAuditCommand(options = {}) {
+  const result = auditTests(process.cwd());
+  console.log(options.json ? JSON.stringify(result, null, 2) : renderTestsAudit(result));
+  if (!result.ok) process.exit(2);
+}

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

@@ -1,34 +1,11 @@
-/**
- * MORPH-SPEC Feature Validation Command
- *
- * Content-aware validation of feature outputs at each phase.
- * Checks section presence, schema consistency, and contract correctness.
- *
- * Usage:
- *   morph-spec validate <feature-name> [--phase <phase>] [--json] [--verbose]
- *
- * Example:
- *   morph-spec validate user-portal --phase plan
- *   morph-spec validate user-portal --json
- */
-
 import fs from 'fs';
 import path from 'path';
 import chalk from 'chalk';
 import { parsePlan } from '../../lib/plan/plan-parser.js';
-import { knownPersonas, planHash, validatePlan } from '../../lib/plan/checks.js';
-
-/**
- * Expected sections per markdown output — matched against *section markers*
- * (headings and line-start bold labels), not whole-file substrings; see
- * `extractSectionMarkers`. plan.md is judged by the plan parser instead.
- *
- *   required    → ERROR if absent.
- *   recommended → WARNING if absent.
- *   optional    → silent. Tracked when present, never penalized.
- *
- * Each entry is a string or an array of acceptable aliases (any-of).
- */
+import { knownPersonas, planHash, planRuleOptions, validatePlan } from '../../lib/plan/checks.js';
+
+// Matched against section markers (headings and line-start bold labels), never whole-file
+// substrings. required → ERROR, recommended → WARNING, optional → never penalized; an array is any-of.
 const OUTPUT_SECTIONS = {
   'verifier.md': {
     required: [
@@ -60,9 +37,6 @@ const OUTPUT_SECTIONS = {
   },
 };
 
-/**
- * Phase-to-output mapping (v5 NLH)
- */
 const PHASE_OUTPUTS = {
   plan: ['plan.md', 'checks.json'],
   uiux: ['design-system.md', 'mockups.md', 'components.md', 'flows.md'],
@@ -70,9 +44,6 @@ const PHASE_OUTPUTS = {
   review: ['verifier.md', 'reviewer.md'],
 };
 
-/**
- * Phase-to-folder mapping (v5 filesystem convention)
- */
 const PHASE_FOLDERS = {
   plan: '2-plan',
   uiux: '1-design',
@@ -80,20 +51,7 @@ const PHASE_FOLDERS = {
   review: '4-review',
 };
 
-/**
- * Extract section markers from markdown content.
- *
- * A marker is a line that structurally introduces a section:
- *   - a markdown heading           → `## Arquitetura da solução`
- *   - a line-start bold label      → `**Status:** Aceito`
- *
- * Bold labels are included on purpose (deviation from heading-only): reports
- * write `**Verdict:**` as a line-start bold label, not a heading. They are
- * structural, not prose, so this avoids the accidental-prose-match problem that
- * whole-file substring matching had.
- *
- * Returns lowercased marker texts.
- */
+// Line-start bold labels count: reports write `**Verdict:**` as a label, not a heading.
 function extractSectionMarkers(content) {
   const markers = [];
   for (const rawLine of content.split('\n')) {
@@ -111,9 +69,6 @@ function extractSectionMarkers(content) {
   return markers;
 }
 
-/**
- * Validate a single output file
- */
 function validateOutput(featurePath, outputFile) {
   const filePath = path.join(featurePath, outputFile);
   const result = {
@@ -143,7 +98,6 @@ function validateOutput(featurePath, outputFile) {
     return result;
   }
 
-  // Skip section checks for files without defined sections
   const sections = OUTPUT_SECTIONS[outputFile];
   if (!sections) {
     return result;
@@ -151,7 +105,6 @@ function validateOutput(featurePath, outputFile) {
 
   validateMarkdownSections(content, sections, result);
 
-  // Size warnings
   if (result.lineCount < 10) {
     result.warnings.push(`File is very short (${result.lineCount} lines) — may be incomplete`);
   }
@@ -159,19 +112,17 @@ function validateOutput(featurePath, outputFile) {
   return result;
 }
 
-/**
- * plan.md is judged by the same parser and rules as `morph-spec plan-check`.
- * `planDir` is `.morph/features/{f}/2-plan`, so the project is four levels up.
- */
+// `planDir` is `.morph/features/{f}/2-plan`, so the project is four levels up.
 function validatePlanOutput(content, planDir, result) {
   const plan = parsePlan(content);
-  const { errors, warnings } = validatePlan(plan, { personas: knownPersonas(path.resolve(planDir, '..', '..', '..', '..')) });
+  const root = path.resolve(planDir, '..', '..', '..', '..');
+  const feature = path.basename(path.resolve(planDir, '..'));
+  const { errors, warnings } = validatePlan(plan, { personas: knownPersonas(root), ...planRuleOptions(root, feature) });
   result.errors.push(...errors);
   result.warnings.push(...warnings);
   result.sections.found.push(...plan.sections.filter((x) => x.key).map((x) => x.name));
 }
 
-/** checks.json must parse and carry the hash of the plan.md beside it. */
 function validateChecksOutput(content, planDir, result) {
   let doc;
   try {
@@ -189,16 +140,6 @@ function validateChecksOutput(content, planDir, result) {
   result.sections.found.push(`${doc.checks?.length ?? 0} check(s), ${doc.slices?.length ?? 0} slice(s)`);
 }
 
-/**
- * Validate markdown sections against section markers (headings + bold labels).
- *
- * Each `entry` is a string or array of acceptable aliases (any-of). A section
- * is present when at least one alias is a substring of at least one marker.
- *
- *   required    → missing produces an ERROR
- *   recommended → missing produces a WARNING
- *   optional    → tracked when present, never penalized
- */
 function validateMarkdownSections(content, sections, result) {
   const markers = extractSectionMarkers(content);
   const match = (entry) => {
@@ -234,13 +175,6 @@ function validateMarkdownSections(content, sections, result) {
   }
 }
 
-/**
- * Resolve the list of `{ file, dir }` outputs to validate.
- *
- * @param {string} featurePath  Absolute path to the feature directory.
- * @param {string|null} phase   Phase key, or null to validate everything.
- * @returns {{ outputFiles?: Array<{file:string, dir:string}>, error?: string }}
- */
 function resolveOutputFiles(featurePath, phase) {
   if (phase) {
     const files = PHASE_OUTPUTS[phase];
@@ -250,7 +184,6 @@ function resolveOutputFiles(featurePath, phase) {
     return { outputFiles: files.map(file => ({ file, dir: searchPath })) };
   }
 
-  // Validate every existing output across the feature root + phase folders.
   const outputFiles = [];
   const isOutput = name => name.endsWith('.md') || name.endsWith('.cs') || name === 'checks.json';
   const entries = fs.readdirSync(featurePath, { withFileTypes: true });
@@ -267,17 +200,7 @@ function resolveOutputFiles(featurePath, phase) {
   return { outputFiles };
 }
 
-/**
- * Pure validation core — no console output, no process.exit.
- *
- * @param {string} featurePath  Absolute path to the feature directory.
- * @param {{ phase?: string }} [options]
- * @returns {{
- *   feature: string, phase: string, valid: boolean, error?: string,
- *   totalErrors: number, totalWarnings: number, totalFound: number,
- *   results: object[]
- * }}
- */
+/** Pure core: no console output, no process.exit. */
 export function runFeatureValidation(featurePath, options = {}) {
   const phase = options.phase || null;
   const feature = path.basename(featurePath);
@@ -312,9 +235,6 @@ export function runFeatureValidation(featurePath, options = {}) {
   };
 }
 
-/**
- * Main validate command (CLI wrapper around `runFeatureValidation`)
- */
 export async function validateFeatureCommand(featureName, options = {}) {
   if (!featureName) {
     console.error(chalk.red('Error: Feature name required'));
@@ -340,7 +260,6 @@ export async function validateFeatureCommand(featureName, options = {}) {
   const { results, totalErrors, totalWarnings, totalFound } = validation;
   const schemaWarnings = [];
 
-  // JSON output mode
   if (options.json) {
     const output = {
       feature: featureName,
@@ -367,7 +286,6 @@ export async function validateFeatureCommand(featureName, options = {}) {
     return;
   }
 
-  // Visual output
   console.log(chalk.cyan('\n┌────────────────────────────────────────────────────────────┐'));
   console.log(chalk.cyan('│                MORPH-SPEC FEATURE VALIDATOR                │'));
   console.log(chalk.cyan('└────────────────────────────────────────────────────────────┘\n'));
@@ -376,7 +294,6 @@ export async function validateFeatureCommand(featureName, options = {}) {
   if (phase) console.log(chalk.gray(`Phase: ${phase}`));
   console.log('');
 
-  // File-by-file results
   for (const result of results) {
     const symbol = result.exists
       ? (result.errors.length === 0 ? '✅' : '❌')
@@ -387,25 +304,21 @@ export async function validateFeatureCommand(featureName, options = {}) {
 
     console.log(`${symbol} ${name}${result.exists ? chalk.gray(` (${result.lineCount} lines)`) : ''}`);
 
-    // Sections found
     if (result.sections.found.length > 0 && (options.verbose || result.errors.length > 0)) {
       result.sections.found.forEach(s => {
         console.log(chalk.green(`   ✓ ${s}`));
       });
     }
 
-    // Errors
     result.errors.forEach(err => {
       console.log(chalk.red(`   ✗ ${err}`));
     });
 
-    // Warnings
     result.warnings.forEach(warn => {
       console.log(chalk.yellow(`   ⚠ ${warn}`));
     });
   }
 
-  // Summary
   console.log('');
   console.log(chalk.gray('─'.repeat(60)));