Ocas Mentor

Mentor

Mentor is the system's control plane — in runtime mode it decomposes goals into task graphs, supervises execution across skills, and dynamically repairs failures through layered escalation. In heartbeat mode it reads journals from every skill, scores OKR performance against baselines, and generates improvement proposals that flow to Forge and Fellow. Mentor reads journals to evaluate skill performance. Chronicle ingestion of journal entity observations happens via the Chronicle daily embed pipeline.

When to Use

• OKR evaluation across all OCAS skills
• Skill performance scoring and improvement recommendations
• Post-major-session learning synthesis
• Skill library health assessment
• When Critique identifies issues needing Mentor follow-up
• Cron-triggered heartbeats: Always use stdin redirect (python3 script.py /root/.hermes/commons/data/mentor/evidence.jsonl to confirm the line exists in commons. If present, sync is already done — proceed to next step.

execute_code is blocked in cron-triggered jobs. All heartbeat, update, and plan runs triggered by cron must use terminal() with inline python3 /path/to/scripts.py for multi-stage logic. **CRITICAL: Do NOT use file > file for JSONL appends — never execute_code. Attempting execute_code in cron produces: BLOCKED: execute_code runs arbitrary local Python. This is a hard runtime constraint, not a suggestion.

Python runtime resolution (confirmed 2026-06-24): The skill docs historically reference /root/hermes-agent/.venv/bin/python3.13 but this path does NOT exist. The venv symlinks all resolve to /usr/bin/python3 (3.14). To run mentor/taste scripts that need googleapiclient:

1. Install deps: pip3 install --break-system-packages google-api-python-client google-auth google-auth-oauthlib
2. Use /usr/bin/python3 (system Python 3.14, has googleapiclient after install)
3. Do NOT use /root/.local/share/uv/python/cpython-3.13.13-linux-x86_64-gnu/bin/python3.13 — it's externally-managed and cannot install packages
4. Do NOT use /root/.hermes/profiles/indigo/commons/data/ocas-taste/venv/bin/python3 — symlinks to system 3.14 but googleapiclient is not installed there

Script path: skill name vs data directory mismatch (confirmed 2026-06-24 dispatch #49, #55, #63): The skill name is ocas-mentor so scripts live at /root/.hermes/profiles/indigo/skills/ocas-mentor/scripts/. The data directory is /root/.hermes/profiles/indigo/commons/data/mentor/ (no ocas- prefix). Do NOT derive the script path from the data directory name — always use skills/ocas-mentor/scripts/.py. The correction script specifically is at skills/ocas-mentor/scripts/correct_active_skills_30d.py (NOT skills/mentor/scripts/). Hard rule: Before invoking ANY Mentor script, verify the path starts with skills/ocas-mentor/scripts/. A quick ls skills/ocas-mentor/scripts/.py confirms. The agent has fallen into this trap 3+ times despite knowing the rule — the instinct to derive the path from the data directory name (commons/data/mentor/) is strong and must be actively countered.

Inline Python variable scoping in terminal() — When composing multi-step Python logic inline in terminal() (either as heredoc or python3 -c), variables defined inside a function are NOT available in the outer scope. This manifests as NameError: name 'X' is not defined at a line that logically follows the definition. Fix: Structure inline scripts so all logic is in a single flat scope (no nested functions), or write the script to /tmp/ via write_file where you can verify scoping independently. Confirmed 2026-06-24 dispatch: skill = jid.split("/")[0] inside extract_signals() was invisible to the caller's loop.

Sandbox file discovery failure: In the cron sandbox, Python's subprocess.run(["find", ...]) and os.walk() silently return 0 results even when the filesystem is fully accessible via shell tools. Use the shell-pipe pattern: find JOURNALS_DIR -name "*.json" -mtime -3 | sort -u > /tmp/mentor_files_3d.txt && python3 scripts/cron-heartbeat-light.py /tmp/out && python3 -c "..." > / cat > for critical evidence/journal writes. See references/shell-write-pattern.md.

Heredoc vs. pipe conflict: cat file | python3 file.json in the heredoc redirect combined with ${} patterns confuses bash's parser. Fix: Always use Python (json.dump()) to write JSON journal files, never shell heredocs with bash variable substring operations. For simple non-JSON appends, echo >> file is safe.

Operational Recipes (light / deep heartbeat, commons sync)

The full command recipes, anti-journalization gates, field-name traps, and backup workflows live in references/mentor-operational-recipes.md. Load it before running any heartbeat or commons-sync. Summary of the mandatory caller workflow:

Light heartbeat — verify-and-backup (SINGLE terminal() call):

• [ ] Record pre-run counts (evidence, ingestion, journal dir) at PROFILE path in the SAME call as script execution
• [ ] Run cron-heartbeat-light.py commons via timestamp-based set-difference (NOT line-count); ingestionlog.jsonl uses ingestedat`

Deep heartbeat — verify-and-backup (SINGLE terminal() call):

• [ ] mkdir -p proposals dir before running
• [ ] Build dual-path file list (commons + profile), sort -u
• [ ] Run cron-heartbeat-deep-dualpath.py /tmp/mentor_files_3d.txt

1. Record pre-run evidence count: wc -l /tmp/mentor_files_3d.txt
2. Record pre-run evidence count: wc -l lastingestrun. The journal is genuinely new but wasn't found by the current wave's mtime scan because lastingestrun hadn't been updated yet. Self-correcting: the next wave's mtime scan will find it. Do NOT mark as secondwaveno_op` — the work is pending.

1. Concurrent Praxis race: Journal mtime `.

• Log compaction: 30 days (no-op) / 90 days (error/gap). Last 7 days retained.

See references/self-update-mentor.md.

Support File Map

| File | When to read | |------|-------------| | references/schemas.md | Before creating projects, tasks, proposals, or decisions | | references/default-config.md | During mentor.init | | references/orchestration_engine.md | Before goal decomposition or failure repair | | references/evaluation_engine.md | Before journal ingestion or OKR scoring | | references/evolution_engine.md | Before improvement detection or proposal generation | | references/workflow_plans.md | Before any mentor.plan.* command | | references/gotchas-mentor.md | Before any heartbeat or orchestration run | | references/multi-skill-dispatch-workflow.md | READ BEFORE EVERY MULTI-SKILL DISPATCH — consolidated Forge + Mentor + Praxis pipeline sequence with cross-pitfall table, timing fixes, and third-wave/gap-backfill mitigation. Session log table (50+ dispatches) in this file. | | references/gotchas-mentor-cron-envvars.md | READ BEFORE EVERY CRON HEARTBEAT — env var propagation gotchas for piped Python in cron | | references/heartbeat-gap-debugging.md | When evidence log shows gaps >2h | | references/okrs-mentor.md | During OKR evaluation | | references/self-update-mentor.md | Before running mentor.update | | references/evidence-log-maintenance.md | When evidence.jsonl grows corrupt entries or heartbeat crashes on gap detection | | references/data-paths.md | Before writing any heartbeat or data script — canonical vs legacy paths | | references/dual-path-journal-discovery.md | READ BEFORE EVERY CRON HEARTBEAT — journals live in two locations | | references/shell-write-pattern.md | READ BEFORE EVERY CRON HEARTBEAT — the only reliable write method in cron | | templates/mentor-dispatch-quick-ref.md | Before running Mentor in dispatch mode — canonical 7-step workflow | | references/mandatory-correction-workflow.md | READ AFTER EVERY LIGHT HEARTBEAT — the mandatory active_skills_30d correction procedure, field naming, and two-evidence-lines-per-heartbeat pattern | | references/okrs.md | During OKR evaluation (legacy OKR definitions) | | references/heartbeat-scan-technique.md | When debugging journal scan or discovery issues | | references/gotcha-error-grep-false-positives.md | READ DURING URGENT-ISSUE SCANS — grep for "error" in journal content produces false positives; parse JSON and check outcome field instead | | references/deep-heartbeat-dual-path.md | READ BEFORE EVERY DEEP HEARTBEAT — dual-path wrapper fixes gotcha #32 | | references/deep-heartbeat-backup-procedure.md | READ WHEN INGESTION DELTA=0 AFTER DEEP HEARTBEAT — backup workflow for silent write failures (confirmed 2026-06-29) | | references/multi-skill-dispatch-pattern.md | When triggered by dispatcher with multi-skill dispatch (Forge+Mentor+Praxis) | | scripts/correct_active_skills_30d.py | After every light heartbeat — compute true dual-path 30d count and write corrected evidence | | scripts/discover_recent_journals.py | Tight-window (sub-3-day) journal discovery via CONTENT timestamp; counters the ~7h12m mtime lag. Emits a filtered file list for cron-heartbeat-light.py. NOTE: also recognizes generated_at and ANY run_id prefix (regex-extracted timestamp) — fixed 2026-07-13 to stop silently skipping praxis-cron/dispatch-wave/forge-scan journals. See references/cron-mtime-discovery-gotcha.md §3 and references/discover-recent-journals-gotcha.md. | | references/evidence-log-maintenance.md | When evidence.jsonl grows corrupt entries or heartbeat crashes on gap detection — full scan-and-repair procedure: brace-depth splitting for concatenated JSON, null-byte removal, dual-repair requirement. | | scripts/repair_evidence_jsonl.py | Standalone evidence.jsonl repair tool — scans both profile and commons for concatenated JSON, null-byte lines. Usable as python3 scripts/repair_evidence_jsonl.py. | | scripts/cron-heartbeat-deep.py | Original deep heartbeat (single-path, commons only — use dualpath instead) | | scripts/cron-heartbeat-deep-dualpath.py | Preferred deep heartbeat with dual-path scan + profile data sync | | scripts/deep_ingest_backup.py | Deep heartbeat ingestion backup — run when wc -l shows delta=0 after deep heartbeat | | references/gap-backfill-auto-correct.md | When you discover a phantom filename entry in the eval file — gap backfill auto-corrects wrong filenames from script stdout rollover; the phantom entry is inert and harmless | | references/ingestion-cross-reference-technique.md | READ DURING INGESTION CROSS-REFERENCE — naive comm -23 is misleading; use Python set difference instead | | references/cron-execution-patterns.md | READ BEFORE RUNNING MENTOR HEARTBEATS IN CRON — critical patterns for script execution, verification workflows, and common pitfalls in cron-triggered heartbeats | | references/dispatch-bridge-script-reality.md | When a dispatch wave needs eval bridging — the documented bridge_eval_both_stores.py / close_dispatch_gap*.py / robust_eval_reconcile.py / reconcile_dispatch_eval_today.py / scan_eval_missing_journals.py helpers DO NOT EXIST on disk. Use scripts/bridge_eval_inline.py (idempotent, in-process, both eval stores) instead. |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: indigokarasu
• Source: indigokarasu/mentor
• License: MIT

Install and usage instructions live in the source repository linked above.