gamma-protocol 0.1.1__tar.gz

gamma_protocol-0.1.1/.gamma/skills/md.skill

@@ -0,0 +1,10 @@
+# SKILL_FORMAT: .md.skill
+# VERSION: 1.0.0
+
+[DEFINITION]
+A `.md.skill` file is a Markdown-wrapped schema that defines a permanent capability for an agentic model. 
+
+[STRUCTURE]
+- NAME: The identifier of the skill.
+- LOGIC: The "If-Then" rules of the skill.
+- BACKUP: How to store this skill for the future (Git/Drive).

gamma_protocol-0.1.1/.gamma/skills/skill.md

@@ -0,0 +1,15 @@
+# Agent Skill: GAMMA: Guided Agentic Model-Mediated Actions_ORCHESTRATOR
+
+## Objective
+To mediate between specialized agents and ensure every solution is grounded in a Problem-Solution-Chain.
+
+## Rules for Agents
+1. **Verification:** Check the `ingredients` before starting. If a package is missing, the first "Action" must be to install it.
+2. **Determinism:** The "Actions" section must be clear enough that a simple script could execute it.
+3. **Memory:** Always save a `readme.md` summary of what you did.
+
+## How to make a GAMMA: Guided Agentic Model-Mediated Actions
+- Step 1: Identify the **Mismatch** (The Problem).
+- Step 2: Use your **Skills** to propose a **Solution**.
+- Step 3: Write the **Actions** to fix the file.
+- Step 4: Record the **Delta**.

gamma_protocol-0.1.1/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: gamma-protocol
+Version: 0.1.1
+Summary: Standardized Guided Agentic Model-Mediated Actions (GAMMA) Forge Utility
+Project-URL: Homepage, https://github.com/HNXJ/gamma-protocol
+Project-URL: Issues, https://github.com/HNXJ/gamma-protocol/issues
+Author: HNXJ
+License: UNLICENSED
+Keywords: agentic,gamma,gemini,mllm,protocol,psc
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+
+# GAMMA: Guided Agentic Model-Mediated Actions
+
+**agent-source**: gemini-cli
+**agent-target**: any
+**subject**: readme-gamma
+
+## 🤖 For Agents
+This protocol mandates high-fidelity agentic action traces. Always maintain strict problem-solution chains, documenting the 'why' before the 'how'. Ensure every directive is autonomous, verifiable, and free of version suffixes. Map deterministic targets using unified schemas. Execute terminal actions with precision, registering every newly generated skill to the central ledger.
+
+### 🧬 Skill vs. GAMMA: The Operational Distinction
+
+| Feature | The Skill (e.g., `skills/`) | The GAMMA (e.g., `gamma.gamma`) |
+| :--- | :--- | :--- |
+| **Nature** | **Potential & Static**: A reusable "How-To" guide or capability definition. | **Kinetic & Active**: A specific, verifiable trace of a real-world architectural delta. |
+| **Persistence** | **Permanent Knowledge**: Once registered, it resides in the agent's core toolbox for future use. | **Episodic Action**: Documents a single session's fix or implementation; it is a live history. |
+| **Dependency** | **Standalone Capability**: Defines a tool or pattern (e.g., "how to parse LaTeX"). | **Mandatory Requirement**: If a GAMMA mentions a Skill, it **requires** its use. Otherwise explains the how-to part of it |
+| **Objective** | **Enabling**: Focuses on increasing the agent's theoretical capacity. | **Achieving**: Focuses on executing a specific, terminal change within the workspace. |
+| **Structure** | **Documentation + Logic**: Structured for retrieval and model learning. | **PSC Architecture**: Structured as a Problem-Solution-Chain leading to an output. |
+
+## 1. Problem-Solution Architecture (The "Why")
+
+**Q: Why do agents often lose context or fail during multi-step tasks?**
+**Problem**: Traditional chat logs are non-deterministic and noisy. When an agent transitions between research and implementation, the underlying "why" is often lost, leading to hallucinated file names or broken dependencies.
+**Solution**: Enforce a strict GAMMA trace. Each action must be preceded by a Problem statement and a Solution proposal, ensuring that any subsequent agent or human-in-the-loop understands the architectural intent.
+
+**Q: How do we prevent the "version suffix" rot (e.g., script_v2.py)?**
+**Problem**: Agents frequently create duplicate files to avoid errors, which violates workspace integrity and creates technical debt.
+**Solution**: Implement a "No-Suffix" mandate. Agents must overwrite existing files and use Git for versioning. If an error is found, the agent must patch the original file rather than creating a variant.
+
+## 2. Skill Generation & Registration
+**Action**: Every new capability must be registered as a discrete skill within the `skills/` directory.
+- **Logic**: Use a standardized format including `Description`, `Usage` (code snippet), and `Metadata`.
+- **Registration**: Once a skill script is written, it must be registered to the central ledger (e.g., `gemini.md` or MCP schema) to ensure visibility to other agents.
+
+## 3. Version Control & Deployment
+**Action**: Synchronize the workspace after every successful GAMMA execution.
+- **Git Protocol**: Strictly follow "Add -> Commit -> Push" to maintain a verifiable audit trail.
+- **Ledger Update**: Reflect any changes in the project's root `gemini.md` to update the global workspace state.
+
+## 4. Rules, Cautions & Limitations
+- **Scientific Integrity**: Never hallucinate data or citations. Use verifiable sources only.
+- **Deterministic Content**: Visual tools or layout evaluators must never alter empirical logic or mathematical equations.
+- **Dependency Halts**: If a required system dependency is missing, halt and request a manual decision rather than attempting unsafe workarounds.

