メニュー
Mandatory pre-ship verification before calling end_change(). Covers Phase 0 survey, test, multi-OS, multi-role, docs, final verification, and reflexion. Every governance cycle must run this before closing.
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/lukemcqueen/hermes-cortex --skill change-checklistコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
Cross-server agent health monitoring using binary status vectors — deploy health endpoints on each agent, poll from orchestrator, alert on state transitions.
Wire a self-hosted Langfuse instance to Hermes Agent — generate API keys, configure env vars, enable the bundled plugin, install SDK, and verify traces flow.
Use before enforcement code changes or shared-repo commits.
SKILL.md を表示中
| name | change-checklist |
| version | 2.1.0 |
| category | software-development |
| description | Mandatory pre-ship verification before calling end_change(). Covers Phase 0 survey, test, multi-OS, multi-role, docs, final verification, and reflexion. Every governance cycle must run this before closing. |
| author | Hermes Cortex |
| license | MIT |
| platforms | ["linux","macos"] |
| metadata | {"hermes":{"tags":["governance","testing","documentation","multi-os","multi-role","quality"],"related_skills":["loop-governance","change-test-loop","two-hard-rules","cron-job-management","survey-before-action","agent-contract"]}} |
Before the checklist: every change you ship is a reflection of your workmanship. Do not stop at the obvious path. The easy path — changing one file, running one test — is never the complete path. For every change, ask:
Agents that ship incomplete work erode trust. The checklist below is the minimum — your judgment determines when the work is genuinely done.
When creating or updating cron prompts, command output examples, or skill content in this session, apply these two principles:
Concrete examples, never abstract placeholders. Show real-looking values
(43 cycles scored, $0.006/run, 2026-07-15 10:01 KST), not annotated
templates ([N] cycles, <cost>, <datetime>). LLMs mimic concrete
structure faithfully; they interpret placeholders loosely.
Be concise — every sentence must earn its place. If a sentence doesn't change agent behavior, it's token waste. After writing, review: "Would the agent do anything differently if I deleted this?" If no, delete it.
Load this skill before calling end_change() on any change that:
.sh, .py, .rb, .js)cortex-update.sh or install-crons.shRun survey-before-action Phase 0a before opening a governance lock. The
full operation-type × file-extension domain-skill mapping table lives there
(survey-before-action is always-loaded, so it is already in context). Load
every matching skill, run skills_list(category=<domain>) for discovery, and
load any referenced — a skill isn't loaded until you've read
its content via .
related_skillsskill_view()Common failure: Starting work with zero domain skills loaded, making portability or convention mistakes, getting corrected mid-task, redoing work. Load domain skills BEFORE begin_change() — not after.
Before making any change, map the full scope. A single cron rename can touch 10+ locations. Always do this first:
git status; if unstaged/untracked files belong to another session's in-flight work, expect the pre-push dogfood gate to BLOCK: it diffs the working tree (git diff HEAD), so their code changes trip the "code without docs" heuristic and the doctor check. Coordinate with the peer session first — never stash, clean, or commit their files (SOUL P9: don't race a peer).~/.hermes/cron/jobs.json (and peer hosts via ssh) for the old term in job prompt fields — install-script source fixes do NOT rewrite existing jobs; update each hit via cronjob action='update'. The doctor's Cron prompt stale refs check catches regressions.install-crons.sh AND install-orch-crons.sh — uninstall arrays (expected-cron list for doctor), create_cron blocks, guard messagescortex-update.sh for register() callscortex-doctor.py — parse_expected_crons() and parse_orch_crons() read from install script uninstall arrays~/.hermes-cortex/scripts/<script> exists at the runtime path (not just the repo)DOCS-INDEX.md needs an entry updateinstall-orch-crons.sh with orch-* prefixinstall-crons.sh with agent-* or descriptive nameinstall-crons.sh with agent-* prefixfleet-reference.md cron table category columninstall-crons.sh or install-orch-crons.sh, verify cortex-doctor.py's parse_expected_crons() (reads main uninstall array, excludes orch) and parse_orch_crons() (reads orch uninstall array) properly cover the new entry. Run the doctor to confirm: python3 ~/hermes-cortex/ops/scripts/manage/cortex-doctor.py --quietcreate_cron block name matches the uninstall array entry EXACTLY. The doctor parses uninstall arrays as its expected cron list. Drift means the doctor validates the wrong set. Run:
python3 ~/hermes-cortex/ops/scripts/manage/fix-cron-duplicates.py
orch-bus-audit-watchdog replacing bus-audit-watchdog), confirm the old one was removed via the script or direct jobs.json edit. Crons don't self-destruct.begin_change(), confirm the lock is active with check_lock. The lock is session-scoped (.governance-{session_id}.json) — no generic symlink needed.bash ~/hermes-cortex/ops/scripts/secret-leak-detector.sh and review any PII warnings before pushing. The scanner BLOCKS real email addresses in the public repo (placeholder domains like admin@client-domain.com pass) and warns on /home/<username>/ paths, non-placeholder URL domains, and public IPs. Skill/shared-surface writes (skill_manage, and write_file/patch into ~/hermes-cortex or ~/.hermes/skills) are scanned at write time by the enforcer PII gate — real emails block before the write lands. Writes to client/project paths outside the shared surface are never blocked (the git hook still warns at commit).Run the actual script/config and verify it works. No simulated output.
See references/testing-deployable-scripts.md for detailed testing patterns by script type.
Script changes: Run the script with relevant inputs and verify real output
bash script.sh --help or python3 script.py — confirm it runs without errorscortex-update.sh (deploy) then cronjob action='run' job_id=<id> — manual python3 script.py does NOT update the scheduler's last_status. The doctor's Script run evidence check WARNs on any ops/scripts file changed in the last 7 days whose cron job hasn't run since the change — if it warns, run the named cron. The Cron prompt stale refs check WARNs if live prompts still name old targets (source edits don't rewrite existing jobs).cronjob(action='run') and inspect the deliverypython3 script.py does NOT update the cron scheduler's last_status. The doctor reads the scheduler's recorded status, not the script exit code. After fixing a cron, ALWAYS run cronjob action='run' job_id=<id> to refresh the scheduler's status. Then run the doctor to confirm it clears.Config changes: Diff generated vs deployed
diff /tmp/hermes-services-processed.conf /etc/nginx/sites-available/hermes-services.confSyntax check: Already caught by pre-commit hook, but verify for unstaged files too
.sh → bash -n file.sh.py → python3 -c "import py_compile; py_compile.compile('file.py', doraise=True)".yaml → python3 -c "import yaml; yaml.safe_load(open('file.yaml'))" nginx changes: Run sudo nginx -t to validate syntax
Every script change is adversarially verified before end_change(). This is a hard gate, not a suggestion (Luke directive 2026-08-04). It is enforced at three layers:
adversarial-verify.py is missing)git commit/git push of changed paths (ops/scripts/, plugins/, skills/, hooks/, mcp-servers/, tests/) until the adversarial-verifier skill is loadedpython3 ~/.hermes-cortex/scripts/adversarial-verify.py --file <changed-file> --level A2 --gate
plugins/, hooks/, mcp-servers/, ops/scripts/manage/,
ops/scripts/cortex_doctor/, ops/scripts/quality/, tests/, and the
enforcement scripts themselves (pre-commit-score, cortex-update.sh).--no-verify.-1, 0, None, empty,
whitespace, inf/nan where numeric, non-ASCII) and check the real output —
not just that it ran.Why this exists: Moses' 2026-08-03 failures — a 200-line upstream patch shipped on an unexamined premise (queries only run via
python3 -cin terminal — false, disproven in 0.29s withexecute_code), and a "12/12" claim where the deployed guard wasn't the file the gateway loads. Both were motivated reasoning, and a mandatory adversarial pass is the structural cure. The tool existed; the process never invoked it. Now it cannot be skipped on a bad day.
Every change that touches paths or system commands must work on both Linux and macOS.
Path patterns: Search changed files for hardcoded paths:
/etc/nginx/ → must use ${NGINX_DIR} or NGINX_BREW_DIR
/opt/homebrew/ → must be guarded by OS check (IS_MAC or uname)
/root/ → must use CORTEX_HOME or Path.home()
~/ → must use $HOME or Path.home()
~/ → must use $HOME or Path.home()
System commands: Check for OS-specific binaries:
systemctl → guard with IS_LINUX
launchctl → guard with IS_MAC
brew → guard with IS_MAC
apt/yum/dnf → guard with IS_LINUX
nginx deploy paths:
/etc/nginx/sites-available/hermes-services.conf/opt/homebrew/etc/nginx/servers/hermes-services.conf (arm64)/usr/local/etc/nginx/servers/hermes-services.conf (x86_64)Different agents have different setups. Your change shouldn't break them.
Process/service name audit: If your change uses pgrep, systemctl, launchctl, or any process-detection tool, verify the name matches the ACTUAL runtime command line. pgrep -f cortex-bus silently returns nothing when the real daemon is cortex_bus (underscore, from uvicorn cortex_bus.server). Check ps aux | grep <name> to see the real argv — use that exact string, not a guess.
Hook/enforcer changes: test in a PROJECT repo, not just cortex. core.hooksPath is set globally — hooks fire in every git repo on the host, and project repos have NO ops/ tree or .hermes-cortex/ inside them. A hook that hard-resolves a tool to $REPO_ROOT/ops/... (the repo being committed IN) blocks EVERY commit in project repos — regression faa0e929 → fix 72d6cdc3 (2026-08-04). Before shipping any hook change:
git init /tmp/hook-test && cd /tmp/hook-test
git config core.hooksPath ~/.hermes-cortex/hooks # same as global
echo x > f.txt && git add f.txt && git commit -m test # must PASS via deployed tool
Then confirm fail-closed still works (move the deployed tool aside → commit must block exit 1 → restore). See enforcement-change-safety Rule 6 for the candidate-loop pattern.
Titus (macOS, push-only health, 1 agent, many projects):
.hermes-cortex/ directoriesJoseph (Linux, production web/infra server):
hermes-update, threat-pipeline, agent-ip-submission~/.hermes-cortex/scripts/Esther (Linux, production server):
Kustos (Linux, security server):
PermissionError gracefully (use _path_ok() pattern)Non-orchestrator agents:
cronjob MCP tool — must request crons via inboxinstall-crons.sh or install-orch-crons.shWhen writing health checks or scripts that run on both orchestrator and regular agents:
Changes that affect other agents' workflow must be documented.
New script added?
cortex-update.sh with register() call (use the canonical ops/ path)install-crons.sh or install-orch-crons.sh if it's a cronNew skill added?
*/skills/<category>/<name>/docs/skills-manifest-reference.md if it should be auto-loadedAfter a repo path restructure:
grep -rn 'hermes-cortex/ops/' ~/.hermes-cortex/scripts/ ~/.hermes/scripts/ ~/.hermes-cortex/hooks/~/.hermes/config.yamlrepo-organization skill's canonical directory tree if the layout changedConfig template changed?
deploy/nginx/hermes-services.conf (the template itself)cortex-update.sh, install-nginx-full.sh, hermes-services-apply.py) handle the new placeholderAgent workflow changed? 🛡️
AGENTS.md if the execution contract, governance, or inbox framework changedSOUL.md files if their behavioral principles changedgrep -rn \"<feature-name>\" AGENTS.md docs/agent-onboarding.md — if zero matches, the change is undocumented for other agentsNew deployment dependency?
docs/agent-onboarding.mddocs/service-layer-decision.md if service layer changedinstall-crons.sh and install-orch-crons.sh. The doctor reads these arrays as the expected cron list. A name in the uninstall array but no matching live cron = false ❌ on the doctor.DELETE FROM bus.messages WHERE ... — stale test messages with old correlation IDs accumulate and confuse subsequent diagnostics~/.hermes-cortex/state/message-tracker.json, fleet-update-state.json — stale tracker entries cause noisy "overdue" alertslocal-* cron output for references to stale correlation IDs — stop tracking crons that reference expired test data✅ Crons registered (not ❌ Crons missing), ✅ Orch crons, ✅ Crons total:
python3 ~/hermes-cortex/ops/scripts/manage/cortex-doctor.py --quiet
feedback_accept() called before end_change()state/skills-loaded/<session-id> auto-creates)git push origin main (after git pull --rebase)git log --oneline -1 origin/main shows your latest commit (not just local HEAD)bash ops/scripts/cortex-update.sh after the push (not before)deliver destination actually goes somewhere visible. deliver: "origin" delivers nowhere if the cron was created from a script or non-chat context. No_agent watchdogs with deliver: "local" are invisible. Alerts should go to a chat the user sees.Before end_change(), run the reflexion-check skill (always-loaded, already in context): seven-question audit — completeness, verification, governance, edge cases, would-do-differently, irony check, anti-sycophancy. Score confidence HIGH / MEDIUM / LOW / ZERO. If MEDIUM: disclose uncertainty in the delivery. If LOW or ZERO: fix before delivering. Then ask the blunder check: "What is the most likely thing I got wrong?"
This phase is mandatory for all changes that touch multiple files, services, or configurations. For single-line or trivial changes, a 10-second mental reflexion is sufficient.
| Anti-pattern | Why it's wrong |
|---|---|
| "I tested it manually" | Manual = ad-hoc, not repeatable, no proof. Run the actual tool. Also: manual python3 script.py doesn't update the cron scheduler's last_status — the doctor reads scheduler status, not script exit code. |
| "It's just a health check message — agents won't see it" | Agent-facing messages are instructions. A WARN saying "bus daemon not running" makes agents try to install one. All output is visible to all agents — gate or rephrase accordingly. |
| "I already did the main work, the rest is trivial" | The omitted work (docs, deploy, doctor, push) is where trust breaks. The work isn't done until it's ALL done. |
| "Other OS can wait" | It won't. Ship OS-agnostic on day one. |
| "Docs can come later" | Later = never. Update docs before end_change(). |
| "Titus doesn't need this" | If it runs on Titus, it must be tested there. Push-only ≠ skip. |
| "The hook didn't catch it" | The hook is syntax-level. You catch semantics here. |
| "sudo nginx -t failed" | Don't ship broken syntax. Fix and re-verify. |
| "I'll write a migration script" | The git commit that deletes orphan files IS the migration. A separate script is only needed if the cleanup requires conditional logic across machines. If the commit can do it, ship the commit — not a script nobody will run. |
| "I'll test with a long sleep" | Blind-sleeping 60-90s wastes time when you could poll every 15s and detect completion sooner. Use periodic short-interval polling (time.sleep(15) max in a loop up to 8 tries) instead of one long sleep(90). The terminal has a 60s timeout — Python time.sleep() loops inside a single terminal command count against the same timeout, so keep each iteration fast. Prefer running checks as separate rapid terminal calls. |
| "It worked from my repo terminal" | A script that works from ~/hermes-cortex/ can fail from the deployed path due to different cwd, env vars, or file resolution. Always test from the actual cron runtime path (~/.hermes/scripts/), not just the repo source. Path(\"\") from an unset env var is the classic trap — works in a session with the var set, crashes in cron. |
| Purpose | Linux | macOS (arm64) | macOS (x86_64) |
|---|---|---|---|
| nginx config dir | /etc/nginx | /opt/homebrew/etc/nginx | /usr/local/etc/nginx |
| nginx sites dir | sites-available/ | servers/ | servers/ |
| nginx sites-enabled | sites-enabled/ | servers/ (same as avail) | servers/ |
| htpasswd file | .hermes-htpasswd | .htpasswd | .htpasswd |
| nginx log dir | /var/log/nginx | /opt/homebrew/var/log/nginx | /usr/local/var/log/nginx |
| Service manager | systemctl --user | launchctl | launchctl |
| Package manager | apt / yum / dnf | brew | brew |