Add source provenance and publish-scope preflight checks

[joshka]

Parent: #100

Related Gitcrawl context: openclaw/gitcrawl#81

Observed Workflow

Discrawl supports both Discord bot API sync and local Discord Desktop cache import. That combination is useful, but the source mix can matter for metadata quality.

During initial use, a combined sync path refreshed messages from wiretap but left guild metadata insufficient for public/private publish classification. A later discrawl sync --source discord restored the role/visibility metadata needed for publish --public-only checks.

Current Workaround

The workaround was to remember that privacy-sensitive publish checks need bot-sourced guild metadata and to run a Discord-only repair sync before repeating the publish check.

That is easy to miss, especially when discrawl sync defaults to a combined source.

Request

Add source/provenance and publish-scope preflight diagnostics.

Example shape:

discrawl doctor --publish-scope --json
discrawl publish --public-only --check
discrawl status --sources --json

Useful Output

• whether guild metadata came from bot sync, wiretap import, snapshot import, or an incomplete local cache record
• whether role/private-channel metadata is present enough for public/private filtering
• whether publish --public-only is likely to export zero rows because metadata is incomplete
• suggested repair command, such as discrawl sync --source discord, when bot metadata is required
• clear warning when only local desktop cache data is available

Why This Matters

The use case is not just "can I search locally?" It is local maintainer archive work with private/public boundaries. A user or Codex agent should be able to tell whether the archive has enough provenance and metadata to make a publish-scope decision.

Acceptance Criteria

• doctor --json or a dedicated check reports metadata quality relevant to public/private filtering.
• publish --public-only --check can validate scope without writing a snapshot.
• The diagnostic recommends a concrete repair step when bot-sourced metadata is missing.
• The output distinguishes missing metadata from an intentionally empty public export.

---

Prepared with Codex, confirmed as accurate by human.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 26, 2026, 1:21 PM ET / 17:21 UTC.

Summary
Keep open: current main still has source-specific sync and fail-closed public-only filtering, but it does not provide the requested source-provenance diagnostics, publish-scope preflight, or publish --public-only --check dry run.

Reproducibility: not applicable. as a bug reproduction: this is a feature/diagnostic request. Source inspection shows the current commands lack the requested preflight/status surface rather than failing an existing documented behavior.

Root-cause cluster
Relationship: canonical
Canonical: #103
Summary: This issue is the narrow canonical follow-up for source provenance and publish-scope diagnostics; the parent issue and docs PR preserve adjacent workflow context but do not replace the remaining implementation work.

Members:

• partial_overlap: Track initial local Discord maintainer-archive use friction #100 - The parent workflow-friction tracker explicitly lists this issue as the source/provenance and publish-scope preflight slice.
• partial_overlap: Document maintainer archive workflows #107 - The open documentation PR describes a manual publish preflight workflow, but it does not add the requested CLI diagnostics or check-only publish behavior.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.

Next step
Maintainers should first choose the CLI/API shape and provenance model because the request adds security-sensitive diagnostic surface and likely new flags.

Security
Needs attention: Security-sensitive issue: the requested diagnostics affect privacy-boundary confidence for public snapshot publishing, but no patch was reviewed.

Review details

Best possible solution:

Add one shared read-only publish-scope analyzer, then expose the maintainer-approved CLI surface for provenance, metadata completeness, predicted public export counts, and repair guidance.

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

Not applicable as a bug reproduction: this is a feature/diagnostic request. Source inspection shows the current commands lack the requested preflight/status surface rather than failing an existing documented behavior.

Is this the best way to solve the issue?

Unclear until maintainers choose the public command shape and provenance model. The narrow maintainable direction is a shared analyzer reused by the selected CLI entry points, not separate ad hoc checks.

AGENTS.md: not found in the target repository.

Remaining risk / open question:

• The issue proposes example command shapes rather than a settled CLI/API contract, so maintainers should choose whether this belongs in doctor, status, publish --check, or a shared analyzer.
• Uniform provenance may need a schema or compatibility decision because current source hints are partly stored in raw JSON and are not modeled consistently across bot sync, wiretap import, and snapshot import.
• Any implementation must preserve the existing fail-closed public-only behavior when role or permission metadata is incomplete.

Codex review notes: model internal, reasoning high; reviewed against 670994a45f61.

Label changes

Label justifications:

• P2: This is a bounded improvement to an existing publish workflow with privacy implications, but it is not a confirmed leak, outage, or urgent regression.
• impact:security: The request concerns public/private snapshot boundaries and whether archive metadata is sufficient to make safe publish-scope decisions.

Evidence reviewed

Security concerns:

• [medium] Preserve fail-closed publish filtering — internal/share/share.go:1866
  A preflight should make incomplete metadata visible without weakening the current behavior that treats missing role or permission metadata as not public.
  Confidence: 0.86

What I checked:

• Target AGENTS.md check: No AGENTS.md exists under the target repository root; the only AGENTS.md found was in a sibling ClawSweeper checkout and was not target-repository policy. (670994a45f61)
• Doctor lacks publish-scope diagnostics: runDoctor registers only --json, rejects all positional arguments, and reports config/auth/database/FTS state rather than publish metadata quality. (internal/cli/admin_commands.go:498, 670994a45f61)
• Publish has no check-only path: runPublish registers publish/export flags but no --check flag, then calls share.Export before returning output. (internal/cli/share_commands.go:17, 670994a45f61)
• Status lacks source/provenance mode: runStatus registers only --json and Store.Status returns aggregate counts and sync times, not bot/wiretap/snapshot provenance or metadata completeness. (internal/cli/admin_commands.go:404, 670994a45f61)
• Public-only filtering depends on metadata quality: The snapshot filter reads guild/channel raw JSON, treats missing @everyone role permissions as not public, and applies category/channel overwrites before allowing public export. (internal/share/share.go:1866, 670994a45f61)
• Source hints are partial: Wiretap-created guild, channel, and message raw JSON includes source=discord_desktop, but current schema does not expose uniform provenance for bot, wiretap, snapshot, and incomplete-cache metadata. (internal/discorddesktop/import.go:1283, 670994a45f61)

Likely related people:

• vincentkoc: Current blame and pickaxe history tie the publish command, doctor/status surface, public-only share filter, and earlier desktop wiretap import work to this contributor. (role: recent area contributor; confidence: high; commits: 6a91d9cc67bb, f01e699c1c86, 0a247939e841; files: internal/cli/share_commands.go, internal/cli/admin_commands.go, internal/share/share.go)
• Peter Steinberger: History shows adjacent CLI split and wiretap provenance-related work in the same source and diagnostic area. (role: adjacent contributor; confidence: medium; commits: 14b4b06a6527, e22a3709caea; files: internal/cli/admin_commands.go, internal/discorddesktop/import.go)

How this review workflow works

• 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.