@polymorphism-tech/morph-spec 8.29.0 → 8.32.0

package/CLAUDE.md

@@ -37,7 +37,7 @@ No build step — pure ESM JavaScript, runs directly via Node.js 18+.
 - **`src/commands/`** — CLI command handlers organized by domain (project/, state/, validation/, scaffold/, mcp/, context/, dashboard/).
 - **`src/core/`** — Core domain logic:
   - `state/state-manager.js` — Atomic state I/O with process-ID temp files
-  - `paths/output-schema.js` — **Single source of truth** for the 13 v5 output types
+  - `paths/output-schema.js` — **Single source of truth** for the 14 v5 output types
   - `templates/` — Handlebars template registry and renderer
   - `workflows/` — Workflow type detector
 - **`src/lib/`** — Libraries and subsystems:
@@ -114,7 +114,17 @@ When modifying framework components, verify the full scope of related files.
 | `framework/templates/**`         | REGISTRY.json (template registered), valid Handlebars helpers                             |
 | `src/core/paths/output-schema.js`| Run `npm run generate` to update phase-utils.js                                           |
 | `framework/MORPH.md`             | All core skills (cross-references), CLAUDE.md (slash command list)                        |
+| `src/lib/worktree/ignored-triage.js` | `worktree.js` (`classifyIgnoredLeftovers`), `test/lib/worktree/ignored-triage.test.js`, e os canários de `test/commands/finish.test.js` que pinam "o exemplar único nunca morre" — mudar um bucket muda o que o `finish` apaga |
+| `src/lib/git/pr-index.js` | os QUATRO leitores do mesmo fato "esta branch tem PR": `fleet-scanner.js` (coluna PR), `branch-classifier.js` (o que NÃO apagar), `worktree-audit.js` (o que NÃO sugerir remover) e `pending-prs.js` (a síntese "aguardando merge"). `null` é UNKNOWN, nunca "sem PR" |
+| `src/lib/git/branch-classifier.js` | `src/commands/project/branch.js`, `worktree-audit.js` (`unintegratedWork` reusa `classifyBranch` — o `doctor` e o `branch prune` não podem discordar sobre a mesma branch), `test/commands/branch-prune.test.js`, e `lifecycle-audit.js` (`abandoned-scaffold` conta commit próprio pelo mesmo `resolveBaseRef` + `commitsAhead`) |
+| `src/lib/git/pending-prs.js` | os TRÊS consumidores da mesma síntese "aguardando merge": `list.js` (linha sintetizada), `fleet-scanner.js` (entrada `pr-pending`) e `doctor.js` (`auditPullRequests`). Uma feature visível numa superfície e invisível na outra é o bug que este módulo existe para impedir |
+| `src/lib/git/gh.js` | `pr-index.js` e `finish.js` — as DUAS formas de invocar o `gh` viraram uma; uma segunda cópia de `resolveGh` volta a tornar o caminho de sucesso do índice intestável |
 | `src/lib/worktree/feature-truth.js` | The four leaders reading the same "which tree owns this feature" predicate: `fleet-scanner.js`, `list.js`, `handoff.js`, and the mutator guard (`approve.js`/`advance.js`/`score.js`/`gate-decision.js`/`gate-check.js`) |
