@alucify/cli 0.6.5 → 0.7.1

package/dist/docs/help/mcp-server/resources/terminology-resource.md

@@ -0,0 +1,74 @@
+---
+order: 1
+title: "Terminology Resource"
+description: "The shared glossary that MCP exposes to Claude Code to prevent naming drift."
+---
+
+# Terminology Resource
+
+In addition to tools, Alucify's MCP server exposes a **resource** that Claude Code can read: your project's shared terminology glossary.
+
+## What It Is
+
+A machine-readable list of the canonical terms, names, and concepts used in your project. It's derived from your [AppGraph](../../concepts/appgraph.md) — every node name, every functional area label, every schema field.
+
+## Why It Matters
+
+Terminology drift is one of the top sources of AI coding mistakes. The agent invents a new name (`user_profile`) when your codebase already has one (`UserAccount`) — and now you've got two concepts where there should be one. The terminology resource lets Claude Code see your glossary before generating code or writing docs, so it uses your terms rather than inventing new ones.
+
+## How Claude Code Uses It
+
+When a session starts, Claude Code reads the terminology resource as part of its context. You'll see it referenced in the session's resource list. The AI naturally prefers existing terms over new ones when the glossary is available.
+
+You can also prompt explicitly:
+> "Check the Alucify terminology before naming the new field."
+
+## Updating the Glossary
+
+The glossary is auto-generated from your current AppGraph. To update it:
+- Run any analysis — code, spec, or progress
+- The resource is refreshed on every analysis completion
+
+There's no manual "update glossary" step.
+
+## Format
+
+The resource content is plain text (structured as an indented outline):
+
+```
+Functional Areas:
+  - Authentication
+    - SSO
+    - Password Reset
+  - Payments
+    ...
+
+Schemas:
+  - UserAccount (id, email, created_at)
+  - Order (id, user_id, total_cents)
+  ...
+```
+
+Claude Code receives this as a single resource body; size scales with your project.
+
+## Toggling the Resource
+
+The resource is enabled by default. To disable it (rare — you'd lose terminology grounding):
+
+Edit `.mcp.json` in your project root and set:
+```json
+{
+  "mcpServers": {
+    "alucify": {
+      "env": {
+        "ALUCIFY_MCP_TERMINOLOGY": "false"
+      }
+    }
+  }
+}
+```
+
+## See Also
+
+- [`find_similar_context`](../tools/find-similar-context.md) — runtime fuzzy search for near-matches
+- [MCP Server Setup](../setup.md)

package/dist/docs/help/mcp-server/setup.md

@@ -0,0 +1,75 @@
+---
+order: 2
+title: "Setting Up the MCP Server for Claude Code"
+description: "How to configure the Alucify MCP server so Claude Code can query your project analysis."
+---
+
+# Setting Up the MCP Server for Claude Code
+
+There are three ways to set up the MCP server, depending on your needs.
+
+## Option 1: Full Integration (Recommended)
+
+```bash
+alucify enable
+```
+
+This installs:
+- MCP server configuration in `.mcp.json`
+- Claude Code hooks for automatic context injection
+- Project rules in `CLAUDE.md`
+- Git post-commit hook for progress tracking
+
+Best for: Teams actively using Alucify for the full workflow.
+
+## Option 2: MCP Server Only (Lightweight)
+
+```bash
+alucify mcp-install
+```
+
+This installs only the MCP server — no hooks, no git integration, no CLAUDE.md changes. A self-contained server file is copied into `.alucify/mcp-server.js` and registered in `.mcp.json`.
+
+Optionally add project rules to CLAUDE.md:
+
+```bash
+alucify mcp-install --with-rules
+```
+
+Best for:
+- Read-only access to an existing analysis
+- Teams where one person runs analysis and others just need MCP access
+- The vendored server can be committed to your repo for zero-install team sharing
+
+## Option 3: NPM Package
+
+Configure `.mcp.json` manually:
+
+```json
+{
+  "mcpServers": {
+    "alucify": {
+      "command": "npx",
+      "args": ["@alucify/mcp"]
+    }
+  }
+}
+```
+
+Best for: Manual setup or custom configurations.
+
+## Verifying Setup
+
+After setup, start a Claude Code session in your project directory. Ask Claude Code a question about your project (e.g., "What screens exist?"). If the MCP server is working, Claude Code will use the Alucify tools to answer.
+
+## How It Works
+
+The MCP server runs as a subprocess communicating with Claude Code via stdio. On each tool call, it reads your latest analysis from `.alucify/` (with 5-second caching for performance). The server is fully read-only — it never modifies your analysis data.
+
+## Removing the MCP Server
+
+```bash
+alucify disable
+```
+
+This removes all integration components but preserves your analysis data in `.alucify/`.

package/dist/docs/help/mcp-server/tools/_meta.json

@@ -0,0 +1 @@
+{ "title": "Tools", "order": 3, "description": "Reference for all MCP tools available to Claude Code" }

package/dist/docs/help/mcp-server/tools/coverage-gaps.md

@@ -0,0 +1,58 @@
+---
+order: 4
+title: "Finding Coverage Gaps"
+description: "How to use the coverage tool to find unimplemented requirements and untested components."
+---
+
+# Finding Coverage Gaps
+
+The `get_remaining_work` tool identifies gaps in your project — requirements without implementations, validations without tests, and orphaned components with no cross-type connections.
+
+## What It Does
+
+Scans your project analysis to find three types of coverage gaps:
+
+1. **Unimplemented requirements** — Requirements that are still planned or have no implementation status
+2. **Untested validations** — Acceptance criteria that haven't been verified with tests
+3. **Orphaned components** — Interfaces, schemas, or logic with no connections to other component types
+
+## Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `type` | string | No | `all` | Focus area: `requirements`, `tests`, or `all` |
+
+## What It Returns
+
+### Summary
+- Overall implementation progress percentage
+- Total requirement, validation, and orphaned component counts
+
+### Requirements Section
+- Per-requirement implementation progress (percentage, done/in-progress/total counts)
+- Implementation gap notes for in-progress components — concrete descriptions of what's missing
+- Validation coverage per requirement (tested / total)
+- Sorted by least-complete first, so the most important gaps surface at the top
+
+### Validations Section
+- Total validation count
+- Count that are tested
+- List of untested validations with a summary of their acceptance criteria
+
+### Orphaned Components
+- Lists of interfaces, schemas, and logic components that have no connections to other component types
+
+## Example Use Cases
+
+| Question | Parameters |
+|----------|------------|
+| "What requirements haven't been implemented?" | `type: "requirements"` |
+| "What's untested?" | `type: "tests"` |
+| "Show me all coverage gaps" | `type: "all"` (or omit) |
+| "Are there any orphaned components?" | `type: "all"` |
+
+## Notes
+
+- Progress is calculated as: `(implemented + in_progress × 0.5) / total`
+- Requirements are sorted by least-complete first to surface the most important gaps
+- Orphaned components are those with no connections to a different component type (e.g., a schema with no connections to any interface or logic)

package/dist/docs/help/mcp-server/tools/find-similar-context.md

@@ -0,0 +1,65 @@
+---
+order: 7
+title: "Finding Similar Concepts"
+description: "How the find_similar_context tool checks for existing terminology in the appgraph."
+---
+
+# Finding Similar Concepts
+
+The `find_similar_context` tool searches the appgraph for nodes whose names match a given term. Use it before introducing new domain language in an artifact to check if the concept already exists under a different name.
+
+## What It Does
+
+Fuzzy-searches all appgraph node names against your input text using Levenshtein-based string similarity (the same algorithm used during artifact integration). Returns ranked matches above a 0.35 similarity threshold.
+
+This prevents the most common congruency issue: terminology drift, where a new artifact calls something "User Profile" when the appgraph already has it as "Account Settings."
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `text` | string | Yes | Candidate term or short phrase to search for |
+| `types` | string[] | No | Filter to specific node types (e.g. `["requirement"]`, `["schema", "interface"]`) |
+| `limit` | number | No | Maximum results to return (default: 5) |
+
+## What It Returns
+
+```json
+{
+  "matches": [
+    {
+      "id": "ns00003",
+      "name": "Invoice",
+      "type": "schema",
+      "similarity": 0.89,
+      "summary": "Billing invoice record"
+    }
+  ]
+}
+```
+
+When no matches meet the threshold:
+
+```json
+{
+  "matches": [],
+  "no_matches_message": "No similar concepts found; this term is new to the graph."
+}
+```
+
+## Example Use Cases
+
+- **Checking entity naming:** `find_similar_context(text: "user account")` — finds "Account" schema node, confirming the graph calls it "Account" not "User Account"
+- **Checking for duplicate features:** `find_similar_context(text: "export invoices as PDF", types: ["requirement"])` — finds "Export invoices as CSV" story, revealing a sibling feature
+- **Broad terminology check:** `find_similar_context(text: "subscription")` — finds all nodes mentioning subscriptions across types
+
+## Related: Terminology Index Resource
+
+The MCP server also exposes an `appgraph://terminology/index` resource — a small JSON document listing the graph's top entity names and existing feature specs. Claude can read this resource for ambient awareness without making individual tool calls. The resource's `usage_hint` field tells Claude when to call `find_similar_context` for deeper lookups.
+
+## Notes
+
+- Similarity uses the same Levenshtein-based algorithm as the integration pipeline's `resolveQuickDecisions`, so author-time checks agree with integration-time matching
+- The 0.35 threshold matches `LOW_SIMILARITY_MERGE_THRESHOLD` — below this, matches are too noisy to be useful
+- Read-only — this tool does not modify the appgraph
+- Names are normalized before comparison (lowercased, punctuation removed) so "User-Profile" matches "user profile"

package/dist/docs/help/mcp-server/tools/get-analysis.md

@@ -0,0 +1,54 @@
+---
+order: 7
+title: "Retrieving Analysis Reports"
+description: "How to use the analysis tool to retrieve congruency, coverage, and quality report summaries."
+---
+
+# Retrieving Analysis Reports
+
+The `get_analysis` tool retrieves summaries of your latest analysis reports — congruency, coverage, or quality — along with scores and top issues.
+
+## What It Does
+
+Locates the most recent analysis report of the requested type and returns a summary, key scores, and the most important issues found.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `report_type` | string | Yes | Type of report: `congruency`, `coverage`, or `quality` |
+| `artifact_name` | string | No | Specific spec name for congruency reports (defaults to the first found) |
+
+## Report Types
+
+### Congruency
+How well a specific spec aligns with your codebase. Returns alignment scores, issues by severity, and the path to the full report.
+
+### Coverage
+Implementation and test coverage across your project. Shows which requirements have implementations and which validations have tests.
+
+### Quality
+A synthesis of findings across all analysis dimensions. Includes priority actions and overall quality assessment.
+
+## What It Returns
+
+- **Report existence** — Whether the requested report was found
+- **Summary** — The first ~500 characters of the report
+- **Full report path** — Absolute path to the complete report file for deeper reading
+- **Scores** — Key metric scores from the report
+- **Top issues** — Up to 5 highest-severity issues found
+
+## Example Use Cases
+
+| Question | Parameters |
+|----------|------------|
+| "How well does our PRD align with code?" | `report_type: "congruency"` |
+| "What's our test coverage look like?" | `report_type: "coverage"` |
+| "What are the top quality issues?" | `report_type: "quality"` |
+| "Show congruency for api-spec.md" | `report_type: "congruency", artifact_name: "api-spec"` |
+
+## Notes
+
+- Returns a graceful "not found" response if the requested report doesn't exist
+- The full report path can be used to read the complete report for more detail
+- Reports are generated during spec analysis — run `analyze-specs` to create them

package/dist/docs/help/mcp-server/tools/get-details.md

@@ -0,0 +1,48 @@
+---
+order: 2
+title: "Getting Detailed Component Info"
+description: "How to retrieve full details for a specific component in your project model."
+---
+
+# Getting Detailed Component Info
+
+The `get_context` tool retrieves the full details of a specific component, including its complete description, source references, and connections.
+
+## What It Does
+
+Given a component ID, returns all available information about that component — its definition, implementation status, source files, and every other component it connects to.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `node_id` | string | Yes | The component ID (e.g., `ni00012`, `ns00003`, `nl00008`, `nr00045`, `nv00023`) |
+
+Component IDs are returned by the [query tool](query.md) and other tools. The ID prefix indicates the type:
+- `ni` — Interface
+- `ns` — Schema
+- `nl` — Logic
+- `nr` — Requirement
+- `nv` — Validation
+
+## What It Returns
+
+- **All component fields** — Name, description, type, subtype, implementation status
+- **Source references** — Primary source file and additional code references
+- **Grounding information** — How well the component is anchored in specifications
+- **Connected components** — Every component this one connects to, with the relationship type and direction (incoming/outgoing), prioritized by edge type
+- **Type-specific content** — Detailed definitions specific to the component type
+- **Implementation gaps** (requirement nodes only) — Lists unimplemented components, in-progress components with gap notes, and untested validations under this requirement
+
+## Example Use Cases
+
+| Question | How Claude Code uses this tool |
+|----------|-------------------------------|
+| "Tell me about the user model" | Queries for "user" → gets ID → calls `get_context` for full details |
+| "What connects to the auth service?" | Gets full node details including all incoming and outgoing connections |
+| "Show me requirement nr00045" | Directly calls `get_context` with the known ID |
+
+## Notes
+
+- Use the [query tool](query.md) first to find component IDs, then this tool for full details
+- Returns all connections in both directions (what this component depends on, and what depends on it)

package/dist/docs/help/mcp-server/tools/impact-analysis.md

@@ -0,0 +1,49 @@
+---
+order: 3
+title: "Analyzing Blast Radius from File Changes"
+description: "How to use the impact tool to see which components are affected by file changes."
+---
+
+# Analyzing Blast Radius from File Changes
+
+The `trace_dependencies` tool shows the blast radius of file changes — which components are directly affected and what depends on them transitively.
+
+## What It Does
+
+Given a list of file paths, finds all project components mapped to those files, then traces outward through dependencies to show the full impact chain (up to 3 hops).
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `file_paths` | string[] | Yes | File paths relative to your workspace root |
+
+## What It Returns
+
+- **Directly affected components** — Components mapped to the changed files, with the reason for the match (source file or code reference)
+- **Blast radius summary** — Counts of direct impacts, transitive impacts, and affected connections
+  - `direct` — Components directly mapped to the changed files
+  - `transitive` — Components reachable within 3 hops through dependencies
+  - `affected_edges` — Total number of connections touching any affected component
+
+## Example Use Cases
+
+| Question | Parameters |
+|----------|------------|
+| "What breaks if I change user.ts?" | `file_paths: ["src/models/user.ts"]` |
+| "Impact of my current changes" | `file_paths: ["src/auth.ts", "src/routes/login.ts"]` |
+| "Is it safe to refactor this file?" | `file_paths: ["src/utils/validators.ts"]` |
+
+## How Matching Works
+
+The tool matches files to components using both:
+- **Source file** — The primary implementation file of a component
+- **Code references** — Additional files that a component references
+
+Path matching is flexible — `src/models/user.ts` will match a component with source file `models/user.ts` and vice versa.
+
+## Notes
+
+- Transitive impact uses breadth-first traversal up to 3 hops
+- This is a read-only analysis — no changes are made
+- Use this tool before making cross-cutting changes to understand the full impact chain

package/dist/docs/help/mcp-server/tools/implementation-tasks.md

@@ -0,0 +1,68 @@
+---
+order: 5
+title: "Getting Implementation Tasks"
+description: "How to get a per-requirement task list of what needs to be implemented, fixed, or tested."
+---
+
+# Getting Implementation Tasks
+
+The `get_implementation_tasks` tool returns a task list for a specific requirement — what components need implementation, which are in-progress with specific gaps, and which validations need tests.
+
+## What It Does
+
+Given a requirement ID, returns three categories of work:
+
+1. **Unimplemented components** — Components linked to this requirement that have no implementation yet, with their source files and descriptions
+2. **In-progress components** — Components with partial implementations, including the specific **implementation gap** describing what's missing (e.g., "has GET handler but missing POST/DELETE branches")
+3. **Untested validations** — Acceptance criteria under this requirement that don't have test coverage yet, including their Gherkin definitions
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `requirement_id` | string | Yes | The requirement node ID (e.g., `nr00012`) |
+
+## What It Returns
+
+```json
+{
+  "requirement": "Enforce Delete Permission for Projects & Flows",
+  "unimplementedNodes": [
+    {
+      "id": "nl02136",
+      "name": "Delete Permission Enforcement",
+      "type": "logic",
+      "sourceFile": "src/services/rbac/permissions.py",
+      "description": "...",
+      "action": "Implement this component"
+    }
+  ],
+  "inProgressNodes": [
+    {
+      "id": "nl02137",
+      "name": "Owner Role Enforcement",
+      "type": "logic",
+      "sourceFile": "src/models/rbac/model.py",
+      "implementationGap": "Missing scope check before mutation",
+      "action": "Fix: Missing scope check before mutation"
+    }
+  ],
+  "untestedValidations": [
+    {
+      "id": "nv00045",
+      "name": "AC: Non-owner cannot delete",
+      "gherkin": "Given a user with editor role..."
+    }
+  ]
+}
+```
+
+## How It's Used
+
+The `/alucify-plan` skill calls this tool for every incomplete requirement when building an implementation plan. The gap notes from in-progress components are cited verbatim in the plan, so the coding agent knows exactly what to fix.
+
+## Notes
+
+- Returns empty arrays if the requirement is fully implemented and tested
+- Gap notes are produced by the progress analysis classifier — they describe specific missing methods, branches, fields, or checks
+- Use `get_remaining_work` first to find which requirements are incomplete, then this tool for per-requirement detail

package/dist/docs/help/mcp-server/tools/link-node.md

@@ -0,0 +1,51 @@
+---
+order: 8
+title: "Linking Nodes to Files"
+description: "How to link appgraph nodes to their implementation files for progress tracking."
+---
+
+# Linking Nodes to Files
+
+The `link_context` tool links an appgraph node to the file that implements it. This is the only MCP tool that modifies the appgraph.
+
+## What It Does
+
+Sets the `source_file` and adds to `codeRefs` on the specified node, so Analyze Progress can mechanically match the file to the node in future runs. Without this link, progress tracking relies on LLM-based matching which can miss connections.
+
+Linking also promotes the node's implementation status:
+- **Implementation nodes** (interface, schema, logic) with no status or `planned` status are promoted to `in_progress`
+- **Validation nodes** with no status or `planned` status are promoted to `implemented` (linking a test file means the test exists)
+- Nodes that already have a status (`in_progress`, `implemented`) are not changed
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `node_id` | string | Yes | The appgraph node ID (e.g., `flow:read-permission-enforcement`, `entity:user`) |
+| `file_path` | string | Yes | Relative path to the file that implements this node |
+
+## When to Use It
+
+Call this tool **after implementing a node** — right after you create or modify the file that satisfies a spec node. The `/alucify-plan` skill prompts you to do this for every node you implement.
+
+## Example
+
+After implementing permission enforcement in `src/services/rbac/permissions.py`:
+
+> "Link the read permission enforcement node to its implementation file"
+>
+> Claude calls: `link_context(node_id: "flow:read-permission-enforcement", file_path: "src/services/rbac/permissions.py")`
+
+## What It Returns
+
+```json
+{
+  "linked": true,
+  "node_id": "flow:read-permission-enforcement",
+  "file_path": "src/services/rbac/permissions.py",
+  "previous_source_file": null,
+  "codeRefs": ["src/services/rbac/permissions.py"]
+}
+```
+
+If the node ID doesn't exist, it returns an error message instead.

package/dist/docs/help/mcp-server/tools/query.md

@@ -0,0 +1,53 @@
+---
+order: 1
+title: "Searching Your Project Model"
+description: "How to use the query tool to search for components by type, name, or status."
+---
+
+# Searching Your Project Model
+
+The `query_context` tool lets Claude Code search your project for specific components by type, name, status, or subtype.
+
+## What It Does
+
+Searches your project analysis and returns compact summaries of matching components — their names, descriptions, implementation status, and source files.
+
+## Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `type` | string | No | — | Filter by component type: `interface`, `schema`, `logic`, `requirement`, `validation` |
+| `subtype` | string | No | — | Filter by subtype (e.g., `screen`, `core`, `epic`, `story`) |
+| `name_pattern` | string | No | — | Case-insensitive substring match on component name |
+| `status` | string | No | — | Filter by implementation status: `planned`, `in_progress`, `implemented`, `tested` |
+| `limit` | number | No | 20 | Maximum number of results to return |
+
+All filters are combined with AND logic — only components matching all specified criteria are returned.
+
+## What It Returns
+
+For each matching component:
+- ID and type
+- Name and description (truncated to 200 characters)
+- Implementation status
+- Implementation gap (for in-progress components — describes what's missing)
+- Source file path
+- Number of connections to other components
+
+Results are sorted by number of connections (most connected first).
+
+## Example Use Cases
+
+| Question | Parameters |
+|----------|------------|
+| "What screens exist?" | `type: "interface", subtype: "screen"` |
+| "Find anything related to auth" | `name_pattern: "auth"` |
+| "What's still planned?" | `status: "planned"` |
+| "Show me data models" | `type: "schema"` |
+| "What requirements are tested?" | `type: "requirement", status: "tested"` |
+
+## Notes
+
+- Claude Code calls this tool automatically when you ask relevant questions
+- This is a read-only operation — it never modifies your analysis
+- The tool queries the latest analysis data (cached for 5 seconds)

package/dist/docs/help/mcp-server/tools/tools-reference.md

@@ -0,0 +1,63 @@
+---
+order: 1
+title: "Tools Reference"
+description: "Quick reference for every MCP tool Alucify exposes to Claude Code."
+---
+
+# MCP Tools Reference
+
+A one-page reference for every tool Alucify's MCP server exposes to Claude Code. Click any tool name for full parameters and examples.
+
+## Querying
+
+| Tool | Purpose |
+|---|---|
+| [`query_context`](query.md) | Search nodes by type, subtype, name, status, limit |
+| [`get_context`](get-details.md) | Full details on a single node (by ID) |
+| [`find_similar_context`](find-similar-context.md) | Fuzzy name search (prevents terminology drift) |
+
+## Analysis
+
+| Tool | Purpose |
+|---|---|
+| [`trace_dependencies`](impact-analysis.md) | Blast radius — files → affected nodes, 3 hops |
+| [`get_analysis`](get-analysis.md) | Congruency / coverage / quality reports |
+| [`get_remaining_work`](coverage-gaps.md) | Unimplemented requirements, untested validations |
+| [`get_implementation_tasks`](implementation-tasks.md) | Per-requirement task list with gap notes |
+
+## Planning & Validation
+
+| Tool | Purpose |
+|---|---|
+| [`verify_plan`](verify-plan.md) | Mechanical checks on a plan (IDs, coverage, drift) |
+| [`diff_context`](version-diff.md) | Diff two AppGraph versions |
+
+## Write (use carefully)
+
+| Tool | Purpose |
+|---|---|
+| [`link_context`](link-node.md) | Link a node to an implementation file; promotes status |
+
+All tools except `link_context` are read-only. `link_context` writes to the current AppGraph and should be called intentionally — typically when you've just implemented something and want to mark the link.
+
+## Typical Compositions
+
+**Understanding impact before a change:**
+1. `trace_dependencies` on the file(s) you're about to touch
+2. `get_context` on the returned high-impact nodes
+3. Proceed with implementation knowing the blast radius
+
+**Planning new work:**
+1. `get_remaining_work` — what's open?
+2. `get_implementation_tasks` — what does closing each gap look like?
+3. `verify_plan` — mechanical validation before presenting to the user
+
+**Preventing terminology drift:**
+1. `find_similar_context` on the name you're about to coin
+2. If a similar node exists, use its exact name rather than creating a duplicate
+
+## See Also
+
+- [MCP Server Setup](../setup.md)
+- [Using MCP with Claude Code](../using-with-claude-code.md)
+- [Claude Code Integration](../../integrations/claude-code.md)