feat(sync): support bounded updated windows

[altaywtf]

Summary

Add a bounded Intercom updated window so historical backfills can crawl from..to ranges instead of repeatedly including the recent tail.

Changed

• adds fincrawl sync --updated-before alongside --updated-since
• validates inverted/missing window bounds
• keeps sync high-water marks monotonic for historical backfills
• updates agent describe output and docs with bounded backfill examples

Risks

• live sync window semantics affect incremental crawling and resume state
• bounded historical runs must not move normal tail state backwards

Verification

• go test ./internal/cli ./internal/syncer ./internal/intercom
• ./scripts/verify
• $HOME/.agents/skills/codex-review/scripts/codex-review --mode local clean after fixing the accepted watermark finding

Complexity

Reduced for large backfills: callers can crawl older ranges without noisy overlap against already-crawled recent data.

---

Summary by cubic

Adds a bounded sync window to Intercom syncs so you can backfill a specific updated range without crawling the live tail. High-water marks now advance safely and never move backward.

• New Features

  • Added --updated-before to pair with --updated-since for a [from..to] window.
  • Validates windows: --updated-before requires --updated-since and must be after it.
  • Dry-run shows computed updated_after/updated_before and raw updated_since/updated_before_input.
  • Updated docs and agent describe with examples, e.g. fincrawl sync --updated-since 180d --updated-before 90d --limit 0.

• Bug Fixes

  • High-water mark advancement is monotonic for backfills and tail syncs; newer marks are preserved even if the candidate is older or malformed.

^{Written for commit b0ab474. Summary will update on new commits. Review in cubic}

[Copilot]

Pull request overview

Adds support for bounded Intercom “updated” windows so historical backfills can sync a from..to range without repeatedly re-crawling the most recent tail, while keeping the tail high-water mark monotonic.

Changes:

• Adds fincrawl sync --updated-before (requires --updated-since) and validates window bounds in the CLI.
• Prevents the Intercom tail HighWaterMark from moving backwards after a bounded historical run.
• Updates agent describe output and documentation with bounded backfill examples; adds regression tests.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
README.md	Documents bounded backfill example using --updated-since + --updated-before.
internal/syncer/intercom.go	Advances tail high-water mark monotonically via advanceHighWaterMark.
internal/syncer/intercom_test.go	Adds test ensuring older bounded windows don’t regress HighWaterMark.
internal/cli/cli.go	Adds --updated-before, parsing/validation, and passes bounded window to syncer.
internal/cli/cli_test.go	Adds CLI usage + dry-run tests for bounded window validation/output.
internal/cli/agent_dx.go	Exposes new flag in describe schema and examples.
docs/roadmap.md	Updates roadmap wording to reflect bounded window support.
docs/architecture.md	Adds bounded backfill example to architecture doc.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cubic-dev-ai]

1 issue found across 8 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="internal/syncer/intercom.go">

<violation number="1" location="internal/syncer/intercom.go:265">
P2: When `candidate` fails to parse but `current` is valid, this returns the malformed `candidate`, overwriting a good high water mark. The error-handling branch should preserve `current` when `candidateErr != nil` and `current` is parseable.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
Fix all with cubic | Re-trigger cubic}