paqad-ai 0.2.2 → 0.3.0

package/README.md

@@ -63,10 +63,11 @@ npx paqad-ai onboard
 | **Documentation**        | Stack, architecture, design-system, registry, and module documentation flows         |
 | **Hybrid RAG**           | Optional vector indexing, hybrid retrieval, reranking, evals, and benchmarks         |
 | **Security**             | OWASP-mapped pentest workflow with incremental retests                               |
+| **Spec compliance**      | Obligation extraction, test evidence checks, and failing skeleton generation         |
 | **Built-in agent roles** | 20 internal specialist roles for routing, review, design, verification, and security |
 | **Context controls**     | Chunking, scoring, dedup, summarization, and budget enforcement                      |
 | **Pack system**          | Built-in and custom stack packs for framework-specific behavior                      |
-| **Operations**           | `doctor`, `refresh`, `update`, `patterns`, and capability toggles                    |
+| **Operations**           | `doctor`, `compliance`, `refresh`, `update`, `patterns`, and capability toggles      |
 
 ---
 
@@ -276,6 +277,19 @@ Conditional steps, parallel execution, failure handling (`abort` / `skip` / `ret
 
 Verified solutions stored globally at `~/.paqad/patterns/`. Scored by framework overlap + keyword match, staleness penalty after 180 days.
 
+### Spec compliance verification
+
+Structured feature specs can be turned into executable obligation artifacts before implementation starts.
+
+| Workflow                  | What it does                                                                |
+| ------------------------- | --------------------------------------------------------------------------- |
+| **Obligation extraction** | Parses structured Markdown specs into deterministic obligation indexes      |
+| **Compliance checking**   | Scans tests for explicit obligation evidence and reports coverage gaps      |
+| **Skeleton generation**   | Creates failing Vitest stubs from obligations before implementation begins  |
+| **Index doctoring**       | Validates schema version and duplicate IDs before checks or skeleton output |
+
+Compliance artifacts live under `.paqad/compliance/` and are designed so the durable module docs can outlive the original feature spec once the behavior is implemented.
+
 ### Health, refresh, and update workflows
 
 The operational side matters too: paqad-ai keeps generated artifacts and project state from quietly drifting.
@@ -285,6 +299,7 @@ The operational side matters too: paqad-ai keeps generated artifacts and project
 | **Doctor**       | Validates framework artifacts, copied instructions, MCP config, docs, and RAG state |
 | **Refresh**      | Re-detects stack and regenerates stack or design-system outputs                     |
 | **Update**       | Rewrites framework-managed artifacts against the current package version            |
+| **Compliance**   | Extracts spec obligations, checks evidence, generates skeletons, validates indexes  |
 | **Capabilities** | Toggles active capability layers with dependency rules                              |
 | **Patterns**     | Lists, prunes, and exports the global pattern library                               |
 
@@ -368,6 +383,22 @@ paqad-ai doctor
 
 Exits `1` on failure, `0` on pass.
 
+### `paqad-ai compliance`
+
+Spec verification and test-evidence tooling.
+
+```bash
+paqad-ai compliance extract --spec docs/features/spec-compliance-verification.md
+paqad-ai compliance check
+paqad-ai compliance review docs/features/spec-compliance-verification.md
+paqad-ai compliance skeleton --out tests/compliance-skeletons
+paqad-ai compliance doctor
+paqad-ai compliance boundary
+paqad-ai compliance patterns
+```
+
+Use it to persist an obligation index, run spec-quality review, check tests for explicit `@obligation` evidence, generate failing Vitest skeletons, validate index/report health, and run boundary/pattern gap tooling before CI or review.
+
 ### `paqad-ai refresh`
 
 Re-detects stack and regenerates derived artifacts without full re-onboarding.
@@ -496,6 +527,7 @@ your-project/
     ├── rag.ignore.yaml                    # Optional RAG corpus include/exclude rules
     ├── secrets.env                        # Optional API keys for remote RAG providers
     ├── audit.log                          # Build, fallback, and provider mismatch events
+    ├── compliance/                        # Obligation indexes and related compliance artifacts
     ├── doc-progress.json
     ├── pentest/runs/                      # generated when pentest workflows run
     ├── session/                           # Handoff, budget, dedup stats
@@ -515,6 +547,7 @@ Entry files stay thin. Knowledge lives in shared instruction bundles that extern
 | -------------------- | -------------------------------------- | --------------------------------------------------------- |
 | **Onboarding**       | `paqad-ai onboard`                     | Detect stack → confirm → generate everything              |
 | **Health check**     | `paqad-ai doctor`                      | Validate artifacts, config, docs                          |
+| **Spec compliance**  | `paqad-ai compliance ...`              | Extract obligations, check evidence, generate skeletons   |
 | **Refresh**          | `paqad-ai refresh`                     | Re-detect stack, update derived docs                      |
 | **Update**           | `paqad-ai update`                      | Regenerate framework files after version bump             |
 | **RAG**              | `paqad-ai rag ...`                     | Build, inspect, clear, and benchmark hybrid retrieval     |