@polymorphism-tech/morph-spec 8.28.0 → 8.31.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:
@@ -115,6 +115,11 @@ When modifying framework components, verify the full scope of related files.
 | `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/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.28.0  
+**Version:** 8.31.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.28.0 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v8.31.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -47,6 +47,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 +291,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]')