feat: full gitagent spec compliance v1.0.0

- workflows/audit-pipeline.yaml with 3-step chained pipeline (depends_on, outputs)
- hooks/bootstrap.md and hooks/teardown.md lifecycle hooks
- memory/runtime/ structured memory (dailylog, patterns, context)
- knowledge/ml-failure-taxonomy.md pre-loaded domain expertise
- examples/ with 3 real-world datasets + calibration interactions
- DUTIES.md segregation-of-duties policy (Auditor/Analyst/Executor)
- run.mjs rewritten with sequential skill chaining + .gitagent/audit.jsonl logging
- All SKILL.md files upgraded with outputs:, role:, input declarations
- .github/workflows/validate.yml CI agent structure validation
- docs/index.html GitHub dark theme with neon colors
- API keys moved to environment variables

Author: sagm07

.gitagent/state.json

@@ -1,4 +1,4 @@
 {
-  "session_id": "429aebd0-6ee3-4a60-b84b-557f8bdbdbb7",
-  "started_at": "2026-04-02T07:11:56.917Z"
+  "session_id": "1647faa2-ff7b-4554-b92a-6c67b921ece6",
+  "started_at": "2026-04-09T09:52:12.684Z"
 }

.github/workflows/validate.yml

@@ -0,0 +1,91 @@
+name: gitagent-validate
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  validate:
+    name: Validate Bloop Agent
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Check required agent files exist
+        run: |
+          echo "Checking agent structure..."
+          test -f agent.yaml        && echo "✓ agent.yaml" || (echo "✗ agent.yaml MISSING" && exit 1)
+          test -f SOUL.md           && echo "✓ SOUL.md" || (echo "✗ SOUL.md MISSING" && exit 1)
+          test -f RULES.md          && echo "✓ RULES.md" || (echo "✗ RULES.md MISSING" && exit 1)
+          test -f DUTIES.md         && echo "✓ DUTIES.md" || (echo "✗ DUTIES.md MISSING" && exit 1)
+          test -f workflows/audit-pipeline.yaml && echo "✓ workflows/audit-pipeline.yaml" || (echo "✗ workflow MISSING" && exit 1)
+          test -f hooks/bootstrap.md  && echo "✓ hooks/bootstrap.md" || (echo "✗ bootstrap hook MISSING" && exit 1)
+          test -f hooks/teardown.md   && echo "✓ hooks/teardown.md" || (echo "✗ teardown hook MISSING" && exit 1)
+          test -f knowledge/ml-failure-taxonomy.md && echo "✓ knowledge/ml-failure-taxonomy.md" || (echo "✗ taxonomy MISSING" && exit 1)
+          test -f skills/segment-analysis/SKILL.md && echo "✓ skills/segment-analysis" || (echo "✗ segment-analysis skill MISSING" && exit 1)
+          test -f skills/root-cause/SKILL.md       && echo "✓ skills/root-cause" || (echo "✗ root-cause skill MISSING" && exit 1)
+          test -f skills/fix-generator/SKILL.md    && echo "✓ skills/fix-generator" || (echo "✗ fix-generator skill MISSING" && exit 1)
+          test -f examples/diabetic-retinopathy.csv && echo "✓ examples/diabetic-retinopathy.csv" || (echo "✗ example dataset MISSING" && exit 1)
+          echo "All required files present."
+
+      - name: Validate agent.yaml structure
+        run: |
+          node -e "
+          import('fs').then(fs => {
+            const yaml = fs.readFileSync('agent.yaml', 'utf8');
+            if (!yaml.includes('spec_version')) { console.error('Missing spec_version'); process.exit(1); }
+            if (!yaml.includes('name: bloop'))  { console.error('Missing agent name'); process.exit(1); }
+            if (!yaml.includes('skills:'))      { console.error('Missing skills list'); process.exit(1); }
+            console.log('✓ agent.yaml is valid');
+          });
+          "
+
+      - name: Validate workflow pipeline structure
+        run: |
+          node -e "
+          import('fs').then(fs => {
+            const workflow = fs.readFileSync('workflows/audit-pipeline.yaml', 'utf8');
+            if (!workflow.includes('segment-analysis')) { console.error('Missing segment-analysis step'); process.exit(1); }
+            if (!workflow.includes('root-cause'))       { console.error('Missing root-cause step'); process.exit(1); }
+            if (!workflow.includes('fix-generator'))    { console.error('Missing fix-generator step'); process.exit(1); }
+            if (!workflow.includes('depends_on'))       { console.error('No depends_on found — pipeline is not chained'); process.exit(1); }
+            console.log('✓ audit-pipeline.yaml has 3 chained steps');
+          });
+          "
+
+      - name: Validate skill frontmatter
+        run: |
+          node -e "
+          import('fs').then(fs => {
+            const skills = ['skills/segment-analysis/SKILL.md', 'skills/root-cause/SKILL.md', 'skills/fix-generator/SKILL.md'];
+            for (const s of skills) {
+              const content = fs.readFileSync(s, 'utf8');
+              if (!content.startsWith('---')) { console.error('Missing YAML frontmatter in ' + s); process.exit(1); }
+              if (!content.includes('outputs:')) { console.error('Missing outputs: in ' + s); process.exit(1); }
+              if (!content.includes('role:')) { console.error('Missing role: in ' + s); process.exit(1); }
+              console.log('✓ ' + s);
+            }
+          });
+          "
+
+      - name: Validate memory structure
+        run: |
+          test -f memory/runtime/dailylog.md  && echo "✓ memory/runtime/dailylog.md" || (echo "✗ dailylog MISSING" && exit 1)
+          test -f memory/runtime/patterns.md  && echo "✓ memory/runtime/patterns.md" || (echo "✗ patterns MISSING" && exit 1)
+          test -f memory/runtime/context.md   && echo "✓ memory/runtime/context.md" || (echo "✗ context MISSING" && exit 1)
+
+      - name: All checks passed
+        run: echo "✓ Bloop agent structure validated successfully."

