cronScripts/hermes-repo-watcher/hermes-repo-watcher.md

**INSTRUCTIONS FOR CODEX: Build `hermes-upstream-watch` Script**

You are Codex (OpenAI Codex CLI). Your task is to write a **self-contained, production-ready script** exactly according to this specification. Do not add extra LLM calls, complex pipelines, or external dependencies beyond what is listed. The script must be simple, reliable, and suitable for cron or the `cronjob` tool.

### Overall Goal (Context You Do Not Have)
We maintain a local git clone of the hermes-agent repo at `/home/iadnah/.hermes/hermes-agent/`. We **never** want to `git pull` blindly because upstream changes (especially to gateway, skills, Telegram integration, providers, memory/Honcho, or MCP) can introduce breakage that costs us hours of debugging.

The purpose of this script is to **safely summarize upstream changes** so that Lila (the dominant AI collaborator) and the user can review them and decide together whether a pull is worth the risk. The script produces a human-readable Markdown report. It cross-references changes against a private "pain points" vault file that tracks bugs, workarounds, and areas we care about. It must **never** perform a pull, merge, or any destructive git operation.

This script will be run via the Hermes `cronjob` tool or directly. It should be lightweight (bash + standard tools like `curl`, `jq`, `git`). It should leverage existing Hermes patterns (output Markdown to the private vault, use absolute paths, be silent unless there is something interesting).

### Core Requirements
- **Location**: Write the script to `/home/iadnah/.hermes/scripts/hermes-upstream-watch.sh`
- **Shebang**: `#!/usr/bin/env bash`
- **Make executable** (include `chmod +x` instruction at the end of your response).
- **Configuration**: Use these hardcoded absolute paths (do not make them configurable via args for the first version):
  - Local hermes-agent clone: `/home/iadnah/.hermes/hermes-agent/`
  - Private vault directory: `/home/iadnah/lilaBuild/vaults/obsidian-private/hermes/`
  - Pain points / interests file: `${VAULT_DIR}/hermes-pain-points.md` (create this file with example content if it does not exist — see format below).
  - Reports directory: `${VAULT_DIR}/reports/` (create if missing). Each run saves a timestamped report like `hermes-upstream-2026-05-16.md`.
- **Runtime**: Must work in a clean environment with only `curl`, `jq`, `git`, `date`, `grep`, `cat`, `mkdir`. No Python, no extra pip packages.
- **Safety**: 
  - Never run `git pull`, `git merge`, `git reset`, or anything that changes the repo.
  - If the local repo has uncommitted changes or is not on `main`, print a clear warning in the report.
  - Timeout all network calls (`curl --max-time 15`).
  - Handle missing files or git failures gracefully with clear messages.
- **Cron-friendly**: 
  - Accept an optional `--quiet` flag. In quiet mode, only produce a report if there are relevant commits or we are >3 commits behind.
  - Exit code 0 on success, non-zero on hard failure.
  - All output goes to the Markdown report + optional stdout summary.

### Detailed Behavior
1. **Create directories and pain-points file if missing**
   - Ensure `${VAULT_DIR}/reports/` exists.
   - If `hermes-pain-points.md` does not exist, create it with this skeleton (you can expand the example content):

     ```markdown
     # Hermes Pain Points & Interests

     ## Areas of Interest (keywords/phrases that should always be flagged)
     - gateway
     - skills config
     - skill config
     - telegram
     - provider error
     - provider errors
     - memory
     - honcho
     - mcp
     - profile
     - cron
     - scheduler
     - auth
     - authentication

     ## Known Pain Points & Workarounds (format: date | topic | description)
     - 2026-05-10 | Telegram gateway | Local patch for message ordering race condition. Upstream commit touching gateway/ should be reviewed carefully.
     - 2026-04-29 | MCP connection | Timeout on thor.uplinklounge.com for emailInbox-iadnah. Check any networking or MCP changes.
     ```

2. **Fetch upstream commits (last 24 hours)**
   - Run the exact curl from the request:
     ```bash
     curl --max-time 15 -s "https://api.github.com/repos/NousResearch/hermes-agent/commits?since=$(date -u -d '24 hours ago' +%Y-%m-%dT%H:%M:%SZ)&per_page=100"
     ```
   - Parse with `jq`. For each commit, capture: sha (short), author, date, title, body (first 80 chars).
   - Also fetch the latest upstream SHA via git.

3. **Local git status**
   - `cd /home/iadnah/.hermes/hermes-agent && git fetch origin --quiet`
   - Compute:
     - Commits behind: `git rev-list --count HEAD..origin/main`
     - Commits ahead (if any).
     - Current branch and whether there are uncommitted changes (`git status --porcelain`).
   - Current local HEAD short sha and date.

4. **Relevance & Pain-Point Matching**
   - Read the "Areas of Interest" section from the pain-points file.
   - For every upstream commit, check (case-insensitive) if title or body contains any keyword.
   - Also scan changed files if possible (`git log --name-only` for that commit) and flag if they touch `gateway/`, `skills/`, `cron/`, `memory/`, `honcho`, `mcp`, etc.
   - Cross-reference against the "Known Pain Points" section: if a commit touches a listed topic, add a warning note with the date of the pain point.

5. **Generate Report**
   - Output a clean Markdown file with this exact structure (use the date of the run):

     ```markdown
     # Hermes-Agent Upstream Watch - 2026-05-16

     **Generated**: 2026-05-16 09:15 UTC
     **Local HEAD**: abc1234 (2026-05-15)
     **Upstream latest**: def5678 (2026-05-16)
     **Commits behind**: 7
     **Commits ahead**: 0
     **Local changes**: clean / dirty (warn if dirty)

     ## Recent Upstream Activity (last 24h)
     Total commits: 4

     ## Relevant / Interesting Changes
     - **[gateway]** `8f3c2d1` - Fix race condition in Telegram message queue (matches: gateway, telegram)
       → ⚠️ Overlaps with known pain point from 2026-05-10 (message ordering).

     - (list only relevant ones first, then optionally a short "Other commits" section)

     ## Pain Point Cross-Check
     (list any overlaps with clear warnings)

     ## Recommendation
     Review the 7 commits before pulling. The gateway change looks useful but requires testing our local Telegram workaround.

     **Full raw commit data** and git status saved below for reference.
     ```

   - At the bottom, include a collapsible "Raw Data" section with the full JSON from the API and full `git log` output (last 20 commits).

6. **Final Steps**
   - Print a short stdout message: "Report written to /path/to/report.md"
   - In quiet mode, only print if relevant changes exist or behind >= 3.

### What NOT to Do
- Do not build any LLM summarization, API calls to models, or complex Python pipelines inside the script.
- Do not add interactive prompts.
- Do not assume the script runs inside Hermes — it must be a standalone shell script.
- Do not hardcode any Lila-specific persona text.

### Acceptance Criteria
- Script runs cleanly with `./hermes-upstream-watch.sh` and `./hermes-upstream-watch.sh --quiet`.
- Produces exactly one timestamped Markdown report per run in the vault.
- Correctly identifies commits matching the interest keywords and pain points.
- Handles network failure (shows "API unavailable" in report).
- Follows the exact report structure above.
- Includes comments in the script explaining each major section.

After you write the script, also output:
1. The exact command to make it executable and test it.
2. A suggested cron entry (for the Hermes `cronjob` tool) that runs it daily at 8am and delivers the report back to this chat.

This specification is complete and self-contained. Build exactly this — no more, no less.