opencode-metis 0.1.0

package/opencode/skill/specification-validation/reference/ambiguity-detection.md

@@ -0,0 +1,132 @@
+# Ambiguity Detection Reference
+
+Techniques for detecting and scoring ambiguous language in specifications.
+
+## Vague Language Patterns
+
+| Pattern | Example | Recommendation |
+|---------|---------|----------------|
+| Hedge words | "should", "might", "could" | Use "must" or "will" |
+| Vague quantifiers | "fast", "many", "various" | Specify metrics |
+| Open-ended lists | "etc.", "and so on" | Enumerate all items |
+| Undefined terms | "the system", "appropriate" | Define specifically |
+| Passive voice | "errors are handled" | Specify who/what |
+| Weak verbs | "support", "allow" | Use concrete actions |
+
+## Ambiguity Score
+
+```
+ambiguity_score = vague_patterns / total_statements * 100
+
+  0-5%:   Excellent clarity
+  5-15%:  Acceptable
+  15-25%: Recommend clarification
+  25%+:   High ambiguity
+```
+
+## Ambiguity Red Flags
+
+- "should", "might", "could", "may"
+- "fast", "slow", "many", "few"
+- "etc.", "and so on", "..."
+- "appropriate", "reasonable"
+- "some", "several", "a few"
+- "as needed", "when necessary"
+- "properly", "correctly"
+
+## Automated Detection
+
+### Ambiguity Scan
+
+```bash
+grep -inE "(should|might|could|may|various|etc\.|and so on|appropriate|reasonable|fast|slow|many|few)" [file]
+```
+
+### Counting Script
+
+```bash
+# Count vague patterns
+vague_count=$(grep -icE "(should|might|could|may|various|etc\.|appropriate|reasonable)" [file])
+
+# Count total lines (rough statement count)
+total=$(wc -l < [file])
+
+# Calculate percentage
+echo "Ambiguity: $((vague_count * 100 / total))%"
+```
+
+## Category-Specific Patterns
+
+### Requirements Ambiguity
+
+| Vague | Specific |
+|-------|----------|
+| "The system should be fast" | "Response time < 200ms p95" |
+| "Handle many users" | "Support 10,000 concurrent users" |
+| "User-friendly interface" | "WCAG 2.1 AA compliant, 5 clicks max to any feature" |
+| "Secure authentication" | "OAuth 2.0 with JWT, 15-min token expiry" |
+
+### Architecture Ambiguity
+
+| Vague | Specific |
+|-------|----------|
+| "Scalable design" | "Horizontal scaling via K8s, stateless services" |
+| "Proper error handling" | "Errors caught at service boundary, logged with correlation ID" |
+| "Standard patterns" | "Repository pattern for data access, Service layer for business logic" |
+
+### Implementation Ambiguity
+
+| Vague | Specific |
+|-------|----------|
+| "Validate input" | "Check email format (RFC 5322), length 5-254 chars, sanitize HTML" |
+| "Handle edge cases" | "Null user -> 404, Empty list -> empty array, Invalid ID -> 400" |
+| "Add appropriate logging" | "Log INFO for requests, WARN for retries, ERROR with stack trace" |
+
+## Remediation Strategies
+
+### For Requirements
+
+1. **Add metrics**: Replace qualitative with quantitative
+2. **Define boundaries**: Specify min/max/exact values
+3. **List explicitly**: Replace "etc." with complete list
+4. **Name actors**: Replace "the system" with specific component
+
+### For Design
+
+1. **Reference standards**: Link to design patterns, RFCs, specs
+2. **Show examples**: Include code snippets or diagrams
+3. **Define interfaces**: Specify method signatures, not just descriptions
+4. **Enumerate options**: List all valid states/values
+
+### For Implementation
+
+1. **Write tests first**: Tests define unambiguous behavior
+2. **Use types**: Let type system enforce constraints
+3. **Add assertions**: Make implicit assumptions explicit
+4. **Document edge cases**: Comment unusual handling
+
+## Report Format
+
+```
+Ambiguity Analysis
+
+File: [path]
+Score: [X]% ([level])
+
+High-Priority (should -> must):
+- Line 23: "should validate" -> "must validate"
+- Line 45: "may include" -> "includes" or "does not include"
+
+Medium-Priority (vague quantifiers):
+- Line 67: "fast response" -> "< 200ms"
+- Line 89: "many records" -> "up to 10,000 records"
+
+Low-Priority (style):
+- Line 12: "etc." -> list all items
+- Line 34: "appropriate" -> define criteria
+
+Recommendations:
+1. Address high-priority items before implementation
+2. Clarify quantifiers with stakeholders
+3. Replace open-ended lists with explicit enumerations
+```

package/opencode/skill/specification-validation/reference/constitution-validation.md

