@polymorphism-tech/morph-spec 8.29.0 → 8.32.0

package/src/commands/project/checkpoint.js

@@ -1,209 +1,209 @@
-/**
- * MORPH-SPEC Checkpoint Save/Restore Command
- *
- * Save and restore full context at phase boundaries.
- *
- * Usage:
- *   morph-spec checkpoint save <feature-name>
- *   morph-spec checkpoint restore <feature-name>
- *   morph-spec checkpoint list <feature-name>
- */
-
-import fs from 'fs';
-import path from 'path';
-import chalk from 'chalk';
-import { loadState, saveState, getFeature } from '../../core/state/state-manager.js';
-
-/**
- * Get checkpoints directory for a feature
- */
-function getCheckpointsDir(featureName) {
-  return path.join(process.cwd(), '.morph/checkpoints', featureName);
-}
-
-/**
- * Save checkpoint command
- */
-export async function checkpointSaveCommand(featureName, options = {}) {
-  if (!featureName) {
-    console.error(chalk.red('Error: Feature name required'));
-    process.exit(1);
-  }
-
-  const feature = getFeature(featureName);
-  if (!feature) {
-    console.error(chalk.red(`Error: Feature '${featureName}' not found`));
-    process.exit(1);
-  }
-
-  const outputDir = path.join(process.cwd(), '.morph/features', featureName);
-  if (!fs.existsSync(outputDir)) {
-    console.error(chalk.red(`Error: No outputs found for '${featureName}'`));
-    process.exit(1);
-  }
-
-  // Create checkpoint directory with timestamp
-  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-  const label = options.label || feature.phase;
-  const checkpointName = `${label}_${timestamp}`;
-  const checkpointDir = path.join(getCheckpointsDir(featureName), checkpointName);
-  fs.mkdirSync(checkpointDir, { recursive: true });
-
-  // Copy all output files
-  const files = fs.readdirSync(outputDir);
-  let fileCount = 0;
-  for (const file of files) {
-    const src = path.join(outputDir, file);
-    const stat = fs.statSync(src);
-    if (stat.isFile()) {
-      fs.copyFileSync(src, path.join(checkpointDir, file));
-      fileCount++;
-    }
-  }
-
-  // Save state snapshot
-  const stateSnapshot = {
-    feature: { ...feature },
-    timestamp: new Date().toISOString(),
-    phase: feature.phase,
-    label,
-    files: files.filter(f => fs.statSync(path.join(outputDir, f)).isFile())
-  };
-  fs.writeFileSync(
-    path.join(checkpointDir, '_checkpoint.json'),
-    JSON.stringify(stateSnapshot, null, 2)
-  );
-
-  console.log(chalk.green(`\n✓ Checkpoint saved: ${checkpointName}`));
-  console.log(chalk.gray(`  Phase: ${feature.phase}`));
-  console.log(chalk.gray(`  Files: ${fileCount}`));
-  console.log(chalk.gray(`  Path: ${checkpointDir}\n`));
-}
-
-/**
- * Restore checkpoint command
- */
-export async function checkpointRestoreCommand(featureName, checkpointName, options = {}) {
-  if (!featureName) {
-    console.error(chalk.red('Error: Feature name required'));
-    process.exit(1);
-  }
-
-  const checkpointsDir = getCheckpointsDir(featureName);
-  if (!fs.existsSync(checkpointsDir)) {
-    console.error(chalk.red(`Error: No checkpoints found for '${featureName}'`));
-    process.exit(1);
-  }
-
-  // Find checkpoint to restore
-  let targetDir;
-  if (checkpointName) {
-    targetDir = path.join(checkpointsDir, checkpointName);
-    if (!fs.existsSync(targetDir)) {
-      console.error(chalk.red(`Error: Checkpoint '${checkpointName}' not found`));
-      process.exit(1);
-    }
-  } else {
-    // Restore latest
-    const checkpoints = fs.readdirSync(checkpointsDir)
-      .filter(d => fs.statSync(path.join(checkpointsDir, d)).isDirectory())
-      .sort()
-      .reverse();
-
-    if (checkpoints.length === 0) {
-      console.error(chalk.red(`Error: No checkpoints found for '${featureName}'`));
-      process.exit(1);
-    }
-
-    targetDir = path.join(checkpointsDir, checkpoints[0]);
-    checkpointName = checkpoints[0];
-  }
-
-  // Read checkpoint metadata
-  const metaPath = path.join(targetDir, '_checkpoint.json');
-  if (!fs.existsSync(metaPath)) {
-    console.error(chalk.red('Error: Checkpoint metadata not found'));
-    process.exit(1);
-  }
-
-  const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
-
-  // Restore output files
-  const outputDir = path.join(process.cwd(), '.morph/features', featureName);
-  fs.mkdirSync(outputDir, { recursive: true });
-
-  const files = fs.readdirSync(targetDir).filter(f => f !== '_checkpoint.json');
-  for (const file of files) {
-    fs.copyFileSync(path.join(targetDir, file), path.join(outputDir, file));
-  }
-
-  // Restore state
-  const state = loadState();
-  if (state.features[featureName] && meta.feature) {
-    // Preserve some current fields, restore phase and outputs
-    state.features[featureName].phase = meta.feature.phase;
-    state.features[featureName].outputs = meta.feature.outputs;
-    state.features[featureName].tasks = meta.feature.tasks;
-    state.features[featureName].approvalGates = meta.feature.approvalGates;
-    state.features[featureName].updatedAt = new Date().toISOString();
-    saveState(state);
-  }
-
-  console.log(chalk.green(`\n✓ Checkpoint restored: ${checkpointName}`));
-  console.log(chalk.gray(`  Phase: ${meta.phase}`));
-  console.log(chalk.gray(`  Files restored: ${files.length}`));
-  console.log(chalk.gray(`  Original date: ${meta.timestamp}\n`));
-}
-
-/**
- * List checkpoints command
- */
-export async function checkpointListCommand(featureName, options = {}) {
-  if (!featureName) {
-    console.error(chalk.red('Error: Feature name required'));
-    process.exit(1);
-  }
-
-  const checkpointsDir = getCheckpointsDir(featureName);
-  if (!fs.existsSync(checkpointsDir)) {
-    console.log(chalk.gray(`No checkpoints found for '${featureName}'.\n`));
-    return;
-  }
-
-  const checkpoints = fs.readdirSync(checkpointsDir)
-    .filter(d => fs.statSync(path.join(checkpointsDir, d)).isDirectory())
-    .sort()
-    .reverse();
-
-  if (checkpoints.length === 0) {
-    console.log(chalk.gray(`No checkpoints found for '${featureName}'.\n`));
-    return;
-  }
-
-  // JSON output
-  if (options.json) {
-    const list = checkpoints.map(cp => {
-      const metaPath = path.join(checkpointsDir, cp, '_checkpoint.json');
-      const meta = fs.existsSync(metaPath) ? JSON.parse(fs.readFileSync(metaPath, 'utf8')) : {};
-      return { name: cp, phase: meta.phase, timestamp: meta.timestamp, files: meta.files?.length || 0 };
-    });
-    console.log(JSON.stringify({ feature: featureName, checkpoints: list }, null, 2));
-    return;
-  }
-
-  // Visual output
-  console.log(chalk.cyan(`\nCheckpoints for '${featureName}':\n`));
-
-  for (const cp of checkpoints) {
-    const metaPath = path.join(checkpointsDir, cp, '_checkpoint.json');
-    let meta = {};
-    if (fs.existsSync(metaPath)) {
-      meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
-    }
-
-    const date = meta.timestamp ? new Date(meta.timestamp).toLocaleString() : 'unknown';
-    console.log(chalk.white(`  ${cp}`));
-    console.log(chalk.gray(`    Phase: ${meta.phase || 'unknown'} | Files: ${meta.files?.length || '?'} | ${date}`));
-  }
-  console.log('');
-}
+/**
+ * MORPH-SPEC Checkpoint Save/Restore Command
+ *
+ * Save and restore full context at phase boundaries.
+ *
+ * Usage:
+ *   morph-spec checkpoint save <feature-name>
+ *   morph-spec checkpoint restore <feature-name>
+ *   morph-spec checkpoint list <feature-name>
+ */
+
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { loadState, saveState, getFeature } from '../../core/state/state-manager.js';
+
+/**
+ * Get checkpoints directory for a feature
+ */
+function getCheckpointsDir(featureName) {
+  return path.join(process.cwd(), '.morph/checkpoints', featureName);
+}
+
+/**
+ * Save checkpoint command
+ */
+export async function checkpointSaveCommand(featureName, options = {}) {
+  if (!featureName) {
+    console.error(chalk.red('Error: Feature name required'));
+    process.exit(1);
+  }
+
+  const feature = getFeature(featureName);
+  if (!feature) {
+    console.error(chalk.red(`Error: Feature '${featureName}' not found`));
+    process.exit(1);
+  }
+
+  const outputDir = path.join(process.cwd(), '.morph/features', featureName);
+  if (!fs.existsSync(outputDir)) {
+    console.error(chalk.red(`Error: No outputs found for '${featureName}'`));
+    process.exit(1);
+  }
+
+  // Create checkpoint directory with timestamp
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const label = options.label || feature.phase;
+  const checkpointName = `${label}_${timestamp}`;
+  const checkpointDir = path.join(getCheckpointsDir(featureName), checkpointName);
+  fs.mkdirSync(checkpointDir, { recursive: true });
+
+  // Copy all output files
+  const files = fs.readdirSync(outputDir);
+  let fileCount = 0;
+  for (const file of files) {
+    const src = path.join(outputDir, file);
+    const stat = fs.statSync(src);
+    if (stat.isFile()) {
+      fs.copyFileSync(src, path.join(checkpointDir, file));
+      fileCount++;
+    }
+  }
+
+  // Save state snapshot
+  const stateSnapshot = {
+    feature: { ...feature },
+    timestamp: new Date().toISOString(),
+    phase: feature.phase,
+    label,
+    files: files.filter(f => fs.statSync(path.join(outputDir, f)).isFile())
+  };
+  fs.writeFileSync(
+    path.join(checkpointDir, '_checkpoint.json'),
+    JSON.stringify(stateSnapshot, null, 2)
+  );
+
+  console.log(chalk.green(`\n✓ Checkpoint saved: ${checkpointName}`));
+  console.log(chalk.gray(`  Phase: ${feature.phase}`));
+  console.log(chalk.gray(`  Files: ${fileCount}`));
+  console.log(chalk.gray(`  Path: ${checkpointDir}\n`));
+}
+
+/**
+ * Restore checkpoint command
+ */
+export async function checkpointRestoreCommand(featureName, checkpointName, options = {}) {
+  if (!featureName) {
+    console.error(chalk.red('Error: Feature name required'));
+    process.exit(1);
+  }
+
+  const checkpointsDir = getCheckpointsDir(featureName);
+  if (!fs.existsSync(checkpointsDir)) {
+    console.error(chalk.red(`Error: No checkpoints found for '${featureName}'`));
+    process.exit(1);
+  }
+
+  // Find checkpoint to restore
+  let targetDir;
+  if (checkpointName) {
+    targetDir = path.join(checkpointsDir, checkpointName);
+    if (!fs.existsSync(targetDir)) {
+      console.error(chalk.red(`Error: Checkpoint '${checkpointName}' not found`));
+      process.exit(1);
+    }
+  } else {
+    // Restore latest
+    const checkpoints = fs.readdirSync(checkpointsDir)
+      .filter(d => fs.statSync(path.join(checkpointsDir, d)).isDirectory())
+      .sort()
+      .reverse();
+
+    if (checkpoints.length === 0) {
+      console.error(chalk.red(`Error: No checkpoints found for '${featureName}'`));
+      process.exit(1);
+    }
+
+    targetDir = path.join(checkpointsDir, checkpoints[0]);
+    checkpointName = checkpoints[0];
+  }
+
+  // Read checkpoint metadata
+  const metaPath = path.join(targetDir, '_checkpoint.json');
+  if (!fs.existsSync(metaPath)) {
+    console.error(chalk.red('Error: Checkpoint metadata not found'));
+    process.exit(1);
+  }
+
+  const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+
+  // Restore output files
+  const outputDir = path.join(process.cwd(), '.morph/features', featureName);
+  fs.mkdirSync(outputDir, { recursive: true });
+
+  const files = fs.readdirSync(targetDir).filter(f => f !== '_checkpoint.json');
+  for (const file of files) {
+    fs.copyFileSync(path.join(targetDir, file), path.join(outputDir, file));
+  }
+
+  // Restore state
+  const state = loadState();
+  if (state.features[featureName] && meta.feature) {
+    // Preserve some current fields, restore phase and outputs
+    state.features[featureName].phase = meta.feature.phase;
+    state.features[featureName].outputs = meta.feature.outputs;
+    state.features[featureName].tasks = meta.feature.tasks;
+    state.features[featureName].approvalGates = meta.feature.approvalGates;
+    state.features[featureName].updatedAt = new Date().toISOString();
+    saveState(state);
+  }
+
+  console.log(chalk.green(`\n✓ Checkpoint restored: ${checkpointName}`));
+  console.log(chalk.gray(`  Phase: ${meta.phase}`));
+  console.log(chalk.gray(`  Files restored: ${files.length}`));
+  console.log(chalk.gray(`  Original date: ${meta.timestamp}\n`));
+}
+
+/**
+ * List checkpoints command
+ */
+export async function checkpointListCommand(featureName, options = {}) {
+  if (!featureName) {
+    console.error(chalk.red('Error: Feature name required'));
+    process.exit(1);
+  }
+
+  const checkpointsDir = getCheckpointsDir(featureName);
+  if (!fs.existsSync(checkpointsDir)) {
+    console.log(chalk.gray(`No checkpoints found for '${featureName}'.\n`));
+    return;
+  }
+
+  const checkpoints = fs.readdirSync(checkpointsDir)
+    .filter(d => fs.statSync(path.join(checkpointsDir, d)).isDirectory())
+    .sort()
+    .reverse();
+
+  if (checkpoints.length === 0) {
+    console.log(chalk.gray(`No checkpoints found for '${featureName}'.\n`));
+    return;
+  }
+
+  // JSON output
+  if (options.json) {
+    const list = checkpoints.map(cp => {
+      const metaPath = path.join(checkpointsDir, cp, '_checkpoint.json');
+      const meta = fs.existsSync(metaPath) ? JSON.parse(fs.readFileSync(metaPath, 'utf8')) : {};
+      return { name: cp, phase: meta.phase, timestamp: meta.timestamp, files: meta.files?.length || 0 };
+    });
+    console.log(JSON.stringify({ feature: featureName, checkpoints: list }, null, 2));
+    return;
+  }
+
+  // Visual output
+  console.log(chalk.cyan(`\nCheckpoints for '${featureName}':\n`));
+
+  for (const cp of checkpoints) {
+    const metaPath = path.join(checkpointsDir, cp, '_checkpoint.json');
+    let meta = {};
+    if (fs.existsSync(metaPath)) {
+      meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+    }
+
+    const date = meta.timestamp ? new Date(meta.timestamp).toLocaleString() : 'unknown';
+    console.log(chalk.white(`  ${cp}`));
+    console.log(chalk.gray(`    Phase: ${meta.phase || 'unknown'} | Files: ${meta.files?.length || '?'} | ${date}`));
+  }
+  console.log('');
+}

package/src/commands/project/doctor.js

@@ -1,11 +1,14 @@
 import { join, relative } from 'path';
 import { execSync } from 'child_process';
+import { existsSync } from 'fs';
 import { platform, homedir } from 'os';
 import fs from 'fs-extra';
 import chalk from 'chalk';
 import { logger } from '../../utils/logger.js';
 import { pathExists, readJson } from '../../utils/file-copier.js';
 import { checkClaudeMdImport } from '../../utils/claude-md-injector.js';
+import { buildPrIndex } from '../../lib/git/pr-index.js';
+import { pendingPrFeatures, MORPH_BRANCH_RE } from '../../lib/git/pending-prs.js';
 import {
   checkCLIOutdated,
   checkProjectOutdated,
@@ -14,6 +17,7 @@ import {
 import { resetMorphSettings } from '../../utils/claude-settings-manager.js';
 import { checkMissingAgents, checkAgentsDrift } from '../../utils/agents-installer.js';
 import { getProjectTags } from '../../lib/stack-filter.js';
+import { auditGraph } from '../../lib/graph/graph-health.js';
 import { auditFeatureLifecycle } from '../../core/state/lifecycle-audit.js';
 
 const isWindows = platform() === 'win32';
@@ -555,10 +559,12 @@ async function doctorMcpCommand(targetPath) {
  * Orphan worktrees used to accumulate invisibly: `fleet` only reports worktrees
  * on a `morph/*` branch, so anything else never showed up anywhere.
  *
- * `--prune` runs the one safe repair (`git worktree prune`: admin records for
- * directories that are already gone). Deleting a directory that still exists is
- * reported with the exact command, never performed — same PROVE-or-DECLINE
- * discipline as the finish teardown.
+ * `--prune` runs the safe repairs: `git worktree prune` (admin records for
+ * directories that are already gone) and the removal of EMPTY unregistered
+ * residue directories, which by definition hold nothing that can be lost.
+ * Deleting a directory that still HOLDS something is reported with the exact
+ * command, never performed — same PROVE-or-DECLINE discipline as the finish
+ * teardown.
  */
 export async function doctorWorktreesCommand(targetPath, options = {}) {
   const { auditWorktrees, pruneWorktrees } = await import('../../lib/worktree/worktree-audit.js');
@@ -567,19 +573,28 @@ export async function doctorWorktreesCommand(targetPath, options = {}) {
     const beforeIssues = auditWorktrees(targetPath);
     const beforeMissing = beforeIssues.filter((i) => i.type === 'registered-missing').length;
     const beforeDangling = beforeIssues.filter((i) => i.type === 'dangling-registration').length;
+    const beforeEmptyDirs = beforeIssues.filter((i) => i.type === 'unregistered-dir' && i.empty).length;
     const result = await pruneWorktrees(targetPath);
     if (result.pruned) logger.success(`git worktree prune: ${beforeMissing} registro(s) órfão(s) removido(s).`);
     else logger.warn(`prune falhou: ${result.error}`);
+    if (result.removedEmptyDirs.length) {
+      logger.success(`${result.removedEmptyDirs.length}/${beforeEmptyDirs} diretório(s) vazio(s) removido(s): ${result.removedEmptyDirs.join(', ')}`);
+    }
     if (result.clearedRegistrations.length) {
       logger.success(`registro de worktree limpo em ${result.clearedRegistrations.length}/${beforeDangling} feature(s): ${result.clearedRegistrations.map((r) => r.feature).join(', ')}`);
     }
   }
 
   const issues = auditWorktrees(targetPath);
+  // `severity: 'info'` entries (a worktree carrying unintegrated work) are
+  // REPORTED but are not failures — a `doctor --worktrees || ...` in CI must not
+  // go red because somebody has an open PR. The human path below splits the same
+  // way; both surfaces must agree on what counts as broken.
+  const isProblem = (i) => i.severity !== 'info';
 
   if (options.json) {
     console.log(JSON.stringify({ issues }, null, 2));
-    return issues.length === 0;
+    return !issues.some(isProblem);
   }
 
   logger.header('MORPH-SPEC Worktrees');
@@ -588,18 +603,90 @@ export async function doctorWorktreesCommand(targetPath, options = {}) {
     return true;
   }
 
-  logger.warn(`${issues.length} inconsistência(s):`);
-  for (const i of issues) {
+  // `unintegrated-work` is NOT an inconsistency — it is a worktree doing its
+  // job, reported so the reader knows why no cleanup is offered for it. Counting
+  // it as a problem is how a diagnostic starts nagging people into destroying
+  // things to make the warning go away.
+  const informational = issues.filter((i) => !isProblem(i));
+  const problems = issues.filter(isProblem);
+
+  if (problems.length) logger.warn(`${problems.length} inconsistência(s):`);
+  for (const i of problems) {
     console.log(`  ⚠ ${i.type}`);
     console.log(`     ${i.detail}`);
     console.log(`     → ${i.fix}`);
   }
-  if (issues.some((i) => i.type === 'registered-missing' || i.type === 'dangling-registration') && !options.prune) {
-    logger.dim('\n  Rode `morph-spec doctor --worktrees --prune` para limpar os registros órfãos.');
+  for (const i of informational) {
+    console.log(`  ℹ ${i.type}`);
+    console.log(`     ${i.detail}`);
+    console.log(`     → ${i.fix}`);
+  }
+  // An EMPTY unregistered directory is prunable too — it holds nothing that can
+  // be lost — so the hint must mention it, or the one issue `--prune` now fixes
+  // automatically would still read as a manual chore.
+  const prunable = (i) => i.type === 'registered-missing'
+    || i.type === 'dangling-registration'
+    || (i.type === 'unregistered-dir' && i.empty);
+  if (problems.some(prunable) && !options.prune) {
+    logger.dim('\n  Rode `morph-spec doctor --worktrees --prune` para limpar os registros órfãos e os diretórios vazios.');
+  }
+  if (!problems.length) {
+    logger.success('Nenhuma inconsistência — os itens acima são informativos.');
+    return true;
   }
   return false;
 }
 
+/** Dias a partir dos quais um PR aberto vira aviso. */
+const PR_STALE_DAYS = 7;
+
+/**
+ * As inconsistências de PR desta árvore.
+ *
+ *   pr-awaiting-merge   — PR aberto há muito, sem cópia local: trabalho em
+ *                         revisão que nenhuma superfície local reivindica.
+ *   pr-merged-not-landed — o PR mergeou mas `archive/{f}` não está aqui. O
+ *                         archive viaja no diff do PR, então ou falta um
+ *                         `git pull`, ou ele não estava no diff.
+ *
+ * Offline-safe: índice `null` devolve `null`, NUNCA lista vazia — lista vazia
+ * afirmaria "perguntei e não achei nada", que é diferente de "não pude
+ * perguntar". Achado #3: um `[]` disfarçado de "sem problema" é o que fazia
+ * `doctor` imprimir `✓ pull requests` mesmo sem conseguir consultar o `gh`.
+ *
+ * @returns {Array<{feature:string,type:string,detail:string}>|null}
+ *   null = DESCONHECIDO (índice não pôde ser construído); nunca "sem PRs".
+ */
+function auditPullRequests(root) {
+  const index = buildPrIndex(root);
+  if (!index) return null;
+  const issues = [];
+
+  for (const p of pendingPrFeatures(root, { index }) || []) {
+    if (p.ageDays != null && p.ageDays >= PR_STALE_DAYS) {
+      issues.push({
+        feature: p.feature,
+        type: 'pr-awaiting-merge',
+        detail: `PR #${p.number} aberto há ${p.ageDays}d e sem cópia local — mergeie ou feche`,
+      });
+    }
+  }
+
+  for (const [branch, pr] of index) {
+    const m = branch.match(MORPH_BRANCH_RE);
+    if (!m || pr.state !== 'MERGED') continue;
+    const feature = m[1];
+    if (existsSync(join(root, '.morph', 'archive', feature))) continue;
+    issues.push({
+      feature,
+      type: 'pr-merged-not-landed',
+      detail: `PR #${pr.number} foi mergeado mas .morph/archive/${feature} não está aqui — falta \`git pull\`?`,
+    });
+  }
+
+  return issues;
+}
+
 export async function doctorCommand(options = {}) {
   // `--json` and `--prune` only mean something under `--worktrees`. Falling
   // through to the human health check would hand a script a banner and a table
@@ -1074,6 +1161,42 @@ export async function doctorCommand(options = {}) {
     hasWarnings = true;
   }
 
+  // Pull requests — o pendurado (aberto há dias sem cópia local) e o mergeado
+  // que não pousou (archive não chegou nesta árvore). Offline-safe: sem `gh`,
+  // sem origin no GitHub, ou qualquer falha, `auditPullRequests` nunca lança
+  // (achado #7 — mesma guarda fail-open que `fleet-scanner.js` já usa para a
+  // síntese idêntica) e devolve `null` — achado #3: um índice desconhecido
+  // renderiza como "não verificado", nunca como `✓ ok`, porque `[]` e
+  // "não pude perguntar" não são a mesma coisa.
+  let prIssues;
+  try {
+    prIssues = auditPullRequests(targetPath);
+  } catch {
+    prIssues = null; // fail-open — um doctor não pode ficar mais ruidoso porque o gh sumiu
+  }
+  if (prIssues === null) {
+    checks.push({ name: 'pull requests', status: 'skip', msg: 'gh indisponível — não verificado' });
+  } else if (prIssues.length === 0) {
+    checks.push({ name: 'pull requests', status: 'ok' });
+  } else {
+    checks.push({
+      name: 'pull requests',
+      status: 'warn',
+      msg: `${prIssues.length} pendência${prIssues.length === 1 ? '' : 's'} (veja abaixo)`,
+    });
+    hasWarnings = true;
+  }
+
+  // Codebase graph — opcional (ADR-002). Nunca 'missing': um projeto que não
+  // usa o grafo tem de continuar com o doctor verde.
+  const graphAudit = auditGraph(targetPath);
+  if (graphAudit.status === 'warn') {
+    checks.push({ name: 'codebase graph', status: 'warn', msg: graphAudit.msg });
+    hasWarnings = true;
+  } else {
+    checks.push({ name: 'codebase graph', status: 'ok', msg: graphAudit.msg });
+  }
+
   // Check key templates exist (in framework package, not project copy)
   const frameworkTemplatesRoot = join(import.meta.dirname, '..', '..', '..', 'framework', 'templates');
   const keyTemplates = [
@@ -1119,6 +1242,11 @@ export async function doctorCommand(options = {}) {
       console.log(chalk.red(`  ✗ ${check.name}`) + chalk.gray(' (missing)'));
     } else if (check.status === 'error') {
       console.log(chalk.red(`  ✗ ${check.name}`) + chalk.gray(` (${check.msg})`));
+    } else if (check.status === 'skip') {
+      // "Não verificado" — nem ok nem falha. Nunca soma em hasWarnings/hasErrors:
+      // um `gh` indisponível não pode deixar o doctor mais barulhento nem mudar
+      // o exit code (achado #3).
+      console.log(chalk.gray(`  ○ ${check.name}`) + chalk.gray(check.msg ? ` (${check.msg})` : ''));
     }
   }
 
@@ -1133,6 +1261,17 @@ export async function doctorCommand(options = {}) {
     console.log(chalk.gray("    Fix: 'morph-spec approve' (order), '--description' on create, or 'morph-spec delete' for dead scaffolds."));
   }
 
+  // Per-feature detail for the PR inconsistencies (item: pendurado ou merge
+  // que não pousou).
+  if (prIssues?.length) {
+    logger.blank();
+    console.log(chalk.yellow('  Pull requests pendentes:'));
+    for (const issue of prIssues) {
+      console.log(chalk.gray(`    • ${issue.feature} [${issue.type}] — ${issue.detail}`));
+    }
+    console.log(chalk.gray('    `finish --pr` abre o PR; quem encerra a feature é o merge.'));
+  }
+
   logger.blank();
 
   if (hasErrors) {