@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

package/src/core/paths/output-schema.js

@@ -1,84 +1,27 @@
-/**
- * Output Schema — Single Source of Truth (v5)
- *
- * ALL output type definitions live here. Edit ONLY this file to add, rename,
- * or relocate output types.
- */
-
 import { join } from 'path';
 
-// ============================================================================
-// Schema Definition
-// ============================================================================
-
-/**
- * Schema for output types produced by morph-spec NLH phases.
- *
- * Fields:
- *   filename     - The file's basename (e.g. 'plan.md'). Single-file types only.
- *   phaseDir     - Subdirectory within .morph/features/{feature}/
- *   phase        - The morph-spec phase that produces this output
- *   protected    - Whether the file requires an approval gate before editing
- *   approvalGate - (optional) Which gate protects this file
- *
- * Multi-file types (`multi: true`) hold N files in a directory instead of one
- * fixed basename. They carry `dirname` + `filenamePattern` + `displayFilename`
- * INSTEAD of `filename`, and every derivation keyed by basename
- * (FILENAME_TO_OUTPUT, PROTECTED_SPEC_FILES) skips them —
- * there is no single basename to key on. `getOutputPath` returns the DIRECTORY
- * for these types.
- */
 export const OUTPUT_SCHEMA = {
-  // 2-plan/ — the plan gate freezes both: plan.md accepts only an append in
-  // `## Errata`, checks.json only a rewrite by `morph-spec plan-check`.
   plan:           { filename: 'plan.md',               phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
   checks:         { filename: 'checks.json',           phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
 
-  // 1-design/ (optional)
   uiDesignSystem: { filename: 'design-system.md',      phaseDir: '1-design',    phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
   uiMockups:      { filename: 'mockups.md',            phaseDir: '1-design',    phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
   uiComponents:   { filename: 'components.md',         phaseDir: '1-design',    phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
   uiFlows:        { filename: 'flows.md',              phaseDir: '1-design',    phase: 'uiux',      protected: true,  approvalGate: 'uiux' },
 
-  // 3-implement/ — the slice reports (`reports/F{n}.md`, see getTaskReportPath) are the record.
-  // N files, one per scenario whose proof judges what a MODEL answers
-  // (`prova: eval` in the plan). Runtime evidence: input, model, output, verdict — pointing
-  // at the `runner: "evals"` node when the stack declares one. CONDITIONAL by
-  // construction: never in phases.json requiredOutputs. Readers: morph-review
-  // dispatch prompt.
   evidencias:     { dirname: 'evidencias', filenamePattern: '^C\\d+\\.md$', displayFilename: '{Cn}.md',
                     phaseDir: '3-implement', phase: 'implement', protected: false, multi: true },
 
-  // 4-review/
-  // Um relatório por papel; o canônico da fase é o do verificador.
   verifierReport: { filename: 'verifier.md',           phaseDir: '4-review',    phase: 'review',    protected: false },
   reviewerReport: { filename: 'reviewer.md',           phaseDir: '4-review',    phase: 'review',    protected: false },
   securityReport: { filename: 'security.md',           phaseDir: '4-review',    phase: 'review',    protected: false },
 };
 
-// ============================================================================
-// Builder Functions (Windows-safe via path.join)
-// ============================================================================
-
-/**
- * Leaf segment of a schema entry: the basename for single-file types, the
- * directory name for multi-file ones. Keeps every path builder from having to
- * know about `multi` on its own.
- */
 function leafSegment(entry) {
   return entry.multi ? entry.dirname : entry.filename;
 }
 
-/**
- * Get the morph-relative path for a specific output type of a feature.
- *
- * For `multi` types this is the DIRECTORY holding the N files
- * (".morph/features/my-feature/3-implement/evidencias"), not a single file.
- *
- * @param {string} featureName
- * @param {string} outputType  - camelCase output type key from OUTPUT_SCHEMA
- * @returns {string} e.g. ".morph/features/my-feature/2-plan/plan.md"
- */
+/** For `multi` types this is the directory holding the N files. */
 export function getOutputPath(featureName, outputType) {
   const entry = OUTPUT_SCHEMA[outputType];
   if (!entry) {
@@ -88,10 +31,6 @@ export function getOutputPath(featureName, outputType) {
     .replace(/\\/g, '/');
 }
 
-/**
- * Get the absolute filesystem path for a specific output type.
- * For `multi` types this is the directory — see {@link getOutputPath}.
- */
 export function getAbsoluteOutputPath(projectRoot, featureName, outputType) {
   const entry = OUTPUT_SCHEMA[outputType];
   if (!entry) {
@@ -100,42 +39,20 @@ export function getAbsoluteOutputPath(projectRoot, featureName, outputType) {
   return join(projectRoot, '.morph', 'features', featureName, entry.phaseDir, leafSegment(entry));
 }
 
-/**
- * Get the feature base directory (morph-relative, forward slashes).
- */
 export function getFeatureDir(featureName) {
   return join('.morph', 'features', featureName).replace(/\\/g, '/');
 }
 
-/**
- * Per-task sub-agent report — the durable "return value" channel for a
- * dispatched implementation task (MORPH.md §6). A sub-agent's final text
- * message may never reach the orchestrator (idle_notification with no text
- * is an observed failure mode); the file it writes here always does. Doesn't
- * fit OUTPUT_SCHEMA's one-fixed-filename-per-type model since the filename
- * is parameterized by taskId, so it's a sibling helper instead of a schema
- * entry.
- *
- * @param {string} featureName
- * @param {string} taskId - e.g. "T7"
- * @returns {string} morph-relative, forward-slash path
- */
 export function getTaskReportPath(featureName, taskId) {
   return join('.morph', 'features', featureName, '3-implement', 'reports', `${taskId}.md`)
     .replace(/\\/g, '/');
 }
 
-/** Absolute filesystem variant of {@link getTaskReportPath}. */
 export function getAbsoluteTaskReportPath(projectRoot, featureName, taskId) {
   return join(projectRoot, '.morph', 'features', featureName, '3-implement', 'reports', `${taskId}.md`);
 }
 
-/**
- * Get all output paths for a feature, ready for state.json `outputs` block.
- *
- * Multi-file types contribute their DIRECTORY, so `created` for them means
- * "the folder exists" — the state index tracks presence, not file count.
- */
+/** `multi` types contribute their directory, so `created` means "the folder exists". */
 export function getAllOutputPaths(featureName) {
   const outputs = {};
   for (const [key] of Object.entries(OUTPUT_SCHEMA)) {
@@ -147,14 +64,6 @@ export function getAllOutputPaths(featureName) {
   return outputs;
 }
 
-// ============================================================================
-// Derived Constants
-// ============================================================================
-
-/**
- * filename → output type. Multi-file types are absent by construction: they
- * have N basenames, so there is nothing to key on.
- */
 export const FILENAME_TO_OUTPUT = Object.fromEntries(
   Object.entries(OUTPUT_SCHEMA)
     .filter(([, entry]) => !entry.multi)
@@ -165,20 +74,12 @@ export const OUTPUT_PHASE_MAP = Object.fromEntries(
   Object.entries(OUTPUT_SCHEMA).map(([key, entry]) => [key, entry.phase])
 );
 
-/**
- * Protected spec files and the approval gate that locks them.
- */
 export const PROTECTED_SPEC_FILES = Object.fromEntries(
   Object.entries(OUTPUT_SCHEMA)
     .filter(([, entry]) => entry.protected && entry.approvalGate && !entry.multi)
     .map(([, entry]) => [entry.filename, entry.approvalGate])
 );
 
-// ============================================================================
-// Contracts
-// ============================================================================
-
-/** The output type whose code blocks declare the contracts the code must honour. */
 export function resolveContractsOutputType() {
   return 'plan';
 }

package/src/core/state/feature-identity.js

@@ -1,32 +1,8 @@
-/**
- * Feature identity — the fields that keep a feature.json from being an
- * anonymous shell (the {status, updatedAt}-only scaffolds nobody could later
- * identify). name/createdAt/workType are auto-stamped at birth (explicit
- * `morph-spec create` or the state-sync hook's implicit registration);
- * `description` is the one field a human must supply.
- *
- * `missingIdentity` powers the audit surfaces (`list`, `doctor`) that flag
- * pre-existing anonymous features LENIENTLY (warn, never invalidate old
- * feature.json). `create` enforces `description` HARD at birth — the two-tier
- * split the schema's `required` array can't express (adding fields there would
- * invalidate every feature.json that predates this).
- *
- * Pure module — no filesystem/CLI side effects.
- */
-
 export const IDENTITY_FIELDS = ['name', 'description', 'workType', 'createdAt'];
 
 const blank = (v) => v === undefined || v === null || String(v).trim() === '';
 
-/**
- * Identity fields absent from a feature.json (empty array = fully identified).
- * `description` leads because its absence is the real anonymity signal.
- * `workType` is intentionally excluded — absent workType defaults to 'feature',
- * so it is never a marker of an anonymous shell.
- *
- * @param {object} feature - feature.json contents
- * @returns {string[]} missing identity field names
- */
+// `workType` is excluded on purpose: absent, it defaults to `feature`.
 export function missingIdentity(feature) {
   const missing = [];
   if (blank(feature?.description)) missing.push('description');

package/src/core/state/gate-order.js

@@ -1,19 +1,3 @@
-/**
- * Gate monotonicity — single source of truth.
- *
- * A gate may only be approved once its predecessors are approved. The strict
- * chain is plan → review. uiux is optional: it requires plan but gates nothing
- * downstream, so a feature that skips UI/UX is never blocked.
- *
- * Policy-stamped gates (approvedBy: "policy:{type}", written at birth by
- * `morph-spec create` for a work type's skippedGates) count as approved, so
- * chore/hotfix (plan pre-stamped) satisfy prereqs naturally.
- *
- * Pure module — no filesystem/CLI side effects. Consumed by
- * `approve`/`advance` (refuse), the state-sync hook (warn), and `list`/`doctor`
- * (report).
- */
-
 export const GATE_PREREQ = {
   plan: [],
   uiux: ['plan'],
@@ -22,22 +6,11 @@ export const GATE_PREREQ = {
 
 const isApproved = (gates, name) => gates?.[name]?.approved === true;
 
-/**
- * Prerequisite gates NOT yet approved that block approving `gate`.
- * @param {string} gate - gate about to be approved
- * @param {object} gates - feature.approvalGates
- * @returns {string[]} unmet prerequisite gate names (empty = clear to approve)
- */
 export function unmetPrereqs(gate, gates) {
   const prereqs = GATE_PREREQ[gate] || [];
   return prereqs.filter((p) => !isApproved(gates, p));
 }
 
-/**
- * All monotonicity violations currently present in a feature's gates.
- * @param {object} gates - feature.approvalGates
- * @returns {Array<{gate: string, missing: string[]}>} empty when in order
- */
 export function gateOrderViolations(gates) {
   if (!gates || typeof gates !== 'object') return [];
   const out = [];

package/src/core/state/lifecycle-audit.js

@@ -1,23 +1,3 @@
-/**
- * Feature-lifecycle audit — the consolidated inconsistency scanner behind
- * `morph-spec doctor`. Read-only, non-throwing: scans `.morph/features/*` and
- * the thin root index and reports what's already wrong in the repo, without
- * touching state (never calls loadState — a diagnostic must not mutate).
- *
- * Issue types:
- *   • gate-order    — a gate approved with a predecessor pending (item 4)
- *   • identity      — a feature missing description/name/createdAt (item 3)
- *   • orphan-folder — a feature folder with no feature.json
- *   • stale-index   — a root-index entry with no feature folder (auto-heals on
- *                     the next loadState, but surfaced so it's not a mystery)
- *   • branch-drift  — the root's copy of a feature.json disagrees with the copy
- *                     committed on `morph/{f}` (B5 — the root's view lags)
- *   • abandoned-scaffold — an `in_progress` feature that never produced
- *                     anything: no artifacts, no approved gate, and a branch
- *                     with no commit of its own (see abandonedScaffold)
- *   • corrupt       — a feature.json that won't parse
- */
-
 import { execFileSync } from 'child_process';
 import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
 import { join } from 'path';
@@ -26,40 +6,19 @@ import { missingIdentity } from './feature-identity.js';
 import { detectDefaultBranch } from '../../lib/git/default-branch.js';
 import { commitsAhead, resolveBaseRef } from '../../lib/git/branch-classifier.js';
 
-/** The operational truth of a feature.json: its status and which gates are approved. */
 function operationalShape(fj) {
   const gates = {};
   for (const [g, v] of Object.entries(fj?.approvalGates || {})) gates[g] = v?.approved === true;
   return JSON.stringify({ status: fj?.status ?? null, gates });
 }
 
-/**
- * Does the root's working-tree copy of a feature.json disagree with the copy
- * COMMITTED on that feature's own branch?
- *
- * `.morph/state.json` is gitignored and derived, and every worktree keeps its
- * own — so "the index diverges between worktrees" is by design, not a defect to
- * fix by making the index authoritative (that would undo the whole per-feature
- * state model). The defect is that the divergence was INVISIBLE: since v8.4 the
- * authoritative feature.json travels committed on `morph/{f}`, so a primary root
- * parked on the default holds a copy that silently lags, and everything derived
- * from it (status, gates, and the index rebuilt from it) lags with it.
- *
- * Comparison is on the OPERATIONAL fields only — status and approved-gate flags
- * — not on bytes: reformatting or a timestamp bump is not a divergence anyone
- * needs to hear about.
- *
- * Fail-open at every step: no repo, no branch, no blob, unparseable JSON → no
- * issue. A diagnostic that invents problems is worse than one that misses some.
- *
- * @returns {string|null} the issue detail, or null when the copies agree
- */
+// Compares only status and approved gates (bytes and timestamps are not drift).
+// Fail-open: no repo, branch, blob or parseable JSON means no issue.
 function branchDrift(baseDir, feature, rootFj) {
   const branch = `morph/${feature}`;
   try {
     const current = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: baseDir, stdio: 'pipe' })
       .toString().trim();
-    // On the feature's own branch the working tree IS the branch — nothing to compare.
     if (current === branch) return null;
 
     execFileSync('git', ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], { cwd: baseDir, stdio: 'pipe' });
@@ -77,18 +36,9 @@ function branchDrift(baseDir, feature, rootFj) {
   }
 }
 
-/**
- * How long a scaffold has to sit untouched before it counts as abandoned.
- *
- * A dead scaffold and a feature born five minutes ago have the SAME shape:
- * `create` forks `morph/{f}` off the default branch without committing, so at
- * birth the branch has no commit of its own and the folder holds nothing but
- * `feature.json`. Only elapsed time separates the two — and a check that fires
- * on every fresh `create` is one people learn to scroll past.
- */
+// A dead scaffold and a feature born minutes ago have the same shape; only age tells them apart.
 const ABANDONED_SCAFFOLD_MIN_AGE_MS = 24 * 60 * 60 * 1000;
 
-/** Newest timestamp the feature carries, in ms; falls back to the folder's mtime. */
 function lastTouched(fdir, fj) {
   let newest = 0;
   for (const ts of [fj?.updatedAt, fj?.createdAt]) {
@@ -99,12 +49,7 @@ function lastTouched(fdir, fj) {
   try { return statSync(fdir).mtimeMs; } catch { return 0; }
 }
 
-/**
- * Does the feature dir hold any FILE other than its own `feature.json`?
- *
- * Files, not entries: `create` scaffolds the phase folders empty, so an empty
- * `2-plan/` is the absence of work, not evidence of it.
- */
+// Files, not entries: `create` scaffolds the phase folders empty.
 function hasArtifacts(fdir) {
   let entries;
   try { entries = readdirSync(fdir, { withFileTypes: true }); } catch { return false; }
@@ -119,22 +64,7 @@ function hasArtifacts(fdir) {
   return false;
 }
 
-/**
- * Commits on the feature's branch that the base does not already contain, or
- * `null` when git cannot answer (no repo, no resolvable base, no branch, no
- * rev-list). "Cannot prove" must never read as "proved zero" — the predicate
- * below hinges on this number, so an unanswerable repo has to stay silent.
- *
- * The counting itself is `branch-classifier.js`'s `commitsAhead` against its
- * `resolveBaseRef`, NOT a second copy: `origin/{default}` is the authority on
- * what actually landed, and two drifting answers to "does this branch carry
- * anything of its own?" is exactly what the `doctor`/`branch prune` split was
- * unified to avoid.
- *
- * Note the field evidence this exists for: the branch pointed at the merge
- * commit of somebody else's PR. That is the base's own tip — reachable from
- * the base, and therefore zero commits of its own.
- */
+// `null` when git cannot answer: "cannot prove" must never read as "proved zero".
 function ownCommitCount(baseDir, branch) {
   try {
     execFileSync('git', ['rev-parse', '--git-dir'], { cwd: baseDir, stdio: 'pipe' });
@@ -146,31 +76,15 @@ function ownCommitCount(baseDir, branch) {
   try {
     execFileSync('git', ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], { cwd: baseDir, stdio: 'pipe' });
   } catch {
-    return 0; // the branch never existed — nothing was ever committed for it
+    return 0; // the branch never existed: nothing was committed on it
   }
   return commitsAhead(baseRef, branch, baseDir);
 }
 
-/**
- * The orphan skeleton `create --worktree` can leave behind: a feature.json on
- * its own, `status: in_progress`, no tasks, no gates, and a branch parked on
- * somebody else's commit. Every one of those alone is normal at some point in
- * a feature's life; together, and only after the feature has gone stale, they
- * mean nobody ever came back to it.
- *
- * The artifact test is deliberately broader than the "0 tasks" the report
- * named: a plan drafted and waiting on its gate also has zero tasks and is
- * very much alive. What a dead scaffold has is NOTHING — checked in the root
- * and, if the feature registered one, in its worktree, where uncommitted work
- * would otherwise be invisible to both the disk scan and `rev-list`.
- *
- * @returns {string|null} the issue detail, or null when the feature is alive
- */
 function abandonedScaffold(baseDir, feature, fdir, fj) {
   if (fj?.status !== 'in_progress') return null;
 
-  // "0 gates": a gate stamped `policy:{workType}` at birth (chore/hotfix) was
-  // never a decision anyone took, so it must not read as progress.
+  // A gate stamped `policy:{workType}` at birth was never a decision, so it is not progress.
   const decided = Object.values(fj.approvalGates || {}).some(
     (g) => g?.approved === true && !String(g?.approvedBy ?? '').startsWith('policy:'),
   );
@@ -185,8 +99,6 @@ function abandonedScaffold(baseDir, feature, fdir, fj) {
   const age = Date.now() - lastTouched(fdir, fj);
   if (age < ABANDONED_SCAFFOLD_MIN_AGE_MS) return null;
 
-  // The registered branch when the feature has one, `morph/{f}` otherwise —
-  // same name `branchDrift` above assumes.
   const branch = fj.worktree?.branch || `morph/${feature}`;
   if (ownCommitCount(baseDir, branch) !== 0) return null;
 
@@ -196,10 +108,6 @@ function abandonedScaffold(baseDir, feature, fdir, fj) {
     + 'ou retome a feature';
 }
 
-/**
- * @param {string} [baseDir] - project root (defaults to cwd)
- * @returns {Array<{ feature: string, type: string, detail: string }>} issues
- */
 export function auditFeatureLifecycle(baseDir = process.cwd()) {
   const issues = [];
   const featuresDir = join(baseDir, '.morph', 'features');
@@ -256,7 +164,7 @@ export function auditFeatureLifecycle(baseDir = process.cwd()) {
           issues.push({ feature: name, type: 'stale-index', detail: 'in state.json index but no feature folder' });
         }
       }
-    } catch { /* index is derivable — non-fatal */ }
+    } catch { }
   }
 
   return issues;