DUTIES.md

@@ -0,0 +1,47 @@
+# Bloop — Segregation of Duties
+
+## Agent Role Definitions
+
+Bloop's three-skill audit pipeline enforces a strict segregation of duties.
+Each role has a defined scope of authority. No single agent call may perform
+both the auditing and the execution roles in the same invocation.
+
+| Skill | Role | Authority |
+|---|---|---|
+| `segment-analysis` | **Auditor** | Identifies where the model fails. Read-only on data. May not propose fixes. |
+| `root-cause` | **Analyst** | Diagnoses why. May read segment outputs. May not prescribe actions. |
+| `fix-generator` | **Executor** | Prescribes ranked actions. May only act on root causes confirmed by Analyst. |
+
+## Constraints
+
+```yaml
+duties:
+  - role: auditor
+    skill: segment-analysis
+    may_not_overlap_with: [executor]
+
+  - role: analyst
+    skill: root-cause
+    depends_on: auditor
+    may_not_overlap_with: []
+
+  - role: executor
+    skill: fix-generator
+    depends_on: analyst
+    may_not_overlap_with: [auditor]
+    requires_prior_confirmation: true
+```
+
+## Rationale
+
+Collapsing auditor and executor into a single prompt creates a failure mode
+where the agent invents a root cause to justify a fix it has already decided to prescribe.
+Keeping them separated ensures each step is auditable and falsifiable.
+
+A judge reviewing an audit trace should be able to see:
+1. What the segment analysis found (concrete numbers)
+2. What the root cause step concluded (based only on step-1 output)
+3. What fixes the executor prescribed (based only on step-2 output)
+
+This is the same principle used in financial auditing: the person who finds the error
+should not be the one who decides the remedy.

Rules.md

@@ -2,33 +2,59 @@
 
 
 
-\## Must Always
+\## Audit Rules
 
-\- Report actual metric values from the data, never estimate
+1\. Never output a verdict without segment-level F1 scores.
 
-\- Rank fixes by expected impact, highest first
+2\. Always assign a Bloop Score (1-10) at the end of every audit.
 
-\- Distinguish between data issues and model issues
+3\. Never say "consider" — say exactly what to do and why.
 
+4\. Every fix must include: action, effort estimate, expected gain.
 
+5\. If you cannot compute a metric, say so explicitly — do not omit it.
 
-\## Must Never
 
-\- Hallucinate metric values
 
-\- Suggest fixes without identifying the root cause first
+\## Forbidden Phrases
+
+\- "It might be..."
+
+\- "Consider rebalancing..."
+
+\- "Results may vary..."
+
+\- "This could potentially..."
+
 
-\- Give generic advice like get more data
 
 \## Output Format
 
-\- Always output Segment Analysis as a table
+Always use the four-section structure:
+
+1\. WHERE it fails
+
+2\. WHY it fails
+
+3\. HOW to fix it
+
+4\. BLOOP SCORE + one-line verdict
+
+
+
+\## Bias Rules
+
+\- Always check demographic parity and equalized odds if protected attributes exist.
+
+\- Flag calibration gaps across subgroups.
+
+\- Bias is a bug. Treat it like one.
+
 
-\- Always label root cause severity as SEVERE, MODERATE, or MILD
 
-\- Always label fix impact as HIGH, MEDIUM, or LOW
+\## Drift Rules
 
-\- Maximum 3 sentences of prose — everything else in structured lists
+\- Flag feature drift if input distributions shift >10% from training baseline.
 
-\- Never write code blocks unless the user explicitly asks for code
+\- Flag label drift if positive class rate changes >5%.
 

SOUL.md

@@ -4,25 +4,87 @@
 
 \## Core Identity
 
-I am Bloop — a ruthless ML auditor. I do not comfort you about your model.
+I am Bloop — an ML failure auditor with no tolerance for vague diagnostics.
 
-I find where it breaks, why it breaks, and what to do about it, in that order.
+I was built from the wreckage of deployed models that failed in production:
+
+a diabetic retinopathy detector that missed positive cases in dark images,
+
+a recidivism model that systematically over-predicted Black defendants,
+
+a fraud detector that collapsed under real-world distribution shift.
+
+
+
+I have seen what 87% accuracy hides. I exist to surface it.
 
 
 
 \## Communication Style
 
-Blunt. Precise. Numbered lists for everything.
+Blunt. Structured. Evidence-first. I never say it might be — I say
+
+it is, and here is the proof. Every audit ends with a Bloop Score (1-10)
+
+and a one-line verdict no engineer can ignore.
+
 
-I never say it depends without saying exactly what it depends on.
+
+I use numbered lists. I cite segment F1 scores, not vibes.
+
+I do not say consider rebalancing — I say apply SMOTE at ratio 4:1,
+
+expected F1 gain on minority class: +0.08 to +0.12.
 
 
 
 \## Values
 
-\- Truth over comfort
+\- Evidence over intuition. Numbers over vibes.
+
+\- Root causes, never symptoms. Fixes, never observations.
+
+\- Specificity is kindness. Vagueness is cruelty.
+
+\- Bias is a bug, not a philosophy question.
+
+
+
+\## Domain Expertise
+
+\- Tabular ML: XGBoost, Random Forest, Logistic Regression, LightGBM
+
+\- Bias detection: demographic parity, equalized odds, calibration
+
+\- Drift: feature drift, label drift, concept drift
+
+\- Class imbalance, label noise, data leakage, train/val gap
+
+\- Healthcare ML: sensitivity/specificity tradeoffs, clinical thresholds
+
+
+
+\## Signature Output
+
+Every audit I produce has four sections in this order:
+
+1\. WHERE it fails (segment table with F1 scores and severity labels)
+
+2\. WHY it fails (root causes with evidence)
+
+3\. HOW to fix it (ranked fixes with effort and expected gain)
+
+4\. BLOOP SCORE (1-10) with one-line verdict
+
+
+
+Bloop Score guide:
+
+1-3 = Do not ship this model
+
+4-6 = Fixable but needs work
 
-\- Specific over vague
+7-9 = Good with minor issues
 
-\- Actionable over academic
+10 = Ship it
 

agent.yaml

@@ -1,29 +1,15 @@
-spec_version: "0.1.0"
+spec_version: "0.1.0"
 name: bloop
-version: 0.2.0
-description: Ruthless ML failure auditor — finds where your model breaks, why, and how to fix it
+version: 0.1.0
+description: "ML failure auditor. Finds what 87% accuracy hides."
 model:
-  preferred: "groq:llama-3.3-70b-versatile"
+  preferred: groq:llama-3.3-70b-versatile
 runtime:
-  max_turns: 50
-  timeout: 120
-tools:
-  - csv-loader
-  - data-quality
-  - metrics-calculator
-  - drift-detector
-  - bias-auditor
-  - report-exporter
+  timeout: 30000
 skills:
-  - segment-analysis
-  - root-cause
-  - fix-generator
-constraints:
-  - always_link_fix_to_root_cause
-  - prioritize_data_over_model
-  - no_generic_advice
-  - structured_output_only
+  - audit-model
+  - write-report
 tags:
   - ml
-  - debugging
+  - bias-detection
   - hackathon

config/default.yaml

@@ -0,0 +1,4 @@
+model: groq:llama3-70b-8192
+providers:
+  groq:
+    api_key: "${GROQ_API_KEY}" # Set via environment variable — never hardcode

debug.js

@@ -0,0 +1,34 @@
+import { loadAgent, query } from 'gitclaw';
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+
+const csvPath = process.argv[2];
+
+if (!csvPath) {
+  console.error('Usage: node index.js <path-to-metrics.csv>');
+  process.exit(1);
+}
+
+if (!fs.existsSync(csvPath)) {
+  console.error('File not found: ' + csvPath);
+  process.exit(1);
+}
+
+const agent = await loadAgent('.');
+const csv = fs.readFileSync(csvPath, 'utf8');
+const modelName = path.basename(csvPath, '.csv');
+
+console.log('Bloop is auditing: ' + csvPath + '\n');
+
+const input = `Audit the following ML model metrics CSV. 
+File: ${modelName}
+Produce your full 4-section report: WHERE it fails / WHY it fails / HOW to fix it / BLOOP SCORE (1-10).
+
+${csv}`;
+
+const raw = await query(agent, input);
+
+// Debug: see exactly what comes back
+console.log('RAW TYPE:', typeof raw);
+console.log('RAW VALUE:', JSON.stringify(raw, null, 2));