beads/docs/core-concepts
Bee 83184f4c6a
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>
2026-09-12 06:41:33 -07:00
..
adaptive-ids.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00
dependencies.md docs: supersedes is a replacement link, not a version chain (#6212) 2026-09-12 06:41:33 -07:00
graph-links.md docs: supersedes is a replacement link, not a version chain (#6212) 2026-09-12 06:41:33 -07:00
hash-ids.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00
index.md Rename the reserved "graph" mermaid node id so diagrams render (#4958) 2026-07-23 17:14:09 -07:00
issues.md docs: align user docs and CLI reference with the v1.1.0 release (#4874) 2026-07-17 14:17:28 -07:00
labels.md fix(labels): normalize labels on write, and warn when one contains a space (#5812) (#5813) 2026-08-20 08:08:24 -07:00
metadata.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00
sync-concepts.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00