@@ -0,0 +1,301 @@
+# Constitution Validation Reference
+
+Techniques for validating code against project governance rules.
+
+## Level System (L1/L2/L3)
+
+| Level | Name | Blocking | Autofix | Use Case |
+|-------|------|----------|---------|----------|
+| **L1** | Must | Yes | AI auto-corrects | Critical rules - security, correctness, architecture |
+| **L2** | Should | Yes | No (needs human judgment) | Important rules requiring manual attention |
+| **L3** | May | No | No | Advisory/optional - style preferences, suggestions |
+
+**Level Behavior:**
+
+| Level | Validation | Implementation | AI Behavior |
+|-------|------------|----------------|-------------|
+| `L1` | Fails check, blocks | Blocks phase completion | **Automatically fixes** before proceeding |
+| `L2` | Fails check, blocks | Blocks phase completion | Reports violation, **requires human action** |
+| `L3` | Reports only | Does not block | Optional improvement, can be ignored |
+
+---
+
+## Rule Schema
+
+Each rule in the constitution uses this YAML structure:
+
+```yaml
+level: L1 | L2 | L3
+pattern: "regex pattern"    # OR
+check: "semantic description for LLM interpretation"
+scope: "glob pattern for files to check"
+exclude: "glob patterns to skip (comma-separated)"
+message: "Human-readable violation message"
+```
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `level` | Required | `L1` \| `L2` \| `L3` | Determines blocking and autofix behavior |
+| `pattern` | One of | Regex | Pattern to match violations in source code |
+| `check` | One of | String | Semantic description for LLM interpretation |
+| `scope` | Required | Glob | File patterns to check (supports `**`) |
+| `exclude` | Optional | Glob | File patterns to skip (comma-separated) |
+| `message` | Required | String | Human-readable violation message |
+
+---
+
+## Rule Types
+
+### Pattern Rules
+
+Pattern rules use regex to match violations in source code. These are deterministic and fast.
+
+**When to use:**
+- Text patterns that can be matched literally
+- Syntax violations (forbidden imports, banned functions)
+- Secret detection (API keys, passwords)
+
+**Regex Tips:**
+- Escape special characters: `\.` for literal dot
+- Use `\s*` for flexible whitespace
+- Use `\b` for word boundaries
+- Escape backslashes in YAML: `\\b` for `\b`
+
+**Example - Detecting Barrel Exports:**
+
+```yaml
+level: L1
+pattern: "export \\* from"
+scope: "src/**/*.ts"
+exclude: "src/index.ts"
+message: Barrel exports prohibited. Import from specific files.
+```
+
+### Check Rules
+
+Check rules use semantic descriptions that the LLM interprets. These are flexible but non-deterministic.
+
+**When to use:**
+- Architectural patterns that require understanding context
+- Rules that span multiple lines or files
+- Semantic concepts (like "database calls only in repositories")
+
+**Example - Repository Pattern:**
+
+```yaml
+level: L1
+check: Database queries (Prisma, TypeORM, Knex, raw SQL) only in files matching *Repository.ts or *Repository.js
+scope: "src/**/*.{ts,js}"
+exclude: "**/repositories/**"
+message: Direct database call outside repository layer.
+```
+
+---
+
+## Validation Execution
+
+For each parsed rule:
+
+1. **Glob files matching scope** (excluding patterns in `exclude`)
+2. **For Pattern rules**: Execute regex match against file contents
+3. **For Check rules**: Use LLM to interpret semantic check
+4. **Collect violations** with file path, line number, code snippet
+5. **Categorize by level** for reporting
+
+---
+
+## Rule Parsing
+
+```pseudocode
+FUNCTION: parse_constitution(markdown_content)
+  rules = []
+  current_category = null
+
+  FOR EACH section in markdown:
+    IF section.header.level == 2:
+      current_category = section.header.text  # e.g., "Code Quality", "Security"
+    ELSE IF section.header.level == 3:
+      yaml_block = extract_yaml_code_block(section.content)
+      IF yaml_block:
+        rule = {
+          id: generate_rule_id(current_category, index),  # e.g., "SEC-001"
+          name: section.header.text,                       # e.g., "No Hardcoded Secrets"
+          category: current_category,
+          level: yaml_block.level,
+          pattern: yaml_block.pattern,
+          check: yaml_block.check,
+          scope: yaml_block.scope,
+          exclude: yaml_block.exclude,
+          message: yaml_block.message,
+        }
+        IF rule.pattern OR rule.check:
+          # Derive behavior from level
+          rule.blocking = (rule.level == "L1" OR rule.level == "L2")
+          rule.autofix = (rule.level == "L1")
+          rules.append(rule)
+  RETURN rules
+```
+
+---
+
+## Category ID Prefixes
+
+| Category | Prefix | Example |
+|----------|--------|---------|
+| Security | SEC | SEC-001 |
+| Architecture | ARCH | ARCH-001 |
+| Code Quality | QUAL | QUAL-001 |
+| Testing | TEST | TEST-001 |
+| Custom | CUST | CUST-001 |
+| [Custom Name] | First 4 letters uppercase | PERF-001 |
+
+---
+
+## Common Rule Patterns
+
+### Security
+
+```yaml
+# SQL Injection Detection
+level: L1
+pattern: "\\.(query|execute|raw)\\s*\\([^)]*\\$\\{|\\+\\s*['\"]"
+scope: "**/*.{ts,js}"
+message: Potential SQL injection. Use parameterized queries.
+
+# No Sensitive Data in Logs
+level: L2
+pattern: "console\\.(log|info|warn|error)\\([^)]*password|secret|token|key"
+scope: "src/**/*.{ts,js}"
+message: Sensitive data may be logged. Remove or redact.
+```
+
+### Architecture
+
+```yaml
+# No Cross-Package Relative Imports
+level: L2
+check: Imports between packages must use package name, not relative path
+scope: "packages/*/src/**"
+message: Cross-package import must use package name, not relative path.
+
+# Service Layer Boundaries
+level: L1
+check: HTTP calls (fetch, axios, got) only in files under services/ or api/
+scope: "src/components/**"
+message: API calls must go through service layer.
+```
+
+### Code Quality
+
+```yaml
+# No TODO in Main Branch
+level: L3
+pattern: "TODO|FIXME|XXX|HACK"
+scope: "src/**/*.{ts,js}"
+message: Unresolved TODO marker. Complete or track in issue.
+```
+
+### Testing
+
+```yaml
+# No .only in Committed Tests
+level: L1
+pattern: "\\.(only|skip)\\s*\\("
+scope: "**/*.test.*, **/*.spec.*"
+message: Remove .only/.skip before committing tests.
+```
+
+---
+
+## Compliance Report Format
+
+```markdown
+## Constitution Compliance Report
+
+**Constitution:** CONSTITUTION.md
+**Target:** [spec-id or file path or "entire codebase"]
+**Checked:** [ISO timestamp]
+
+### Summary
+
+- Passed: [N] rules
+- L3 Advisories: [N] rules
+- L2 Blocking: [N] rules
+- L1 Critical: [N] rules
+
+### Critical Violations (L1 - Autofix Required)
+
+#### SEC-001: No Hardcoded Secrets
+- **Location:** `src/services/PaymentService.ts:42`
+- **Finding:** Hardcoded secret detected. Use environment variables.
+- **Code:** `const API_KEY = 'sk_live_xxx...'`
+- **Autofix:** Replace with `process.env.PAYMENT_API_KEY`
+
+### Blocking Violations (L2 - Human Action Required)
+
+#### ARCH-001: Repository Pattern
+- **Location:** `src/services/UserService.ts:18`
+- **Finding:** Direct database call outside repository.
+- **Code:** `await prisma.user.findMany(...)`
+- **Action Required:** Extract to UserRepository
+
+### Advisories (L3 - Optional)
+
+#### QUAL-001: Function Length
+- **Location:** `src/utils/helpers.ts:45`
+- **Finding:** Function exceeds recommended 25 lines (actual: 38)
+- **Suggestion:** Consider extracting helper functions
+
+### Recommendations
+
+1. [Prioritized action item based on violations]
+2. [Next action item]
+```
+
+---
+
+## Graceful Degradation
+
+| Scenario | Behavior |
+|----------|----------|
+| No CONSTITUTION.md | Report "No constitution found. Skipping constitution checks." |
+| Invalid rule format | Skip rule, warn user, continue with other rules |
+| Invalid regex pattern | Report as config error, skip rule |
+| Scope matches no files | Report as info, not a failure |
+| File read error | Skip file, warn, continue |
+
+---
+
+## Scope Patterns
+
+### Common Patterns
+
+| Pattern | Matches |
+|---------|---------|
+| `**/*.ts` | All TypeScript files |
+| `src/**/*.ts` | TypeScript files in src/ |
+| `**/*.{ts,js}` | TypeScript and JavaScript |
+| `packages/*/src/**` | All packages' src folders |
+| `apps/web/**` | Only the web app |
+
+### Monorepo Scoping
+
+```yaml
+# Web package only
+scope: "packages/web/src/**/*.{ts,tsx}"
+
+# All packages
+scope: "packages/*/src/**/*.ts"
+
+# Shared libraries
+scope: "libs/*/src/**/*.ts"
+```
+
+---
+
+## Performance Considerations
+
+1. **Pattern rules are faster** than Check rules (no LLM needed)
+2. **Narrow scopes** reduce file scanning
+3. **Specific excludes** prevent unnecessary checks
+4. **Batch similar rules** under same scope for efficiency