Skip to content

docs: close remaining spec/implementation documentation gaps - #102

Merged
kmturley merged 1 commit into
mainfrom
docs/spec-gaps
Jul 31, 2026
Merged

docs: close remaining spec/implementation documentation gaps#102
kmturley merged 1 commit into
mainfrom
docs/spec-gaps

Conversation

@kmturley

Copy link
Copy Markdown
Member

Summary

Last item from an internal spec-compliance audit: five places where the spec was silent about or contradicted shipped, tested behavior.

  • Added a "Computed package fields" section documenting installed, verified, and downloads — real fields the manager/registry compute and attach to package metadata, previously undocumented anywhere.
  • Noted the two-tier Package Validation (structural errors vs. non-fatal recommendations) next to the Scan logic section, since the recommendations system (packageRecommendations()) was implemented but never mentioned in the spec.
  • Windows App directory table now says %AppData% (matching the actual, platform-idiomatic implementation) instead of the literal $HOME — the code was right and the spec was wrong here, not the other way around.
  • Install logic: reworded the Admin-privileges step to describe the conditional elevation (skip it when a compatible archive is available, added for issue Archive plugin installs unnecessarily require administrator elevation #83) and reordered it after file filtering to match actual execution order.
  • Install logic: installer execution is described as "wait for it to complete" rather than "run the process in a separate thread" — fileInstall() is fully synchronous (execFileSync), so "separate thread" was inaccurate in both particulars, not just imprecise.

Docs-only change, no code touched.

Test plan

  • npm run check passes (format, lint, build, tests — 207/207, unchanged since this is documentation-only)

🤖 Generated with Claude Code

Last item from an internal spec-compliance audit: five places where
the spec was silent about or contradicted shipped, tested behavior.

- Added a "Computed package fields" section documenting installed,
  verified, and downloads - real fields the manager/registry compute
  and attach to package metadata, previously undocumented anywhere.
- Noted the two-tier Package Validation (structural errors vs
  non-fatal recommendations) next to the Scan logic section, since the
  recommendations system (packageRecommendations()) was implemented
  but never mentioned in the spec.
- Windows App directory table now says %AppData% (matching the actual,
  platform-idiomatic implementation) instead of the literal $HOME -
  the code was right and the spec was wrong here, not the other way
  around.
- Install logic: reworded the Admin-privileges step to describe the
  conditional elevation (skip it when a compatible archive is
  available) added for issue #83, and reordered it after file
  filtering to match actual execution order.
- Install logic: installer execution is described as "wait for it to
  complete" rather than "run the process in a separate thread" -
  fileInstall() is fully synchronous (execFileSync), so "separate
  thread" was inaccurate in both particulars, not just imprecise.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@kmturley
kmturley merged commit bffa0e2 into main Jul 31, 2026
6 checks passed
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