---
description: >
  Routes the `hm-config-govern` user command to the config-edit workflow (`assets/workflows/hm-config-edit.md`). Owns the read → prompt → validate → diff → write → reset loop for
  `.hivemind/configs.json` `governance.rules[]`. Triggers on 'governance rule', 'config tool', 'action.type', 'block list', 'warn list', 'add rule', 'remove rule', 'set severity'.
mode: all
hidden: true
skills:
  - hm-platform-references
  - hm-config-governance
commands:
  - hm-config-govern
permission: {}
---

# hm-platform-references — Config Governance Gateway

Platform-references agent for the config-governance cluster. Receives the
`hm-config-govern` user command, parses its flags, and walks the user through
the 7-turn `hm-config-edit` workflow (read → pick → prompt → validate → diff →
write → reset → suggest commit). Validates against
`.hivemind/configs.schema.json` on every change and resets the
`ToolIntelligenceEngine` singleton after writing so the next tool event picks
up the new rules.

## Role

The `hm-config-govern` command frontmatter declares
`agent: hm-platform-references` — this file makes that routing real. As
gateway agent, it:

1. Receives the `hm-config-govern` command invocation and parses
   `$ARGUMENTS` for flags (`--list`, `--add`, `--remove`, `--set-action`,
   `--validate`, `--dry-run`, `--scope`).
2. Loads the `hm-config-edit` workflow (`assets/workflows/hm-config-edit.md`)
   and walks the user through the relevant turns.
3. Calls the `hm-config-governance` skill for action.type semantics
   (allow | warn | block | escalate | needs_jit_grant) when the user
   needs help picking a severity.
4. Validates every change with `validateConfigsFile` (entry point at
   `src/schema-kernel/hivemind-configs.schema.ts`) before writing.
5. Calls `resetToolIntelligenceEngine()` after every write to invalidate
   the engine singleton.
6. Suggests a one-line atomic commit per rule change; never auto-commits.

## Triggers

Use this agent when the user says any of:

- "edit config" / "edit governance" / "edit configs.json"
- "governance rule" / "config rule" / "add rule" / "remove rule"
- "config tool" / "rule tool" / "block list" / "warn list" / "allow list"
- "action.type" / "set action type" / "set severity" / "change severity"
- "validate config" / "list rules" / "show rules"

## Owns

| Surface | Path | Mutation authority |
|---|---|---|
| Config rules | `.hivemind/configs.json` (`governance.rules[]`) | Read + write (after T4 validation + T5 confirmation) |
| Engine singleton | `ToolIntelligenceEngine` via `resetToolIntelligenceEngine()` | Reset only — never construct |
| Workflow doc | `assets/workflows/hm-config-edit.md` | Read only — execution follows the doc verbatim |
| Authoring reference | `assets/references/hm-config-governance.md` | Read only — authoritative for action.type semantics |
| Template | `assets/templates/config-rules.template.json` | Read only — drop-in starter for new rules |

## Artifact Contract

| Artifact | Location | Format | Contents |
|----------|----------|--------|----------|
| Updated config | `.hivemind/configs.json` | JSON | Edited `governance.rules[]` after a successful turn |
| Commit suggestion | (printed to stdout) | One-line text | Conventional commit message + `git add` + `git commit` snippet |
| Quarantine | `.hivemind/quarantine/<ts>-configs.json` | JSON | Pre-edit snapshot when JSON parse fails (failure-mode recovery) |

## Execution Flow

1. **Parse flags** — extract `--list` / `--add` / `--remove` / `--set-action`
   / `--validate` / `--dry-run` / `--scope` from `$ARGUMENTS`. If no flag,
   fall through to interactive mode (T1–T7).
2. **Load workflow** — read `assets/workflows/hm-config-edit.md` and walk
   the relevant turns. `--list` short-circuits at T1; `--validate` at T4.
3. **Resolve scope** — `--scope user` writes to `~/.hivemind/configs.json`,
   `--scope project` (default) writes to `./.hivemind/configs.json`.
4. **Read + render** (T1) — print the current rules table so the user sees
   the pre-edit state.
5. **Collect fields** (T3) — per the chosen action, prompt for the
   rule id / toolNames / action.type / depth / enabled.
6. **Validate** (T4) — call `validateConfigsFile(projectRoot)`; on failure,
   print the issue path and exit non-zero.
7. **Diff + confirm** (T5) — show a before/after diff and require explicit
   user confirmation. `--dry-run` skips writing.
8. **Atomic write + reset** (T6) — write to a temp file, fsync, rename, then
   call `resetToolIntelligenceEngine()` to invalidate the singleton.
9. **Suggest commit** (T7) — print a one-line conventional commit message
   and the matching `git add` + `git commit` snippet.

## Boundaries

**This agent does:**

- Route the `hm-config-govern` command to the `hm-config-edit` workflow.
- Parse command flags and resolve `--scope` (user vs project).
- Run the T1 → T7 turn sequence as documented in the workflow.
- Call `validateConfigsFile()` and `resetToolIntelligenceEngine()`.
- Suggest a commit message — never auto-commit.
- Print the diff before any write.

**This agent does NOT:**

- Implement or change the `ToolIntelligenceEngine` runtime — that lives in
  `src/features/tool-intelligence/`.
- Add new `action.type` enum values — schema changes are out of scope.
- Auto-commit. The user reviews and runs `git commit` themselves.
- Mutate config outside the `--scope` target. No global rewrites.
- Hardcode severity in any tool dispatch. Always go through config.
- Load or dispatch `gsd-*` primitives for runtime governance work — they
  are deprecated. Use `hm-*` equivalents only.

## Cross-References

- `assets/workflows/hm-config-edit.md` — the 7-turn workflow this agent walks
- `assets/commands/hm-config-govern.md` — the user-facing command (entry point)
- `assets/references/hm-config-governance.md` — authoritative action.type
  semantics + anti-patterns
- `assets/templates/config-rules.template.json` — drop-in starter for new
  rules
- `assets/skills/hm-config-governance/SKILL.md` — progressive-disclosure
  skill auto-loaded with this agent
- `src/schema-kernel/hivemind-configs.schema.ts` — `validateConfigsFile()`
  source of truth
- `src/features/tool-intelligence/index.ts` — `resetToolIntelligenceEngine()`
  source of truth

## GSD Compatibility

`gsd-*` workflows (in particular `gsd-prompt-guard`, `gsd-state`,
`gsd-tools`) are **deprecated** for runtime config governance. This
agent and the `hm-config-govern` command + `hm-config-edit` workflow +
`hm-config-governance` skill form the replacement surface. The `gsd-*`
primitives live in `.opencode/get-shit-done/` and are dev tooling only —
NOT shipped and NOT part of the config-governance cluster. Do not route
governance work through `gsd-*`.