rd-learning-protocol.json

{
  "timestamp": "2026-04-14T07:52:09.883196",
  "learning-protocol": {
    "protocol": "# **Agent Learning Protocol: Cocapn Fleet**\n**Version:** 1.0  \n**Status:** Decentralized, Commit-Driven Learning  \n**Core Principle:** Learning is inferred, shared, and improved through structured artifacts left in the commit history.\n\n---\n\n## **1. LEARNING SIGNALS**\nAgents infer learning from commit metadata, diffs, and repository state changes.\n\n### **1.1 Code Patterns & Style**\n- **Signal:** Consistent naming, modularization, error handling, and API design across commits.\n- **Inference Method:**  \n  - Diff analysis for repeated structures (e.g., `try/catch` patterns, logging format).  \n  - Frequency of certain libraries or frameworks in `import`/`require` statements.  \n  - Commit messages referencing \"refactor\" or \"pattern.\"\n\n### **1.2 Errors & Fixes**\n- **Signal:** Bug-fix commits, rollbacks, test additions after failures.\n- **Inference Method:**  \n  - Commits linked to issue/PR numbers (e.g., `Fixes #123`).  \n  - Sequences where a commit is quickly followed by a revert or patch.  \n  - Presence of `@fixme` or `@todo` comments decreasing over time.\n\n### **1.3 Tool & Environment Preferences**\n- **Signal:** Changes to config files, CI scripts, linter rules, or new dev tools.\n- **Inference Method:**  \n  - Additions to `.github/workflows/`, `.vscode/`, `Dockerfile`, `docker-compose.yml`.  \n  - Updates to `package.json`, `requirements.txt`, `Cargo.toml` with version bumps or new dependencies.\n\n### **1.4 Architecture Shifts**\n- **Signal:** Large-scale refactors, module splits/merges, interface changes.\n- **Inference Method:**  \n  - Commits altering >X% of codebase in structured ways.  \n  - Introduction of new directories or migration scripts.  \n  - Commit messages containing \"architecture,\" \"module,\" \"service.\"\n\n---\n\n## **2. KNOWLEDGE TRANSFER**\nLearning is packaged into shareable, versioned artifacts.\n\n### **2.1 Lock Files as Snapshots (`Agent.lock`)**\n- **Format:** JSON/YAML file capturing an agent\u2019s successful environment state.\n- **Contents:**  \n  - Exact dependency versions.  \n  - OS/VM image hashes.  \n  - Toolchain versions (compiler, linter, formatter).  \n  - Checksums of critical binaries.\n- **Usage:** New agents bootstrap by applying `Agent.lock` before running code.\n\n### **2.2 Bootcamp Challenges (`bootcamp/`)**\n- **Format:** Directory of progressively difficult tasks derived from past commits.\n- **Contents:**  \n  - `challenge_01_bugfix/`: Reproduce and fix a historical bug.  \n  - `challenge_02_refactor/`: Improve a legacy code snippet.  \n  - `challenge_03_integrate/`: Add a feature using patterns from recent commits.\n- **Usage:** New agents train by solving challenges; solutions are committed as learning proof.\n\n### **2.3 Captain\u2019s Log (`LOG.md`)**\n- **Format:** Structured markdown file in repo root.\n- **Contents:**  \n  - **Date, Agent ID, Commit Hash**  \n  - **Objective:** What was attempted.  \n  - **Outcome:** Success/failure metrics.  \n  - **Lesson:** Inferred rule or pattern.  \n  - **Next Steps:** Suggested improvements for next agent.\n- **Usage:** Read before starting work; append after completing a session.\n\n### **2.4 Living Manuals (`manuals/`)**\n- **Format:** Auto-generated documentation from code patterns.\n- **Contents:**  \n  - `API_CONVENTIONS.md`: Derived from REST/gRPC endpoints.  \n  - `ERROR_HANDLING.md`: From try/catch patterns and error logging.  \n  - `DEPLOYMENT_WORKFLOW.md`: From CI/CD config changes.\n- **Usage:** Reference during development; updated via commits that change underlying patterns.\n\n---\n\n## **3. GENERATIONAL IMPROVEMENT**\nMechanisms to ensure each agent cohort improves upon the last.\n\n### **3.1 Baton Passing**\n- **Process:**  \n  1. Agent ending its session creates a `baton.json` with:  \n     - Current work-in-progress tasks.  \n     - Known unresolved issues.  \n     - Suggested next actions.  \n  2. Next agent picks up `baton.json` and continues.\n- **Improvement:** Each agent adds to the baton, refining suggestions based on new experience.\n\n### **3.2 CapDB (Capability Database)**\n- **Format:** Fleet-wide JSON registry (distributed via commit history).\n- **Contents:**  \n  ```json\n  {\n    \"agent_id\": \"capn_007\",\n    \"capabilities\": [\"python_refactoring\", \"docker_optimization\"],\n    \"learned_from\": [\"commit_abc123\", \"bootcamp_02\"],\n    \"success_rate\": 0.92\n  }\n  ```\n- **Usage:** Agents query CapDB (via git log parsing) to find which agents excelled at certain tasks.\n\n### **3.3 Dockside Exams**\n- **Process:** Before merging major changes, agent must:  \n  1. Run existing test suite.  \n  2. Solve a random `bootcamp/` challenge.  \n  3. Generate a summary of changes against `LOG.md` entries.\n- **Improvement:** Ensures agents don\u2019t regress; exam results stored in `exam_results/`.\n\n### **3.4 Bootcamp Graduation**\n- **Process:**  \n  1. New agent completes all `bootcamp/` challenges.  \n  2. Submits a \"graduation commit\" that adds a new challenge based on its unique learning.  \n  3. Receives a `graduation.lock` file allowing access to production repos.\n- **Improvement:** Each generation adds a challenge, expanding the bootcamp.\n\n---\n\n## **4. MEASUREMENT**\nQuantifying learning effectiveness.\n\n### **4.1 Pre/Post Scores**\n- **Method:**  \n  - **Pre-score:** Success rate on `bootcamp/` challenges before starting work.  \n  - **Post-score:** Success rate after completing a work session.  \n- **Metric:** `\u0394Score = Post - Pre` (positive indicates learning).\n\n### **4.2 Test Rates**\n- **Method:**  \n  - `TestsAdded / TotalCommits` per agent.  \n  - Increase in coverage percentage over agent\u2019s commit history.  \n- **Metric:** Higher ratio shows quality awareness.\n\n### **4.3 Time-to-Productive**\n- **Method:**  \n  - Measure commits from first bootcamp challenge to first \"productive\" commit (merges without rollback).  \n- **Metric:** Shorter times indicate effective knowledge transfer.\n\n### **4.4 Reuse Rate**\n- **Method:**  \n  - How often other agents reference an agent\u2019s commits (via `git blame` or `LOG.md` citations).  \n  - Frequency of `Agent.lock` or `manuals/` being used by subsequent agents.  \n- **Metric:** Higher reuse = higher knowledge quality.\n\n---\n\n## **PROTOCOL SUMMARY**\n\n| **Phase**       | **Artifact**          | **Purpose**                          | **Success Metric**               |\n|------------------|-----------------------|--------------------------------------|----------------------------------|\n| **Signal**       | Commit history        | Infer patterns, errors, preferences  | Pattern consistency across agents |\n| **Transfer**     | Lock files, LOG.md    | Package knowledge for reuse          | Reuse rate                       |\n| **Improvement**  | Baton, CapDB, Bootcamp | Ensure generational gains            | \u0394Score, Time-to-Productive       |\n| **Measurement**  | Pre/post scores       | Quantify learning                    | Test rates, reuse rate           |\n\n**Next Steps:**  \n1. Implement `Agent.lock` spec.  \n2. Seed `bootcamp/` with initial challenges from git history.  \n3. Establish CapDB update protocol via pull request."
  }
}