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.