docs(agents): update config integrity section for git-backed seal system - #68
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1954a457d6
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| ### Git-backed config integrity | ||
|
|
||
| PR #67 shipped a git-backed integrity system that supersedes the mutable `.sha256` sidecar for external verification. Seals are stored as an append-only log at `$HERMES_DOTFILES_DIR/hermes/config_integrity.jsonl` and committed to the dotfiles git repo — a commit cannot be silently forged by any process that can write `config.yaml`. |
There was a problem hiding this comment.
Please qualify this guarantee to the cases where the process cannot also write/commit in the dotfiles repo. The implementation in skills/devops/config-integrity-watchdog/config_integrity.py only rejects uncommitted log changes and then trusts the latest seal entry, while seal() is a normal local append plus git commit; a same-user process that tampers with config.yaml can append/commit a matching seal (or run hermes config seal) and hermes config verify will accept it. As written, this overstates the security property for local compromise scenarios.
Useful? React with 👍 / 👎.
| PR #67 shipped a git-backed integrity system that supersedes the mutable `.sha256` sidecar for external verification. Seals are stored as an append-only log at `$HERMES_DOTFILES_DIR/hermes/config_integrity.jsonl` and committed to the dotfiles git repo — a commit cannot be silently forged by any process that can write `config.yaml`. | ||
|
|
||
| **CLI commands** (dispatched via `hermes config`, implemented in `hermes_cli/config_integrity_cli.py`): | ||
| - `hermes config seal` — hash config, append to log, commit to dotfiles git |
There was a problem hiding this comment.
Please document the fallback case here: seal() appends the log entry and then returns 0 even when git_commit() fails, printing only a warning that the fingerprint is a mutable fallback. In environments where $HERMES_DOTFILES_DIR is missing, not a git repo, or commits fail, following this command description makes automation believe a tamper-evident git baseline was created when it was not.
Useful? React with 👍 / 👎.
| **CLI commands** (dispatched via `hermes config`, implemented in `hermes_cli/config_integrity_cli.py`): | ||
| - `hermes config seal` — hash config, append to log, commit to dotfiles git | ||
| - `hermes config verify` — compare current hash to latest seal; exits 0=ok, 1=tampered, 2=log tampered, 3=no baseline | ||
| - `hermes config restore` — `git checkout HEAD` to revert config, back up tampered file, re-seal |
There was a problem hiding this comment.
Please avoid saying restore re-seals the config: the restore implementation appends a restore event, but load_baseline() only treats seal events as baselines. If HEAD's hermes/config.yaml does not match the latest seal (for example, a config commit was made without hermes config seal), restore can warn yet return success, and later verify still compares against the old sealed hash. This wording can make agents assume restore establishes a new baseline when it does not.
Useful? React with 👍 / 👎.
… mark arc complete (#76) Session close-out audit found the Outcome section only mentioned PR #67. PR #69 explicitly self-describes as "follow-up to #67" (unsigned-commit git fallback) and PR #68 (AGENTS.md docs) is also a direct follow-up; neither was recorded. Also clarifies that #71/#72 (cron ticker heartbeat/stall fix) are an unrelated arc shipped the same day, not part of this project. Claude-Session: https://claude.ai/code/session_01PQKCc5mDedYAiCNyXnTezh Co-authored-by: Claude <noreply@anthropic.com>
2 participants
Summary
Updates AGENTS.md to document the git-backed config integrity system shipped in PR #67, which supersedes the mutable
.sha256sidecar for external verification.What changed
### Config integrity seal and interprocess lock(lines 396–411):save_config(), not the primary verification toolrestore_config()guidance: use it instead ofseal_config()when bypassingsave_config()New
### Git-backed config integritysubsection:hermes config seal/verify/restoreCLI commands and their exit codesskills/devops/config-integrity-watchdog/skill location and its auto-deployed scriptsHERMES_CONFIGandHERMES_DOTFILES_DIRenv varshermes config verify(notverify_config_integrity()) in new cron jobs and watchdog promptsTest plan
Documentation-only change. Verify by reading the updated section in AGENTS.md and confirming it matches what PR #67 actually shipped (
hermes_cli/config_integrity_cli.py,skills/devops/config-integrity-watchdog/).Generated by Claude Code