duplicates.md recommends --clean for fingerprint backfill without warning it deletes every other project

[vitali87]

What

docs/guide/duplicates.md:378 says:

Graphs indexed before duplicate detection existed carry no fingerprints; re-index once with --clean to backfill them.

--clean is more destructive than that sentence suggests (cli_help.py:264):

DESTRUCTIVE: Delete every project from the shared graph and clear the selected repository's sync cache. With --update-graph, rebuild after deletion. Asks for confirmation when other projects would be destroyed; use --yes to skip the prompt.

So a user with several projects in one shared graph, following this instruction to fix a fingerprint problem in one repository, destroys the indexed data for all the others. The confirmation prompt is the only thing standing between the doc's advice and that outcome, and --yes removes it.

The advice is technically correct, which is why it survived

I checked whether the gentler flag would do, and it would not. Fingerprints are stamped at parse time (parsers/ast_fingerprint.py via function_ingest.py), so any re-parse backfills them — but the incremental path skips unchanged files (graph_updater.py:2291-2295, hash match → skipped_count += 1; continue). An old graph's files have not changed, so --update-graph alone re-parses nothing and backfills nothing. There is no force-reparse flag.

--clean really is the mechanism. The problem is purely that the doc states the remedy without its blast radius.

Suggested fix

Keep the recommendation, add the consequence and the safe path — something like: --clean clears every project in the shared graph, so confirm the prompt only if this graph holds just this repository; otherwise re-index the affected project into its own graph. Worth checking whether a scoped variant is feasible, but the doc change stands on its own.

The same sentence appears again at duplicates.md:506.

How this surfaced

The fix-doc-qualified-name session cited this line to me as a phrasing precedent while I was writing a migration note for #1437. It went to verify its own use of the precedent, found --clean was wrong for that purpose, and switched to --update-graph. My paragraph names no flag so it was unaffected, but the original line remains.

Worth recording the general shape: a convention copied from the codebase is evidence about style, not about correctness, and citing it as precedent propagates whatever was never checked the first time.

[vitali87]

Update: the investigation that produced this issue turned up a stronger precedent, and it changes the recommended fix.

cgr already warns about exactly this class of staleness, by name (logs.py:846):

PARSER_FINGERPRINT_MISMATCH = "Parser code changed since this graph was built. Incremental sync keeps results from the old parser for unchanged files, so the graph may be stale. Run 'cgr start --clean' to rebuild it from scratch."

_warn_if_parser_changed (graph_updater.py:2049) emits it and does not force a re-parse — it only warns. So the codebase's own position is that --clean is the remedy when parser behaviour changes under an existing graph, which is precisely the fingerprint-backfill case.

That settles the part I was unsure about above: --clean should stay. Anyone tempted to soften it to --update-graph would produce an instruction that runs, reports success, and changes nothing — worse than the destructive one, because the failure is silent.

So the fix is narrower than "reconsider the flag": keep the recommendation, add the blast radius. The sentence at duplicates.md:378 (and again at :506) should say that --clean clears every project in the shared graph, and that it is safe to confirm only when that graph holds just this repository.

Same correction has now been applied to the document-tier note in #1437, which had the identical vagueness — it said "re-index" without naming a flag, and .md files were already hashed before the document tier existed, so --update-graph would have skipped them and left the graph untouched.

Credit to the fix-doc-qualified-name session for finding the PARSER_FINGERPRINT_MISMATCH string; it reached the same conclusion after briefly making the opposite correction on its own PR.