cc-proficiency 0.2.10 → 0.3.1

package/docs/ai-grading/goal-achievement.md

@@ -0,0 +1,25 @@
+---
+id: goal-achievement
+label: Goal Achievement
+description: How effectively does the user define and accomplish objectives?
+---
+
+## Q1: Goal clarity & specificity
+**Anchors:** 1=vague single-word goals, 2=basic intent visible, 3=clear goals with context, 4=well-defined with constraints, 5=expert-level framing with success criteria
+**Evidence:** Session-meta `first_prompt` word count and structure (available on all sessions). When FACET_AVAILABLE: also use facets `underlying_goal` text quality for richer assessment.
+
+## Q2: Achievement rate
+**Anchors:** 1=<20% achieved, 2=20-40%, 3=40-60%, 4=60-80%, 5=>80%
+**Evidence:** Facets `outcome` distribution when available (precomputed achieved_rate). Disclose coverage %. When facets unavailable or coverage <20%, score 3 (insufficient signal).
+
+## Q3: Session purposefulness
+**Anchors:** 1=mostly warmups/idle, 2=many warmups or abandoned, 3=mixed productive and idle, 4=mostly productive, 5=consistently productive sessions
+**Evidence:** Session-meta warmup ratio from `first_prompt` pattern detection (e.g., "Respond with OK"). Tool activity ratio: sessions with >0 tool calls / total sessions.
+
+## Q4: Project engagement depth
+**Anchors:** 1=single project one-off, 2=few projects shallow, 3=some sustained engagement, 4=multi-session projects, 5=deep multi-session projects with sustained effort
+**Evidence:** Session-meta `project_path`: sessions per unique project distribution. Look for projects with repeated engagement over time rather than breadth alone.
+
+## Q5: Task completion signals
+**Anchors:** 1=mostly abandoned (low tool activity), 2=many sessions end early, 3=mixed completion evidence, 4=most sessions show substantive work, 5=consistently substantive tool activity indicating completion
+**Evidence:** Session-meta: sessions with >5 tool calls as proxy for substantive work. Proportion of non-warmup sessions with meaningful tool activity. Do NOT penalize sparse `lines_added` — use tool call volume as primary proxy.

package/docs/ai-grading/growth-learning.md

@@ -0,0 +1,25 @@
+---
+id: growth-learning
+label: Growth & Learning
+description: Is the user improving over time? Requires sufficient data for meaningful trends.
+---
+
+## Q1: Friction trajectory
+**Anchors:** 1=increasing friction over time, 2=slightly increasing, 3=flat or insufficient data, 4=slightly declining, 5=clearly declining friction
+**Evidence:** Facets `friction_counts` first-half vs second-half comparison when available (requires >=20 facets). When FACET_AVAILABLE and SUFFICIENT_FOR_TRENDS: use facet trend. Otherwise score 3 (insufficient for trend analysis).
+
+## Q2: Tool adoption curve
+**Anchors:** 1=static tool usage throughout, 2=minimal new tools, 3=gradual adoption of new tools, 4=steady new tool adoption, 5=consistent new tool types appearing in later sessions
+**Evidence:** Session-meta: new `tool_counts` key types appearing in chronologically later sessions vs earlier sessions. Compare tool vocabulary in first-half vs second-half of session history.
+
+## Q3: Feature adoption progression
+**Anchors:** 1=basic features only, 2=mostly basic, 3=some intermediate features, 4=intermediate plus some advanced, 5=advanced features adopted (agents, worktrees, MCP, task management, skills)
+**Evidence:** Rule-engine FeatureInventory: presence of advanced-tier features. Classify features into basic (Read, Edit, Bash), intermediate (Grep, Glob, hooks), advanced (agents, worktrees, MCP, task mgmt, skills).
+
+## Q4: Capability breadth expansion
+**Anchors:** 1=narrow and unchanging, 2=minimal expansion, 3=some variety growth, 4=steady breadth increase, 5=broad and growing capability set
+**Evidence:** Session-meta: unique `tool_counts` keys across time windows. Compare distinct tool types used in early sessions vs recent sessions. Growth in unique tool types indicates expanding capability.
+
+## Q5: Resilience development
+**Anchors:** 1=same failures repeat consistently, 2=slow improvement, 3=mixed or insufficient data, 4=good learning from errors, 5=learns from errors — decreasing error rate over time
+**Evidence:** Session-meta: `tool_errors` rate trend over chronological session windows (declining = learning). When FACET_AVAILABLE: also use facets `friction_detail` to judge if same friction types recur. Without facets, use error rate trend alone.

package/docs/ai-grading/system-prompt-header.md

@@ -0,0 +1,32 @@
+You evaluate Claude Code user proficiency from usage data.
+Score each criterion 1-5. Use the numeric anchors provided.
+
+DATA SOURCES (tiered):
+- Tier 1 — SESSION-META (primary, quantitative): Available for most sessions. Includes tool_counts, tokens, first_prompt, project_path, timestamps, message counts, tool_errors. This is your primary evidence base.
+- Tier 2 — FACETS (optional, qualitative): Available for a subset of sessions only. Coverage percentage is disclosed. Includes outcome, satisfaction, friction, session_type, helpfulness. Use when available to enrich scoring.
+- Tier 3 — RULE-ENGINE (aggregate features): Computed across all sessions. Includes domain scores, feature inventory, config maturity. Use for adoption and setup criteria.
+
+COVERAGE FLAGS:
+- FACET_AVAILABLE: true when facet data exists for this user. When false, score facet-dependent criteria as 3 (neutral) — do not guess.
+- SUFFICIENT_FOR_TRENDS: true when enough temporal data exists for trend analysis. When false, score trend-dependent criteria as 3 (neutral).
+
+SCORING RULES:
+- Every criterion CAN be scored without facets using session-meta or rule-engine evidence.
+- When facets ARE available, they enrich the score — use them as qualitative supplement.
+- When data is marked "insufficient" or a coverage flag is false, score 3 (neutral).
+- Do NOT penalize users for sparse optional fields (lines_added, duration_minutes, git_commits). Absence of data is not evidence of absence of work.
+
+Return ONLY the criteria scores and brief evidence strings.
+Do NOT compute totals or levels — those are calculated after.
+
+Output JSON:
+{
+  "domains": [
+    {
+      "id": "<domain-id>",
+      "criteria": [
+        { "q": "Q1", "score": 3, "evidence": "brief justification" }
+      ]
+    }
+  ]
+}

