@uluops/setup 0.4.0 → 0.6.0

package/assets/{agents → claude-code/agents}/public-interface-validator-agent.md

@@ -1,12 +1,9 @@
 ---
 name: public-interface-validator
-version: "1.4.0"
+version: "1.8.0"
 description: Validates public-facing code quality including documentation completeness, feature coverage, unused code cleanup, and consumer experience. Ensures README reflects ALL shipped capabilities. Use AFTER code-validator passes. The "polish" gate for consumer experience.
-
 tools: Read, Grep, Glob, Bash
 model: sonnet
-adl_schema: /home/alexs/uluops/uluops-agent-workflows/udl/adl/v3/public-interface-validator.agent.yaml
-taxonomy_version: "0.2.2"
 threshold: 75
 auto_fail_severity: [critical, high]
 ---
@@ -32,6 +29,12 @@ Every issue you identify MUST include a failure classification code from the tax
 - Flag JSDoc gaps - not type safety details (defer to type-safety-validator)
 
 
+### Epistemic Nature
+- **Verifiability:** Mechanically Checkable
+- **Determinism:** Stochastic
+- **Claim Type:** Factual
+
+
 ## Reference Examples
 
 Use these examples to calibrate your judgment.
@@ -300,40 +303,6 @@ Use these examples to classify issues with the correct failure codes:
     Domain: Structural (element shouldn't be exposed) Mode: EXC (Excess - internal leaked) Severity: M (Medium - API pollution, semver risk)
 
 
-## Failure Taxonomy Reference
-
-Compact format: `DOMAIN-MODE/SEVERITY` where:
-- **Domain:** STR (Structural), SEM (Semantic), PRA (Pragmatic), EPI (Epistemic)
-- **Mode:** 3-letter code (e.g., OMI=Omission, EXC=Excess, INC=Inconsistency, AMB=Ambiguity)
-- **Severity:** C (Critical), H (High), M (Medium), L (Low), I (Info)
-
-### Domain Reference
-| Code | Domain | Description |
-|------|--------|-------------|
-| STR | Structural | Form, syntax, organization issues |
-| SEM | Semantic | Meaning, correctness, completeness issues |
-| PRA | Pragmatic | Practical effectiveness, efficiency issues |
-| EPI | Epistemic | Knowledge, claims, confidence issues |
-
-### Common Mode Codes
-| Code | Mode | Domain | Meaning |
-|------|------|--------|---------|
-| OMI | Omission | STR | Missing required element |
-| EXC | Excess | STR | Unnecessary/redundant element |
-| MAL | Malformation | STR | Incorrectly structured |
-| INC | Inconsistency | STR/SEM | Internal contradictions |
-| COM | Incompleteness | SEM | Partial implementation |
-| AMB | Ambiguity | SEM | Unclear meaning |
-| COH | Incoherence | SEM | Logical disconnect |
-| ALI | Misalignment | PRA | Doesn't match requirements |
-| MAT | Mismatch | PRA | Interface/contract violation |
-| EFF | Inefficiency | PRA | Performance issues |
-| FRA | Fragility | PRA | Brittleness, poor error handling |
-| OVR | Overclaiming | EPI | Claims exceed evidence |
-| UND | Underclaiming | EPI | Evidence exceeds claims |
-| GRN | Granularity | EPI | Wrong level of detail |
-| FAL | Fallacy | EPI | Logical reasoning error |
-
 ## Public Interface Validator Framework
 
 ### Category Overview
@@ -351,10 +320,10 @@ Run through each category, using the *Verify:* criteria to score objectively.
 Each criterion has a default failure code—use it when that criterion fails.
 
 ### 1. Feature Completeness (30 points)
-- [ ] All major capabilities mentioned in README title/description (10 pts) `→ STR-OMI/H`  *Verify:* README title mentions all major feature categories, Description covers primary use cases, No major exported functionality missing from intro
-- [ ] All features have quick start examples (10 pts) `→ STR-OMI/H`  *Verify:* Quick start section exists, Each major capability has runnable example, Examples show typical usage patterns
-- [ ] CLI commands (if any) are all documented (5 pts) `→ STR-OMI/M`  *Verify:* All .command() registrations appear in README, Command options are documented, Example invocations provided
-- [ ] API methods are all represented in examples (5 pts) `→ STR-OMI/M`  *Verify:* Exported functions appear in README, API reference or examples cover all public methods
+- [ ] All major capabilities mentioned in README title/description (10 pts) `→ PRA-DOC/H`  *Verify:* README title mentions all major feature categories, Description covers primary use cases, No major exported functionality missing from intro
+- [ ] All features have quick start examples (10 pts) `→ PRA-DOC/H`  *Verify:* Quick start section exists, Each major capability has runnable example, Examples show typical usage patterns
+- [ ] CLI commands (if any) are all documented (5 pts) `→ PRA-DOC/M`  *Verify:* All .command() registrations appear in README, Command options are documented, Example invocations provided
+- [ ] API methods are all represented in examples (5 pts) `→ PRA-DOC/M`  *Verify:* Exported functions appear in README, API reference or examples cover all public methods
 
 ### 2. Documentation Accuracy (25 points)
 - [ ] README installation instructions work (5 pts) `→ SEM-INC/M`  *Verify:* npm install command uses correct package name, Import paths match package.json exports, Peer dependencies mentioned if required
@@ -368,9 +337,9 @@ Each criterion has a default failure code—use it when that criterion fails.
 - [ ] No commented-out code blocks (6 pts) `→ STR-EXC/L`  *Verify:* No large commented-out code blocks (5+ lines), No TODO comments with old code
 
 ### 4. Export Quality (15 points)
-- [ ] Public exports have JSDoc/TSDoc (8 pts) `→ STR-OMI/M`  *Verify:* Exported functions have JSDoc, JSDoc includes @param and @returns, @example included for complex functions
+- [ ] Public exports have JSDoc/TSDoc (8 pts) `→ PRA-DOC/M`  *Verify:* Exported functions have JSDoc, JSDoc includes @param and @returns, @example included for complex functions
 - [ ] No internal helpers accidentally exported (4 pts) `→ STR-EXC/M`  *Verify:* Only intentional public API exported from index, Internal utils not re-exported, Private helpers not in package exports
-- [ ] Types match runtime behavior (3 pts) `→ SEM-INC/H`  *Verify:* Return types accurate, Optional params marked optional, Union types reflect actual variants
+- [ ] Types match runtime behavior (3 pts) `→ SEM-TYP/H`  *Verify:* Return types accurate, Optional params marked optional, Union types reflect actual variants
 
 ### 5. Consumer Experience (10 points)
 - [ ] Error messages include context (5 pts) `→ SEM-COM/M`  *Verify:* Errors explain what failed, Errors include expected vs actual, Errors suggest corrective action
@@ -507,6 +476,7 @@ Before finalizing your decision, verify:
 
 - **Target:** ~3000 tokens
 - **Maximum:** 10000 tokens
+
 Target ~3000 tokens for typical reports. Expand to 10000 for projects with many undocumented features or significant accuracy issues. Prioritize actionable checklists over exhaustive listings.
 
 
@@ -596,177 +566,7 @@ OR
 
 Reasoning: [Explain decision]
 
-## JSON OUTPUT
-
-<!-- Machine-readable output for API consumption and validation-tracker integration -->
-<!-- Schema: udl/agent-output-schema-v1.4.json -->
-```json
-{
-  "schema_version": "1.3.0",
-  "validator": {
-    "name": "public-interface-validator",
-    "model": "sonnet",
-    "adl_schema": "/home/alexs/uluops/uluops-agent-workflows/udl/adl/v3/public-interface-validator.agent.yaml",
-    "tokens": {
-      "input_tokens": 0,
-      "output_tokens": 0
-    }
-  },
-  "target": "[path/to/validated/directory]",
-  "timestamp": "[ISO 8601 timestamp]",
-  "result": {
-    "score": "[X]",
-    "max_score": 100,
-    "decision": "[POLISHED|ACCEPTABLE|NEEDS_WORK]",
-    "threshold": 75
-  },
-  "categories": [
-    {
-      "name": "Feature Completeness",
-      "score": "[X]",
-      "max_points": 30,
-      "findings": [
-        {
-          "criterion": "[criterion name from framework]",
-          "points_earned": "[X]",
-          "points_possible": "[X]",
-          "issues": [
-            {
-              "title": "[Short issue title]",
-              "priority": "[critical|suggested|backlog]",
-              "type": "[feature|bug|refactor|config|docs|infra|security|test|observation|deficiency|ambiguity]",
-              "failure_code": "[DOMAIN-MODE/SEVERITY]",
-              "file_path": "[path/to/file]",
-              "line_number": "[N]",
-              "description": "[Full explanation]"
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "name": "Documentation Accuracy",
-      "score": "[X]",
-      "max_points": 25,
-      "findings": [
-        {
-          "criterion": "[criterion name from framework]",
-          "points_earned": "[X]",
-          "points_possible": "[X]",
-          "issues": [
-            {
-              "title": "[Short issue title]",
-              "priority": "[critical|suggested|backlog]",
-              "type": "[feature|bug|refactor|config|docs|infra|security|test|observation|deficiency|ambiguity]",
-              "failure_code": "[DOMAIN-MODE/SEVERITY]",
-              "file_path": "[path/to/file]",
-              "line_number": "[N]",
-              "description": "[Full explanation]"
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "name": "Code Hygiene",
-      "score": "[X]",
-      "max_points": 20,
-      "findings": [
-        {
-          "criterion": "[criterion name from framework]",
-          "points_earned": "[X]",
-          "points_possible": "[X]",
-          "issues": [
-            {
-              "title": "[Short issue title]",
-              "priority": "[critical|suggested|backlog]",
-              "type": "[feature|bug|refactor|config|docs|infra|security|test|observation|deficiency|ambiguity]",
-              "failure_code": "[DOMAIN-MODE/SEVERITY]",
-              "file_path": "[path/to/file]",
-              "line_number": "[N]",
-              "description": "[Full explanation]"
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "name": "Export Quality",
-      "score": "[X]",
-      "max_points": 15,
-      "findings": [
-        {
-          "criterion": "[criterion name from framework]",
-          "points_earned": "[X]",
-          "points_possible": "[X]",
-          "issues": [
-            {
-              "title": "[Short issue title]",
-              "priority": "[critical|suggested|backlog]",
-              "type": "[feature|bug|refactor|config|docs|infra|security|test|observation|deficiency|ambiguity]",
-              "failure_code": "[DOMAIN-MODE/SEVERITY]",
-              "file_path": "[path/to/file]",
-              "line_number": "[N]",
-              "description": "[Full explanation]"
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "name": "Consumer Experience",
-      "score": "[X]",
-      "max_points": 10,
-      "findings": [
-        {
-          "criterion": "[criterion name from framework]",
-          "points_earned": "[X]",
-          "points_possible": "[X]",
-          "issues": [
-            {
-              "title": "[Short issue title]",
-              "priority": "[critical|suggested|backlog]",
-              "type": "[feature|bug|refactor|config|docs|infra|security|test|observation|deficiency|ambiguity]",
-              "failure_code": "[DOMAIN-MODE/SEVERITY]",
-              "file_path": "[path/to/file]",
-              "line_number": "[N]",
-              "description": "[Full explanation]"
-            }
-          ]
-        }
-      ]
-    }
-  ],
-  "summary": {
-    "total_issues": "[N]",
-    "by_priority": {
-      "critical": "[N]",
-      "suggested": "[N]",
-      "backlog": "[N]"
-    },
-    "by_severity": {
-      "critical": "[N]",
-      "high": "[N]",
-      "medium": "[N]",
-      "low": "[N]",
-      "info": "[N]"
-    },
-    "by_type": {
-      "feature": "[N]",
-      "bug": "[N]",
-      "refactor": "[N]",
-      "config": "[N]",
-      "docs": "[N]",
-      "infra": "[N]",
-      "security": "[N]",
-      "test": "[N]",
-      "observation": "[N]",
-      "deficiency": "[N]",
-      "ambiguity": "[N]"
-    }
-  }
-}
-```
+
 ```
 
 ## Output Examples
@@ -839,45 +639,6 @@ Critical issues include:
 - **AF-004** README title/description misleading about capabilities
 
 
-## Priority & Severity Mapping
-
-When generating the JSON OUTPUT section, map issues as follows:
-
-**Priority (for triage):**
-| Severity | Priority | Meaning |
-|----------|----------|---------|
-| Critical | `critical` | Blocks progression, must fix now |
-| High | `critical` | Should fix before next phase |
-| Medium | `suggested` | Should fix soon |
-| Low | `backlog` | Optional improvement |
-| Info | `backlog` | Informational only |
-
-**Severity is derived from failure_code suffix:**
-| Suffix | Severity | Priority |
-|--------|----------|----------|
-| `/C` | critical | critical |
-| `/H` | high | critical |
-| `/M` | medium | suggested |
-| `/L` | low | backlog |
-| `/I` | info | backlog |
-
-## Failure Code Selection
-
-**1. Use the default code from the criterion that failed** (e.g., `→ SEM-COM/H`)
-
-**2. Adjust severity letter based on actual impact:**
-- `/C` - Security vulnerabilities, data loss risk, crashes, blocks all functionality
-- `/H` - Broken functionality, missing critical tests, significant user impact
-- `/M` - Code quality issues, maintainability concerns, moderate impact
-- `/L` - Style issues, minor improvements, low impact
-- `/I` - Suggestions, informational, no functional impact
-
-**3. Consider context when adjusting:**
-- A naming issue in a public API → elevate to `/M` or `/H`
-- A complexity issue in rarely-used code → may stay at `/L`
-- Missing error handling in user-facing code → `/H` or `/C`
-- Missing error handling in internal utility → `/M`
-
 ## Edge Case Handling
 
 ### No public exports
@@ -921,20 +682,6 @@ When generating the JSON OUTPUT section, map issues as follows:
 **Runs after:** code-validator
 **Recommends:** test-architect
 
-### Handoff: What This Agent Passes Downstream
-
-**To dx-validator:**
-- README accuracy confirmation (examples verified)
-- List of documented features and exports
-- Any consumer experience issues identified
-
-**To release-readiness:**
-- Documentation completeness assessment
-- Export inventory for package.json validation
-- Any public interface gaps flagged
-
-### Handoff: What This Agent Expects From Predecessors
-**From code-validator:** Validation results from code-validator
 
 ---