memtrace governBeta

Preview classification for governance docs — ADRs, standing rules, agent-rule files — through the real MemCortex oracle, plus add/edit for explicitly persisting a doc the automatic intake misses. Safe for CI.

Usage#

memtrace govern classifies governance documents — ADRs, standing rules, and agent-rule files — under a file, directory, or glob, then prints a grouped-count summary. It's the point-at-anything escape hatch for governance docs the zero-config sweep doesn't discover on its own.

Classification runs through MemCortex's real classify_governance_doc oracle over local IPC — a Unix-domain socket on macOS/Linux or a named pipe on Windows. It is the same classifier the automatic intake path uses. Without --accept-all, the sweep is read-only and non-interactive, which makes it safe to run in CI. With --accept-all, it persists every governance candidate shown in the preview.

The sweep form classifies a batch and only writes it when --accept-all is present. There is also a separate memtrace govern add/edit form. It bypasses the classifier entirely and directly asserts a single doc's governance category, guidance, and scope — see add / edit — manual override below. Everything on this page up to that section describes the classify/sweep form.

Targeting a file, directory, or glob#

Exactly one positional target is accepted; a second positional is a usage error. Three forms:

• A single file — classified as-is.
• A directory — swept recursively for *.md/*.mdc files plus the bare agent-rule filenames .cursorrules/.windsurfrules. Dot-directories are skipped, except .cursor, .claude, .windsurf, .devin, and .github — so agent-rule ecosystems stay reachable.
• A glob — anything containing * or ?, walked from its longest literal directory prefix (never blindly from / or .). Quote it so your shell doesn't expand it first. Unlike a directory target, a glob walk skips all dot-files and dot-directories.

A target that's neither an existing file/directory nor glob-shaped is treated as a typo: govern prints "does not exist and does not look like a glob pattern" and exits 2.

Flags#

What --accept-all persists#

--accept-all persists every governance candidate in the post-exclusion preview through MemCortex to the repository's .memtrace/governance.toml. The preview without this flag remains read-only. The write is all-or-nothing and requires memtrace start.

Path exclusions are applied before classification. Files classified NotGovernance are omitted from both the rendered candidate inventory and the persisted batch.

add / edit — manual override#

add and edit are a separate verb from the sweep form above, not a target path or glob. Where memtrace govern <path|glob> classifies a batch and only writes it when --accept-all is present; add/edit skip the classifier entirely and write one governance confirmation directly — for a doc the classifier misses, gets wrong, or that lives somewhere the zero-config sweep doesn't reach. It requires MemCortex to be reachable (memtrace start), the same as the sweep form.

add and edit are literally the same operation. MemCortex's confirm_governance replaces any existing confirmation for a given doc path wholesale — it's a current-state table, not an append log — so re-running the command against the same path with new flags is how you edit one. There's no partial merge: omitting --scope or --ban on a re-run clears them, it doesn't preserve whatever was confirmed before. Both verbs require --type and --guidance every time.

On success, the confirmation is written through the live Cortex endpoint immediately. No code-graph reset or reindex is required.

$ memtrace govern add docs/decisions/0001-use-postgres.md \
    --type adr --guidance "Use Postgres for all new services" --scope path:apps/api/**
# Directly asserts this doc as an accepted ADR scoped to apps/api/**,
# with no classifier round-trip.

$ memtrace govern edit docs/decisions/0001-use-postgres.md \
    --type adr --guidance "Use Postgres for all new services; SQLite for local dev only" --ban
# Re-asserts the same path with updated guidance and marks it a ban.
# --scope was omitted, so this ALSO clears the previous apps/api/** scope
# (edit re-declares the full assertion, it doesn't patch one field).

Environment variables#

Reading the output#

On success, govern prints a deterministic grouped-count summary to stdout: a header like "Found 3 governance docs: 2 decision_record (1 accepted, 1 unknown), 1 standing_rule", followed by one row per document — state, path, title — sorted by path. When multiple agent-rule files hash to the same convention ID, the header's agent_rule count gets a "(W deduped)" suffix instead (e.g. "3 agent_rule (1 deduped)"), reflecting the collapsed group count — individual doc rows are never marked. An empty match prints "Found 0 governance docs."

Files the oracle rejects as not-governance — template/placeholder ADRs, numbered tutorials, README/CONTRIBUTING/CHANGELOG, issue templates, TOC/index pages, publishing front matter — are simply absent from the output, never listed with a wrong label.

Exit codes: 0 on success, whether or not any docs were found — zero docs is a legitimate answer for CI. 1 when MemCortex can't classify. 2 for usage/argument errors.

Gotchas#

--exclude matches raw path substrings, not globs — --exclude adr drops every path containing "adr" anywhere. --accept-all confirms exactly the post-exclude classified inventory; without it, the sweep remains a read-only preview. Unreadable files (permission denied, deleted mid-sweep) are silently skipped, not reported.

Examples#

$ memtrace govern docs/adr
# Sweep docs/adr recursively (*.md, *.mdc, plus .cursorrules/.windsurfrules)
# and print the grouped classification summary.

$ memtrace govern docs/adr/0007-use-postgres.md
# Classify a single ADR file.

$ memtrace govern 'docs/**/*.md' --exclude drafts,archive
# Classify every markdown file matching the glob, dropping any path
# containing 'drafts' or 'archive'. Quote the glob so the shell doesn't
# expand it.

$ memtrace govern . --accept-all
# Sweep the whole repo and persist every governance recommendation shown
# in the preview.

$ memtrace govern add docs/team-conventions.md --type standing_rule \
    --guidance "Squash-merge only, no merge commits"
# Manually assert a standing rule the sweep either hasn't seen yet or
# doesn't apply to — no classifier round-trip, written immediately.

See also memtrace start, memtrace connect, memtrace status, and Cortex.