anima check lacks seed upgrade guidance

[IMSUVEN]

Summary

When a repository was initialized with an older anima seed, anima check can correctly report that a newer seed is available, but the output is not actionable enough for an autonomous coding agent to complete the upgrade reliably.

Minimal repro

For a repository on an older seed, anima check may return output like:

seed: v1 -> v2 available

Seed updates available:
  v2: Add `anima check` awareness to Cultivation section

The human-facing expectation was effectively: "tell the coding agent to run anima check, and it will understand how to upgrade the repo."

Problem

From the agent perspective, anima check only reports state. It does not answer the operational questions needed to safely apply the upgrade:

• Which file(s) should be edited?
• Is this a mechanical seed migration or a judgment call?
• What exact patch is intended for v1 -> v2?
• Is there a canonical command to apply the seed update?

Because of that, the output is informative but not executable. A general-purpose coding agent should not infer the exact documentation change from the one-line seed note alone.

Expected behavior

Any of these would make the workflow agent-usable:

1. anima check prints a concrete next command, such as an explicit seed upgrade/apply command.
2. anima check prints target files and a canonical patch preview for each seed update.
3. anima check --json exposes structured upgrade metadata that an agent can consume safely.
4. The seed update message explicitly distinguishes between deterministic/mechanical changes and advisory changes that require human judgment.

Why this matters

There is currently a mismatch between:

• what anima check tells a human: there is a seed update
• what an autonomous coding agent needs in order to modify a real repository safely

That gap can stall the upgrade flow: the tool identifies the update, but does not provide enough machine-actionable guidance to apply it.

[IMSUVEN]

A follow-up from the actual upgrade attempt.

I was able to complete the migration in the downstream repo, but only after inspecting anima's implementation details. That is the core product problem here: the upgrade path was discoverable only by reading source, not by using the CLI.

What actually happened in practice:

• I first applied a reasonable documentation update based on the v2 message alone.
• anima check still reported v1 -> v2 available.
• To understand why, I had to inspect the installed binary and then read IMSUVEN/anima source.
• Only then did it become clear that the upgrade required two exact mechanics:
  • adding the precise sentence Run anima check to see which areas of the harness need attention.
  • adding the marker <!-- anima:seed:2 -->

There was no way to infer the seed marker requirement from anima check output alone.

I also hit a second mismatch:

• the downstream repo intentionally uses docs/architecture.md
• anima check only recognizes docs/ARCHITECTURE.md

So even after the seed migration was done, anima check still reported architecture: not found until I added a compatibility file. That behavior is consistent with the current implementation, but it is not obvious from the tool output and it creates unnecessary friction for repos that intentionally chose lowercase for filesystem compatibility reasons.

My concrete suggestions:

1. Add an explicit upgrade command.
   Example: anima upgrade-seed or anima apply-seed-update.

2. If anima check reports a seed update, print the exact required actions.
   For this case, that would have included the marker requirement.

3. Add --json output for machine-readable upgrade instructions.
   Agents need exact targets, not hints.

4. Make architecture detection more flexible.
   Either accept both docs/ARCHITECTURE.md and docs/architecture.md, or explicitly report that only the uppercase path is recognized.

5. Consider separating "semantic guidance update" from "generation marker bump" in the output.
   Right now they are conflated, but from an automation perspective they are different classes of change.

My honest takeaway: the current experience is fine for a human maintainer who already knows anima internals, but it is not yet a reliable self-describing upgrade flow for a general coding agent. The CLI knows the rules; it should expose them.