Ground checks in guidance and reshape ghost review into one packet - #263
Draft
nahiyankhan wants to merge 3 commits into
Draft
Ground checks in guidance and reshape ghost review into one packet#263nahiyankhan wants to merge 3 commits into
nahiyankhan wants to merge 3 commits into
Conversation
chailandau
reviewed
Aug 19, 2026
| must resolve during `ghost validate`; unresolved nodes and missing headings are | ||
| errors. Write the guidance node first, then the check in the same change. | ||
|
|
||
| The removed check keys are `name`, `description`, `source`, `tools`, and |
Collaborator
There was a problem hiding this comment.
Does this need to be in here or can it stick in a changelog instead?
…cket Check format ghost.check/v2: context, severity, and resolving references are required; name, description, source, tools, and turn_limit are retired; .agents/checks shape compatibility ends with a teaching migration error. Unresolved check references are validation errors. ghost review drops material-path routing (resolve.ts deleted) and emits one grounded packet: all checks or a requested subset, deduped cited guidance excerpts, cited-node materials via pull transport, fenced untrusted diff, and a traceability findings contract. Review refuses packages ghost validate would reject.
nahiyankhan
force-pushed
the
checks-v2-grounded-review
branch
from
August 19, 2026 17:00
72e598a to
65d6624
Compare
chailandau
reviewed
Aug 19, 2026
| ...(frontmatter.references | ||
| ? { references: [...frontmatter.references] } | ||
| : {}), | ||
| context: frontmatter.context, |
Checks and nodes now share one word for the same concept: for states the situation in which the guidance or check applies. The check schema rejects context with a teaching error, matching how the node schema handled its own rename. Median-tells check payloads are rephrased as situations rather than descriptions of what the check does.
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
2 participants
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: Review checks now must cite the guidance they enforce, and
ghost reviewemits a single grounded packet the reviewing agent can act on without follow-up commands.Problem: v1 checks were free-floating assertions: they carried their own
name,description,source,tools, andturn_limit, could exist without citing any guidance node, andghost reviewrouted them through material-path matching that produced partial, multi-step packets with offered checks and gaps the agent had to chase.Solution: Introduce check format
ghost.check/v2. Checks now requirefor(the situation in which the check applies, matching the node retrieval field),severity, and resolvingreferencesinto guidance nodes; unresolved references are validation errors, so check-first authoring is retired and every check is grounded in prose the author shipped.ghost reviewdrops material-path routing entirely (resolve.tsdeleted) and emits one packet: all checks or a requested subset (ghost review [...checkIds]), deduped cited guidance excerpts, cited-node materials via the pull transport (--no-materialsfor locator-only output), the untrusted diff fenced, and a traceability contract for findings. Review refuses packages thatghost validatewould reject, and.agents/checksshape compatibility ends with a teaching migration error.Validation:
pnpm build: passpnpm test: pass (18 files, 222 tests)pnpm check: pass (biome, typecheck, terminology, file-size, package, release workflows, vessel-light closure)ghost validateagainstpackages/vessel-light/.ghostandpackages/vessel-react/.ghostwith the built CLI: 0 errors, 0 warningsChangeset: added (
.changeset/checks-v2-grounded-review.md, minor: breaking check format and/coretype changes gated behind a minor pre-1.0 release)ghost Review: not run; this branch changes the review machinery itself and the repo root carries no
.ghost/package to review against.File changes
packages/ghost/src/ghost-core/check/types.ts, load.ts, lint.ts, index.ts
Define the
ghost.check/v2frontmatter:for,severity, andreferencesrequired; legacy fields removed. Loading and linting enforce the new shape, emit a teaching migration error for v1/.agents/checksshapes, and treat unresolved references as validation errors.packages/ghost/src/ghost-core/check/guidance-ref.ts (renamed from
source-ref.ts)Check references now point at guidance nodes, not sources;
parseSourceRefbecomesparseGuidanceRefwith optional heading anchors.packages/ghost/src/review/review-packet.ts
The one-shot packet: selected checks, deduped guidance excerpts cited by those checks, cited-node materials through the pull transport, fenced diff, and the findings traceability contract. Handles check-id filtering with unknown-id suggestions (exit 2 when none resolve) and
--no-materials.packages/ghost/src/review/resolve.ts (deleted)
Material-path routing removed; checks are no longer matched to touched files.
packages/ghost/src/review/guidance-excerpt.ts (renamed from
baseline.ts)Extracts the cited guidance prose (whole node or anchored heading section) for the packet.
packages/ghost/src/commands/review-command.ts
New CLI surface: positional check ids,
--no-materials, exit codes, and refusal when the package or its checks would failghost validate.packages/ghost/src/commands/command-discovery.ts
Command help/summary text updated for the new review shape.
packages/ghost/src/scan/check-files.ts, check-reference-lint.ts, check-scaffold.ts, file-kind.ts, fingerprint-package-lint.ts
Package-level validation resolves check references against the node corpus; scaffolded example checks emit the v2 shape.
packages/ghost/src/embed/snapshot.ts
Snapshot output tracks the new check fields.
packages/ghost/src/ghost-core/index.ts
Public
/coreexports follow the rename and the v2 frontmatter type (breaking for typed consumers, noted in the changeset).packages/ghost/src/skill-bundle/SKILL.md, references/authoring.md, making.md, nodes.md, schema.md
Skill teaches v2 check authoring: cite guidance first, then assert; documents the new packet shape and reference syntax.
packages/ghost/src/init-payloads/median/median-tells.md
Starter check migrated to v2.
packages/vessel-light/.ghost/checks/.md, packages/vessel-react/.ghost/checks/.md, packages/vessel-react/.ghost/manifest.yml
Shipped example packages migrated to the v2 check format.
packages/ghost/test/cli.test.ts, ghost-core/check-md.test.ts, guidance-ref.test.ts, fingerprint-package.test.ts, embed.test.ts, public-exports.test.ts
Tests rewritten for the v2 shape, review filtering, exit codes, refusal behavior, and the renamed export.
CLAUDE.md, README.md, packages/ghost/README.md, apps/docs/src/pages/index.astro, docs/purposes.md
Docs describe checks as grounded assertions and the review command as a one-shot packet.
scripts/check-terminology.mjs
Retires vocabulary from the v1 check model.
.changeset/checks-v2-grounded-review.md
Minor changeset covering the breaking check format, review reshape, and
/coretype change.Screenshots/Demos: N/A