fix: keep captured comments in chronological order

[steipete]

What Problem This Solves

Conversation capture could export comments out of chronological order when their source timestamps used different fractional-second precision.

User Impact

Captured comments now follow their actual source times, including nanoseconds and timezone offsets. The capture schema and deterministic kind/ID tie order remain unchanged; comments without a source time still sort first.

Why This Change Was Made

RFC3339Nano strings do not sort chronologically as text: .11Z sorts before .1Z, and both sort before the whole-second Z. The comparator now uses the already validated timestamps as instants.

Evidence

A locally built CLI synced a synthetic HTTP fixture and exported comments at the whole second, .1, and .11. Before the fix, capture returned them in reverse chronological order; afterward it returns the correct order. The regression test additionally covers nanoseconds, absent timestamps, equivalent offsets and precision, and kind/ID ties.

Full make check passed, including coverage, vet, vulnerability/dead-code checks, smoke, release-script tests, docs, and snapshot packaging. Independent autoreview is clean through P2.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed September 15, 2026, 3:22 AM ET / 07:22 UTC.

ClawSweeper review

What this changes

The PR sorts exported conversation comments by their actual timestamps and adds regression coverage, documentation, and a changelog entry.

Merge readiness

⛔ Blocked before merge - 2 items remain

The fix remains necessary: main and v0.10.0 still sort timestamps lexically. No introduced correctness defect was found, but the reported CLI verification needs observable output before merge.

Priority: P2
Reviewed head: cd6fcb70f8420ad032ed688654586bb2c068bc49

Review scores

Measure	Result	What it means
Overall readiness	🦪 silver shellfish (2/6)	The patch is focused and source-correct, while runtime proof remains a narrative claim without observable output.
Proof confidence	🦪 silver shellfish (2/6)	Needs stronger real behavior proof before merge: The body reports exercising the real sync-to-capture CLI against an HTTP fixture, but supplies no captured output showing buildThread's corrected exported order. Add the redacted terminal transcript or capture result from that run; tests and make-check claims remain supplemental. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs stronger real behavior proof before merge: The body reports exercising the real sync-to-capture CLI against an HTTP fixture, but supplies no captured output showing buildThread's corrected exported order. Add the redacted terminal transcript or capture result from that run; tests and make-check claims remain supplemental. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	7 items	Current main still contains the defect: The capture comparator uses string ordering, which places fractional timestamps before the whole-second timestamp and .11 before .1. Latest release retains lexical ordering: The same comparator is present in v0.10.0; this change is not already shipped. Normalization preserves deterministic ties: buildThread calls buildComment before sorting. Its timestamp normalization rejects invalid input and formats valid timestamps in UTC with RFC3339Nano, so equivalent offsets and precision produce identical strings and reach the existing kind/ID tie-breakers.
Findings	None	None.
Security	None	None.

How this fits together

Gitcrawl capture reads synced GitHub conversations from a local SQLite archive and exports deterministic JSON. Comment ordering affects the exported conversation and its semantic content hash.

flowchart LR
  A[Synced SQLite archive] --> B[Completed comment observation]
  B --> C[Validate and normalize timestamps]
  C --> D[Sort by time then kind and ID]
  D --> E[Hash conversation]
  E --> F[JSON capture output]

Loading

Before merge

• Add real behavior proof - Needs stronger real behavior proof before merge: The body reports exercising the real sync-to-capture CLI against an HTTP fixture, but supplies no captured output showing buildThread's corrected exported order. Add the redacted terminal transcript or capture result from that run; tests and make-check claims remain supplemental. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Complete next step (P2) - Add observable proof from the reported CLI run before merge: copied terminal output, exported JSON, or a terminal screenshot showing corrected comment order. Redact credentials, private endpoints, IP addresses, and other private data. Updating the PR body should trigger a fresh review; if it does not, ask a maintainer to comment @clawsweeper re-review.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test delta	Production +8/-1; tests +61	The small comparator expansion directly addresses chronological ordering and is accompanied by focused regression coverage.

Technical review

Best possible solution:

Keep the existing capture schema and timestamp normalization while comparing comment timestamps chronologically, preserving empty-time and kind/ID ordering.

Do we have a high-confidence way to reproduce the issue?

Yes, source inspection establishes the failure: comments at the whole second, .1, and .11 are sorted incorrectly by main's string comparator. No runtime reproduction was executed in this review.

Is this the best way to solve the issue?

Yes. Comparing already validated and normalized timestamps is a narrow repair; normalization also makes the retained string-equality check safe for equivalent-instant ties.

AGENTS.md: found, but no applicable review policy affected this item.

Codex review notes: model internal, reasoning medium; reviewed against efaeb1ff0c5b.

Labels

Label changes:

• add P2: This repairs incorrect ordering in conversation exports with a limited, well-defined scope.
• add rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The body reports exercising the real sync-to-capture CLI against an HTTP fixture, but supplies no captured output showing buildThread's corrected exported order. Add the redacted terminal transcript or capture result from that run; tests and make-check claims remain supplemental. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Label justifications:

• P2: This repairs incorrect ordering in conversation exports with a limited, well-defined scope.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The body reports exercising the real sync-to-capture CLI against an HTTP fixture, but supplies no captured output showing buildThread's corrected exported order. Add the redacted terminal transcript or capture result from that run; tests and make-check claims remain supplemental. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

What I checked:

• Current main still contains the defect: The capture comparator uses string ordering, which places fractional timestamps before the whole-second timestamp and .11 before .1. (internal/capture/capture.go:362, efaeb1ff0c5b)
• Latest release retains lexical ordering: The same comparator is present in v0.10.0; this change is not already shipped. (internal/capture/capture.go:362, 9898b678a4d8)
• Normalization preserves deterministic ties: buildThread calls buildComment before sorting. Its timestamp normalization rejects invalid input and formats valid timestamps in UTC with RFC3339Nano, so equivalent offsets and precision produce identical strings and reach the existing kind/ID tie-breakers. (internal/capture/capture.go:354, cd6fcb70f842)
• Focused regression coverage: The added test checks seven comments covering missing timestamps, whole seconds, nanoseconds, fractional precision, equivalent offsets, and kind/ID ties. Tests were inspected, not executed during this read-only review. (internal/capture/comment_order_test.go:35, cd6fcb70f842)
• CLI proof is described but not captured: The complete supplied body describes a locally built CLI syncing an HTTP fixture and exporting corrected order. The live body matches that snapshot, and discussion contains only bot status messages. No transcript, exported result, screenshot, or linked runtime artifact accompanies the claim. This is relevant production-path evidence in narrative form, not merely a unit-test claim, but the observed result cannot be audited. (cd6fcb70f842)
• Feature-history routing: Local history identifies Josh Lehman across capture export, rate-limit observations, and repository identity work; GitHub maps the capture export commit to jalehman. Historical blame and follow traversal encountered unavailable blobs, so no exact source-line introduction attribution is asserted. (internal/capture/capture.go, 2b532382962e)

Likely related people:

• jalehman: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Attach the reported CLI run's redacted commands and exported comment IDs/timestamps showing whole-second, .1, and .11 ordering.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.