@valentia-ai-skills/framework 2.0.6 → 2.0.8

package/README.md

@@ -58,10 +58,26 @@ npx ai-skills status         # Show installed entities, team info, detected tool
 npx ai-skills list           # List locally bundled skills
 npx ai-skills analyze        # Analyze staged/last commit against active skills
 npx ai-skills analyze --last # Analyze the most recent commit
+npx ai-skills upload-code-audit --path ./CodeMatters/  # Upload a CodeMatters audit package
+npx ai-skills audit-status --project "My Project"      # Show latest audit summary for a project
 npx ai-skills doctor         # Health check (config, API, tools, entity counts)
 npx ai-skills help           # Show help
 ```
 
+#### Code Quality Audits
+
+```bash
+# Upload a CodeMatters audit package to the Skills Console
+npx ai-skills upload-code-audit --path ./CodeMatters/
+npx ai-skills upload-code-audit --path ./CodeMatters/ --dry-run   # validate only
+npx ai-skills upload-code-audit --path ./CodeMatters/ --token <token>
+
+# Show the latest audit summary for a project in the terminal
+npx ai-skills audit-status --project "Clinical Sanctuary"
+```
+
+The `--path` directory for `upload-code-audit` must contain a `manifest.json` file and the generated markdown reports from the `code-quality-auditor` skill. See the [Code Quality Audits](#code-quality-audits) section below for the expected format.
+
 #### Legacy Codebase Intelligence Scanner
 
 ```bash
@@ -70,9 +86,9 @@ npx ai-skills upload-legacy-scan --path ./my-project-intelligence/
 npx ai-skills upload-legacy-scan --path ./my-project-intelligence/ --dry-run   # validate only
 npx ai-skills upload-legacy-scan --path ./my-project-intelligence/ --token <token>
 
-# Download a project's skills from the console → install into your local AI tools
+# Download a project → recreates exact intelligence folder structure (modules/, diagrams/, reports)
 npx ai-skills legacy-projects add "My Project"
-npx ai-skills legacy-projects add "My Project" --path ./output-dir/  # also save raw files locally
+npx ai-skills legacy-projects add "My Project" --path ~/projects/  # save to a specific directory
 
 # List all legacy projects for your team
 npx ai-skills legacy-projects list
@@ -93,6 +109,8 @@ The `--path` directory for `upload-legacy-scan` must contain a `manifest.json` f
 | `AI_SKILLS_API_URL` | Override the Supabase Edge Function URL |
 | `AI_SKILLS_ANALYZE_URL` | Override the analyze commit function URL |
 | `AI_SKILLS_SCAN_URL` | Override the scan results function URL |
+| `AI_SKILLS_UPLOAD_CODE_AUDIT_URL` | Override the upload-code-audit Edge Function URL |
+| `AI_SKILLS_MANAGE_CODE_AUDITS_URL` | Override the manage-code-audits Edge Function URL |
 | `AI_SKILLS_UPLOAD_LEGACY_URL` | Override the upload-legacy-scan Edge Function URL |
 | `AI_SKILLS_MANAGE_LEGACY_URL` | Override the manage-legacy-projects Edge Function URL |
 
@@ -279,6 +297,121 @@ A post-commit git hook is automatically installed during setup to run analysis a
 
 ---
 
