Report incomplete guidance loading

[nahiyankhan]

Category: improvement
User Impact: Users and agents can distinguish missing guidance from guidance excluded by loading errors.

Problem: Invalid files could disappear behind a complete-menu claim, while some filesystem and glossary errors looked like absent content.

Solution: Expose skipped-file diagnostics through gather, pull, and review, report actual menu completeness, and fail on unreadable directories or malformed present glossaries. Keep invalid checks out of generation diagnostics.

Compatibility: Breaking API change: contract.completeness.complete widens from literal true to boolean; consumers must check it. Healthy results include diagnostics: []. Partial loads keep their success status; all-miss CLI pulls keep empty stdout and exit 2. No on-disk migration.

Scope: One of five independent PRs split from the original #291. This branch targets main and contains only this concern, its tests, and its documentation.

Related: Enforce resolved material access boundaries, Preserve guidance meaning in CLI output, Add read-only installed skill checks, Fix and validate rendered guidance examples.

Validation:

• pnpm run quality:all: passed on this standalone branch, including build, package/release checks, tests (246 passed), workspace builds, and package validations.
• Pre-commit checks and git diff origin/main...HEAD --check: passed.
• Fresh dependency installation hit registry checksum errors. Validation used an isolated copy of the existing checkout's dependencies; the lockfile is unchanged.

Changeset: Existing minor changeset retained, with the breaking API change labeled for the 0.x preview.

ghost Review: Review packet assembled against apps/docs/.ghost. This package does not bind the changed CLI/test/docs files, so the packet is coverage context, not a passing brand review. Used the current ghost review --package apps/docs/.ghost --base origin/main --format json and inspected ghost manifest; the older ghost check, --include-memory, and dump:cli-help workflows are unavailable in this checkout.

File changes (16 files)

File	Purpose
.changeset/visible-load-diagnostics.md	Record diagnostics and the completeness type change.
packages/ghost/README.md	Explain diagnostics and completeness checks.
packages/ghost/src/commands/gather-command.ts	Render diagnostics and stop claiming an incomplete menu is complete.
packages/ghost/src/commands/pull-command.ts	Preserve diagnostics in output and all-miss stderr.
packages/ghost/src/embed/gather.ts	Return diagnostics and actual load completeness.
packages/ghost/src/embed/pull.ts	Return diagnostics for successful and all-miss pulls.
packages/ghost/src/embed/snapshot.ts	Reject malformed present glossaries and contextualize read failures.
packages/ghost/src/embed/types.ts	Add diagnostics and widen the completeness type.
packages/ghost/src/internal/load-diagnostics.ts	Format existing skipped-file records as actionable warnings.
packages/ghost/src/review/review-packet.ts	Include invalid guidance and check diagnostics.
packages/ghost/src/scan/check-files.ts	Retain YAML errors and propagate directory read failures.
packages/ghost/src/scan/node-files.ts	Retain YAML errors and propagate directory read failures.
packages/ghost/src/skill-bundle/SKILL.md	Explain excluded guidance and loading warnings.
packages/ghost/src/skill-bundle/references/ground.md	Distinguish excluded guidance from authored absence.
packages/ghost/src/skill-bundle/references/schema.md	Document diagnostics and failure behavior.
packages/ghost/test/load-diagnostics.test.ts	Cover partial and all-invalid loads, check separation, malformed files, and filesystem failures.

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