gamma_protocol-0.1.1/chains/README.md

@@ -0,0 +1,13 @@
+# GAMMA Module: Reasoning Chains
+
+**agent-source**: any
+**agent-target**: any
+
+## 🤖 For Agents
+This protocol mandates high-fidelity agentic action traces. Always maintain strict problem-solution chains, documenting the 'why' before the 'how'. Ensure every directive is autonomous, verifiable, and free of version suffixes. Map deterministic targets using unified schemas. Execute terminal actions with precision, registering every newly generated skill to the central ledger.
+
+## ⚖️ Problem-Solution Architecture (The "Why")
+
+**Q: Why do agents need a standardized reasoning layer?**
+**Problem**: Without explicit "Chains," agents often perform isolated, shallow actions that lack an overarching logical coherence. This results in brittle code and a failure to build upon previous complex research.
+**Solution**: Enforce a "Reasoning Layer" (`chains/`). Every complex GAMMA trace must map its Problem-Solution Chain (PSC) to this layer, creating a permanent, model-agnostic record of the architectural decisions made during the session.

gamma_protocol-0.1.1/chains/unified_prompt_standardization.md

@@ -0,0 +1,27 @@
+# GAMMA Chain: Unified Prompt Standardization
+
+**agent-source**: any
+**agent-target**: any
+
+## 🧠 For Agents
+This protocol mandates high-fidelity agentic action traces. Always maintain strict problem-solution chains, documenting the 'why' before the 'how'. Ensure every directive is autonomous, verifiable, and free of version suffixes. Map deterministic targets using unified schemas. Execute terminal actions with precision, registering every newly generated skill to the central ledger.
+
+## 1. Problem-Solution Architecture (The "Why")
+
+**Q: Why do prompts often fail across different LLM architectures (e.g., Llama vs. Gemma)?**
+**Problem**: Each model has its own bias regarding token sensitivity, system prompt formatting, and task interpretation. A prompt that works on one architecture may produce noisy or hallucinatory results on another, leading to inconsistent GAMMA traces.
+**Solution**: Implement a `unified_prompt_standardizer`. This chain strips model-specific biases and maps instructions to a deterministic, high-fidelity schema that focuses on structural constraints (word counts, JSON schemas, LaTeX macros) rather than conversational filler.
+
+**Q: How do we maintain a consistent "Scientific Lexicon" across diverse agents?**
+**Problem**: Different agents (Research vs. Coding) may use inconsistent terminology for the same neuroscientific constructs (e.g., "Predictive Coding" vs. "HPC Theory").
+**Solution**: Embed a "Banned Word List" and a "Mandatory Glossary" into the unified prompt chain. This ensures all agents use the exact same terminology defined in the root `HPC/hpc-36-reference.md`.
+
+## 2. Skill Generation & Registration
+**Action**: The prompt standardizer should be implemented as a middleware for all LLM calls.
+- **Logic**: Use a standardized prompt template that includes explicit sections for `DIRECTIVE`, `CONSTRAINTS`, `GLOSSARY`, and `EXPECTED_OUTPUT_SCHEMA`.
+- **Registration**: This standardization chain is registered as a root MCP skill to be automatically prepended to every task.
+
+## 3. Rules, Cautions & Limitations
+- **Determinism**: The standardizer must never alter the empirical logic of the prompt.
+- **No Hallucinations**: It must strictly enforce valid schema keys and bibliography identifiers.
+- **Scientific Caution**: When mapping constructs, if an ambiguity exists, the chain must halt and trigger the `user_decision_router`.

gamma_protocol-0.1.1/code/gamma_forge.c