+## Code Quality Audits
+
+The framework supports ingesting audit packages generated by the `code-quality-auditor` skill. Once uploaded, the audit becomes reviewable in the **Skills Console** under the **Code Audits** section, with score history preserved per project.
+
+### How It Works
+
+1. **Audit** — Run the `code-quality-auditor` skill against a codebase and generate a `CodeMatters/` folder
+2. **Upload** — `npx ai-skills upload-code-audit --path <folder>` sends the package to the Skills Console and creates a new historical audit entry
+3. **Review** — Tech leads review the latest audit in the **Code Audits** section, update review status, and compare it against previous runs
+4. **Track** — The console keeps score trends, finding counts, report tabs, diagrams, and remediation guidance per project
+5. **Check** — Developers can run `npx ai-skills audit-status --project <name>` to see the latest audit summary in the terminal
+
+### CodeMatters Package Format
+
+The folder passed to `--path` should follow this layout:
+
+```text
+CodeMatters/
+├── manifest.json
+├── CODE_AUDIT_OVERVIEW.md
+├── SECURITY_AUDIT.md
+├── ERROR_HANDLING.md
+├── CORRECTNESS.md
+├── CRASH_RISK.md
+├── CODE_QUALITY.md
+├── STANDARDS.md
+├── PERFORMANCE.md
+├── MAINTAINABILITY.md
+├── DEPENDENCY_HEALTH.md
+├── ACCESSIBILITY.md
+├── TEST_COVERAGE.md
+├── ARCHITECTURE.md
+├── FRAMEWORK_REVIEW.md
+├── REMEDIATION_PLAN.md
+└── *.mmd / *.mermaid   # optional diagrams
+```
+
+**Canonical `manifest.json` shape:**
+
+```json
+{
+  "project_name": "Clinical Sanctuary",
+  "audited_at": "2026-04-02T12:00:00.000Z",
+  "overall_score": 48,
+  "overall_grade": "D",
+  "tech_stack": {
+    "language": "TypeScript",
+    "framework": "React",
+    "runtime_version": "Node 20"
+  },
+  "is_healthcare": true,
+  "findings": {
+    "critical": 5,
+    "high": 5,
+    "medium": 5,
+    "low": 18,
+    "total": 33
+  },
+  "scores": {
+    "security": { "score": 42, "grade": "F", "finding_count": { "critical": 5, "high": 5, "medium": 5, "low": 18 } },
+    "error_handling": { "score": 55, "grade": "D", "finding_count": { "critical": 0, "high": 1, "medium": 4, "low": 3 } },
+    "correctness": { "score": 65, "grade": "C", "finding_count": { "critical": 0, "high": 1, "medium": 3, "low": 2 } },
+    "crash_risk": { "score": 50, "grade": "D", "finding_count": { "critical": 0, "high": 2, "medium": 2, "low": 1 } },
+    "code_quality": { "score": 72, "grade": "C", "finding_count": { "critical": 0, "high": 0, "medium": 2, "low": 6 } },
+    "standards": { "score": 60, "grade": "C", "finding_count": { "critical": 0, "high": 0, "medium": 2, "low": 4 } },
+    "performance": { "score": 65, "grade": "C", "finding_count": { "critical": 0, "high": 0, "medium": 2, "low": 3 } },
+    "maintainability": { "score": 68, "grade": "C", "finding_count": { "critical": 0, "high": 0, "medium": 1, "low": 5 } },
+    "dependency_health": { "score": 35, "grade": "F", "finding_count": { "critical": 0, "high": 3, "medium": 1, "low": 2 } },
+    "accessibility": { "score": 55, "grade": "D", "finding_count": { "critical": 0, "high": 0, "medium": 3, "low": 4 } },
+    "test_coverage": { "score": 0, "grade": "F", "finding_count": { "critical": 0, "high": 0, "medium": 0, "low": 6 } },
+    "architecture": { "score": 72, "grade": "C", "finding_count": { "critical": 0, "high": 0, "medium": 1, "low": 2 } }
+  }
+}
+```
+
+The uploader is slightly defensive around aliases such as `project`, `name`, `overallScore`, `overallGrade`, `auditedAt`, `category_scores`, and `categories`, but the shape above is the supported v1 contract.
+
+### Skills Console — Code Audits View
+
+After upload, each project appears in the **Code Audits** section with:
+
+| View | Contents |
+|------|----------|
+| **List** | Latest audit per project, score bars, severity totals, status, delta vs previous |
+| **Detail** | Score breakdown, comparison panel, audit history chart, review status, reviewer notes |
+| **Report Tabs** | Overview, category reports, remediation plan, diagrams |
+| **All Files** | Full file list with filtering and inline preview |
+
+### CLI Commands
+
+```bash
+# Upload a new audit run (history is preserved)
+npx ai-skills upload-code-audit --path ./CodeMatters/
+
+# Validate the payload without uploading
+npx ai-skills upload-code-audit --path ./CodeMatters/ --dry-run
+
+# Show the latest audit summary for a project
+npx ai-skills audit-status --project "Clinical Sanctuary"
+```
+
+### Deployment Requirements
+
+To enable Code Audits in a deployed environment, you need to ship the backend pieces and the updated console:
+
+1. Run the new Supabase migration: `skills-console/supabase/migrations/015_code_audits.sql`
+2. Deploy the new Edge Functions:
+   `supabase functions deploy upload-code-audit`
+   `supabase functions deploy manage-code-audits`
+3. Redeploy the Skills Console frontend so `/code-audits` and `/code-audits/:id` are available
+
+The `upload-code-audit` function will attempt to create and use the `code-audits` Storage bucket automatically as a best-effort backup mirror. Postgres remains the source of truth even if the storage mirror is unavailable.
+
+---
+
 ## Legacy Codebase Intelligence Scanner
 
 The framework supports ingesting intelligence packages generated by legacy codebase scanners. Once uploaded, the extracted skills, architecture diagrams, and reports become reviewable in the **Skills Console** under the **Legacy Scanners** section.
