FEAT-006: document JSONL audit row future-field-additions policy (CHK006)

[brettheap]

Context

Deferred from FEAT-006 quality checklist agent-registry-quality.md CHK006.

The FEAT-006 spec locks the required field set for the JSONL agent_role_change audit row as a closed set:

• event_type, ts_utc, agent_id, prior_role, new_role, confirm_provided, socket_peer_uid

(see specs/006-agent-registration/spec.md FR-014 and specs/006-agent-registration/data-model.md §4.4)

What is not explicitly stated is the policy for future field additions to the audit row:

• "strictly additive" — new fields may appear; consumers MUST tolerate unknown keys
• "version-bumped" — breaking changes (renames, removals, type changes) require a new event_type

Why this is deferred from FEAT-006

• The implementation is unaffected — the current required field set is fully specified and snapshot-testable.
• No downstream consumer of events.jsonl exists yet in MVP. FEAT-007 (log attachment), FEAT-008 (events), FEAT-009 (input delivery), and FEAT-010 (routing) will be the first features that read these rows.
• Fixing this in FEAT-006 would require coordinating language with FEAT-001's broader events.jsonl policy (which currently has no global additivity policy either).

What needs to happen

When the first downstream consumer ships (likely FEAT-007 or FEAT-008), add a one-sentence policy to FEAT-001's events.jsonl schema docs and reference it from FEAT-006 FR-014 + data-model.md §4.4. Recommended language:

Future fields MAY be added to existing event-types in a strictly additive manner (consumers MUST tolerate unknown keys). Breaking changes (renames, removals, type changes) require a new event_type value; the old value MUST remain emittable for at least one feature release for back-compat.

Acceptance criteria

• FEAT-001 / FEAT-006 spec or data-model documents the additivity rule explicitly
• Downstream feature spec (FEAT-007 or whichever consumes audit rows first) cites the rule
• Snapshot tests for the audit row continue to pass after the rule is added

References

• specs/006-agent-registration/spec.md FR-014
• specs/006-agent-registration/data-model.md §4.4
• specs/006-agent-registration/checklists/agent-registry-quality.md CHK006

Priority

Low — documentation-quality gap with no implementation impact. Address when the first audit-log consumer ships.