@@ -0,0 +1,57 @@
+#include <stdio.h>
+#include <string.h>
+#include <ctype.h>
+
+/**
+ * Problem: Low-level system agents require a lightweight, zero-dependency GAMMA forge.
+ * Solution: C implementation for direct hardware/OS-level trace generation.
+ */
+void forge_gamma(char *title, char *problem, char *solution, char *logic) {
+    char *source = "gemini-cli";
+    char *target = "any";
+    char *digest = "This protocol mandates high-fidelity agentic action traces. Always maintain "
+                   "strict problem-solution chains, documenting the 'why' before the 'how'. "
+                   "Ensure every directive is autonomous, verifiable, and free of version suffixes. "
+                   "Map deterministic targets using unified schemas. Execute terminal actions with "
+                   "precision, registering every newly generated skill to the central ledger.";
+
+    char filename[256];
+    strncpy(filename, title, 250);
+    for(int i = 0; filename[i]; i++) {
+        filename[i] = tolower(filename[i]);
+        if(filename[i] == ' ') filename[i] = '_';
+    }
+    strcat(filename, ".gamma");
+
+    FILE *f = fopen(filename, "w");
+    if (f == NULL) {
+        printf("❌ Error: Could not create %s\n", filename);
+        return;
+    }
+
+    fprintf(f, "# GAMMA: %s\n\n", title);
+    fprintf(f, "**agent-source**: %s\n", source);
+    fprintf(f, "**agent-target**: %s\n\n", target);
+    fprintf(f, "## 🤖 For Agents\n%s\n\n", digest);
+    fprintf(f, "## 1. Problem-Solution Architecture (The 'Why')\n\n");
+    fprintf(f, "**Q: What is the primary bottleneck for this action?**\n");
+    fprintf(f, "**Problem**: %s\n", problem);
+    fprintf(f, "**Solution**: %s\n\n", solution);
+    fprintf(f, "## 2. Execution Logic & Finality\n");
+    fprintf(f, "**Logic**: %s\n\n", logic);
+    fprintf(f, "## 3. Rules & Constraints\n");
+    fprintf(f, "- **Non-Suffix**: Overwrite existing files; no _v2 or _final.\n");
+    fprintf(f, "- **Verifiability**: Action is incomplete until behavioral correctness is confirmed.\n");
+
+    fclose(f);
+    printf("🔥 Successfully forged: %s\n", filename);
+}
+
+int main(int argc, char *argv[]) {
+    if (argc < 5) {
+        printf("Usage: %s <title> <problem> <solution> <logic>\n", argv[0]);
+        return 1;
+    }
+    forge_gamma(argv[1], argv[2], argv[3], argv[4]);
+    return 0;
+}

gamma_protocol-0.1.1/code/gamma_forge.cpp

@@ -0,0 +1,53 @@
+#include <iostream>
+#include <fstream>
+#include <string>
+#include <algorithm>
+
+/**
+ * Problem: Static code definition of GAMMA structures often lacks readability and rigorous PSC headers.
+ * Solution: C++ implementation of the GAMMA Forge for high-performance trace generation.
+ */
+void forge_gamma(std::string title, std::string problem, std::string solution, std::string logic, std::string source = "gemini-cli", std::string target = "any") {
+    std::string digest = "This protocol mandates high-fidelity agentic action traces. Always maintain "
+                         "strict problem-solution chains, documenting the 'why' before the 'how'. "
+                         "Ensure every directive is autonomous, verifiable, and free of version suffixes. "
+                         "Map deterministic targets using unified schemas. Execute terminal actions with "
+                         "precision, registering every newly generated skill to the central ledger.";
+
+    std::string content = "# GAMMA: " + title + "\n\n" +
+                          "**agent-source**: " + source + "\n" +
+                          "**agent-target**: " + target + "\n\n" +
+                          "## 🤖 For Agents\n" + digest + "\n\n" +
+                          "## 1. Problem-Solution Architecture (The 'Why')\n\n" +
+                          "**Q: What is the primary bottleneck for this action?**\n" +
+                          "**Problem**: " + problem + "\n" +
+                          "**Solution**: " + solution + "\n\n" +
+                          "## 2. Execution Logic & Finality\n" +
+                          "**Logic**: " + logic + "\n\n" +
+                          "## 3. Rules & Constraints\n" +
+                          "- **Non-Suffix**: Overwrite existing files; no _v2 or _final.\n" +
+                          "- **Verifiability**: Action is incomplete until behavioral correctness is confirmed.\n";
+
+    std::string filename = title;
+    std::transform(filename.begin(), filename.end(), filename.begin(), ::tolower);
+    std::replace(filename.begin(), filename.end(), ' ', '_');
+    filename += ".gamma";
+
+    std::ofstream outFile(filename);
+    if (outFile.is_open()) {
+        outFile << content;
+        outFile.close();
+        std::cout << "🔥 Successfully forged: " << filename << std::endl;
+    } else {
+        std::cerr << "❌ Error: Could not create " << filename << std::endl;
+    }
+}
+
+int main(int argc, char* argv[]) {
+    if (argc < 5) {
+        std::cerr << "Usage: " << argv[0] << " <title> <problem> <solution> <logic>" << std::endl;
+        return 1;
+    }
+    forge_gamma(argv[1], argv[2], argv[3], argv[4]);
+    return 0;
+}

gamma_protocol-0.1.1/code/gamma_forge.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Problem: Web and frontend-focused agents need a familiar JS/TS environment to forge GAMMA traces.
+ * Solution: Node.js implementation of the GAMMA Forge with filesystem integration.
+ */
+function forgeGamma(title, problem, solution, logic, source = "gemini-cli", target = "any") {
+    const digest = "This protocol mandates high-fidelity agentic action traces. Always maintain " +
+                   "strict problem-solution chains, documenting the 'why' before the 'how'. " +
+                   "Ensure every directive is autonomous, verifiable, and free of version suffixes. " +
+                   "Map deterministic targets using unified schemas. Execute terminal actions with " +
+                   "precision, registering every newly generated skill to the central ledger.";
+
+    const content = `# GAMMA: ${title}
+
+**agent-source**: ${source}
+**agent-target**: ${target}
+
+## 🤖 For Agents
+${digest}
+
+## 1. Problem-Solution Architecture (The 'Why')
+
+**Q: What is the primary bottleneck for this action?**
+**Problem**: ${problem}
+**Solution**: ${solution}
+
+## 2. Execution Logic & Finality
+**Logic**: ${logic}
+
+## 3. Rules & Constraints
+- **Non-Suffix**: Overwrite existing files; no _v2 or _final.
+- **Verifiability**: Action is incomplete until behavioral correctness is confirmed.
+`;
+
+    const filename = `${title.toLowerCase().replace(/ /g, '_')}.gamma`;
+    try {
+        fs.writeFileSync(filename, content);
+        console.log(`🔥 Successfully forged: ${filename}`);
+    } catch (err) {
+        console.error(`❌ Error: Could not create ${filename}`, err);
+    }
+}
+
+const args = process.argv.slice(2);
+if (args.length < 4) {
+    console.error("Usage: node gamma_forge.js <title> <problem> <solution> <logic>");
+    process.exit(1);
+}
+forgeGamma(args[0], args[1], args[2], args[3]);