@@ -288,8 +421,8 @@ The framework supports ingesting intelligence packages generated by legacy codeb
 1. **Scan** — A compatible scanner tool analyses an existing codebase and produces an intelligence folder
 2. **Upload** — `npx ai-skills upload-legacy-scan --path <folder>` ships the intelligence package to your team's Skills Console, creating or refreshing the project
 3. **Review** — Tech leads review auto-generated skills, reports, and diagrams in the Skills Console, approving or flagging each document
-4. **Install** — Developers run `npx ai-skills legacy-projects add <project-name>` to download approved skills from the console and have them installed into their local AI tools automatically
-5. **Code** — AI tools (Claude Code, Cursor, Copilot, Windsurf) now have full context about the legacy project's patterns
+4. **Download** — Developers run `npx ai-skills legacy-projects add <project-name>` to reconstruct the full intelligence package folder locally — identical structure to the original scan output (`modules/`, `diagrams/`, report `.md` files, `manifest.json`)
+5. **Code** — AI tools (Claude Code, Cursor, Copilot, Windsurf) can now read the local package using the project's legacy-reading skills
 6. **Rescan** — Re-running `upload-legacy-scan` on the same project name replaces all documents with the latest scan output
 
 ### Intelligence Package Format
@@ -310,24 +443,35 @@ my-project-intelligence/
     ├── api-registry.md
     ├── business-rules.md
     ├── risk-assessment.md
-    └── reproduction-guide.md
+    ├── reproduction-guide.md
+    └── custom-audit-findings.md
 ```
 
 **`manifest.json` schema:**
 
 ```json
 {
-  "project_name": "legacy-billing-service",
-  "tech_stack": ["Node.js", "PostgreSQL", "React"],
+  "project": "legacy-billing-service",
+  "scanned_at": "2026-03-30T12:00:00.000Z",
+  "skills": [],
   "statistics": {
-    "module_count": 24,
-    "total_endpoints": 68,
-    "total_business_rules": 142,
+    "total_modules": 24,
     "completeness_score": 78
+  },
+  "reports": [
+    { "document_type": "api_registry", "file": "reports/api-registry.md" },
+    { "document_type": "custom_audit_findings", "name": "Custom Audit Findings", "file": "reports/custom-audit-findings.md", "type": "report" }
+  ],
+  "tech_stack": {
+    "language": "Node.js",
+    "database": "PostgreSQL",
+    "frontend": "React"
   }
 }
 ```
 
+Any extra markdown file in `reports/` is uploaded as a `report` document automatically, even if it is not one of the built-in report names. If you want explicit control, add it to `manifest.json -> reports`; custom entries must use `type: "report"`. Built-in `overview` and `reproduction_guide` remain guide documents.
+
 ### Skills Console — Legacy Scanners View
 
 After upload, each project appears in the **Legacy Scanners** section of the Skills Console with five tabs:
@@ -348,9 +492,9 @@ Approved skills are promoted into the team's standard toolkit and distributed on
 # Upload a scan package (add new project or replace existing)
 npx ai-skills upload-legacy-scan --path ./my-project-intelligence/
 
-# Download a project's skills and install them into your local AI tools
-npx ai-skills legacy-projects add "My Project"
-npx ai-skills legacy-projects add "My Project" --path ./output/  # also write raw files locally
+# Download a project → recreates the exact intelligence package folder structure locally
+npx ai-skills legacy-projects add "Clinical Sanctuary"
+npx ai-skills legacy-projects add "Clinical Sanctuary" --path ~/projects/  # save to specific dir
 
 # List all projects with status, module count, and completeness score
 npx ai-skills legacy-projects list