# MCP Tool Specification: validate_documentation

## Status: FUTURE

> This tool does not yet exist in SmartStack.mcp. This file is a specification for its implementation.
> Until implemented, use the `docs-sync-checker` agent as a fallback.

## Tool Definition

```typescript
{
  name: "mcp__smartstack__validate_documentation",
  description: "Validate documentation freshness, completeness, and accuracy for SmartStack modules",
  parameters: {
    module: {
      type: "string",
      description: "Module path (e.g., 'business/support/sla'). Empty for all modules.",
      required: false
    },
    checkType: {
      type: "string",
      enum: ["freshness", "completeness", "accuracy", "all"],
      default: "all",
      description: "Type of validation to perform"
    },
    path: {
      type: "string",
      description: "Project path (default: SmartStack.app path from config)",
      required: false
    }
  }
}
```

## Check Types

### freshness
Compare `docs-manifest.json` with git history to detect stale documentation.

**Input:** manifest entries, git log
**Logic:**
```
FOR each module in manifest:
  lastCodeCommit = git log -1 --format="%aI" -- {codeFiles}
  IF lastCodeCommit > module.lastDocUpdate:
    status = "drift"
    driftDays = daysBetween(module.lastDocUpdate, lastCodeCommit)
```

**Output:**
```json
{
  "modules": [
    {
      "path": "business/support/sla",
      "status": "drift",
      "driftDays": 15,
      "lastCodeChange": "2026-01-28",
      "lastDocUpdate": "2026-01-13"
    }
  ]
}
```

### completeness
Verify that documented modules have all 8 business-first sections.

**Input:** doc-data.ts files, i18n JSON files
**Logic:**
```
FOR each module with documentation:
  Read doc-data.ts
  Check presence of:
    1. overview (valeur métier)
    2. useCases (cas d'usage)
    3. benefits (bénéfices concrets) — in i18n
    4. beforeAfter (avant/après) — in i18n
    5. features (fonctionnalités)
    6. steps (comment ça marche)
    7. faq (FAQ métier) — in i18n
    8. technicalRef (référence technique)
  Report missing sections
```

**Output:**
```json
{
  "modules": [
    {
      "path": "business/support/sla",
      "completeness": "6/8",
      "missingSections": ["beforeAfter", "faq"],
      "i18nComplete": { "fr": true, "en": false, "it": false, "de": false }
    }
  ]
}
```

### accuracy
Compare documented permissions, endpoints, and entities against actual code.

**Input:** doc-data.ts, controllers, PermissionConfiguration.cs, entities
**Logic:**
```
FOR each module:
  documentedPermissions = docData.permissions
  actualPermissions = scan PermissionConfiguration.cs for module path
  IF documentedPermissions != actualPermissions:
    issues.push("permission mismatch")

  documentedEndpoints = docData.apiEndpoints
  actualEndpoints = scan Controller for [Http*] attributes
  IF documentedEndpoints != actualEndpoints:
    issues.push("endpoint mismatch")

  documentedEntities = docData (entity references)
  actualEntities = scan Domain/Entities for module
  IF documentedEntities != actualEntities:
    issues.push("entity mismatch")
```

**Output:**
```json
{
  "modules": [
    {
      "path": "business/support/sla",
      "accuracy": "partial",
      "issues": [
        {
          "type": "endpoint_mismatch",
          "documented": ["GET /api/business/sla", "POST /api/business/sla"],
          "actual": ["GET /api/business/sla", "POST /api/business/sla", "PATCH /api/business/sla/{id}/status"],
          "message": "Endpoint PATCH /api/business/sla/{id}/status exists in code but not in documentation"
        }
      ]
    }
  ]
}
```

## Combined Output (checkType: "all")

```json
{
  "summary": {
    "totalModules": 5,
    "synced": 2,
    "drift": 2,
    "missing": 1,
    "overallScore": "60%"
  },
  "modules": [
    {
      "path": "business/support/sla",
      "freshness": { "status": "drift", "driftDays": 15 },
      "completeness": { "score": "6/8", "missingSections": ["beforeAfter", "faq"] },
      "accuracy": { "status": "partial", "issues": 1 }
    }
  ],
  "recommendations": [
    "Run `/documentation` for business/support/sla to sync documentation",
    "Run `/business-analyse` for business/support/tickets to create documentation"
  ]
}
```

## Integration Points

| Consumer | When | Fallback |
|----------|------|----------|
| BA step-04 (validate) | During specification validation | Read manifest + git log |
| Drift hook (pre-commit) | Before commit | Bash script reading manifest |

## Implementation Notes

- Tool should read `docs-manifest.json` from project root
- Must handle missing manifest gracefully (return "no manifest" status)
- Git operations should use `--no-pager` flag
- Performance: cache git log results across modules
- The tool should be idempotent (no side effects)
