Epic: notion-md frictionless, progressively-disclosed sync

[schickling-assistant]

Problem

notion-md must now land the entire VRS end-to-end in PR #775, not just the v-next sync core. The completed v-next core removed the major single-source footguns, but the VRS still defines additional surfaces that remain incomplete: files/media, comments, webhook-triggered refresh, data-source schema/view integration boundaries, explicit destructive modes, and object-store lifecycle.

North Star

Make notion-md fully VRS-complete in one PR:

• The common single-source path remains stateless.
• Bidirectional merge complexity remains opt-in via source: shared.
• Files are self-describing; the engine dispatches on frontmatter, not CLI flags or arity.
• The CLI remains track / status / sync.
• Watch, dry-run, files, comments, webhooks, object lifecycle, and destructive modes are all first-class, tested, and documented parts of the same reconcile model.

Completed In PR #775

• Author v-next requirements/spec invariants in VRS.
• Run the competing-designs bake-off and write the winning spec.
• Implement the v-next CLI/core:
  • track / status / sync, no public clone
  • semantic-equivalence canonicalizer
  • stateless reconcile for source: local | remote
  • base-backed shared reconcile only for source: shared
  • explicit source schema gate, no legacy default
  • dry-run for write-capable commands
  • watch through the v-next reconcile path
  • public package surface no longer exports legacy sync helpers
• Test-suite overhaul for the completed sync core:
  • semantic-equivalence tests
  • adversarial footgun tests
  • offline corpus replay
  • live Notion corpus verification
  • live Notion watch smoke
  • OTEL watch span assertions
  • downstream datasource-sync adapter validation
• Initial docs/VRS/changelog alignment for the completed sync core.

Remaining Work Now In Scope For PR #775

• VRS truth pass: remove or resolve all future, designed, not implemented, and not fully implemented language for surfaces that are part of this VRS; split anything genuinely out-of-scope into a separate VRS boundary with explicit ownership.
• Files/media payloads: implement the file payload/object-store model for media/file blocks and file property values, including pull/materialize, safe preservation, push/update behavior, dry-run output, and fake/live tests.
• Comments bridge: implement comment payload modeling, read/materialize behavior, explicit push/bridge semantics, conflict/safety policy, and fake/live tests.
• Webhook trigger path: implement schema-decoded webhook payload ingestion as an interruptible trigger source for the same reconcile/watch machinery; include service identity/OTEL spans and tests.
• Data-source schema/view boundary: finish the notion-md side of schema/view snapshots or make the datasource-sync ownership boundary executable and tested from notion-md so the VRS is not aspirational.
• Destructive modes: implement explicit, safe CLI/API modes for unknown-block deletion and Roughdraft review-markup handling, or revise the VRS requirements/spec so they are explicitly not part of notion-md.
• Object-store lifecycle: implement reachable-object validation plus garbage collection for orphaned content-addressed objects, with dry-run and tests.
• CLI/API/docs: expose the completed surfaces through principled track / status / sync flags or subcommands without reintroducing legacy mode complexity; update docs/cli.md, docs/sync-safety.md, docs/troubleshooting.md, docs/file-format.md, and docs/vrs/spec.md timelessly.
• E2E verification: add focused fake tests, required live smoke where external Notion behavior matters, downstream datasource-sync integration tests where impacted, OTEL assertions, and run devenv tasks run check:all --no-tui before ready.

Acceptance Evidence Required Before Ready

• All VRS requirements/spec rows either implemented and tested or explicitly moved out of this package's VRS scope.
• devenv tasks run check:quick --no-tui passes.
• devenv tasks run check:all --no-tui passes.
• Live Notion integration covers all Notion-dependent surfaces introduced by this expansion.
• PR feat(notion-md): v-next frictionless, progressively-disclosed sync (#774) #775 body lists final implemented surfaces, decisions, verification, concerns, and remaining non-blocking follow-ups.

Exit

PR #775 closes this epic only when the full notion-md VRS surface is implemented end-to-end or the VRS is deliberately narrowed so no unimplemented surfaces remain in scope.

Posted on behalf of @schickling

field	value
agent_name	🚩 co1-summit
agent_session_id	d74abf32-e0e4-443d-bd30-d2926f571d0f
agent_tool	Codex CLI
agent_tool_version	0.137.0
agent_runtime	Codex CLI 0.137.0
agent_model	unknown
runtime_profile	/nix/store/h2fzkx1acfyaidg5bmdamarf7856a2s8-coding-agent-runtime-profile/share/coding-agents/profile.json
skills_manifest	/nix/store/3v899lwjyzgkr7x7h4m5hlbbpn1jkbds-agent-skills-corpus/share/agent-skills/manifest.json
worktree	effect-utils/schickling/2026-06-10-756
machine	dev3
tooling_profile	dotfiles@unknown-dirty