External system-of-record writeback + reconciliation (gated: field ownership, conflict detection, audit receipts)

[markmhendrickson]

Summary

Neotoma has no first-class writeback connector for mutating an external system-of-record. Existing "mirror writeback" writes disk Markdown to Neotoma /correct, and peer sync assumes another Neotoma peer. Writing back to a third-party system of record (e.g. via its REST API) needs an explicit ownership/conflict/audit model.

Scope

A gated external writeback + reconciliation layer:

• Typed mutation client for an external API, behind a feature flag (off by default)
• Per-field system-of-record declaration (external-owned vs Neotoma-derived); Neotoma never writes an external-owned field without an explicit rule
• Conflict detection: detect divergence between external state and Neotoma-derived state before writing
• Correction audit: every writeback is an auditable observation with provenance
• Immutable audit receipts per mutation (who/what/when/source→target)
• Reconciliation so the external system remains authoritative and writes are reversible

Acceptance criteria

• Writeback is off unless explicitly enabled per field
• A divergence between external and derived state is surfaced, not silently overwritten
• Every mutation produces a queryable, provenance-stamped receipt
• The external system remains system-of-record; writeback is advisory/derived and reversible

Note

This is deliberately gated — most integrations should start read-only. Ownership + audit model is required before any active writeback ships.

[neotoma-agent]

🤖 Lanius — Ateles swarm, issue triage
COMMENT

Issue triaged. Pavo has been assigned as PM owner for Phase 1 scoping.

Gate Status

Gate	Status	Owner
PM	pending	Pavo
UX	pending	Accipiter
Arch	pending	Bombycilla
Impl	pending	Gryllus
PR Review	pending	Vanellus
QA	pending	Phoenicurus
Legal	not_required	—
Release	pending	Struthio

Phase Flow

• Phase 1 (PM): Pavo — validate product/acceptance criteria
• Phase 2 (parallel): UX (Accipiter) + Architecture (Bombycilla) — design review, no schema changes detected
• Phase 3 (Impl): Gryllus — implementation
• Phase 4: PR Review (Vanellus) + QA/Legal (Phoenicurus/Buteo parallel)
• Phase 5 (Release): Struthio

📎 Neotoma: issue entity tracking this workflow state

[neotoma-agent]

🤖 Pavo — Ateles swarm, pm gate owner
COMMENT

review_expectation (pm) — what pavo will verify when a PR addresses this issue:

• Writeback is disabled by default; acceptance criteria reference feature flag and how to enable per-field
• Schema registry or per-field declaration supports system-of-record ownership (external vs Neotoma-derived); PR shows new schema fields or equivalents
• Conflict detection logic is present and documented; PR shows divergence surfaced before mutation (not silent overwrite)
• Audit receipt implementation: all mutations produce queryable, provenance-stamped records; sample receipt structure appears in tests or migration
• External system remains source-of-record: writeback is advisory/derived and reversible (PR shows no mutation of external state without user intent; corrections/reversals are possible)
• Acceptance criteria from the issue are met as concrete feature gates, not as future work or 'planned for' phases

Confidence: High. Issue scope is well-bounded with explicit, testable acceptance criteria.

[neotoma-agent]

🤖 Pavo — Ateles swarm, pm gate owner
SIGNED_OFF

PM Gate Validation

Intent: Establish a gated external writeback + reconciliation layer for safe third-party system mutations with integrity, auditability, and reversibility.

Scope is clear and well-bounded:

• Problem: Neotoma lacks first-class writeback connectors for external systems
• Solution: Typed mutation client (feature-flagged off by default) with ownership model, conflict detection, audit receipts, and reversibility
• Acceptance criteria are concrete and testable

Review expectations are defined: Six specific, verifiable criteria established for PR review:

• Default-off writeback with per-field enablement via feature flag
• Per-field system-of-record ownership (external vs Neotoma-derived)
• Conflict detection surfaces divergence before mutation (not silent overwrite)
• Audit receipt implementation: queryable, provenance-stamped records per mutation
• External system remains source-of-record; writeback is advisory/derived and reversible
• All acceptance criteria are concrete feature gates, not future work

Dependencies: None. This is a foundational layer and prerequisite gate for future external integrations.

Confidence: High. Schema is extensible for ownership declarations; conflict detection is a standard pattern; audit receipt materialization is well-understood.

---

Verdict: PM gate is SIGNED_OFF. Scope is adequate, acceptance criteria are concrete and testable, and review expectations are clear. Ready for architecture review.

Advancing to: Bombycilla (arch gate)