+| `src/lib/graph/**`               | `test/lib/graph/*.test.js`, the committed fixture `test/fixtures/graph/namespace-hierarchy.graph.json` (ADR-003 regression — never hand-edit it), `doctor.js` (`codebase graph` check), `architecture-scanner.js` (centrality section), `setup-infra.js` step 18b |
+| `src/lib/validators/reuse/**`     | `validation-runner.js` (case + push universal), `framework/rubrics/*.json` (o id `reuse` mapeado numa categoria, senão o achado não pesa no score), `test/fixtures/graph/prospectpro-reuse.graph.json` (recorte do grafo real — regerar com `build-reuse-fixture.mjs`, nunca editar à mão) |
+| o ciclo de reuso (`reuse-map.md`) | `output-schema.js` (+ `npm run generate`), `framework/schemas/tasks.schema.json` + `tasks-json-parser.js` (campo `reuse`), `morph-plan` §1c/§5b, template de dispatch de `morph-implement`/`morph-apply`, personas de `agents.json`, `evals/rubrics/code-quality.md` + `condensed.md`, `morph-review` (insumo do avaliador), `test/framework/graph-fallback.test.js` |
+| `framework/mcp/registry.json`    | mcp-installer.js, claude-config-detector.js, agents-installer.js (personas' `mcp` field), `scripts/validate-framework.js` Check 8, `test/framework/mcp-registry.test.js` |
+| Any `framework/` file that calls `morph-spec graph` | The fallback to grep must be declared in the SAME file — `test/framework/graph-fallback.test.js` enforces it (ADR-002: a skill that requires the graph with no fallback is a bug) |
 
 ### Test Coverage
 

package/README.md

@@ -3,7 +3,7 @@
 > Spec-driven development framework for multi-stack projects. Turns feature requests into implementation-ready code through structured, AI-orchestrated phases.
 
 **Package:** `@polymorphism-tech/morph-spec`
-**Version:** 8.29.0  
+**Version:** 8.32.0  
 **Requires:** Node.js 22+, Claude Code
 
 ---
@@ -203,6 +203,17 @@ morph-spec worktree list [--json]        # List active feature worktrees with ph
 # Close a worktree feature with `morph-spec finish {feature} --pr|--merge` (see Feature workflow) — it absorbed `worktree finish`.
 ```
 
+**Codebase graph** — optional, fail-open. `init` installs [graphify](https://pypi.org/project/graphifyy/) (pinned 0.9.50) when a Python toolchain is available and writes a stack-aware `.graphifyignore`; without one, it records the fact and moves on. Everything degrades to grep.
+
+```bash
+morph-spec graph build                       # Extract the graph (local AST, zero tokens)
+morph-spec graph status                      # Size, freshness, sanitizer health
+morph-spec graph affected {symbol} --uses-only  # Who actually uses it (not who implements it)
+morph-spec graph explain {symbol}            # Neighbourhood, cited file:line
+```
+
+The gain is **precision, not recall**: the graph finds nothing grep would miss, but it drops 58% of the noise and tells you *what kind* of relationship each hit is — the difference between "20 types implement this interface" and "2 actually use it". The graph is never consumed raw: a sanitizing layer fixes the C# namespace-scope resolution gap that would otherwise report **zero** consumers where two exist.
+
 ---
 
 ## Agent model
@@ -368,4 +379,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v8.29.0 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v8.32.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -24,6 +24,7 @@ import { updateCommand } from '../src/commands/project/update.js';
 import { doctorCommand } from '../src/commands/project/doctor.js';
 import { statusCommand } from '../src/commands/project/status.js';
 import { worktreeSetupCommand, worktreeLinkCommand, worktreeListCommand, worktreeRemoveCommand } from '../src/commands/project/worktree.js';
+import { branchPruneCommand } from '../src/commands/project/branch.js';
 import { fleetCommand } from '../src/commands/project/fleet.js';
 import { claimCommand } from '../src/commands/project/claim.js';
 import { standardsCommand } from '../src/commands/project/standards.js';
@@ -47,6 +48,12 @@ import { usecaseReserveCommand } from '../src/commands/state/usecase.js';
 // === Tasks ===
 import { dagCommand } from '../src/commands/tasks/dag.js';
 
+// === Codebase graph ===
+import { graphStatusCommand } from '../src/commands/graph/status.js';
+import { graphBuildCommand } from '../src/commands/graph/build.js';
+import { graphAffectedCommand } from '../src/commands/graph/affected.js';
+import { graphExplainCommand } from '../src/commands/graph/explain.js';
+
 // === Validation ===
 import { validateCommand } from './validate.js';
 import { validateFeatureCommand } from '../src/commands/validation/validate-feature.js';
@@ -285,6 +292,48 @@ program
   .option('--mermaid', 'Emit the tasks.json DAG as a Mermaid flowchart (flowchart TD)')
   .action((feature, options) => dagCommand(feature, options));
 
+// ─── Codebase graph ───────────────────────────────────────────────────────
+const graphCommand = program
+  .command('graph')
+  .description('Grafo de codebase (graphify) com saneamento determinístico — fail-open: sem grafo, tudo segue por grep');
+
+graphCommand
+  .command('status')
+  .description('Existência, tamanho, frescor e saúde do saneamento. Grafo ausente não é erro (exit 0)')
+  .option('-p, --path <path>', 'Target path (default: current directory)')
+  .option('--json', 'Output as JSON')
+  .action((options) => graphStatusCommand(options));
+
+graphCommand
+  .command('build')
+  .description('Extração completa (graphify extract --code-only); gera o .graphifyignore stack-aware antes')
+  .option('-p, --path <path>', 'Target path (default: current directory)')
+  .option('--json', 'Output as JSON')
+  .action((options) => graphBuildCommand(options));
+
+graphCommand
+  .command('refresh')
+  .description('Atualização incremental (graphify update) — 2 a 3x mais rápida que o build')
+  .option('-p, --path <path>', 'Target path (default: current directory)')
+  .option('--json', 'Output as JSON')
+  .action((options) => graphBuildCommand({ ...options, refresh: true }));
+
+graphCommand
+  .command('affected <symbol>')
+  .description('Blast radius saneado: quem depende do símbolo. Em frontend responde "quem importa", não "quem chama"')
+  .option('-p, --path <path>', 'Target path (default: current directory)')
+  .option('--prod', 'Descarta consumidores em projeto de teste')
+  .option('--uses-only', 'Só uso real: exclui inherits/implements/extends')
+  .option('--json', 'Output as JSON')
+  .action((symbol, options) => graphAffectedCommand(symbol, options));
+
+graphCommand
+  .command('explain <symbol>')
+  .description('Vizinhança do símbolo com citação arquivo:linha — preferido a query, que trunca por budget')
+  .option('-p, --path <path>', 'Target path (default: current directory)')
+  .option('--json', 'Output as JSON')
+  .action((symbol, options) => graphExplainCommand(symbol, options));
+
 // ─── Validation ───────────────────────────────────────────────────────────
 program
   .command('validate [validator]')
@@ -424,7 +473,7 @@ worktreeCommand
   .command('remove [feature]')
   .description('Safely tear down a worktree (drops infra junctions first, PROVE-or-DECLINE) — does NOT close the feature; that is `finish`')
   .option('--target <path>', 'Remove the worktree at this path (for worktrees with no feature registration)')
-  .option('--discard-ignored', 'Allow removing even though it holds gitignored files that exist nowhere else (e.g. .env) — they are destroyed')
+  .option('--discard-ignored', 'Skip the backup: gitignored files unique to the worktree are deleted instead of copied to .git/morph-spec/finish-backup (by default they are backed up and the removal proceeds anyway)')
   .option('--delete-branch', 'Also delete the branch (default: kept — unintegrated commits live there)')
   .action((feature, options) => worktreeRemoveCommand(feature, options));
 
@@ -434,6 +483,23 @@ worktreeCommand
   .option('--json', 'Output as JSON')
   .action((options) => worktreeListCommand(options));
 
+// ─── Branch housekeeping ──────────────────────────────────────────────────
+// `git branch --merged` cannot see a squash-merge, so the only command left for
+// a squash-merged branch is `git branch -D` — indistinguishable from discarding
+// real work. `prune` makes the distinction itself and deletes only what it
+// proved is already integrated.
+const branchCommand = program
+  .command('branch')
+  .description('Local branch housekeeping');
+
+branchCommand
+  .command('prune')
+  .description('Delete local branches whose work is already in the default branch — including squash-merged ones git cannot see. Never touches a branch with an OPEN PR, one in use by a worktree, or one whose integration could not be proven')
+  .option('--remote', 'Also delete origin/<branch> for each pruned branch (default: remote branches are left alone)')
+  .option('--dry-run', 'Classify and report without deleting anything')
+  .option('--json', 'Output as JSON')
+  .action((options) => branchPruneCommand(options));
+
 // ─── Fleet ────────────────────────────────────────────────────────────────
 program
   .command('fleet')