Skip to content

Ghost stack 7/7 — Directory-tree graph, corridor gather, docs + cleanup#196

Draft
nahiyankhan wants to merge 12 commits into
ghost/06-cleanupfrom
ghost/07-directory-tree
Draft

Ghost stack 7/7 — Directory-tree graph, corridor gather, docs + cleanup#196
nahiyankhan wants to merge 12 commits into
ghost/06-cleanupfrom
ghost/07-directory-tree

Conversation

@nahiyankhan

@nahiyankhan nahiyankhan commented Jun 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Stacked PR 7 of 7 · base: ghost/06-cleanup

Two structural changes plus a documentation and cleanup pass. ⚠️ Breaking (minor, pre-1.0).

1. Directory-as-architecture: the tree is the graph

The flat nodes/*.md folder + surfaces.yml spine + frontmatter id/under are replaced by the directory tree as the graph:

Concept Before After
Node identity frontmatter id the file path (marketing/email.md → marketing/email)
Parent / hierarchy surfaces.yml + under the containing directory
A surface a row in surfaces.yml a directory
A surface's prose a node with that id its index.md
The core root implicit implicit; package-root index.md is its prose

surfaces.yml and the nodes/ convention are gone. Node frontmatter carries descriptive properties only (description, relates, incarnation, passthrough). relates/extends refs are path ids (core/trust, brand:core/trust). Moving a node is a rename; ghost validate reports relates that no longer resolve.

The ghost-core/surfaces module is deleted. This touched discovery, schema, and scaffolding only — the graph query layer was already id-based.

2. gather recomposed on a corridor + hub-and-spoke model (fixes a context leak)

The old cascade leaked every core-level sibling into every surface's slice (gathering one feature screen pulled in every other top-level feature). Replaced by folders are walls; files fill the corridor:

  • spine (full bodies): every file from the package root down to the surface's own folder. A sibling folder is a wall — its nodes never appear.
  • edges (full bodies, one hop): each spine node's relates targets, so a broad rule authored once high in the tree (relates: { to: arcade } on features/) reaches every descendant.
  • spokes (pointers: id + description): the surface's own descendants and any edge hub's subtree, which the agent pulls on demand.

GraphSlice JSON gains a spokes array; graph nodes carry their file folder. Grounding for checks/review stays the full-body spine + edges. Validated against a realistic 51-feature monorepo shape.

3. Docs, prose, and dead-code cleanup

  • Docs retrack: getting-started/fingerprint-authoring referenced ~10 removed commands (relay, lint, verify, check, compare, stack, ack, track, diverge) and dead concepts (stacks, selected_context, fingerprint.md). Rewritten onto the real verbs (gather/checks/review) and the corridor model; nested-package guidance replaced with the extends shared-brand model.
  • Framing fix: Ghost is a deterministic CLI and an interpretive skill bundle, not just a "calculator."
  • Stop-slop: removed em dashes across all shipped prose (README, CLAUDE.md, package README, skill bundle, docs site), rewriting them as plain sentences; recast two negative-listing structures.
  • Fossils deleted: schemas/fingerprint.schema.json (a facet-era JSON Schema requiring palette/typography/spacing — a format that no longer exists), its broken generator, and strip-signature.mjs.
  • ghost-ui parked: removed the Design Language catalogue (/ui/*, /tools/ui) and everything that only served it from the docs site; dropped its public mentions. The package stays in the repo, referenced nowhere public.

Decisions locked with the author

  1. Pure path-as-identity — one source of truth for identity and hierarchy.
  2. Corridor model: folders are walls, files fill the corridor; descendants and edge hubs surface as pointer spokes; relates is the one cross-wall connector and a broad rule is authored at the broadest folder where it is true.
  3. checks/ stays a reserved top-level subtree (hard-coded for now; a follow-up makes the reserved set configurable for nested .agents-style reuse).
  4. Package-root index.md = the core node; core stays the implicit root.
  5. Unreleased changesets re-pointed so the 0.19.0 changelog reads as one coherent story.

Validation

  • 98 tests pass; full pnpm check green (biome, typecheck, file-size, terminology, CLI manifest).
  • Docs site builds. End-to-end smoke verified: init → add nodes → validate → scan → gather (corridor spine + edges + spokes, no sibling leak).

Stack

  1. ghost/01-surface-spec … 6. ghost/06-cleanup
  2. ➡️ ghost/07-directory-tree (this PR)

@nahiyankhan nahiyankhan force-pushed the ghost/07-directory-tree branch from 202f824 to f141d98 Compare June 28, 2026 21:26
@nahiyankhan nahiyankhan mentioned this pull request Jun 28, 2026
Closed
@nahiyankhan nahiyankhan changed the title Ghost stack 7/7 — Directory-as-architecture: the tree is the graph Ghost stack 7/7 — Directory-tree graph, corridor gather, docs + cleanup Jun 29, 2026
nahiyankhan added 12 commits June 28, 2026 23:24
@nahiyankhan
docs: refresh README + docs site onto the node-graph model
6cbfcff 
The README, docs site, published package README, and CLAUDE.md still
described the removed facet model (intent/inventory/composition/validate.yml
plus relay/compare/stack/ack/track/diverge/lint/verify). Rewrite them onto
the node-graph model and the current 9-command surface, and tighten the
homepage thesis and hero into a strong, simple intro.
@nahiyankhan
feat!: directory-as-architecture — the tree is the graph
017870c 
Collapse the on-disk node model into the directory tree. A node's id is its
file path (`marketing/email.md` → `marketing/email`) and its parent is its
containing directory; a surface is just a directory, and a directory's own
prose lives in its `index.md` (the package-root `index.md` is the implicit
`core` node).

Removed:
- `surfaces.yml` spine file and the `ghost.surfaces/v1` artifact/module
- the `nodes/` directory convention (any `*.md` outside `checks/` is a node)
- node frontmatter `id` and `under` — identity and containment come from the
  file's location, never from frontmatter or a declared spine

Node frontmatter is now descriptive properties only (`description`, `relates`,
`incarnation`, plus passthrough keys). `relates`/`extends` refs are path ids
(`core/trust`, `brand:core/trust`). Moving a node is a rename; `ghost validate`
reports `relates` that no longer resolve.

The graph query layer (gather/checks/review/slice) is unchanged — it was
already id-based; this only changes discovery, schema, and scaffolding.

`ghost init` scaffolds `manifest.yml` + a core `index.md`; `ghost migrate`
writes a directory tree. Skill bundle, docs, README, and CLAUDE.md updated;
unreleased changesets re-pointed so the 0.19.0 changelog reads as one coherent
facet→directory-tree story.
@nahiyankhan
feat(graph): carry each node's file folder onto the graph
bfc8258 
The corridor model keys composition off a node's file folder (the directory its
source sits in), which diverges from graph-parent for index nodes: features/
bitcoin/index.md has folder features/bitcoin but parent features. Thread folder
through PlacedNode and GhostGraphNode; inherited nodes get a package-qualified
folder so they never sit on a local corridor. Purely additive.
@nahiyankhan
feat(gather)!: corridor spine + hub-and-spoke spokes; fix sibling leak
59acadf 
Recompose resolveGraphSlice on the agreed model — folders are walls, files fill
the corridor:

- spine (full bodies): every node whose file folder is on the corridor from the
  package root down to the surface's own folder. A sibling folder is a wall; its
  nodes never enter the slice. This deletes the old leak where every child of an
  ancestor (incl. every core-level sibling) cascaded into every surface.
- edges (full bodies, one hop): relates targets of every spine node, so a broad
  rule authored once high in the corridor (relates: { to: arcade } on features/)
  reaches every descendant.
- spokes (pointers): the surface's own descendants and each edge hub's subtree,
  as id + description for the agent to pull on demand.

GraphSlice gains spokes[]; gather markdown gains an Available-to-pull section.
Tests encode the six confirmed behaviors against a synthetic feature-tree.
@nahiyankhan
docs+skill: teach the corridor + spine/spokes gather model
585a452
@nahiyankhan
docs: frame Ghost as CLI + interpretive skill, not just a calculator
f573537 
The Architecture paragraph described Ghost as 'the deterministic calculator the
agent reaches for', which amputated the skill bundle. Ghost grounds agent work
with both a deterministic CLI and an interpretive skill bundle that teaches
authoring and use.
@nahiyankhan
docs: retrack the docs site to the current command set and corridor m…
ff9b61e 
…odel

getting-started referenced a pile of removed commands (relay, lint, verify,
check, compare, stack, ack, track, diverge) and dead concepts (stacks,
selected_context, fingerprint.md). Rewrote its gather/govern sections onto the
real verbs (gather/checks/review), led the directory example with root nodes +
a marketing surface (no more bare checkout), and taught the corridor model.

fingerprint-authoring: drop lint/verify/stack; replace the nested-package
section with the extends-based shared-brand model. cli-reference: drop the
'surfaces spine' phrasing. Docs build, frontmatter, and terminology all pass.
@nahiyankhan
docs: stop-slop pass on the gather prose
18c3b2f 
Cut adverb crutches ('simply'), a negative-contrast tail ('not only after a
review finds drift'), 'This is the pre-generation step' throat-clearing, and the
'navigable optionality' quotable. Plain, active phrasing.
@nahiyankhan
docs: strip em dashes from shipped prose (stop-slop)
f40a7a8 
Em dashes were repo-wide slop, not house style. Rewrote every one in the
user-facing surfaces as a colon, period, comma, or parenthetical, and recast two
negative-listing structures on the landing page. Covers README, CLAUDE.md, the
package README, the skill bundle (SKILL + references), the docs site pages, and
the ghost-ui marketing copy. Left typography specimens (the em dash is demo
content there). Patch changeset for the shipped skill-bundle/README prose.
@nahiyankhan
chore: delete dead fingerprint.md-era fossils
e4bea42 
Remove three orphaned artifacts from the pre-node-graph fingerprint.md format:

- schemas/fingerprint.schema.json: JSON Schema requiring palette/typography/
  spacing frontmatter — a format that no longer exists. Not published, last
  touched before the node-graph reset, referenced nowhere.
- scripts/emit-fingerprint-schema.mjs: its generator. Broken — reads from a
  deleted dist/scan/schema.js and a toJsonSchema() that no longer exists.
- scripts/strip-signature.mjs: one-shot helper for stripping '# Signature'
  blocks from fingerprint.md files. Dead format, referenced nowhere.

No code, build step, or CI references any of them.
@nahiyankhan
docs: omit the ghost-ui catalogue from the docs site
fffadef 
Remove the Design Language catalogue (/ui/* pages, the /tools/ui landing) and
everything that only served it: the component/foundation demo components
(ai-elements, primitives, bento, examples, foundations), the registry loader
(lib/component-docs, registry-sidebar, demo-loader, component-page-shell,
open-in-v0), and the catalogue's theme editor (theme-panel, ThemePanelContext).

Drop the ghost-ui entries from the tools index and the dock search. Keep
ghost-ui as the docs site's runtime dependency (ThemeProvider, useTheme,
useStaggerReveal) — that is the shell the site is built with, not documented
content. 150 files removed; build, tests, and checks green.
@nahiyankhan
docs: park ghost-ui, remove its public mentions
a193c02 
Delete two orphaned catalogue data loaders missed in the prior cut
(lib/component-registry, lib/component-source). Drop the ghost-ui row from the
root README package table so it is not advertised on any public surface. In
CLAUDE.md (agent orientation, not public), mark it parked: a standalone shadcn
registry + ghost-mcp server, not coupled to Ghost. The package stays in the repo
for anyone browsing; it is referenced nowhere public.
@nahiyankhan nahiyankhan force-pushed the ghost/07-directory-tree branch from 5d2f7d9 to a193c02 Compare June 29, 2026 03:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@nahiyankhan