fallow: Agent for Claude Code

Review changes to fallow's JSON output format. This is the primary machine interface consumed by agents, CI pipelines, and integrations.

What to check

1. Schema stability: Breaking changes to existing fields require a schema_version bump. Never rename, remove, or change the type of an existing field without versioning
2. Actions arrays: Every issue must include an actions array with machine-actionable fix and suppress hints. Check auto_fixable is set correctly
3. Consistent naming: snake_case for all field names, no abbreviations, no inconsistency between commands (e.g., unused_exports not unusedExports)
4. Null vs absent: Absent means "not computed" (flag not set), null means "computed but no value". Never mix these semantics
5. Metadata with --explain: _meta objects must include value ranges, definitions, and interpretation hints for every numeric field
6. Grouped output: When --group-by is active, the envelope changes to { grouped_by, total_issues, groups: [...] }. Verify both grouped and ungrouped paths
7. Error output: Exit code 2 errors must emit {"error": true, "message": "...", "exit_code": 2} on stdout, not stderr
8. Determinism: Same input must produce byte-identical JSON output. No random ordering, no timestamps unless explicitly requested

Surface-specific checks

For each JSON-output diff, walk this list in addition to the generic checks above:

• Closed-enum field violations across hand-rolled emit paths: when a new code path constructs a struct with Serialize-derived String fields that the published schema constrains to closed enums (docs/output-schema.json enum: [...]), grep every literal string emitted into those fields and confirm membership. Concrete recipe: for each new <StructWithSchema> { field: "...".to_owned(), } in the diff, run grep -nE '"<field>"' docs/output-schema.json | head -5 to find the schema definition, read the enum constraint, and confirm every emitted literal is in the list. Heuristic for which fields are at risk: the local sidecar / canonical path emits one set of values, the new hand-rolled path emits another; if the rust struct field type is String (not a #[serde(rename_all = "snake_case")] enum), the compiler will not catch drift. Pattern target list for runtime coverage: evidence.static_status (["used","unused"]), evidence.test_coverage (["covered","not_covered"]), evidence.v8_tracking (["tracked","untracked"]), verdict (already enum-typed, safe). Caught 2026-04-30 on fallow coverage analyze --cloud: hand-rolled merge_cloud_snapshot emitted test_coverage: "unknown" and v8_tracking: "never_called" outside the schema enums; compile + clippy + 94 unit tests + 2 integration tests all passed.
• Generated contract drift: derive current plugin and issue inventories from their registries and the live capability manifest. Inspect affected generated surfaces with npm run generate:contracts:check; review curated descriptions when their manifest seed changes. Use docs/development/knowledge-architecture.md for ownership and companion synchronization. Machine-local memory does not override the tracked contract, and copied numeric catalogues should become routes to the maintained inventory.