docs: supersedes is a replacement link, not a version chain (#6212)

* docs: supersedes is a replacement link, not a version chain

Reword the DepSupersedes comment (internal/types/types.go), the
`bd supersede` help text, and the graph-links doc: `supersedes` marks an
old issue as replaced by a different issue. It is not a version relation
and does not imply a version chain. The behavior is unchanged.

Promised on #5898 (Q8, quad341 revision 4): a replacement link, not a
version-chain link. docs/CLI_REFERENCE.md is pinned to v1.2.2 and picks
this up at the next release bump (generate-cli-docs.sh --check passes).

Wyvern bead wy-h4xd6f.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PvjeDsoyDfjptvjKZWzcqA

* docs: finish the supersedes rewording pass in graph-links + dependencies

Maintainer review fixup for PR #6212.

The PR's new assertion "This is a replacement link, not a version relation"
left the rest of graph-links.md still telling the version-chain story, so
the page contradicted itself. Each residual line is byte-identical to base,
but the contradiction is new with this commit. Extends the same wording pass
to the sites that actually assert version semantics:

- frontmatter description: "supersedes chains" -> "supersedes (replacement)
  links" (this is the rendered page description)
- the example comment "# View shows the chain" -> "# View shows the
  replacement"
- "### Version History" -> "### Replacement History" and "# bd-rfc3 is now
  the current version" -> "# bd-rfc3 is now the live issue"
- Best Practice 4 "Document supersedes chains - Note why version changed" ->
  "Document replacements - Note why the issue was replaced"

The use-case list ("Design document versions", "Artifact versioning", "RFC
chains") and "Track document evolution" are deliberately left alone:
chained replacements legitimately model document evolution without the link
itself being a version relation.

Also rewords the sibling core-concepts table, docs/core-concepts/
dependencies.md:56, from "Replaced by a newer issue" to "Replaced by a
different issue" so both hand-written pages frame the edge the same way.

No in-repo reference targets the renamed #version-history anchor.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <julianknutsen@users.noreply.github.com>
This commit is contained in:
Bee 2026-09-12 06:41:33 -07:00 • committed by GitHub
commit 83184f4c6a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 11 additions and 11 deletions

View file

@ -28,8 +28,8 @@ Examples:
var supersedeCmd = &cobra.Command{
Use: "supersede <id> --with <new>",
GroupID: "deps",
Short: "Mark an issue as superseded by a newer one",
Long: `Mark an issue as superseded by a newer version.
Short: "Mark an issue as superseded by a replacement issue",
Long: `Mark an issue as superseded by a different (replacement) issue.
The superseded issue is automatically closed with a reference to the replacement.
Useful for design docs, specs, and evolving artifacts.

View file

@ -53,7 +53,7 @@ Dependencies have a type that determines whether they block work.
| `discovered-from` | Found during work on another issue |
| `caused-by` | Root cause link |
| `validates` | Test or verification link |
| `supersedes` | Replaced by a newer issue (`bd supersede old --with new`) |
| `supersedes` | Replaced by a different issue (`bd supersede old --with new`) |
Specify with `--type`:

View file

@ -1,6 +1,6 @@
---
title: Graph Links in Beads
description: "Non-blocking links between issues: replies-to threads, relates-to, duplicates, and supersedes chains"
description: "Non-blocking links between issues: replies-to threads, relates-to, duplicates, and supersedes (replacement) links"
---
Beads supports several types of links between issues to create a knowledge graph. These links enable rich querying and traversal beyond simple blocking dependencies.
@ -114,9 +114,9 @@ bd show bd-bug2
- Original (canonical) issue remains open
- `duplicate_of` field stores the canonical ID
### supersedes - Version Chains
### supersedes - Replacement Links
Marks an issue as superseded by a newer version. The old issue is automatically closed.
Marks an issue as superseded by a different (replacement) issue. The old issue is automatically closed. This is a replacement link, not a version relation: the new issue takes the old one's place.
**Created by:**
- `bd supersede <old-id> --with <new-id>`
@ -142,7 +142,7 @@ bd create --title "Design Doc v2" --type task
bd supersede bd-doc1 --with bd-doc2
# Result: bd-doc1 closed with superseded_by: bd-doc2
# View shows the chain
# View shows the replacement
bd show bd-doc1
# Status: closed
# Superseded by: bd-doc2
@ -247,14 +247,14 @@ bd duplicate bd-bug42 --of bd-bug17
bd duplicate bd-bug58 --of bd-bug17
```
### Version History
### Replacement History
Track document evolution:
```bash
bd supersede bd-rfc1 --with bd-rfc2
bd supersede bd-rfc2 --with bd-rfc3
# bd-rfc3 is now the current version
# bd-rfc3 is now the live issue
```
### Message Threading
@ -272,7 +272,7 @@ Build conversation chains (via orchestrator mail):
1. **Use relates-to sparingly** - Too many links become noise
2. **Prefer specific link types** - `duplicates` is clearer than generic relates-to
3. **Keep threads shallow** - Deep reply chains are hard to follow
4. **Document supersedes chains** - Note why version changed
4. **Document replacements** - Note why the issue was replaced
5. **Query before creating duplicates** - `bd search` first
## See Also

View file

@ -1224,7 +1224,7 @@ const (
DepRepliesTo DependencyType = "replies-to" // Conversation threading
DepRelatesTo DependencyType = "relates-to" // Loose knowledge graph edges
DepDuplicates DependencyType = "duplicates" // Deduplication link
DepSupersedes DependencyType = "supersedes" // Version chain link
DepSupersedes DependencyType = "supersedes" // Replacement link: old issue superseded by a different issue (bd supersede); not a version relation
// Entity types (HOP foundation - Decision 004)
DepAuthoredBy DependencyType = "authored-by" // Creator relationship