Skip to content

Add explicit guidance selection to review - #297

Merged
nahiyankhan merged 3 commits into
mainfrom
feat/review-explicit-guidance
Sep 11, 2026
Merged

nahiyankhan merged 3 commits into
mainfrom
feat/review-explicit-guidance

Conversation

@nahiyankhan

Copy link
Copy Markdown
Collaborator

Stack: Depends on #292. Base is fix/preserve-guidance-output so this diff contains only explicit-guidance review. Land #292 first, then retarget/rebase this PR onto main.

Category: new-feature
User Impact: Review can consider the brand guidance used to build a new surface even when its referenced components or materials did not change.

Problem: Diff-based material matching can miss an unchanged button's guidance when a new checkout uses that button. The host knows which guidance governed the work, but could not supply it to review.

Solution: Add repeatable ghost review --node <id> to include exact, host-selected guidance and offer referencing checks alongside existing material matches and always-offered checks. Preserve full guidance, material declarations, and selection provenance; unknown IDs fail before reading the diff, and no-flag behavior stays unchanged.

ghost review --node component.button --node principle.trust

No receipts, import scanning, truncation, new dependencies, or starter changes. Explicit selection adds review context; it does not prove applicability, create file matches, or suppress coverage gaps.

Validation:

  • pnpm run quality:all: passed, repeated by the pre-push hook. 264 tests across 21 files, including 32 new tests, plus builds, typecheck, packed-consumer installation/imports, release checks, workspace checks, and package validation.
  • Built CLI smoke: unchanged-component check is offered with explicit selection; guidance and unmatched-file gaps remain present.
  • ghost manifest --format json: exposes repeatable --node <id>; help/manifest behavior covered by tests.
  • pnpm check:terminology and merge-base diff checks: passed.
  • Existing lint warnings and two cover-policy warnings remain unchanged.

Changeset: minor added for the new flag and additive packet fields. Existing review JSON/Markdown behavior is unchanged without explicit IDs.

ghost Review:

  • node packages/ghost/dist/bin.js review --package apps/docs/.ghost --base origin/fix/preserve-guidance-output --format json: packet assembled; no docs-material matches or offered checks. All 12 changed files are outside that package's material coverage, so this is a coverage gap, not a passing grade.
  • Independent source review found no blockers. Current CLI manifest used; retired check/manifest-generation workflows are not available in this checkout.
File changes (12 files)
File Purpose
.changeset/explicit-review-guidance.md Release note for additive explicit-node review.
packages/ghost/README.md Explain reviewing guidance behind unchanged components.
packages/ghost/src/commands/command-discovery.ts Advertise explicit guidance in review discovery.
packages/ghost/src/commands/review-command.ts Parse repeatable IDs and validate before diff access.
packages/ghost/src/review/resolve.ts Validate exact identities, widen check selection, and preserve provenance and gaps.
packages/ghost/src/review/review-packet.ts Include complete explicit guidance/material declarations and deduplicate overlaps.
packages/ghost/src/skill-bundle/SKILL.md Teach additive review selection.
packages/ghost/src/skill-bundle/references/making.md Ask the host to supply guidance that governed this change, not every prior pull.
packages/ghost/src/skill-bundle/references/schema.md Document selection, error, and packet-field behavior.
packages/ghost/test/review-explicit-packet.test.ts Cover full content, baseline preservation, overlap, cover/nested IDs, and long guidance.
packages/ghost/test/review-node-cli.test.ts Cover repeated flags, validation order, missing values, check-directory behavior, and help.
packages/ghost/test/review-selection.test.ts Cover exact IDs, mixed/anchored references, stable selection, and non-filtering behavior.

Screenshots/Demos: N/A; no visual changes.

Base automatically changed from fix/preserve-guidance-output to main September 11, 2026 05:07
@nahiyankhan
nahiyankhan marked this pull request as ready for review September 11, 2026 05:40
@nahiyankhan
nahiyankhan merged commit 7cc2e21 into main Sep 11, 2026
4 checks passed
@nahiyankhan
nahiyankhan deleted the feat/review-explicit-guidance branch September 11, 2026 05:40
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.

1 participant