feat: implement document subsystem audit recommendations

.agents/skills/catalog.json

@@ -3,7 +3,20 @@
   "categories": [
     {
       "name": "Everyday",
-      "skills": ["skills", "plan", "run", "test", "fix", "review", "task", "handover", "health", "audit", "export"]
+      "skills": [
+        "skills",
+        "plan",
+        "run",
+        "test",
+        "fix",
+        "review",
+        "task",
+        "handover",
+        "health",
+        "audit",
+        "export",
+        "prompt-perfector"
+      ]
     },
     {
       "name": "Clinical and app",

.agents/skills/prompt-perfector/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: prompt-perfector
+description: Refine, structure, and optimize user prompts for LLMs while ensuring execution occurs in a isolated environment. Use when asked to polish, perfect, or evaluate prompts safely.
+---
+
+# Prompt Perfector
+
+Refines user prompts into structured, highly effective instructions and executes evaluation tasks in an isolated workspace (`Workspace: "branch"`).
+
+## Core Capabilities
+
+1. **Prompt Refinement**: Analyzes input prompts for clarity, context, constraints, output format specifications, and edge cases.
+2. **Environment Isolation**: Ensures any code execution, prompt testing, or subagent tasks spawned for prompt validation run within an isolated workspace (`Workspace: "branch"` or `"share"`).
+
+## Workflow
+
+1. **Deconstruct Intent**: Identify the goal, target model, domain constraints, and missing specifications.
+2. **Enhance Structure**: Apply structured formatting (System Instructions, Context, Input Schema, Output Constraints, Examples).
+3. **Isolated Testing**: If prompt validation requires subagent execution or file testing, invoke subagents with `Workspace: "branch"`.
+4. **Deliver Output**: Present the perfected prompt with a summary of structural enhancements and usage recommendations.

.agents/skills/prompt-perfector/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Prompt Perfector"
+  short_description: "Refine prompts and evaluate them in isolation"
+  default_prompt: "Use $prompt-perfector to refine this prompt for clarity, constraints, and safe isolated evaluation."

.gitignore

@@ -53,6 +53,7 @@
 !/.agents/skills/performance/
 !/.agents/skills/plan/
 !/.agents/skills/privacy/
+!/.agents/skills/prompt-perfector/
 !/.agents/skills/rag-change-lab/
 !/.agents/skills/rag/
 !/.agents/skills/recovery/

AGENTS.md

@@ -475,7 +475,7 @@ Record one `docs/branch-review-ledger.md` row per PR touched, and end with the p
 
 ## Repository productivity skills
 
-Automatically apply repo-local skills under `.agents/skills/` when their descriptions match the user's request. Run `npm run skills` for the validated catalog of 32 canonical single-word skills and `npm run check:skills` to verify catalog integrity. The older long names remain compatibility aliases and must not be counted as unique skills.
+Automatically apply repo-local skills under `.agents/skills/` when their descriptions match the user's request. Run `npm run skills` for the validated catalog of 33 canonical single-word skills and `npm run check:skills` to verify catalog integrity. The older long names remain compatibility aliases and must not be counted as unique skills.
 
 The foundational orchestration skills are:
 

docs/audit-handover-2026-07-14.md

@@ -117,19 +117,19 @@ evals, service-role tenancy regression class, upstream OCR quality labels drivin
 
 ### 4.1 Security / privacy / API
 
-| ID  | Finding                                                     | Evidence                                                 | Remediation wave |
-| --- | ----------------------------------------------------------- | -------------------------------------------------------- | ---------------- |
-| S1  | Authed public-doc DTOs leak `storage_path` / `content_hash` | `documents/route.ts`, `documents/[id]/route.ts`          | Wave D1          |
-| S2  | Auth UI trusts `getSession()`; APIs use `getUser`           | `src/lib/supabase/client.tsx`                            | Wave D3          |
-| S3  | Public-upload quarantine pool high blast radius if enabled  | `upload/route.ts` + pool owner                           | Wave D4          |
-| S4  | Auth 401 envelope `{ error }` only                          | `supabase/auth.ts` vs `http.ts`                          | Wave H1          |
-| S5  | Many hand-rolled `{ error }` omit `code`/`message`          | upload, doc 404s, feedback, demo                         | Wave H1          |
-| S6  | Auth write/admin routes lack rate limits                    | bulk, labels, table-facts, ingestion/*, eval-cases, jobs | Wave H2          |
-| S7  | Document list offset max `1_000_000`                        | `documents/route.ts`                                     | Wave H3          |
-| S8  | Upload reserves max body when Content-Length absent         | `upload/route.ts`                                        | Wave H4          |
-| S9  | Authed stream summarize excludes public docs                | `answer/stream` → `summarizeDocument` owner-only         | Wave H5          |
-| S10 | Bulk returns raw DB `error.message`                         | `documents/bulk/route.ts`                                | Wave D5          |
-| S11 | `/api/jobs` can return demo jobs when env missing           | `jobs/route.ts`                                          | Wave H6          |
+| ID  | Finding                                                     | Evidence                                                  | Remediation wave |
+| --- | ----------------------------------------------------------- | --------------------------------------------------------- | ---------------- |
+| S1  | Authed public-doc DTOs leak `storage_path` / `content_hash` | `documents/route.ts`, `documents/[id]/route.ts`           | Wave D1          |
+| S2  | Auth UI trusts `getSession()`; APIs use `getUser`           | `src/lib/supabase/client.tsx`                             | Wave D3          |
+| S3  | Public-upload quarantine pool high blast radius if enabled  | `upload/route.ts` + pool owner                            | Wave D4          |
+| S4  | Auth 401 envelope `{ error }` only                          | `supabase/auth.ts` vs `http.ts`                           | Wave H1          |
+| S5  | Many hand-rolled `{ error }` omit `code`/`message`          | upload, doc 404s, feedback, demo                          | Wave H1          |
+| S6  | Auth write/admin routes lack rate limits                    | bulk, labels, table-facts, ingestion/\*, eval-cases, jobs | Wave H2          |
+| S7  | Document list offset max `1_000_000`                        | `documents/route.ts`                                      | Wave H3          |
+| S8  | Upload reserves max body when Content-Length absent         | `upload/route.ts`                                         | Wave H4          |
+| S9  | Authed stream summarize excludes public docs                | `answer/stream` → `summarizeDocument` owner-only          | Wave H5          |
+| S10 | Bulk returns raw DB `error.message`                         | `documents/bulk/route.ts`                                 | Wave D5          |
+| S11 | `/api/jobs` can return demo jobs when env missing           | `jobs/route.ts`                                           | Wave H6          |
 
 ### 4.2 Ingestion / indexing