Skip to content

Generated agent context tells agents to run meta verify --db, which always exits 2 #331

Description

@dmealing

Summary

The generated agent context tells an agent to run meta verify --db, with no URL. That command
cannot succeed — it exits 2 with Option '--db <value>' argument missing. The correct form is
meta verify --db <url>.

This is not a regression. Verified on both 0.23.0 and 0.24.0-rc.3:

$ bunx meta verify --db ; echo "exit=$?"
meta: Option '--db <value>' argument missing
exit=2

Where it comes from

The live-database bullet in the generated .metaobjects/AGENTS.md / CLAUDE.md ends with:

Run meta verify --db after any DB-touching work to catch that drift early.

It ships that way — the same sentence is in the agent-context conformance fixtures, e.g.
fixtures/agent-context-conformance/java-react/expected/.metaobjects/AGENTS.md:14 and the
python/expected/.metaobjects/CLAUDE.md alongside it. So every adopter that has run meta init
carries an instruction that fails. Found it in a real one (a TS/Postgres adopter on 0.23.0).

README.md:115 has the same bare form in the "DB-drift verify" command column of the per-language
table, where it also reads as the thing you type.

Why this is worth more than a typo

Most meta verify --db mentions in the docs are referential and are fine as-is — they name the
subverb while explaining ownership ("schema-drift is TS-owned", "an unmodeled view is unmanaged,
so meta verify --db can't even catch the drift"). Those don't need touching.

The AGENTS.md one is different because it is imperative, and it is aimed at an audience that
follows generated context literally. An agent that reads "run this after any DB-touching work" runs
it, gets exit 2, and then either treats the schema gate as broken and skips it, or invents a
workaround. The whole point of shipping agent context is that the instructions in it are executable.

Suggested fix

Change the imperative uses to carry the argument:

  • agent-context template (and the conformance fixtures that pin it): Run `meta verify --db <url>` after any DB-touching work…
  • README.md:115: meta verify --db <url>

Leaving the referential prose alone.

Worth a moment's thought on whether the fixtures should be able to catch this class generally — a
check that every backticked meta … in the generated context is a runnable invocation would have
flagged it, though I appreciate that's a bigger ask than the one-line fix.

Environment

  • Reproduced on @metaobjectsdev/cli 0.23.0 and 0.24.0-rc.3
  • Adopter: TypeScript + Bun + Postgres, meta migrate-owned schema

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions