voidforge-build 23.11.2 → 23.11.3

package/dist/CHANGELOG.md

@@ -6,6 +6,48 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ---
 
+## [23.11.3] - 2026-05-12
+
+### Issue #331 destructive-bug fix + HIGH CVE patch + dep contract pin + CI hardening
+
+Three-phase pipeline output: `/architect --plan` → `/debrief --inbox` → `/campaign`. 12 fix missions + 2 ADRs + 1 LEARNINGS entry + 2 mechanical guards landed in one release.
+
+### Security
+
+- **HIGH CVE patch** — `npm audit fix --omit=dev` resolved three vulnerabilities (2 HIGH, 1 MODERATE) in `fast-xml-parser` (≤5.6.0) and `fast-xml-builder` (≤1.1.6), pulled transitively via `@aws-sdk/xml-builder` through `@aws-sdk/client-ec2`, `client-rds`, `client-s3`, `client-elasticache`, `client-sts`. No SDK major bump required; lockfile-only change. AWS provisioner API surface unaffected.
+
+### Fixed
+
+- **Issue #331 — `npx voidforge-build update` silently overwrote `~/CLAUDE.md` and 44 other methodology files in `$HOME`** when run outside a VoidForge project. Root cause: `findProjectRoot()` in `packages/voidforge/wizard/lib/marker.ts` had no `$HOME` boundary, and its `existsSync()` check could not distinguish the `.voidforge` file marker from the `~/.voidforge/` state directory (ADR-060). Fix: added `statSync().isFile()` guard and `$HOME` walk break. The function now returns null/undefined when no project root is found, never `$HOME` or `/`. Codified as ADR-063 and FORGE_KEEPER Rule #11. New integration test `no-home-writes.integration.test.ts` mechanically enforces "no escape writes" by spawning the built CLI against a temp HOME and asserting zero methodology files leak out of a project boundary.
+- **Issue #260 — new users tried slash commands at their shell prompt and saw "command not found"** because no doc told them to launch Claude Code first. HOLOCRON Quick Start now opens with "Before any slash command: launch Claude Code" instructions before the install snippets.
+- **Issue #333 (partial — npm-prefix only)** — `npm install -g voidforge-build` failing with `EACCES` on `/usr/local` is a fragile-globals problem, not a VoidForge bug, but worth a documented workaround. HOLOCRON now shows the `npm config set prefix ~/.npm-global` recipe.
+
+### Changed
+
+- **Dep contract pin (ADR-062)** — `voidforge-build`'s `voidforge-build-methodology` dependency range changed from `"*"` to `"^23.11.3"`. The wildcard was live on the registry in v23.11.1 and v23.11.2, allowing any future breaking methodology major to silently pair with old CLI installs. Enforced mechanically going forward by a new `check-methodology-pin.sh` script wired as `voidforge-build`'s `prepublishOnly` — `npm publish` fails closed if the methodology range is `*`, `x`, `latest`, empty, or a `>`/`>=` open-ended range.
+- **`packages/methodology/package.json`** — added `"engines": { "node": ">=20.11.0 <25.0.0" }` matching the CLI's existing constraint. Advisory, not enforced, but closes the silent-divergence gap.
+- **`.github/workflows/publish.yml` hardening** (three coordinated changes):
+  - Post-publish `npm view` verification step appended to both publish jobs. 6 attempts × 10s = 60-second propagation window. Hard-fails the job on still-mismatch. Closes the silent "publish succeeded at API but registry never serves" failure mode (v23.11.2 deploy synthesis, Dors + Crusher both flagged it).
+  - `recover-partial` job runs `if: always() && (publish-voidforge.result == 'failure') != (publish-methodology.result == 'failure')` (XOR). On half-publish, it `npm deprecate`s the orphan with a clear "do not install" message and exits 1 to fail the workflow red. `npm unpublish` is intentionally not used (72-hour lockout breaks immutability).
+  - `publish-voidforge` now declares `needs: [test, publish-methodology]` (was `needs: test` only). Methodology publishes first; voidforge-build resolves its pinned `^23.11.3` methodology dep against a registry that already has it. Closes Bel Riose's parallel-publish race window.
+- **`packages/voidforge/scripts/copy-assets.sh`** — `CLAUDE.md` copy now uses the same `sed` strip as `packages/methodology/scripts/prepack.sh` (ADR-058 `<!-- REMOVE-FOR-NPM-PUBLISH ... -->` markers). Closes the inconsistency Rhodes flagged in v23.11.2 deploy synthesis where `voidforge-build`'s bundled scaffold shipped the unstripped template Project block.
+- **`docs/methods/RELEASE_MANAGER.md` Verification Checklist** — two new lines: "ROADMAP.md Current line matches VERSION.md" and "monorepo CLI's methodology dep range is `^<current-version>`, never `*` (ADR-062)". Mechanical drift like the 24-version ROADMAP gap should fail the checklist, not slip silently.
+- **`ROADMAP.md`** — Current pointer bumped from `v23.8.11 (2026-04-12)` to `v23.11.3 (2026-05-12)`. Status block rewritten to reflect the v23.11 series shipped.
+
+### Added
+
+- **ADR-062 — Always pin methodology dep to current version.** Mandates that every `voidforge-build` release bumps the `voidforge-build-methodology` dep range to `^<current-version>`. Enforced via `check-methodology-pin.sh` + prepublishOnly + a CI lint that can be added later.
+- **ADR-063 — Never write to `$HOME`.** Any code path that resolves a project root via directory-walk MUST enforce a `$HOME` boundary. Enforced via `no-home-writes.integration.test.ts` running the CLI against a temp HOME.
+- **`docs/LEARNINGS.md` entry** — generalizable lesson: any directory-tree walker must define a sentinel boundary (typically `$HOME` or `/`) or risk destructive past-root writes.
+- **FORGE_KEEPER Rule #11** — "NEVER write to `$HOME` itself" (companion to Rule #10's "NEVER write to `~/.claude/`"). Codifies ADR-063 for Bombadil's sync logic.
+- **Mechanical guards** — `check-methodology-pin.sh` (pin lint) and `no-home-writes.integration.test.ts` (boundary test). Per Frieren's planning recommendation: disciplines with silent-failure modes get mechanical enforcement; advisory disciplines (ROADMAP sync, partial-publish recovery procedure) stay documented.
+
+### Pipeline
+
+This release is the first multi-phase pipeline executed end-to-end in a single session: `/architect --plan` (17 agents) → `/debrief --inbox` triage (Bashir, 13 open issues categorized) → `/campaign --plan` (16 planning agents merged Phase 1 + Phase 2 into 12 missions across 4 waves) → `/campaign` execution (18 specialist agents). Honest dissents from Faramir ("cut to 6") and Erwin ("split to 2 in v23.11.3, rest in v23.11.4") were surfaced; user selected the full scope. The destructive bug fix (#331) was filed one day before this release and was the highest-priority item — Picard's earlier "tightest patch" framing was correctly overridden by Bashir's triage.
+
+---
+
 ## [23.11.2] - 2026-05-12
 
 ### `voidforge init` mode prompt + methodology surfer-gate distribution

package/dist/CLAUDE.md

@@ -1,13 +1,5 @@
 # CLAUDE.md
 
-<!-- REMOVE-FOR-NPM-PUBLISH: Template section for monorepo root only. Stripped by prepack.sh per ADR-058. Published methodology consumers fill this via `npx voidforge-build init`. -->
-## Project
-
-- **Name:** [PROJECT_NAME]
-- **One-liner:** [ONE_LINE_DESCRIPTION]
-- **Domain:** [DOMAIN]
-- **Repo:** [REPO_URL]
-<!-- END-REMOVE-FOR-NPM-PUBLISH -->
 
 ## Personality
 

package/dist/HOLOCRON.md

@@ -22,6 +22,23 @@
 
 ## 1. Ignition
 
+### Before any slash command: launch Claude Code
+
+VoidForge's slash commands (`/build`, `/campaign`, `/qa`, etc.) run **inside Claude Code**, not in your terminal. If you've never used Claude Code before:
+
+1. Install: `npm install -g @anthropic-ai/claude-code` (or follow [Claude Code's install guide](https://claude.com/claude-code))
+2. Open a terminal in your project directory and run `claude`
+3. Once Claude Code is running, type a slash command at its prompt — e.g., `/campaign`
+
+The rest of this guide assumes you're already inside Claude Code. (Field report #260 — new users repeatedly tried slash commands at their shell prompt and saw "command not found.")
+
+**If `npm install -g` fails with EACCES on `/usr/local`** (the global npm prefix), use a user-space prefix instead of `sudo`:
+```bash
+npm config set prefix ~/.npm-global
+export PATH="$HOME/.npm-global/bin:$PATH"   # add to ~/.zshrc or ~/.bashrc
+```
+Then retry the install. (Field report #333 — sudo-installing globals is fragile and varies by Node distribution.)
+
 ### What VoidForge Is
 
 VoidForge is a **methodology framework** for building full-stack applications with Claude Code. It's not a code template — it's a *process* template. Drop in a Product Requirements Document, and a named team of AI agents across 9 fictional universes builds your application through a 13-phase protocol.

package/dist/VERSION.md

@@ -1,6 +1,6 @@
 # Version
 
-**Current:** 23.11.2
+**Current:** 23.11.3
 
 ## Versioning Scheme
 
@@ -14,6 +14,7 @@ This project uses [Semantic Versioning](https://semver.org/):
 
 | Version | Date | Summary |
 |---------|------|---------|
+| 23.11.3 | 2026-05-12 | Three-phase pipeline (/architect → /debrief --inbox → /campaign) shipped 12 fixes + 2 ADRs + 1 LEARNINGS entry + 2 mechanical guards. **Issue #331** destructive-bug fix: `findProjectRoot()` now enforces `$HOME` boundary + `statSync().isFile()` guard, no more silent overwrite of `~/CLAUDE.md` on `npx voidforge-build update`. **HIGH CVE** fast-xml-parser/builder via `@aws-sdk/*` patched via `npm audit fix`. **Dep contract** pinned: `voidforge-build → voidforge-build-methodology` from `"*"` to `"^23.11.3"` (ADR-062), enforced mechanically by `check-methodology-pin.sh` prepublishOnly script. **engines.node** added to methodology package.json. **publish.yml hardening**: post-publish `npm view` verification step (both jobs, 6×10s retry), `recover-partial` job with `npm deprecate` on XOR-failure, `needs: publish-methodology` ordering on publish-voidforge. **copy-assets.sh** ADR-058 template strip applied (parity with methodology prepack). **Docs**: HOLOCRON Quick Start "launch Claude Code first" preamble + npm-prefix workaround (#260, #333p), FORGE_KEEPER Rule #11 "never write to $HOME" (ADR-063), RELEASE_MANAGER ROADMAP-sync checklist line, ROADMAP.md pointer v23.8.11 → v23.11.3 (24-version drift closed). Marker integration test `no-home-writes.integration.test.ts` mechanically enforces ADR-063. 1390 tests pass. |
 | 23.11.2 | 2026-05-12 | `voidforge init` now prompts browser-vs-CLI when no mode flag is passed (TTY only) and `--browser` was added for explicit opt-in. Headless init prompts for name/dir/oneliner/domain/repo when `--name` is omitted in a TTY. Non-TTY no-flag now errors cleanly instead of silently launching a wizard server. Separately: `packages/methodology/scripts/surfer-gate/` (8 files) now ships in the npm methodology package — closes ADR-051 distribution gap (#317). 9 pattern-table rows + existence-guarded orchestrator-contract bash propagated into the methodology CLAUDE.md. |
 | 23.11.1 | 2026-05-10 | `/git` release-discipline patch — Step 4.5 (auto-tag, default-on) and Step 7 (`--npm` opt-in publish). Closes the silent-release gap that stranded v23.10.0 and v23.11.0 between GitHub and npm. Tag-push triggers the existing `publish.yml` workflow; `--npm` is a same-session fallback. Documents the `latest` dist-tag race when multiple tags are pushed simultaneously. RELEASE_MANAGER.md mirrored. |
 | 23.11.0 | 2026-05-10 | Field Report Triage — 18 reports closed (#313-#320, #322-#330). Two combined batches across multi-tenant retrofit campaigns (#313-#320) and autonomous-mode + AI-execution campaigns (#322-#330). 9 new patterns: adr-verification-gate.md, audit-log.ts, multi-tenant-{pool-bypass,property-test}.ts, rls-test-fixture.py, structural-sql-sentinel.py, refactor-extraction.md, ai-prompt-safety.ts, llm-state-dedup.ts. ai-eval.ts extended with Claude-prompt-eval template. middleware.ts extended with hot-path logging gate. 18 method-doc sections across CAMPAIGN, SYSTEMS_ARCHITECT, SECURITY_AUDITOR, QA_ENGINEER, SUB_AGENTS, BACKEND_ENGINEER, RELEASE_MANAGER, GAUNTLET, AI_INTELLIGENCE, DEVOPS_ENGINEER, FORGE_KEEPER, TESTING, TIME_VAULT. Surfer Gate now ships via npm methodology package + wizard project-init (closes ADR-051 distribution gap #317). Operational learnings added to Picard, Sisko, Coulson, Bashir, Loki, Irulan, Silver Surfer. |

package/dist/docs/methods/FORGE_KEEPER.md

@@ -47,6 +47,7 @@ Keep your VoidForge installation current without breaking your project. Every up
 8. **Keep the mood light.** Bombadil sings. Updates are good news, not chores.
 9. **Batch sync when multiple versions behind.** Compare directly to the latest upstream version — don't step through each intermediate version. Sync to the latest in one pass and batch all content handoffs together. (Field report #35)
 10. **NEVER write to `~/.claude/`.** All methodology files go to the PROJECT root (where `.voidforge` or `.git` exists). Writing to `~/.claude/commands/` or `~/.claude/agents/` creates user-level duplicates that appear alongside project-level commands in Claude Code. Before any sync, check if `~/.claude/commands/` or `~/.claude/agents/` contain VoidForge files — if so, remove them automatically and warn the user.
+11. **NEVER write to `$HOME` itself.** Any code path that resolves a "project root" via directory-walk MUST enforce a `$HOME` boundary — the walk stops at `$HOME` and treats it as "no project found," not as the root. The boundary is mechanical (`statSync().isFile()` guard on the marker file + `$HOME` walk break), not advisory. A walk that falls through to `$HOME` and starts writing methodology files there destructively overwrites the user's personal config (e.g. `~/CLAUDE.md`). Enforced by the `no-home-writes.integration.test.ts` integration test. (ADR-063, Issue #331 — the `npx voidforge-build update` $HOME write incident, v23.11.3.)
 
 ## Shared Methodology Files
 

package/dist/docs/methods/RELEASE_MANAGER.md

@@ -120,6 +120,8 @@ After every commit, Barton verifies:
 - [ ] `git status` shows clean working tree
 - [ ] No untracked files that should have been included
 - [ ] If `--npm` was used: every published package returns the new version from `npm view <name> version`
+- [ ] `ROADMAP.md` "Current:" line matches `VERSION.md` (added v23.11.3 — field-report #309 Fix 4 and v23.11.2 deploy synthesis both flagged drift; ROADMAP had been pinned ~24 versions back before this checklist line existed)
+- [ ] For monorepo CLI/methodology pairs: the CLI's `voidforge-build-methodology` dep range is `^<current-version>`, never `"*"` (ADR-062 — pin tightening shipped in v23.11.3 to close the silent-cross-major drift)
 
 ## CLAUDE.md Command Table Integrity Check
 

package/dist/wizard/lib/marker.d.ts

@@ -18,6 +18,13 @@ export declare function createMarker(version: string, tier?: VoidForgeMarker['ti
 /**
  * Walk up from `startDir` to find the nearest `.voidforge` marker.
  * Returns the directory containing the marker, or null if none found.
+ *
+ * Safety guards (issue #331):
+ *   Option A — marker MUST be a regular file. A `.voidforge` directory
+ *     (e.g. someone's stray folder, or an extension's data dir) is ignored.
+ *   Option B — the walk stops at the user's home directory. We never treat
+ *     `$HOME` or any ancestor as a project root, so `update`/`init` cannot
+ *     overwrite files in `~/` when invoked outside a project.
  */
 export declare function findProjectRoot(startDir?: string): string | null;
 /**

package/dist/wizard/lib/marker.js

@@ -5,8 +5,8 @@
  * The CLI walks up from cwd to find it, determining the project root.
  */
 import { readFile, writeFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { existsSync, statSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
 // ── Constants ────────────────────────────────────────────
@@ -44,12 +44,32 @@ export function createMarker(version, tier = 'full', extensions = []) {
 /**
  * Walk up from `startDir` to find the nearest `.voidforge` marker.
  * Returns the directory containing the marker, or null if none found.
+ *
+ * Safety guards (issue #331):
+ *   Option A — marker MUST be a regular file. A `.voidforge` directory
+ *     (e.g. someone's stray folder, or an extension's data dir) is ignored.
+ *   Option B — the walk stops at the user's home directory. We never treat
+ *     `$HOME` or any ancestor as a project root, so `update`/`init` cannot
+ *     overwrite files in `~/` when invoked outside a project.
  */
 export function findProjectRoot(startDir = process.cwd()) {
-    let current = startDir;
+    const home = resolve(process.env['HOME'] ?? process.env['USERPROFILE'] ?? homedir());
+    let current = resolve(startDir);
     while (true) {
-        if (existsSync(join(current, MARKER_FILE))) {
-            return current;
+        // Option B: never accept $HOME (or anything at/above it) as a project root.
+        if (current === home)
+            return null;
+        const markerPath = join(current, MARKER_FILE);
+        if (existsSync(markerPath)) {
+            // Option A: marker must be a regular file, not a directory.
+            try {
+                if (statSync(markerPath).isFile()) {
+                    return current;
+                }
+            }
+            catch {
+                // stat raced with deletion or permission error — treat as no marker.
+            }
         }
         const parent = dirname(current);
         if (parent === current)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voidforge-build",
-  "version": "23.11.2",
+  "version": "23.11.3",
   "description": "From nothing, everything. A methodology framework for building with Claude Code.",
   "type": "module",
   "engines": {
@@ -14,6 +14,7 @@
     "deploy": "npx tsx scripts/voidforge.ts deploy",
     "build": "tsc && bash scripts/copy-assets.sh",
     "prepack": "bash scripts/prepack-patterns.sh && npm run build",
+    "prepublishOnly": "bash scripts/check-methodology-pin.sh",
     "typecheck": "npx tsc --noEmit",
     "test": "vitest run --pool forks",
     "test:watch": "vitest --pool forks",
@@ -44,7 +45,7 @@
     "@aws-sdk/client-rds": "^3.700.0",
     "@aws-sdk/client-s3": "^3.700.0",
     "@aws-sdk/client-sts": "^3.700.0",
-    "voidforge-build-methodology": "*",
+    "voidforge-build-methodology": "^23.11.3",
     "node-pty": "^1.2.0-beta.12",
     "ws": "^8.19.0"
   },