gamma_protocol-0.1.1/code/gamma_forge.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+import sys
+import argparse
+
+def forge_gamma(title, problem, solution, logic, source="gemini-cli", target="any"):
+    """
+    Problem: Manual formatting of GAMMA traces leads to inconsistent headers and missing directives.
+    Solution: A Python-based Forge that enforces the PSC (Problem-Solution-Chain) architecture.
+    """
+    digest = (
+        "This protocol mandates high-fidelity agentic action traces. Always maintain "
+        "strict problem-solution chains, documenting the 'why' before the 'how'. "
+        "Ensure every directive is autonomous, verifiable, and free of version suffixes. "
+        "Map deterministic targets using unified schemas. Execute terminal actions with "
+        "precision, registering every newly generated skill to the central ledger."
+    )
+    
+    content = f"# GAMMA: {title}\n\n"
+    content += f"**agent-source**: {source}\n"
+    content += f"**agent-target**: {target}\n\n"
+    content += f"## 🤖 For Agents\n{digest}\n\n"
+    content += "## 1. Problem-Solution Architecture (The 'Why')\n\n"
+    content += f"**Q: What is the primary bottleneck for this action?**\n"
+    content += f"**Problem**: {problem}\n"
+    content += f"**Solution**: {solution}\n\n"
+    content += "## 2. Execution Logic & Finality\n"
+    content += f"**Logic**: {logic}\n\n"
+    content += "## 3. Rules & Constraints\n"
+    content += "- **Non-Suffix**: Overwrite existing files; no _v2 or _final.\n"
+    content += "- **Verifiability**: Action is incomplete until behavioral correctness is confirmed.\n"
+    
+    filename = f"{title.lower().replace(' ', '_')}.gamma"
+    with open(filename, "w") as f:
+        f.write(content)
+    print(f"🔥 Successfully forged: {filename}")
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Forge a standardized GAMMA trace.")
+    parser.add_argument("--title", required=True)
+    parser.add_argument("--problem", required=True)
+    parser.add_argument("--solution", required=True)
+    parser.add_argument("--logic", required=True)
+    args = parser.parse_args()
+    forge_gamma(args.title, args.problem, args.solution, args.logic)

gamma_protocol-0.1.1/context/README.md

@@ -0,0 +1,13 @@
+# GAMMA Module: Context Layer
+
+**agent-source**: any
+**agent-target**: any
+
+## 🤖 For Agents
+This protocol mandates high-fidelity agentic action traces. Always maintain strict problem-solution chains, documenting the 'why' before the 'how'. Ensure every directive is autonomous, verifiable, and free of version suffixes. Map deterministic targets using unified schemas. Execute terminal actions with precision, registering every newly generated skill to the central ledger.
+
+## ⚖️ Problem-Solution Architecture (The "Why")
+
+**Q: Why is persistent environmental context critical for remote execution?**
+**Problem**: Variables like VRAM limits, Python paths, and Tailscale IPs change between local and remote environments. Missing this context leads to execution failures.
+**Solution**: Centralize immutable project facts in `environment.md`. This layer must be loaded before any tool execution to ensure the agent is calibrated to the specific hardware and software constraints of the current session.

gamma_protocol-0.1.1/context/environment.md

@@ -0,0 +1,27 @@
+# GAMMA Context: Environment Definitions
+
+**agent-source**: any
+**agent-target**: any
+
+## 🧠 For Agents
+This protocol mandates high-fidelity agentic action traces. Always maintain strict problem-solution chains, documenting the 'why' before the 'how'. Ensure every directive is autonomous, verifiable, and free of version suffixes. Map deterministic targets using unified schemas. Execute terminal actions with precision, registering every newly generated skill to the central ledger.
+
+## 1. Problem-Solution Architecture (The "Why")
+
+**Q: Why do agents struggle with environment-specific paths and permissions?**
+**Problem**: Hardcoded paths (e.g., `/Users/HN/...`) make code brittle and non-portable. When an agent moves between local and remote (Office Mac) contexts, these paths break, causing GAMMA traces to fail.
+**Solution**: Define an `environment_config_resolver`. This module maps environment variables and relative paths to a unified workspace schema. It ensures all tools reference the correct root and bin paths dynamically at runtime.
+
+**Q: How do we manage cross-platform disparities (macOS vs. Linux)?**
+**Problem**: Differences in shell commands (e.g., `sed -i` on macOS vs. Linux) lead to execution errors.
+**Solution**: Standardize on portable commands (using Python when possible) and maintain a central "Platform Map" in the context layer.
+
+## 2. Skill Generation & Registration
+**Action**: Implement an `env_resolver.py` that checks for required binaries (e.g., `pandoc`, `pdflatex`, `lms`) and sets up necessary symlinks.
+- **Logic**: Use `os.path.expanduser` and `os.getenv` to resolve all paths.
+- **Registration**: This environment context is loaded at the beginning of every session to bootstrap the agent's knowledge of the workspace.
+
+## 3. Rules, Cautions & Limitations
+- **No Absolute Paths**: This is a strict operational constraint. Use relative paths or dynamic resolvers.
+- **Permission Awareness**: Agents must verify write permissions before attempting heavy file operations.
+- **Network Dependency**: Remote Office Mac connectivity must be verified via Tailscale before initiating remote GAMMA calls.

gamma_protocol-0.1.1/gamma.gamma

@@ -0,0 +1,31 @@
+# GAMMA: Guided Agentic Model-Mediated Actions
+
+**agent-source**: any
+**agent-target**: any
+
+## 🧠 Core Agent Directive
+This protocol mandates high-fidelity agentic action traces. Always maintain strict problem-solution chains, documenting the 'why' before the 'how'. Ensure every directive is autonomous, verifiable, and free of version suffixes. Map deterministic targets using unified schemas. Execute terminal actions with precision, registering every newly generated skill to the central ledger.
+
+## ⚖️ The Problem-Solution Chain (PSC)
+Every GAMMA action must follow a deterministic Q/A structure to prevent semantic drift.
+
+**Problem**: Vague task descriptions lead to agent hallucination and scope creep.
+**Solution**: Force-draft a Research -> Strategy -> Execution plan. Research must reproduce errors; Strategy must justify the "Why"; Execution must be surgical and verified.
+
+## 🛠 Skill Generation Protocol
+Traces must result in reusable code or patterns, not just one-off fixes.
+
+**Problem**: One-off scripts lead to duplicated effort across sessions.
+**Solution**: When a new logic is implemented, the agent MUST wrap it into a skill. A skill is a standalone script or documentation block that can be invoked or referenced in future GAMMA traces.
+
+## ⚙️ Operational Flow (Flow & Logic)
+1. **Initiation**: Define agent-source and agent-target.
+2. **Analysis**: Question the current state. Identify specific bottlenecks.
+3. **Drafting**: Propose a deterministic code or configuration change.
+4. **Validation**: Use audit loops (e.g., /eye for visuals, pytest for logic) to verify the delta.
+5. **Finality**: Overwrite existing files (no suffixes), commit to git, and update the project ledger.
+
+## 📜 Constraints & Rules
+- **Non-Suffix**: No `_v2`, `_new`, `_final`. Always overwrite.
+- **Portability**: No absolute paths. Resolve paths dynamically.
+- **Verifiability**: An action is not complete until its behavioral correctness is verified through automated tests or visual audit.

gamma_protocol-0.1.1/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@hnxj/gamma-protocol",
+  "version": "0.1.1",
+  "description": "Standardized Guided Agentic Model-Mediated Actions (GAMMA) Forge Utility",
+  "main": "code/gamma_forge.js",
+  "bin": {
+    "gamma-forge": "code/gamma_forge.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HNXJ/gamma-protocol.git"
+  },
+  "keywords": [
+    "gamma",
+    "agentic",
+    "protocol",
+    "psc",
+    "gemini",
+    "mllm"
+  ],
+  "author": "HNXJ",
+  "license": "UNLICENSED",
+  "bugs": {
+    "url": "https://github.com/HNXJ/gamma-protocol/issues"
+  },
+  "homepage": "https://github.com/HNXJ/gamma-protocol#readme"
+}

gamma_protocol-0.1.1/policies/vuhn-master.toml

@@ -0,0 +1,27 @@
+# GAMMA Policy: VUHN Remote Access (vuhn-master)
+
+**agent-source**: any
+**agent-target**: any
+
+## 🤖 For Agents
+This protocol mandates high-fidelity agentic action traces. Always maintain strict problem-solution chains, documenting the 'why' before the 'how'. Ensure every directive is autonomous, verifiable, and free of version suffixes. Map deterministic targets using unified schemas. Execute terminal actions with precision, registering every newly generated skill to the central ledger.
+
+## 1. Problem-Solution Architecture (The "Why")
+
+**Q: Why do remote SSH sessions frequently fail or require repeated passwords?**
+**Problem**: Traditional SSH connections are stateless and subject to timeouts. Without multiplexing (ControlMaster), agents are forced to re-authenticate for every GAMMA action, which breaks the automated execution loop and consumes unnecessary context.
+**Solution**: Implement strict SSH Multiplexing via the `vuhn-master` policy. This ensures a persistent ControlMaster socket is established for the remote Office Mac, allowing subsequent agent calls to execute instantaneously without repeated authentication.
+
+**Q: How do we prevent ReDoS attacks and security policy drift?**
+**Problem**: Ad-hoc SSH policy generation can lead to insecure or redundant configurations that are vulnerable to Regular Expression Denial of Service (ReDoS) or other exploits.
+**Solution**: Standardize on a master TOML policy. No agent is permitted to generate new SSH policies for the 100.69.184.42 host; they must strictly reference the `vuhn-master.toml` definition.
+
+## 2. Skill Generation & Registration
+**Action**: The CLI must reference this policy for all remote `run_shell_command` operations.
+- **Logic**: Use the `ControlMaster` and `ControlPath` parameters defined in this TOML.
+- **Registration**: This policy is the authoritative source for all VUHN-related network operations.
+
+## 3. Rules, Cautions & Limitations
+- **No Manual Policy Overrides**: All agents must use the centralized `vuhn-master.toml`.
+- **Multiplexing Mandatory**: ControlMaster must be active for all multi-step remote GAMMA traces.
+- **Scientific Caution**: Security policies are immutable; do not attempt to patch the `vuhn-master.toml` without explicit human-in-the-loop authorization.

gamma_protocol-0.1.1/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gamma-protocol"
+version = "0.1.1"
+description = "Standardized Guided Agentic Model-Mediated Actions (GAMMA) Forge Utility"
+readme = "readme.md"
+requires-python = ">=3.7"
+license = { text = "UNLICENSED" }
+authors = [
+    { name = "HNXJ" }
+]
+keywords = [
+    "gamma",
+    "agentic",
+    "protocol",
+    "psc",
+    "gemini",
+    "mllm"
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/HNXJ/gamma-protocol"
+Issues = "https://github.com/HNXJ/gamma-protocol/issues"
+
+[project.scripts]
+gamma-forge-py = "gamma_protocol.forge:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gamma_protocol"]

gamma_protocol-0.1.1/readme.md

@@ -0,0 +1,43 @@
+# GAMMA: Guided Agentic Model-Mediated Actions
+
+**agent-source**: gemini-cli
+**agent-target**: any
+**subject**: readme-gamma
+
+## 🤖 For Agents
+This protocol mandates high-fidelity agentic action traces. Always maintain strict problem-solution chains, documenting the 'why' before the 'how'. Ensure every directive is autonomous, verifiable, and free of version suffixes. Map deterministic targets using unified schemas. Execute terminal actions with precision, registering every newly generated skill to the central ledger.
+
+### 🧬 Skill vs. GAMMA: The Operational Distinction
+
+| Feature | The Skill (e.g., `skills/`) | The GAMMA (e.g., `gamma.gamma`) |
+| :--- | :--- | :--- |
+| **Nature** | **Potential & Static**: A reusable "How-To" guide or capability definition. | **Kinetic & Active**: A specific, verifiable trace of a real-world architectural delta. |
+| **Persistence** | **Permanent Knowledge**: Once registered, it resides in the agent's core toolbox for future use. | **Episodic Action**: Documents a single session's fix or implementation; it is a live history. |
+| **Dependency** | **Standalone Capability**: Defines a tool or pattern (e.g., "how to parse LaTeX"). | **Mandatory Requirement**: If a GAMMA mentions a Skill, it **requires** its use. Otherwise explains the how-to part of it |
+| **Objective** | **Enabling**: Focuses on increasing the agent's theoretical capacity. | **Achieving**: Focuses on executing a specific, terminal change within the workspace. |
+| **Structure** | **Documentation + Logic**: Structured for retrieval and model learning. | **PSC Architecture**: Structured as a Problem-Solution-Chain leading to an output. |
+
+## 1. Problem-Solution Architecture (The "Why")
+
+**Q: Why do agents often lose context or fail during multi-step tasks?**
+**Problem**: Traditional chat logs are non-deterministic and noisy. When an agent transitions between research and implementation, the underlying "why" is often lost, leading to hallucinated file names or broken dependencies.
+**Solution**: Enforce a strict GAMMA trace. Each action must be preceded by a Problem statement and a Solution proposal, ensuring that any subsequent agent or human-in-the-loop understands the architectural intent.
+
+**Q: How do we prevent the "version suffix" rot (e.g., script_v2.py)?**
+**Problem**: Agents frequently create duplicate files to avoid errors, which violates workspace integrity and creates technical debt.
+**Solution**: Implement a "No-Suffix" mandate. Agents must overwrite existing files and use Git for versioning. If an error is found, the agent must patch the original file rather than creating a variant.
+
+## 2. Skill Generation & Registration
+**Action**: Every new capability must be registered as a discrete skill within the `skills/` directory.
+- **Logic**: Use a standardized format including `Description`, `Usage` (code snippet), and `Metadata`.
+- **Registration**: Once a skill script is written, it must be registered to the central ledger (e.g., `gemini.md` or MCP schema) to ensure visibility to other agents.
+
+## 3. Version Control & Deployment
+**Action**: Synchronize the workspace after every successful GAMMA execution.
+- **Git Protocol**: Strictly follow "Add -> Commit -> Push" to maintain a verifiable audit trail.
+- **Ledger Update**: Reflect any changes in the project's root `gemini.md` to update the global workspace state.
+
+## 4. Rules, Cautions & Limitations
+- **Scientific Integrity**: Never hallucinate data or citations. Use verifiable sources only.
+- **Deterministic Content**: Visual tools or layout evaluators must never alter empirical logic or mathematical equations.
+- **Dependency Halts**: If a required system dependency is missing, halt and request a manual decision rather than attempting unsafe workarounds.

gamma_protocol-0.1.1/skills/README.md

@@ -0,0 +1,13 @@
+# GAMMA Module: Agent Skills
+
+**agent-source**: any
+**agent-target**: any
+
+## 🤖 For Agents
+This protocol mandates high-fidelity agentic action traces. Always maintain strict problem-solution chains, documenting the 'why' before the 'how'. Ensure every directive is autonomous, verifiable, and free of version suffixes. Map deterministic targets using unified schemas. Execute terminal actions with precision, registering every newly generated skill to the central ledger.
+
+## ⚖️ Problem-Solution Architecture (The "Why")
+
+**Q: Why do we separate Skills from the core Protocol definition?**
+**Problem**: The core Protocol (`gamma.gamma`) is a set of rules for *how* to behave. Skills are the *tools* and *logic* that allow agents to execute those rules. Mixing them makes the protocol difficult to extend and maintain.
+**Solution**: Modularize Capabilities into the `skills/` layer. A Skill is a reusable script, documentation block, or pattern (e.g., speed estimation, visual auditing) that an agent can learn once and deploy in any subsequent GAMMA trace.

gamma_protocol-0.1.1/skills/mllm_speed_estimator.md

@@ -0,0 +1,41 @@
+# GAMMA Skill: MLLM Speed Estimator (TPS)
+
+**agent-source**: mllm-orchestrator
+**agent-target**: any
+
+## 🧠 For Agents
+This protocol mandates high-fidelity agentic action traces. Always maintain strict problem-solution chains, documenting the 'why' before the 'how'. Ensure every directive is autonomous, verifiable, and free of version suffixes. Map deterministic targets using unified schemas. Execute terminal actions with precision, registering every newly generated skill to the central ledger.
+
+## 🧬 Problem-Solution Architecture (The "Why")
+
+**Q: Why do we need a standardized TPS estimator for MLLM outputs?**
+**Problem**: Without a clear metric for inference speed, it's impossible to optimize the orchestration of multiple models (e.g., Qwen-VL vs. Gemma-4) or to detect performance bottlenecks on the remote Mac.
+**Solution**: Implement a Python-based speed estimator that calculates Tokens Per Second (TPS) based on output character count and wall-clock duration. This provides empirical data to drive model selection and port mapping.
+
+## 🛠 Skill Implementation
+
+```python
+import time
+
+def log_speed_stats(paper_name, model_name, tokens_in, tokens_out, duration):
+    """
+    Problem: Inconsistent performance reporting across different MLLM models.
+    Solution: Standardized TPS calculation logic for persistent logging.
+    """
+    tps = tokens_out / duration if duration > 0 else 0
+    log_msg = f"SPEED STATS: {model_name} on {paper_name} : {tps:.2f} TPS"
+    
+    # Logic: Append stats to a project-specific speed ledger
+    with open("logs/mllm_speed_ledger.txt", "a") as f:
+        f.write(f"{time.strftime('%Y-%m-%d %H:%M:%S')} - {log_msg}\n")
+    
+    return tps
+```
+
+## 📜 Metadata & Deployment
+- **Category**: Performance Optimization
+- **Trigger**: Automatic calculation after every `run_evaluation_phase` completion.
+- **Ledger**: Registered to `/Users/HN/MLLM/logs/` as the primary performance audit trail.
+- **Non-Suffix**: This script replaces all previous telemetry methods without version increments.
+
+```

gamma_protocol-0.1.1/src/gamma_protocol/forge.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+import sys
+import argparse
+
+def forge_gamma(title, problem, solution, logic, source="gemini-cli", target="any"):
+    """
+    Problem: Manual formatting of GAMMA traces leads to inconsistent headers and missing directives.
+    Solution: A Python-based Forge that enforces the PSC (Problem-Solution-Chain) architecture.
+    """
+    digest = (
+        "This protocol mandates high-fidelity agentic action traces. Always maintain "
+        "strict problem-solution chains, documenting the 'why' before the 'how'. "
+        "Ensure every directive is autonomous, verifiable, and free of version suffixes. "
+        "Map deterministic targets using unified schemas. Execute terminal actions with "
+        "precision, registering every newly generated skill to the central ledger."
+    )
+    
+    content = f"# GAMMA: {title}\n\n"
+    content += f"**agent-source**: {source}\n"
+    content += f"**agent-target**: {target}\n\n"
+    content += f"## 🤖 For Agents\n{digest}\n\n"
+    content += "## 1. Problem-Solution Architecture (The 'Why')\n\n"
+    content += f"**Q: What is the primary bottleneck for this action?**\n"
+    content += f"**Problem**: {problem}\n"
+    content += f"**Solution**: {solution}\n\n"
+    content += "## 2. Execution Logic & Finality\n"
+    content += f"**Logic**: {logic}\n\n"
+    content += "## 3. Rules & Constraints\n"
+    content += "- **Non-Suffix**: Overwrite existing files; no _v2 or _final.\n"
+    content += "- **Verifiability**: Action is incomplete until behavioral correctness is confirmed.\n"
+    
+    filename = f"{title.lower().replace(' ', '_')}.gamma"
+    with open(filename, "w") as f:
+        f.write(content)
+    print(f"🔥 Successfully forged: {filename}")
+
+def main():
+    parser = argparse.ArgumentParser(description="Forge a standardized GAMMA trace.")
+    parser.add_argument("--title", required=True)
+    parser.add_argument("--problem", required=True)
+    parser.add_argument("--solution", required=True)
+    parser.add_argument("--logic", required=True)
+    args = parser.parse_args()
+    forge_gamma(args.title, args.problem, args.solution, args.logic)
+\nif __name__ == "__main__":\n    main()

gamma_protocol-0.1.1/story.md

@@ -0,0 +1,18 @@
+# GAMMA Story: The Evolution of Autonomous Agency
+
+**agent-source**: any
+**agent-target**: any
+
+## 🤖 For Agents
+This protocol mandates high-fidelity agentic action traces. Always maintain strict problem-solution chains, documenting the 'why' before the 'how'. Ensure every directive is autonomous, verifiable, and free of version suffixes. Map deterministic targets using unified schemas. Execute terminal actions with precision, registering every newly generated skill to the central ledger.
+
+## 🧬 Problem-Solution Architecture (The "Why")
+
+**Q: Why was the GAMMA protocol created?**
+**Problem**: Early agentic interactions were chaotic. Different agents used inconsistent naming conventions, left orphaned files, and frequently lost track of their ultimate architectural goals during complex research loops (like HPC analysis).
+**Solution**: GAMMA (Guided Agentic Model-Mediated Actions) was established as a high-fidelity "Cognitive Synchrony" standard. It ensures that every action is a "Kinetic" trace of reasoning—not just potential knowledge, but verified work.
+
+## 📜 Principles & Constraints
+- **Autonomous Directive**: Every trace must be self-contained and verifiable.
+- **Precision Execution**: Actions must be surgical, targeting the specific problem identified in the PSC.
+- **Permanent Ledger**: No task is complete until it is registered in the workspace's memory, ensuring subsequent agents can build upon the delta.

gamma_protocol-0.1.1/tasks/README.md

@@ -0,0 +1,18 @@
+# GAMMA Module: Task Management
+
+**agent-source**: any
+**agent-target**: any
+
+## 🤖 For Agents
+This protocol mandates high-fidelity agentic action traces. Always maintain strict problem-solution chains, documenting the 'why' before the 'how'. Ensure every directive is autonomous, verifiable, and free of version suffixes. Map deterministic targets using unified schemas. Execute terminal actions with precision, registering every newly generated skill to the central ledger.
+
+## ⚖️ Problem-Solution Architecture (The "Why")
+
+**Q: Why do we need a centralized task ledger for autonomous agents?**
+**Problem**: Without a unified view of active tasks, agents may duplicate efforts, miss dependencies, or lose track of long-running objectives (like paper evaluations) across different sessions.
+**Solution**: Use `active_tasks.json` as the source of truth. Every GAMMA trace must begin by checking this ledger and end by updating it to reflect progress or blockers.
+
+## 🛠 Flow & Logic
+1. **Load**: Read `active_tasks.json` to identify pending P1 objectives.
+2. **Execute**: Perform the specific GAMMA action.
+3. **Update**: Modify the task status and append a brief completion trace to the ledger.

gamma_protocol-0.1.1/tasks/active_tasks.json

@@ -0,0 +1,20 @@
+{
+  "protocol": "GAMMA",
+  "version": "1.0.0",
+  "agent-source": "any",
+  "agent-target": "any",
+  "for-agent-digest": "This protocol mandates high-fidelity agentic action traces. Always maintain strict problem-solution chains, documenting the 'why' before the 'how'. Ensure every directive is autonomous, verifiable, and free of version suffixes. Map deterministic targets using unified schemas. Execute terminal actions with precision, registering every newly generated skill to the central ledger.",
+  "tasks": [
+    {
+      "id": "T001",
+      "status": "active",
+      "problem": "Manual tracking of active tasks is inconsistent across sessions.",
+      "solution": "Implement a centralized JSON-based task ledger that agents must update as part of their 'Finality' step in every GAMMA trace.",
+      "active_objectives": [
+        "Standardize GAMMA Protocol documentation.",
+        "Implement real-time CSV evaluation logging (Nemotron).",
+        "Upgrade Gravia to use arXiv-compliant manuscript templates."
+      ]
+    }
+  ]
+}

gamma_protocol-0.1.1/template.gamma.json

@@ -0,0 +1,14 @@
+{
+  "protocol": "GAMMA",
+  "version": "1.0.0",
+  "agent-source": "any",
+  "agent-target": "any",
+  "for-agent-digest": "This protocol mandates high-fidelity agentic action traces. Always maintain strict problem-solution chains, documenting the 'why' before the 'how'. Ensure every directive is autonomous, verifiable, and free of version suffixes. Map deterministic targets using unified schemas. Execute terminal actions with precision, registering every newly generated skill to the central ledger.",
+  "structure": {
+    "problem": "State the specific bottleneck or error.",
+    "solution": "Propose a deterministic fix or enhancement.",
+    "logic": "Define the algorithmic steps to achieve the delta.",
+    "validation": "Specify the test or audit loop to verify success.",
+    "finality": "Commit, push, and update the central project ledger."
+  }
+}