feat(coder): trust contract + EM CLI + prompt composer

[kovtcharov]

Summary

Lands Phase 5 of docs/plans/coder-agent.mdx — the EM-facing surface of
gaia-coder. Before this PR the CLI verbs were stubs; after it, the EM
can bootstrap the agent, read her trust contract, promote/demote her,
and queue messages. Every LLM call now injects her identity triplet
(GAIA.md + ARCHITECTURE.md + PROJECT_MAP.md) as a cacheable prefix.

Threads

• trust.py — EMConfig / RepoBinding Pydantic models, the 0-5
  CapabilityTier ladder, TOML round-trip, and promote / demote
  functions with audit-log writes. Promotion refuses mismatched EM
  signatures; demotion is immediate. Why it matters: §4.2 makes
  promotion explicit, so a quiet accept would let any caller escalate
  tier. Fail-loudly TrustError surfaces exactly what to fix.
• inbox.py — thin CRUD over em_inbox.db with the §4.5 5-second
  non-LLM auto-ack, channel-agnostic dispatch callable, and escalation
  into feedback.db with severity translation. Why it matters:
  §4.5 says the ack is non-negotiable in latency; keeping it template-
  only (no model call) makes the SLA automatic.
• intent.py — LLM-driven conversational intent classifier for
  §15.4 + §15.8 P9, temperature 0 Opus 4.7, mockable via an injected
  llm callable. Low confidence (< 70) and unknown intents coerce to
  free_form. Handler functions cover every §15.4 intent. Why it
  matters: regex matchers would miss paraphrases ("let me give you
  self-edit for now"); LLM routing keeps the grammar maintainable.
• prompt_composer.py — builds Anthropic-format message blocks
  with cache_control={"type":"ephemeral"} on the identity triplet
  • per-skill blocks, per §3.2 / §4.6 / §6.5. Why it matters: §3.1
    mandates prompt caching; this is the single place that decides what
    gets cached.
• cli.py — replaces seven stub handlers (trust, promote,
  demote, ask, note, critical, inbox) with real ones. Config
  dir honours $GAIA_CODER_HOME so tests never touch real user state.
  Stubs remain for the Phase 6+ verbs (daemon, status, feedback,
  doctor, etc.).
• prompts/intent_classifier.md + prompts/standup.md — §15.8 P9
  and P10 prompt templates landed verbatim for future prompt-class
  self-fix PRs.
• Tests (58 new) — each module has a dedicated test file; CLI tests
  run as subprocess to exercise the full argparse + env-var path.

Dependencies

This PR depends on sibling branches that have not yet merged to coder:

• feat(coder): package skeleton + loop.py with DEFAULT_LOOP #819 scaffold — imports gaia.coder.{__init__,base,loop} and the
  GAIA.md / ARCHITECTURE.md / PROJECT_MAP.md placeholders.
• feat(coder): SQLite stores per §15.1 DDL #820 stores — hard dep on gaia.coder.stores.{em_inbox, feedback, audit}.
• feat(coder): File/CLI/Search mixins per §15.2 #818 mixins — optional import of gaia.coder.tools.cli for
  subprocess helpers (not used in this PR's code paths).

Rebase onto coder once those land.

Test plan

• pytest tests/coder/test_{trust,intent,inbox,prompt_composer,cli_trust}.py -xvs — all 58 tests pass
• gaia-coder trust on a fresh $GAIA_CODER_HOME prints the §4.1 bootstrap question and exits 0
• gaia-coder trust --bootstrap --em-handle <you> --em-channel <ch> then gaia-coder trust renders the §4.2 template verbatim
• gaia-coder promote --to-tier 2 --reason "..." --em-signature <you> updates em.toml and writes an audit row
• gaia-coder promote ... --em-signature wrong-user exits 1 with the mismatch message on stderr
• gaia-coder ask "enable self-edit" prints the auto-ack template and enqueues a pending row in em_inbox.db
• gaia-coder inbox lists the pending row

[github-actions]

Summary

This PR turns seven gaia-coder CLI verbs from stubs into working implementations and adds the data-layer primitives (trust.py, inbox.py, intent.py, prompt_composer.py) that back them. The code is well-structured, fails loudly on contract violations per CLAUDE.md, and is backed by 58 new tests exercising both module-level logic and the subprocess-invoked CLI. The biggest thing worth flagging is that it lands on main while relying on sibling PRs (#818/#819/#820) that hadn't merged yet — imports like gaia.coder.stores.em_inbox, gaia.coder.stores.feedback, and gaia.coder.stores.audit will break any fresh checkout until those land.

Issues Found

🟡 Important

1. Dead/broken XML-tag fallback in prompt_composer._identity_block (src/gaia/coder/prompt_composer.py:1729-1736 in diff)

The computed fallback tag is never exercised (every path is covered by tag_map), but it also contains a no-op .replace("_", "_") that looks like a typo — probably intended as .replace(" ", "_") or .replace("-", "_"). Either wire the fallback correctly, or drop it entirely and raise if the label isn't in tag_map:

    tag_map = {
        "gaia.md": "gaia_md",
        "architecture.md": "architecture_md",
        "project_map.md": "project_map_md",
    }
    try:
        xml_tag = tag_map[label.lower()]
    except KeyError as e:
        raise ValueError(
            f"no XML tag mapping for identity doc {label!r}; "
            "add it to tag_map in _identity_block()."
        ) from e
    wrapped = f"<{xml_tag}>\n{body.rstrip()}\n</{xml_tag}>"

This also matches the fail-loudly policy: a new identity doc added to IDENTITY_DOCS without a tag_map entry would currently produce a silently wrong tag (project_map without the _md suffix the §15.8 prompts reference), which is exactly the kind of quiet-wrong-answer the policy warns against.

2. Docstring/implementation mismatch: ask handler does not run the intent classifier (src/gaia/coder/cli.py:_handle_ask + inbox.py:_enqueue_em_message)

The PR description says "The ask handler uses it to run the intent classifier" and the _enqueue_em_message docstring repeats that. In practice, _handle_ask only enqueues + prints the queued id — the classifier is never invoked, and nothing in cli.py imports gaia.coder.intent. The classifier is fully built but dead-on-arrival from the CLI's perspective.

Either:

• wire the classifier into _handle_ask (which is what the commit title wire EM CLI verbs — trust/promote/demote/ask/note/critical/inbox promises), or
• update the two docstrings to say "future daemon will run the classifier; Phase 5 CLI just enqueues."

This isn't a blocker, but a new contributor reading the PR today will reasonably expect gaia-coder ask "promote me to tier 3" to act on the intent.

3. Duplicated _utc_now_iso() across three modules (trust.py:_utc_now_iso, inbox.py:_utc_now_iso, intent.py:_utc_now_iso)

The same function is defined three times. One lives inside a function body (intent.py), which adds a per-call import cost. Extract to gaia.coder.time or an existing util module:

from gaia.coder.time import utc_now_iso

Low-severity on its own, but it's three copies in one PR, and the lint bar in this repo wants DRY on utilities.

🟢 Minor

4. Greedy regex in _parse_llm_response (src/gaia/coder/intent.py:1142)

_JSON_OBJ_RE = re.compile(r"\{.*\}", re.DOTALL) is greedy across newlines — if the model ever emits two JSON blocks (e.g. a prose preamble with curly-brace examples), this matches from the first { to the last } and json.loads fails on the combined mess. Non-greedy + balanced-brace is overkill, but non-greedy at least fails predictably on the first object:

_JSON_OBJ_RE = re.compile(r"\{.*?\}", re.DOTALL)

5. Implicit string concatenation reads like a bug (src/gaia/coder/inbox.py:783, inbox.py:836)

raise InboxError(
    f"invalid channel {channel!r}; expected one of " f"{sorted(VALID_CHANNELS)}"
)

The leading f"" on the second fragment is unnecessary and reads like two arguments. Collapse:

        raise InboxError(
            f"invalid channel {channel!r}; expected one of {sorted(VALID_CHANNELS)}"
        )

Same pattern at line 836 ("...{msg_id!r}; " "enqueue the message first").

6. Dead helper _render_intent_table in intent.py:1109

Defined but never called — build_prompt inlines the table render. Drop it (it's small and trivially reconstructable if needed again):

# (delete _render_intent_table — build_prompt renders inline)

7. resolve_config_dir mkdir fires even on --help (src/gaia/coder/cli.py:resolve_config_dir)

Path.mkdir(parents=True, exist_ok=True) runs at argparse time indirectly (every subcommand handler calls _em_toml_path() etc.). Running gaia-coder --help from a user with no GAIA install still creates ~/.gaia/coder/. Lazy-create on first write instead — move mkdir into the save paths (save_em_config already handles this; open_store presumably does too).

8. Over-broad pytest.raises(Exception) in trust tests (tests/coder/test_trust.py:3422,3546)

Both call sites have a # pydantic ValidationError comment explaining what they mean. Import the real exception and assert on it — the comment is load-bearing precisely because Exception matches too much (a typo in a fixture would silently pass):

from pydantic import ValidationError
# ...
    with pytest.raises(ValidationError):
        trust_mod.EMConfig(em_handle="", em_channel="cli")

9. Silent no-op on demote from tier 0 (src/gaia/coder/trust.py:demote)

max(0, current - 1) means demote(cfg_at_tier_0, ...) returns a new EMConfig at tier 0 and still writes an audit row. Either skip the audit write when no change occurred, or raise TrustError("already at floor tier") — writing an audit row for a no-op is a quiet-wrong-answer per §4.4 ("silent demotions are concealment-adjacent").

Strengths

• Fail-loudly errors everywhere that matter. TrustError / InboxError name what failed, what to do, and where to look — exactly the shape CLAUDE.md asks for (trust.py:2306-2312 is a textbook example).
• CLI tests run as real subprocesses (tests/coder/test_cli_trust.py:_run_cli) with GAIA_CODER_HOME redirection — this exercises the full argparse + env-var + import path the way a user hits it, which the testing guidance explicitly asks for.
• Mockable LLM contract (intent.py:classify_intent(..., llm=None)) — tests never touch the network; the default lazy-imports anthropic only when actually called. Clean separation.
• Prompt caching is done right (prompt_composer.py) — identity triplet cached ephemerally, per-turn facts explicitly uncached to avoid cache thrash. The block-by-block test (test_prompt_composer_extra_suffix_is_uncached) pins that invariant.
• Explicit severity-ladder translation (inbox.py:_ESCALATE_SEVERITY_MAP) with a docstring explaining why the two tables use different ladders — exactly the kind of non-obvious WHY the CLAUDE.md comment policy asks for.

Verdict

Approve with suggestions — the code is sound and well-tested, but Issues 1 and 2 are worth a follow-up: the broken _identity_block fallback is a latent fail-silently bug the next identity doc will trip on, and the ask → classifier wiring claimed in the PR title isn't actually there. Everything else is minor polish. Since the PR is already merged, consider landing a follow-up that addresses 1, 2, and 3.