DevForgeKit v3.0.2

Fixed

• npm install -g devforgekit followed by a plain devforgekit could
  fail permanently on Linux/WSL2 when installed with sudo (the
  common case on a system Node.js install where the global prefix is
  root-owned, e.g. Ubuntu/Debian's apt nodejs package). Root cause,
  confirmed live in a clean Ubuntu 22.04 + npm 11.18 container (full
  writeup in docs/NpmGlobalInstallRootCause.md):
  1. npm 11.16+'s allow-scripts security gate silently skips global
     installs' lifecycle scripts by default, so scripts/npm-postinstall.sh
     never ran and cli/node_modules was never populated at install time.
  2. The devforgekit dispatcher's own self-heal fallback
     (self_heal_cli_deps, added specifically for case 1) then tried to
     npm install into cli/ on first run - but a sudo-installed
     package leaves that directory root-owned, so the unprivileged user
     hit EACCES: permission denied, mkdir '.../cli/node_modules'. The
     printed recovery command (cd ... && npm install, no sudo) failed
     with the identical error, leaving no working path forward.
     self_heal_cli_deps now falls back a second time to a user-writable
     mirror of the repo under ~/.cache/devforgekit/cli-fallback/ (real
     copies of cli/bin+cli/src so Node's module resolver can't walk
     symlinks back to the still-unwritable original; every other top-level
     entry - registry/, docs/, profiles/, scripts/, VERSION, etc.
  • is symlinked instead), auto-invalidated after npm update -g devforgekit ships new cli/src. Reproduced on a clean Ubuntu 22.04 +
    npm 11.18 container, and confirmed the identical EACCES also
    reproduces on macOS given the same root-owned-directory condition - not
    WSL- or Linux-specific. Four new regression tests in
    cli/test/index.test.js cover the fallback mirror, registry/
    resolution through it, cache reuse, and stale-mirror invalidation.

Otherwise a documentation and messaging patch. No packaging changes -
the os: ["darwin", "linux"] restriction in package.json is
correct and stays as-is; it prevents a native Windows npm install that
would not run anyway, since the devforgekit dispatcher and
scripts/npm-postinstall.sh are both bash scripts requiring a POSIX
shell that stock Windows (cmd.exe/PowerShell) doesn't provide.

• bootstrap.sh printed a misleading "Bootstrap aborted unexpectedly"
  message for its deliberate, by-design non-macOS rejection. A generic
  EXIT trap (meant for genuinely unexpected failures) fired on this
  expected early exit too, making a first-time Linux user's devforgekit install look like something broke rather than "this is expected, run
  devforgekit <command> directly instead." Found and fixed during real
  Ubuntu/Debian certification (see below); one-line fix (trap - EXIT
  before the exit), verified live on both distros.

Certified this release (real evidence, see docs/PlatformSupport.md)

Part of the v3.0.2 Platform Stabilization Program
(docs/PlatformStabilizationProgram.md) - systematic, evidence-only
platform validation with no new features. Every claim below has a real
command run behind it; nothing is assumed.

• macOS Apple Silicon - certified. Full real-hardware lifecycle: the
  release gate (scripts/rc-validate.sh), the complete CLI regression
  suite, uninstall/services/backup/preferences exercised safely
  (test-mode or an isolated clone/$HOME, never mutating the real
  machine), check/doctor/report/inventory for real.
• Ubuntu 22.04 and Debian 12 - certified. Real fresh-container
  first-time-user lifecycle: no Homebrew, Node.js via NodeSource, npm
  11.18's allow-scripts gate, non-sudo and sudo (root-owned) global
  installs, the full command surface (profile, component, plugin,
  recipe, graph, benchmark, repair, completion for bash and
  zsh), uninstall/reinstall, and source-install-vs-npm-install parity.
  Debian run side-by-side with Ubuntu specifically to surface any
  Ubuntu-specific (rather than apt-family-generic) assumptions - none
  found.
• Fedora, Arch, macOS Intel - not yet certified. Expected to
  work (the dnf/pacman code paths in cli/src/core/platform/linux.js
  are architecturally identical to the certified apt path; Intel Mac
  support is the same common.sh logic as Apple Silicon, just a
  different Homebrew prefix), but genuinely not verified on real
  hardware/environment yet - Fedora/Arch were blocked by a local Docker
  Desktop environment issue unrelated to DevForgeKit (see
  docs/PlatformStabilizationProgram.md's Phase 3 report), Intel Mac by
  lack of hardware access. Recorded honestly as NOT TESTED rather than
  assumed.
• Windows + WSL2 - a supported installation path with real
  installation bugs found and fixed (the root-owned npm install fix
  above reproduces identically under WSL2's Ubuntu userspace). Full
  platform certification on real Windows/WSL2 hardware is still pending
  • what's verified so far is the Ubuntu-container equivalent, which
    cannot check genuinely WSL-specific concerns (Windows PATH leakage,
    /mnt/c interop). Native Windows (no WSL) remains unsupported by
    design - see below.

Changed

• README.md - every Windows-related claim now consistently states
  that native Windows is unsupported and explains why (bash dispatcher,
  not a packaging bug), with a prominent callout in Installation, a
  corrected FAQ, and updated badges/tables that previously implied
  Windows parity with macOS/Linux. Also brought in line with the
  certification results above - no platform claim overstates what's
  actually been verified (see docs/PlatformSupport.md).
• Website (devforgekit.dev) - installation page's Windows journey,
  platform-recommendation cards, FAQ, feature copy, roadmap copy, and
  lib/seo.ts's structured-data operatingSystem field brought in line
  with the same Windows-via-WSL messaging and the certification results.
• Added a Planned: v3.1 Native Windows Support roadmap entry -
  replacing the bash entry point and postinstall script, adding a real
  Windows-native provisioning path for devforgekit install, then
  removing the os restriction once verified on real hardware.
• New docker/platform-certification/ - reusable Dockerfiles (Ubuntu,
  Debian, Fedora, Arch) for reproducing a real first-time-user lifecycle
  per distro, kept for reuse in future certification work rather than
  left as throwaway scripts.

Known limitations carried into this release

See docs/PlatformSupport.md's "Known limitations" section for the full
list with root causes. Two new ones found during Ubuntu/Debian
certification, both investigated and deliberately not papered over with
a workaround: npm uninstall -g devforgekit after a root-owned install
leaves a harmless orphaned cache directory behind (allow-scripts would
block a preuninstall cleanup hook the same way it blocks postinstall,
so a real fix needs a different mechanism than a one-line patch); and
commander@15's conservative engines.node: >=22.12.0 prints a cosmetic
npm warn EBADENGINE on Node <22.12 that does not reflect an actual
incompatibility (DevForgeKit's CLI is pure ESM, not the CommonJS
require(esm) case that floor exists for).

DevForgeKit v3.0.1

First stable public release. Promotes v3.0.1-rc1 to stable after the
RC cycle's real-world verification (npm and Homebrew distribution, a
clean rc-validate run, and dogfooding on a real machine) turned up no
release-blocking issues. No code changes since v3.0.1-rc1 - see that
section below for the full release-engineering changelog (npm/Homebrew
distribution, shell completions, the release-readiness gate, and the
rest of this cycle's work).

DevForgeKit v3.0.1-rc1

Release engineering for v3.0.1-rc1: distribution channels and release
process, plus the verification work that preceded them. No new product
features.

Added

• npm distribution - npm install -g devforgekit is now a real,
  verified install path: a publishable root package.json, a
  self-healing devforgekit dispatcher (populates cli/node_modules
  on first run if npm's postinstall didn't - confirmed live that npm
  11.x's allow-scripts gate can skip it silently), and
  .github/workflows/npm-package.yml validating the real packed
  tarball end-to-end on macOS and Ubuntu.
• Homebrew distribution - Formula/devforgekit.rb, verified with a
  real brew install/brew test/brew uninstall cycle against a
  local test tap. Installs the launcher only; toolchain provisioning
  stays devforgekit install's job. .github/workflows/homebrew-formula.yml
  validates it on every change.
• Shell completions - completions/devforgekit.{bash,zsh,fish},
  generated from the CLI's real command tree
  (scripts/generate-completions.mjs), installed by the Homebrew
  formula and CI-checked for drift.
• docs/CommandSafety.md - every command classified READ ONLY or
  MUTATING, with the naming rule that drove it: a command without an
  explicit mutating verb must never modify the machine.
• docs/CompatibilityReport.md - a backward compatibility matrix
  across every public command: exit codes, --help, --json validity,
  error paths, mutation status, CI safety.
• docs/ApiFreeze.md - every public command, config field, schema,
  output format, and env var classified Stable/Experimental/Internal.
  Stable surfaces cannot change before v4.
• docs/ReleaseReadinessReport.md and docs/DistributionReadiness.md
  • the release-readiness rollup and the per-channel packaging status
    (what's actually Ready vs. Pending vs. Blocked, and why).
• RELEASE.md - the release checklist, tag process, rollback
  process, publishing order, and verification steps for v3.0.1-rc1 and
  beyond.
• devforgekit doctor --release-check - a single-command
  release-readiness gate: version consistency across VERSION/
  package.json/cli/package.json/Formula/devforgekit.rb, required
  documentation, distribution artifacts, registry health, outstanding
  pending-work markers, experimental/debug flags, git tree cleanliness,
  and the current commit's own CI status. Blocks (non-zero exit) if
  anything fails.
• devforgekit rc-validate (scripts/rc-validate.sh) - the full
  Distribution Verification & RC Validation checklist against real
  artifacts: GitHub Release, npm (a real scratch-prefix global install/
  uninstall cycle), Homebrew (a real brew install --build-from-source
  against a local test tap), a fresh-install lifecycle, smoke tests,
  and the full regression suite - writes docs/RCValidationReport.md
  with a real PASS/FAIL verdict.
• Draft-first GitHub Releases - pushing a version tag now creates a
  draft release rather than auto-publishing: real checksums
  (SHA256SUMS.txt), a real SBOM (CycloneDX and SPDX, via npm sbom
  against cli/'s actual dependency tree), and optional GPG signing
  (if a signing key is configured - none is yet) are attached, plus a
  doctor --release-check gate that blocks the release outright if the
  commit isn't ready. Publishing is always a separate, deliberate
  gh release edit <tag> --draft=false.
• Homebrew livecheck - Formula/devforgekit.rb now tracks GitHub
  releases directly (verified live via brew livecheck before adding,
  not guessed).

Fixed

• cli/package.json's test script had no per-test timeout -
  node --test defaults to unbounded, so a genuinely hung test worker
  (found live during this pass: a tui-reduced-motion.test.js process
  stuck for over two hours with near-zero CPU usage) hangs silently
  forever instead of failing loudly. Added --test-timeout=600000
  (an initial 180000 broke real CI - package.test.js's
  analyzePackages() test already had its own deliberately-set,
  CI-confirmed 300s internal bound, documented inline from a prior
  session's own live CI failure; the global timeout needs real margin
  above the slowest already-known-legitimate test, not just above
  local timing), with a regression test guarding the script definition
  itself.

• docs/DistributionReadiness.md - npm and Homebrew were still
  listed as "Pending" long after both shipped (PRs 18-19); updated to
  reflect that packaging is done and only real publishing remains,
  deliberately deferred.

• docs/CommandReference.md - doctor's real flag set (--json,
  --skip-bash, --skip-compatibility, --export, --release-check)
  was undocumented (only --fix was listed), and the new rc-validate
  command was missing entirely.

• README.md/CONTRIBUTING.md test-count badges - stale at 1,088;
  the real current count is 1,299.

• gh release download outside a git working tree - needs an
  explicit -R owner/repo; a scratch directory has no git context to
  infer the repository from otherwise.

• registry verify and workspace benchmark - two commands that
  mutated the machine by default despite read-only names. registry verify now only attempts an install behind an explicit --install
  flag; workspace benchmark no longer switches live git identity
  unless --ops explicitly asks for it. Both fixes shipped with
  canary-file regression tests.

• check --json and the package/repair command family - four
  separate instances of the same bug (a full registry scan running
  strictly sequentially instead of using the shared bounded-concurrency
  worker pool) made these commands hang indefinitely instead of
  completing in seconds. Found by actually running the compatibility
  sweep, not by reading the source.

• repair history --json and benchmark history --json - both
  silently broke their own --json contract on an empty result,
  printing a human-readable sentence instead of [].

• CI running the full test suite twice per commit - push and
  pull_request both triggering the identical ~7-minute suite for the
  same commit on a feature branch. push now runs a fast subset;
  the full suite runs once, on the pull request.

• Two real, timing-sensitive test bugs surfaced while investigating
  a CI failure: a polling helper that could resolve in zero event-loop
  ticks (starving Ink's raw-mode listener setup and silently dropping
  the next keypress), and a fixed-delay assertion too short for real
  CI contention. Both replaced with a poll-until-condition pattern that
  always yields at least once.

• Fish shell completion generation - incomplete backslash escaping
  in generated descriptions (caught live by CodeQL), fixed and verified
  against a synthetic backslash-and-quote input.

• scripts/release.sh rc could produce a version lower than the
  already-shipped release - cutting an RC directly from a clean,
  already-tagged version (e.g. running rc against 3.0.0 after
  v3.0.0 had already shipped) appended -rc1 without bumping the base
  version first, producing 3.0.0-rc1 - semver-lower than the real
  release it was supposedly a candidate for. This is exactly what
  happened cutting this cycle's first RC tag; corrected to 3.0.1-rc1
  and rc now refuses outright when the current clean version is
  already tagged on origin, pointing at patch/minor/major instead
  of guessing which bump was intended.

• scripts/release.sh create never synced package.json's or
  cli/package.json's own "version" field with VERSION - caught
  for real by doctor --release-check's version-consistency gate
  failing the release workflow on the actual RC tag. create now bumps
  all three together; Formula/devforgekit.rb is deliberately left
  alone (its url/sha256 can't reference a tag that doesn't have a
  real tarball yet) and checkVersionConsistency() now excludes it from
  the comparison for the whole lifetime of a pre-release cycle instead
  of deadlocking every RC.

• checkVersionConsistency()'s cli/package.json check ignored its
  own root parameter - read via cliRoot() (always this checkout's
  real path) instead of the passed-in root, so a test exercising it
  against a scratch directory was silently checking this repo's actual
  file instead. Found while adding a regression test for the sync fix
  above; now reads path.join(root, "cli", "package.json").

• WindowsPlatform.osVersion() shelled out unconditionally -
  cmd /c ver 2>nul is cmd.exe syntax, but the command runs through
  whatever shell is native to the current host; on a POSIX host (every
  CI runner, every dev machine here) 2>nul is interpreted by /bin/sh
  as a literal file redirect, leaving a stray file named nul in cli/
  after every test run. Caught by doctor --release-check's
  working-tree-clean gate immediately after CI's own test run left the
  file behind. Now returns null immediately on any non-Windows host
  without spawning a process at all.

Security

• Full security audit - shell-injection, tar zip-slip,
  unattended-plugin-execution, AES-256-GCM tag-pinning, and TOCTOU
  fixes across the credential backends, archive handling, and plugin
  trust system, each with a regression test. See SECURITY.md.
• npm audit: 0 vulnerabilities. gitleaks: 0 secrets.

Performance

• Package/repair size and version lookups (du -sk, which) gained a
  real timeout instead of running unbounded - a single large real
  directory could previously stall an entire scan.

Breaking Changes

• None.

DevForgeKit v3.0.0

DevForgeKit v3.0.0 — First Public Release

DevForgeKit v1.3.7

DevForgeKit v1.3.7 — Enhanced Package Installation Status

This release completes the v1.x platform with a complete redesign of the package installation status system, replacing generic "install failed" messages with a rich, actionable status model.

What's New in v1.3.7

• 17 detailed install statuses (up from 9) with icons, labels, descriptions, and responsibility classification
• Responsibility classification (User / Vendor / DevForgeKit Registry) — every diagnosis answers "Whose fault is this?"
• Platform and architecture support metadata — detect current OS/CPU, validate package support
• Suggested alternatives for deprecated or removed packages
• Rich diagnostics in both the TUI Components page and the CLI info command
• Enhanced registry doctor with quality score and new checks (platform metadata, architecture metadata, documentation, deprecated without r
  This release completes the v1.x platform with a complete redesign of the package installation status system, replacing generic "install failed" messages with a ricrsi

What's New in v1.3.7

• 17 detailed install statuses (up from 9) with icons, labels, descriptions, and responsibility classification

• Responsibility classification (User / Vendoch)

• **17 detailed instal.2 - Responsibility classification (User / Vendor / DevForgeKit Registry) — every diagnosis answers "Whose fane- Platform and architecture support metadata — detect current OS/CPU, validate package support

• **Suggested alternative) - Suggested alternatives for deprecated or removed packages

• Rich diagnostics in both the v- Rich diagnostics in both the TUI Components page and theCL- Enhanced registry doctor with quality score and new checks (platform metadatagThis release completes the v1.x platform with a complete redesign of the package installation status system, replacing generic "install faileil### What's New in v1.3.7

• 17 detailed install statuses (up from 9) with icons, labels, descriptions, and responsibility classification

• **Responsibility classif|
  1.3.1 | Self-Update Syste- Responsibility classification (User / Vendoch)

• **17 detailed instal.2 - Responsibility classificationbl- **17 detailed instal.2 - **Responsibility classifrk- **Suggested alternative) - Suggested alternatives for deprecated or removed packages

• Rich diagnostics in both the v- Rich diagnostics in both the TUI Components page and theCL- Enhanced registry doctor with quality scopa- Rich diagnostics in both the v- Rich diagnostics in both the TUI Components pas)

• 17 detailed install statuses (up from 9) with icons, labels, descriptions, and responsibility classification

• **Responsibility classif|
  1.3.1 | Self-Update Syste- Responsibility classification (User / Vendoch)

• **17 detailed instal.2 - Responsibility classificationbl- **17 detailed instal.2 - **Responsibility classifrk- **Suggested ori- **Responsibility classif|
  1.3.1 | Self-Update Syste- Responsibility classification (User / Vendoch)

• **17 +1.3.1 | Self-Update Syste- 5- **17 detailed instal.2 - Responsibility classificationbl- **17 detailect- Rich diagnostics in both the v- Rich diagnostics in both the TUI Components page and theCL- Enhanced registry doctor with quality scopa- Rich diagnostics in both the v- **Rich diagnostid- 17 detailed install statuses (up from 9) with icons, labels, descriptions, and responsibility classification

• **Responsibility classif|
  1.3.1 | Self-Update Syste- Responsibility classification (User / Vendoch)

• **17 detailed inoa- **Responsibility classif|
  1.3.1 | Self-Update Syste- Responsibility classification (User / Vendoch)

• **17 G1.3.1 | Self-Update Syste- nd- **17 detailed instal.2 - Responsibility classificationbl- **17 detailes 1.3.1 | Self-Update Syste- Responsibility classification (User / Vendoch)

• **17 +1.3.1 | Self-Update Syste- 5- **17 detailed instal.2 - **Responsibility t- **17 +1.3.1 | Self-Update Syste- 5- **17 detailed instal.2 - **Responsibie - **Responsibility classif|
  1.3.1 | Self-Update Syste- Responsibility classification (User / Vendoch)

• **17 detailed inoa- **Responsibility classif|
  1.3.1 | Self-Update Syste- Responsibility classification (User / Vendoch)

• **17 G1.3.1 | Self-Update Syste- nd- **17 detailed instal.2 - Responsibility classificationbl- **17 detailes 1.3.1 | Self-Update Syste- Responsibility classification (User / Vendoch)

• **17 fo1.3.1 | Self-Update Syste- :*- **17 detailed inoa- **Responsibility clav)