Rename gather slice vocabulary to plain language#203
Draft
nahiyankhan wants to merge 2 commits into
Draft
Conversation
Drop the spine/corridor/hub-and-spoke metaphor stack. The slice is full bodies along a surface's path, one-hop relates edges, and pointers. Breaking JSON/type changes (no back-compat): - slice.spokes -> slice.pointers - pointer kind "edge-hub" -> "related" - pointer field .hub -> .from - GraphSpokeKind type -> GraphPointerKind The 'edge' provenance is unchanged (relates links are genuine graph edges). Docs, skill bundle, code comments, and gather CLI output use plain wording; em dashes in the touched CLI output strings are cleaned in passing.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Category: improvement
User Impact: The
gatheroutput and docs describe a surface's context in plain words instead of an unexplained spine/corridor/hub-and-spoke metaphor.Problem: The
gatherslice was narrated with a stack of metaphors (spine, corridor, walls, hub-and-spoke) that a reader had to decode to understand one command, and the metaphor had leaked into the JSON contract asslice.spokes/ kind"edge-hub"/ fieldhub.Solution: Rename the API to plain language and rewrite the prose to match. A slice is full bodies along a surface's path, one-hop
relatesedges, and pointers.edgeprovenance stays (arelateslink genuinely is a graph edge); only the metaphor terms go.Breaking changes (no back-compat by request):
slice.spokes->slice.pointerskind"edge-hub"->"related".hub->.fromGraphSpokeKindtype ->GraphPointerKindValidation:
pnpm build: passpnpm check: pass (biome, typecheck, terminology, file-size, packed tarball, manifest in sync)pnpm test: 115 passed, 9 skippedgather --format json: keys aresurface, ancestors, nodes, pointers;spokesabsent; pointer kindsdescendant/relatedChangeset: added (
major— renamed public JSON/type surface)Ghost Review:
ghost review --base ghost/14-docs-check-binding: not run; this is a vocabulary/output rename with no surface-composition or UI-generation behavior change, and.ghost/is not present in this repo.File changes
packages/ghost/src/ghost-core/graph/slice.ts
Core rename:
GraphSpokeKind->GraphPointerKind,slice.spokes->pointers, kind"edge-hub"->"related", fieldhub->from; internalcorridorFolders->foldersOnPath,spineIds->pathNodeIds; doc comment rewritten without spine/corridor/walls/hub.packages/ghost/src/commands/gather-command.ts
Render
pointers/frominstead ofspokes/hub; cleaned four em dashes in CLI output strings while here.packages/ghost/src/ghost-core/graph/types.ts, node/schema.ts, scan/node-tree.ts, scan/templates.ts, scan/fingerprint-package-layers.ts
Comment-only: drop spine/corridor/walls metaphor wording.
packages/ghost/test/ghost-core/graph-slice.test.ts
Update assertions to
pointers/related; de-metaphor test names and comments.packages/ghost/src/skill-bundle/SKILL.md, references/schema.md
Describe pointers (not spokes); plain path wording.
apps/docs/src/content/docs/cli-reference.mdx, getting-started.mdx, docs/purposes.md
Reconcile prose to the new
pointersfield name and plain path language..changeset/gather-vocab.md
Major changeset documenting the renamed JSON/type surface.
Screenshots/Demos: N/A