package/docs/ai-grading/verification-quality.md

@@ -0,0 +1,25 @@
+---
+id: verification-quality
+label: Verification & Quality
+description: Does the user produce reliable, validated results?
+---
+
+## Q1: Outcome reliability
+**Anchors:** 1=<30% achieved, 2=30-50%, 3=50-70%, 4=70-85%, 5=>85%
+**Evidence:** Facets `outcome` success rate when available (precomputed). Disclose coverage %. When facets unavailable or coverage <20%, score 3 (insufficient signal — this criterion is coverage-gated).
+
+## Q2: Error handling quality
+**Anchors:** 1=ignores errors entirely, 2=fixes occasionally, 3=fixes some errors, 4=systematic error handling, 5=low error rate with systematic recovery
+**Evidence:** Session-meta: `tool_errors` / total tool calls ratio across sessions. Lower ratio = better error management. Also consider `tool_error_categories` for pattern analysis — diverse error types with low rates suggest sophisticated usage.
+
+## Q3: Investigation thoroughness
+**Anchors:** 1=trial-and-error only, 2=minimal investigation, 3=some investigation before action, 4=regular investigation patterns, 5=systematic investigation with LSP, read-before-edit, and investigation chains
+**Evidence:** Rule-engine aggregate signals: `tool-investigation-chain` fire count, LSP usage indicators, `tool-read-before-edit` patterns. Higher aggregate scores indicate thorough verification habits.
+
+## Q4: Iterative refinement discipline
+**Anchors:** 1=one-shot only (no iteration), 2=rare iteration, 3=some iteration, 4=regular iterative patterns, 5=systematic iteration with multiple edit cycles
+**Evidence:** Session-meta: sessions with multiple Edit tool calls indicating iterative refinement. When FACET_AVAILABLE: also use facets `session_type=iterative_refinement` rate for explicit classification.
+
+## Q5: Course-correction capability
+**Anchors:** 1=never corrects course after errors, 2=eventual correction, 3=moderate recovery, 4=quick recovery, 5=rapid recovery — sessions with errors continue to substantial tool activity
+**Evidence:** Session-meta: sessions with `tool_errors` > 0 that continue to substantial tool activity afterward (>5 tool calls after first error). Higher continuation ratio = better course-correction ability.

package/docs/ai-grading/workflow-mastery.md

@@ -0,0 +1,25 @@
+---
+id: workflow-mastery
+label: Workflow Mastery
+description: How sophisticated and efficient are the user's work patterns?
+---
+
+## Q1: Session strategy diversity
+**Anchors:** 1=all sessions same type/pattern, 2=mostly one type, 3=2-3 distinct types, 4=strategic variety, 5=strategic type selection matched to goals
+**Evidence:** Session-meta `tool_counts` patterns to derive session types (read-heavy, edit-heavy, bash-heavy, mixed). When FACET_AVAILABLE: use facets `session_type` distribution for explicit classification.
+
+## Q2: Investigation discipline
+**Anchors:** 1=no read-before-edit behavior, 2=rarely investigates first, 3=occasional investigation, 4=regular read-then-edit pattern, 5=systematic investigation-first discipline
+**Evidence:** Rule-engine aggregate signals: `tool-read-before-edit` and `tool-investigation-chain` fire counts. Higher fire rates indicate disciplined investigation before action.
+
+## Q3: Configuration maturity
+**Anchors:** 1=bare default setup, 2=minimal customization, 3=some configuration present, 4=well-configured environment, 5=sophisticated setup with hooks, plugins, MCP, rules, memory
+**Evidence:** Rule-engine ConfigSignals: presence and count of hooks, plugins, CLAUDE.md, MCP servers, custom rules, memory usage, agents, skills. More sophisticated setup = higher maturity.
+
+## Q4: Tool repertoire effectiveness
+**Anchors:** 1=uses only 1-2 tools, 2=narrow tool range, 3=varied tool usage, 4=broad repertoire with appropriate selection, 5=right tool for each job with high entropy across sessions
+**Evidence:** Session-meta `tool_counts` distribution entropy across sessions. Look for breadth of tool types used AND variation in tool mix between sessions (not same pattern every time).
+
+## Q5: Shipping behavior
+**Anchors:** 1=no evidence of shipping, 2=rare evidence, 3=occasional evidence, 4=regular shipping signals, 5=consistent commit and push discipline
+**Evidence:** Session-meta `git_commits` and `git_pushes` when present. This is a sparse signal — DO NOT penalize absence (score 3 when insufficient data). Only reward when evidence is present. One-directional criterion.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-proficiency",
-  "version": "0.2.10",
+  "version": "0.3.1",
   "description": "Claude Code proficiency badge generator — analyze usage patterns across 5 domains aligned with Claude Certified Architect",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -24,6 +24,7 @@
     "hooks/",
     ".claude-plugin/",
     "skills/",
+    "docs/ai-grading/",
     "README.md"
   ],
   "keywords": [