pmat 3.16.0

PMAT - Zero-config AI context generation and code quality toolkit (CLI, MCP, HTTP)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

# Documentation

> Sub-spec of [pmat-spec.md](../pmat-spec.md) | Component 15

## Documentation Accuracy Enforcement

### Zero Hallucination Policy

All documentation (README.md, CLAUDE.md, GEMINI.md, AGENT.md) must be validated:

```bash
pmat context --output deep_context.md --format llm-optimized
pmat validate-readme \
    --targets README.md CLAUDE.md GEMINI.md AGENT.md \
    --deep-context deep_context.md \
    --fail-on-contradiction --verbose
```

### Validation Checks

| Check | Description |
|-------|-------------|
| Capability claims | Verified against AST (functions exist) |
| File path references | Verified against filesystem |
| Function references | Verified against index |
| External URLs | 404 detection via HTTP HEAD |
| Version numbers | Cross-referenced with Cargo.toml |

### Academic Foundations

- Semantic Entropy (Nature 2024): Detects hallucinated claims
- MIND framework (IJCAI 2025): Multi-dimensional inconsistency detection

## CLI/MCP Documentation Enforcement

Quality gate for documentation completeness:
- All CLI commands must have --help text
- All MCP tools must have descriptions
- All HTTP endpoints must have schema docs

## Link Validation

```bash
pmat doc-validate --check-links README.md
```

- Validates internal links (relative paths)
- Validates external links (HTTP HEAD requests)
- Reports broken anchors and 404s

## Toyota Way Addendum

Documentation follows Toyota Way principles:
- **Genchi Genbutsu**: Go see the actual code, don't guess
- **Jidoka**: Stop-the-line on documentation errors
- **Kaizen**: Continuous improvement of docs with each release

## Enforcement Points

| Hook | Check | Blocking |
|------|-------|----------|
| Pre-commit | Link validation | Warning |
| CI pipeline | Full accuracy validation | Error |
| Release | All docs validated | Blocking |

## PMAT Book: Falsified Provable Contracts

### Schema

Each book chapter has a provable contract YAML in `contracts/` following
the aprender pattern. The contract defines **what must be falsifiable**
about the chapter — no claim exists without a test.

```
contracts/
  pmat-book-build-v1.yaml       # Build + deploy contract (mdbook, CI)
  pmat-book-ch05-v1.yaml        # file:ch05 — Analyze Suite (critical)
  pmat-book-ch07-v1.yaml        # file:ch07 — Quality Gates (critical)
  pmat-book-ch13-v1.yaml        # file:ch13 — Multi-Language Examples (critical)
  pmat-book-ch35-v1.yaml        # file:ch35 — Semantic Search / pmat query (critical)
```

**Naming convention**: Contract filenames match the SOURCE FILE identifier
(`ch05`, `ch07`, `ch13`, `ch35`), NOT the SUMMARY.md chapter number.
The `chapter_file` field is the authoritative path to the .md source.

### Contract Structure (Per Chapter)

```yaml
metadata:
  contract: pmat-book-ch{NN}
  title: "Chapter Title"
  chapter_file: ch{NN}-00-topic.md
  critical: true/false

preconditions:
  - "pmat binary installed"
  - "pmat {command} --help exits 0"

postconditions:
  - "All CLI examples in chapter produce valid output"

falsification:
  - condition: "pmat {command} exits non-zero on test project"
    severity: P0
    action: reject_chapter
  - condition: "Chapter claims feature not in pmat --help"
    severity: P0
    action: reject_chapter
```

### Enforcement

| Gate | Check | Action |
|------|-------|--------|
| `make validate-book` | Critical chapters (5, 7, 13, 14) | Blocks release |
| Pre-push hook | `pmat comply check` includes CB-148 | Warning |
| CI | `mdbook build` + falsification tests | Blocks merge |

### Falsification Principles (Popperian)

1. **Every claim is testable**: If a chapter says "pmat query supports
   --contracts", there's a falsification test that runs the command.
2. **P0 = reject**: Any P0 falsification failure blocks the chapter.
3. **Examples are code**: CLI examples in chapters are extracted and
   run as tests. Stale output = P1 failure.
4. **No stubs**: Chapters with <50 words are rejected (P0).

## Key Files

| File | Purpose |
|------|---------|
| `src/cli/handlers/readme_validate_handlers/` | README validation (module) |
| `src/services/doc_validator.rs` | Link and reference checking |
| `contracts/pmat-book-build-v1.yaml` | Book build/deploy contract |
| `contracts/pmat-book-ch{NN}-v1.yaml` | Per-chapter falsification contracts (ch05, ch07, ch13, ch35) |

## References

- Consolidated from: CLI_MCP_DOCUMENTATION_ENFORCEMENT, documentation-accuracy-enforcement,
  documentation-accuracy-enforcement-toyota-way-addendum, doc-validate