@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

package/src/lib/plan/checks.js

@@ -3,25 +3,21 @@ import { existsSync, readFileSync } from 'fs';
 import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
 import { frozenBody } from '../../../framework/hooks/shared/errata.js';
 import { readAgentsJson } from '../specs/screen-checklist.js';
+import { getFeature } from '../../../framework/hooks/shared/state-reader.js';
 import { findArtifactTerms } from './artifact-vocabulary.js';
-import { PROOF_KINDS, REUSE_VERDICTS, ADR_SCOPES, SECTIONS, CONFLICTS_HEADING } from './plan-parser.js';
+import { PROOF_KINDS, RISK_KINDS, REUSE_VERDICTS, ADR_SCOPES, SECTIONS, CONFLICTS_HEADING } from './plan-parser.js';
 
 export const CHECKS_VERSION = 1;
 export const MAX_SLICE_FILES = 8;
 export const MAX_SLICES = 12;
 export const MAX_PARALLEL = 4;
 
-/** sha256 of the plan without its errata: appending a correction never invalidates checks.json. */
+/** sha256 of the plan without its errata: appending a correction never invalidates the extracted checks. */
 export function planHash(text) {
   return createHash('sha256').update(frozenBody(text), 'utf8').digest('hex');
 }
 
-/**
- * Persona ids the project can dispatch: the installed agents.json, else the package's.
- *
- * @param {string} cwd
- * @returns {string[]|null} null when no agents.json is readable — personas then go unchecked
- */
+/** The installed agents.json, else the package's; null when unreadable (personas then go unchecked). */
 export function knownPersonas(cwd) {
   const agents = readAgentsJson(cwd)?.agents;
   return agents && typeof agents === 'object' ? Object.keys(agents) : null;
@@ -54,14 +50,8 @@ export function dependencyCycle(slices) {
 
 const fileKey = (f) => f.replace(/\\/g, '/').replace(/^\.\//, '').toLowerCase();
 
-/**
- * Waves of slices that may run at the same time: a slice joins a wave only
- * after every slice it depends on ran in an earlier one, and never with a
- * slice that touches one of its files. At most MAX_PARALLEL per wave.
- *
- * @param {{ id: string, depends?: string[], files?: string[] }[]} slices
- * @returns {string[][]} empty when the dependencies have a cycle
- */
+// A slice joins a wave only after its dependencies ran, never with one touching its files, and at most
+// MAX_PARALLEL per wave. Empty on a dependency cycle.
 export function parallelGroups(slices) {
   if (dependencyCycle(slices)) return [];
   const ids = new Set(slices.map((s) => s.id));
@@ -94,14 +84,19 @@ export function parallelGroups(slices) {
   return groups;
 }
 
-/**
- * Judge a parsed plan.
- *
- * @param {ReturnType<import('./plan-parser.js').parsePlan>} plan
- * @param {{ personas?: string[]|null, surfaces?: string[]|null }} [known]
- * @returns {{ errors: string[], warnings: string[] }}
- */
-export function validatePlan(plan, { personas = null, surfaces = null } = {}) {
+// A frozen body already extracted under older rules cannot gain a `risco:` line, so it is not demanded.
+export function planRuleOptions(cwd, featureName) {
+  return {
+    workType: getFeature(featureName, cwd)?.workType ?? null,
+    riskRules: readPlanChecks(cwd, featureName).status !== 'fresh',
+  };
+}
+
+const foldRisk = (s) => s.normalize('NFD').replace(/\p{M}/gu, '').replace(/`/g, '').toLowerCase().trim();
+const RISK_BY_FOLD = new Map(RISK_KINDS.map((r) => [foldRisk(r), r]));
+const REGRESSION_WORK_TYPES = ['bug', 'hotfix'];
+
+export function validatePlan(plan, { personas = null, surfaces = null, workType = null, riskRules = true } = {}) {
   const errors = [];
   const warnings = [];
   const at = (line) => (line ? ` (linha ${line})` : '');
@@ -132,12 +127,26 @@ export function validatePlan(plan, { personas = null, surfaces = null } = {}) {
     } else if (!PROOF_KINDS.includes(c.proof.toLowerCase())) {
       errors.push(`${c.id}: prova "${c.proof}" fora de ${PROOF_KINDS.join(' | ')}${at(c.line)}`);
     }
+    const proof = c.proof?.toLowerCase();
+    const risk = c.risk === null ? null : RISK_BY_FOLD.get(foldRisk(c.risk)) ?? false;
+    if (risk === false) {
+      errors.push(`${c.id}: risco "${c.risk}" fora de ${RISK_KINDS.join(' | ')}${at(c.line)}`);
+    } else if (riskRules && proof === 'teste' && risk === null) {
+      errors.push(`${c.id}: "prova: teste" sem "risco:" (${RISK_KINDS.join(' | ')}) — sem risco, a prova é "leitura" ou "e2e"${at(c.line)}`);
+    } else if (risk && proof === 'leitura') {
+      warnings.push(`${c.id}: risco "${risk}" provado só por leitura${at(c.line)}`);
+    }
     const terms = findArtifactTerms(c.text);
     if (terms.length > 0 && !c.artifactWhy) {
       errors.push(`${c.id} descreve artefato ("${terms.join(', ')}") sem "> Por que artefato:" — reescreva como efeito observável ou justifique${at(c.line)}`);
     }
   }
 
+  const isRegression = (c) => ['teste', 'e2e'].includes(c.proof?.toLowerCase()) && c.risk !== null && RISK_BY_FOLD.get(foldRisk(c.risk)) === 'regressão';
+  if (riskRules && REGRESSION_WORK_TYPES.includes(workType) && plan.scenarios.length > 0 && !plan.scenarios.some(isRegression)) {
+    errors.push(`${workType} sem cenário de regressão — o sintoma do bug real vira um Cn com "prova: teste" e "risco: regressão"`);
+  }
+
   const scenarioIds = new Set(plan.scenarios.map((c) => c.id));
   const sliceIds = new Set(plan.slices.map((s) => s.id));
   const covered = new Set();
@@ -184,7 +193,6 @@ export function validatePlan(plan, { personas = null, surfaces = null } = {}) {
   return { errors, warnings };
 }
 
-/** The checks.json document for a parsed plan. */
 export function buildChecks(feature, text, plan) {
   return {
     version: CHECKS_VERSION,
@@ -202,14 +210,7 @@ export function buildChecks(feature, text, plan) {
   };
 }
 
-/**
- * The feature's extracted checks and whether they still describe the plan on
- * disk. plan-check writes them only with zero errors, so `fresh` also means
- * the plan passed every plan-check rule (no slice over MAX_SLICE_FILES, every
- * scenario covered).
- *
- * @returns {{ status: 'fresh'|'no-plan'|'no-checks'|'unreadable'|'stale', checks: object|null }}
- */
+/** plan-check writes the checks only with zero errors, so `fresh` also means the plan passed every rule. */
 export function readPlanChecks(cwd, featureName) {
   const planPath = getAbsoluteOutputPath(cwd, featureName, 'plan');
   const checksPath = getAbsoluteOutputPath(cwd, featureName, 'checks');

package/src/lib/plan/plan-parser.js

@@ -2,7 +2,8 @@ import { tableCells, isTableLine, SEPARATOR_ROW_RE } from '../specs/gfm-table.js
 import { ARTIFACT_MARKER_RE } from './artifact-vocabulary.js';
 import { markdownLines } from '../../../framework/hooks/shared/errata.js';
 
-export const PROOF_KINDS = ['teste', 'e2e', 'eval', 'manual'];
+export const PROOF_KINDS = ['teste', 'e2e', 'eval', 'manual', 'leitura'];
+export const RISK_KINDS = ['regra', 'dinheiro', 'contrato', 'concorrência', 'dado', 'regressão'];
 export const REUSE_VERDICTS = ['REUSAR', 'ESTENDER', 'CRIAR'];
 export const ADR_SCOPES = ['feature', 'projeto'];
 
@@ -36,6 +37,7 @@ const SCENARIO_RE = new RegExp(String.raw`^[-*]\s+\*\*(C\d+)\*\*${DASH}(.+)$`);
 const ADR_RE = new RegExp(String.raw`^###\s+(ADR-\d+)${DASH}(.+?)\s*$`);
 const SLICE_RE = new RegExp(String.raw`^###\s+(F\d+)${DASH}(.+?)\s*$`);
 const PROOF_RE = /^\s*prova\s*:\s*(.*?)\s*$/i;
+const RISK_RE = /^\s*risco\s*:\s*(.*?)\s*$/i;
 const WHY_RE = new RegExp(String.raw`^\s*>\s*` + ARTIFACT_MARKER_RE.source + String.raw`\s*(.*?)\s*$`, 'i');
 const SCOPE_RE = /^\s*\*\*Alcance:\*\*\s*(.*?)\s*$/i;
 const SLICE_LINE_RE = /^\s*[-*]\s+([\p{L}]+)\s*:\s*(.*?)\s*$/u;
@@ -69,7 +71,7 @@ function parseScenarios(lines) {
     if (line.fenced) { current = null; continue; }
     const m = SCENARIO_RE.exec(line.raw);
     if (m) {
-      current = { id: m[1], text: m[2].trim(), proof: null, artifactWhy: null, line: line.n };
+      current = { id: m[1], text: m[2].trim(), proof: null, risk: null, artifactWhy: null, line: line.n };
       scenarios.push(current);
       continue;
     }
@@ -79,6 +81,8 @@ function parseScenarios(lines) {
     if (why) { current.artifactWhy = why[1] || ''; continue; }
     const proof = PROOF_RE.exec(line.raw);
     if (proof && current.proof === null) { current.proof = proof[1]; continue; }
+    const risk = RISK_RE.exec(line.raw);
+    if (risk && current.risk === null) { current.risk = risk[1]; continue; }
     if (/^\s*>/.test(line.raw)) continue;
     current.text = `${current.text} ${line.raw.trim()}`;
   }
@@ -175,12 +179,7 @@ function parseSlices(lines) {
   return slices;
 }
 
-/**
- * Parse `2-plan/plan.md` into its structure. Pure: no validation, no I/O —
- * `checks.js` judges what this returns.
- *
- * @param {string} text
- */
+/** Pure: no validation, no I/O; `checks.js` judges what this returns. */
 export function parsePlan(text) {
   const lines = markdownLines(text);
   const sections = splitSections(lines);

package/src/lib/projects/registry.js

@@ -1,19 +1,5 @@
-/**
- * Where the morph-spec projects on this machine are — the list the dashboard's
- * portfolio reads. Nothing else records it: each project only knows its own
- * `.morph/`.
- *
- * Three writers register a project as a side note of what they already do —
- * `init`, `update` (never under `--dry-run`) and `dashboard` — and the
- * dashboard adds and removes on request. Registering is fail-open: a registry
- * that cannot be read or written never fails the command that tried.
- *
- * The file lives in the user's home (`~/.morph-spec/projects.json`, or
- * `MORPH_PROJECTS_REGISTRY`), read through `os.homedir()` at call time so a
- * suite that isolates the home also isolates this file. Paths under the
- * system temp dir are never registered: the test suites run `init`/`update`
- * there by the hundred, including through spawned CLIs that keep the real home.
- */
+// Paths under the system temp dir are never registered: test suites run `init`/`update` there by the
+// hundred, through spawned CLIs that keep the real home. The home is read at call time so isolating it works.
 
 import { existsSync, readFileSync, readdirSync } from 'fs';
 import { homedir, tmpdir } from 'os';
@@ -35,7 +21,6 @@ export function projectKey(dir) {
 
 const sameDir = (a, b) => (process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b);
 
-/** A folder is a morph-spec project when morph-spec installed its config there. */
 export function isMorphProject(dir) {
   return existsSync(join(dir, '.morph', 'config', 'config.json'));
 }
@@ -61,18 +46,13 @@ function projectName(dir) {
   }
 }
 
-/**
- * The registered projects that still exist. A folder that was deleted or lost
- * its `.morph/` drops out on read — the file is rewritten on the next write.
- *
- * @returns {{ version: number, projects: Array<{ dir: string, name: string, addedAt: string, lastSeenAt: string, source: string }> }}
- */
+/** Folders that were deleted or lost `.morph/` drop out on read. */
 export function readRegistry() {
   let data = null;
   try {
     const path = registryPath();
     if (existsSync(path)) data = JSON.parse(readFileSync(path, 'utf8'));
-  } catch { /* unreadable registry reads as empty */ }
+  } catch {}
   const projects = Array.isArray(data?.projects) ? data.projects : [];
   return {
     version: REGISTRY_VERSION,
@@ -84,16 +64,7 @@ function write(projects) {
   atomicWriteJson(registryPath(), { version: REGISTRY_VERSION, projects });
 }
 
-/**
- * Note that `dir` is a morph-spec project. Idempotent; refreshes `lastSeenAt`.
- * Never throws.
- *
- * @param {string} dir
- * @param {'init'|'update'|'dashboard'|'manual'} source
- * @param {{ tempRoot?: string }} [opts] - test seam: the folder whose
- *   projects are never registered (the system temp dir)
- * @returns {boolean} true when the project is in the registry afterwards
- */
+/** Idempotent, never throws; `tempRoot` is the test seam for the never-registered folder. */
 export function registerProject(dir, source, { tempRoot = tmpdir() } = {}) {
   try {
     const key = projectKey(dir);
@@ -115,7 +86,7 @@ export function registerProject(dir, source, { tempRoot = tmpdir() } = {}) {
   }
 }
 
-/** Take a project off the list. Its files are not touched. Never throws. */
+/** Never throws; the project's files are not touched. */
 export function unregisterProject(dir) {
   try {
     const key = projectKey(dir);
@@ -128,15 +99,7 @@ export function unregisterProject(dir) {
   }
 }
 
-/**
- * morph-spec projects directly under each root that are not registered yet —
- * the portfolio offers them, the person decides. One level deep: a repos
- * folder is the expected root, and a deeper walk would enter node_modules and
- * worktrees for nothing.
- *
- * @param {string[]} roots
- * @returns {Array<{ dir: string, name: string }>}
- */
+/** Unregistered projects one level under each root: deeper would walk node_modules and worktrees. */
 export function discoverProjects(roots) {
   const registered = readRegistry().projects.map((p) => p.dir);
   const out = [];

package/src/lib/review-reports.js

@@ -27,10 +27,11 @@ const CHECKS_SECTION_RE = sectionRe('Checks');
 const MEDIA_SECTION_RE = /^##\s+M[íi]dia\s+gerada\s*$/m;
 const SCREEN_CHECKLIST_SECTION_RE = sectionRe('Checklist\\s+de\\s+tela');
 
-/** Hotfix: só o verificador, escrito pelo orquestrador sem dispatch. */
+/** Hotfix: só o verificador, escrito pelo orquestrador sem dispatch. Chore: só o revisor (review leve). */
 export function requiredReviewRoles({ workType, securityRequired = false } = {}) {
   if (workType === 'hotfix') return ['verifier'];
-  return securityRequired ? ['verifier', 'reviewer', 'security'] : ['verifier', 'reviewer'];
+  const base = workType === 'chore' ? ['reviewer'] : ['verifier', 'reviewer'];
+  return securityRequired ? [...base, 'security'] : base;
 }
 
 function sectionBodies(text, re) {
@@ -60,7 +61,7 @@ function tableRows(body) {
   return rows;
 }
 
-/** `| id | tipo | onde | evidência |`; `untyped` = tipo fora de {@link BLOCKER_TYPES}. */
+// `| id | tipo | onde | evidência |`; `untyped` = tipo fora de BLOCKER_TYPES.
 function parseBlockers(body) {
   const blockers = [];
   const untyped = [];
@@ -74,10 +75,7 @@ function parseBlockers(body) {
 
 const STATUS_BY_KEY = Object.fromEntries(CHECK_STATUSES.map((s) => [normalize(s), s]));
 
-/**
- * `| Cn | PROVADO|NÃO PROVADO|FALHA | evidência |` de TODAS as seções: uma confirmação
- * traz só os Cn que mudou, então vale a última linha de cada Cn. Status por igualdade exata.
- */
+// Vale a última linha de cada Cn em todas as seções: uma confirmação traz só os Cn que mudou.
 function parseChecks(bodies) {
   const byId = new Map();
   for (const cells of bodies.flatMap(tableRows)) {
@@ -110,10 +108,7 @@ export function parseReviewReport(text) {
   };
 }
 
-/**
- * `missing`: sem arquivo. `partial`: `PARCIAL` na 1ª linha, com ou sem veredito.
- * `unverdicted`: sem `**Verdict:** SHIP|FIX`. `ok`: legível — quem decide é o risk-detector.
- */
+// `partial`: `PARCIAL` na 1ª linha, com ou sem veredito. `ok` só diz legível: quem decide é o risk-detector.
 function stateOf(path, text) {
   if (text === null) return { status: 'missing', path };
   const parsed = parseReviewReport(text);
@@ -148,13 +143,7 @@ export function reviewReports(cwd, featureName) {
   return reviewReportsFromDir(join(cwd, '.morph', 'features', featureName));
 }
 
-/**
- * Todo Cn precisa de uma linha, e só `PROVADO` cobre.
- *
- * @param {string[]} checkIds
- * @param {{id: string, status: string}[]|null} rows - `parseReviewReport(...).checks`
- * @returns {{ missing: string[], notProven: {id: string, status: string}[] }}
- */
+/** Todo Cn precisa de uma linha, e só `PROVADO` cobre. */
 export function checksCoverage(checkIds, rows) {
   const byId = new Map((rows ?? []).map((r) => [r.id, r]));
   const missing = [];
@@ -167,12 +156,7 @@ export function checksCoverage(checkIds, rows) {
   return { missing, notProven };
 }
 
-/**
- * O sinal que `reviewPause` (risk-detector) lê; `checkIds: null` = cobertura não conferível.
- *
- * @param {ReturnType<typeof reviewReportsFromDir>} reports
- * @param {{ required: string[], checkIds: string[]|null }} opts
- */
+/** O sinal que `reviewPause` lê; `checkIds: null` = cobertura não conferível. */
 export function reviewSignal(reports, { required, checkIds }) {
   const out = { required, reports: {} };
   for (const role of ROLE_ORDER) {
@@ -189,7 +173,9 @@ export function reviewSignal(reports, { required, checkIds }) {
         superseded: r.superseded,
       };
   }
-  out.checks = checkIds === null
+  out.checks = !required.includes('verifier')
+    ? { status: 'not-required', missing: [], notProven: [] }
+    : checkIds === null
     ? { status: 'no-checks', missing: [], notProven: [] }
     : { status: 'ok', total: checkIds.length, ...checksCoverage(checkIds, reports.verifier.checks) };
   return out;
@@ -205,7 +191,6 @@ export function combinedVerdict(reports, required) {
   return required.every((r) => reports[r].status === 'ok' && reports[r].verdict === 'SHIP') ? 'SHIP' : null;
 }
 
-/** Todos os bloqueadores tipados dos relatórios presentes, com o papel que os abriu. */
 export function allBlockers(reports) {
   return ROLE_ORDER.flatMap((role) => (reports[role].blockers ?? []).map((b) => ({ ...b, role })));
 }