Skip to content

Make context the node retrieval field - #252

Merged
chailandau merged 3 commits into
mainfrom
chai/desc-to-context
Aug 7, 2026
Merged

Make context the node retrieval field#252
chailandau merged 3 commits into
mainfrom
chai/desc-to-context

Conversation

@chailandau

Copy link
Copy Markdown
Collaborator

Category: improvement
User Impact: Agents can use clearer context frontmatter to decide which brand guidance applies without silently losing retrieval coverage.
Problem: Node retrieval currently reads description, so authors cannot rename the field to context without producing blank gather menus. A fingerprint-only migration would validate successfully while quietly making nodes undiscoverable.
Solution: Make context canonical throughout schema, catalog, gather, pull, review, serialization, validation, docs, and repo-owned packages. Keep description as a deprecated compatibility alias for one release, warn on its use, and serialize it back as context so existing packages remain retrievable during migration.

Validation:

  • pnpm check: passed
  • pnpm exec vitest run packages/ghost/test packages/context-control/test: passed, 180 passed and 1 skipped
  • pnpm test: 203 passed and 1 skipped; one unrelated local environment failure in steering-control because process.execPath contains a space and ghostBin.split() attempts to execute /Users/chai/Library/Application
  • ghost validate for apps/docs/.ghost and packages/vessel-light/.ghost: passed with no warnings
  • ghost validate for packages/vessel-react/.ghost: passed with its existing cover-undeclared warning

Changeset: added as a minor release because this introduces the public context retrieval capability.

ghost Review:

  • ghost check --base main: not available in the current CLI; deterministic package and repository checks ran through pnpm check
  • ghost review --base main --include-memory: not available in the current CLI shape; review packet behavior is covered by the Ghost test suite
File changes

.changeset/node-context-retrieval.md
Records the new public node retrieval capability as a minor release.

packages/ghost/src/ghost-core/node/
Adds canonical context schema and types, accepts deprecated description, and migrates the alias during serialization.

packages/ghost/src/ghost-core/catalog/
Resolves node context with canonical precedence and emits it through gather menu entries while retaining transition aliases.

packages/ghost/src/embed/ and packages/ghost/src/commands/
Uses context in gather selection instructions, coverage, menu output, and pull packets; keeps deprecated JSON compatibility fields for one release.

packages/ghost/src/scan/fingerprint-package-lint.ts
Warns when context is missing and when deprecated description frontmatter needs migration.

packages/ghost/src/review/
Carries context through review baselines and material-backed review nodes.

packages/ghost/src/init-payloads/, packages/vessel-light/.ghost/, packages/vessel-react/{.ghost,fingerprint}/, and apps/docs/.ghost/
Migrates repo-owned node frontmatter to context; check documents retain their separate description schema.

packages/ghost/src/skill-bundle/, README.md, and docs/purposes.md
Documents context as the retrieval payload and the one-release compatibility window.

packages/context-control/
Updates the retrieval benchmark, model prompt, and viewer to evaluate node context.

apps/docs/src/
Updates public examples and gather demonstrations to show context.

packages/ghost/test/
Covers canonical context, deprecated alias reads, precedence, migration serialization, lint warnings, coverage, gather, pull, and embed output.

Screenshots/Demos: N/A; this changes framework terminology and output contracts without changing the rendered design.

chailandau and others added 3 commits August 7, 2026 15:14
Co-authored-by: Goose <opensource@block.xyz>
Ai-assisted: true
Co-authored-by: Goose <opensource@block.xyz>
Ai-assisted: true
Co-authored-by: Goose <opensource@block.xyz>
Ai-assisted: true
@chailandau
chailandau marked this pull request as ready for review August 7, 2026 20:03
@chailandau
chailandau merged commit 75612b3 into main Aug 7, 2026
5 checks passed
@chailandau
chailandau deleted the chai/desc-to-context branch August 7, 2026 20:03
@github-actions github-actions Bot mentioned this pull request Aug 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants