voidforge-build 23.11.1 → 23.11.3

package/dist/CHANGELOG.md

@@ -6,6 +6,73 @@ 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
+
+Two threads of polish: the CLI now asks before launching, and the Silver Surfer gate finally ships in the methodology npm package.
+
+### Added
+
+- **`voidforge init` mode prompt.** With no flag, `init` now asks "Browser wizard or CLI (headless)?" instead of silently launching the browser server. Prompt appears only when stdin is a TTY.
+- **`--browser` flag on `voidforge init`.** Explicit opt-in to the wizard UI — skips the prompt for users (or scripts) that want the prior default behavior.
+- **Interactive headless init.** `voidforge init --headless` now prompts for project name (required), directory (defaulted to `~/Projects/<slug>`), and optional oneliner/domain/repo when `--name` is omitted in a TTY. Fully non-interactive when all flags are passed.
+- **`packages/methodology/scripts/surfer-gate/`** (8 files) — the Silver Surfer PreToolUse hook scripts (`check.sh`, `record-roster.sh`, `bypass.sh`, `_paths.sh`, `validate.sh`, `test.sh`, `README.md`, `settings-snippet.json`) now ship via the `voidforge-build-methodology` npm package, closing the ADR-051 distribution gap (#317). Previously the scripts lived only at the repo root and never reached downstream projects via `npx voidforge-build update`.
+- **9 pattern-table rows** in `packages/methodology/CLAUDE.md` — propagates the v23.11.0 pattern additions (adr-verification-gate, multi-tenant-property-test, multi-tenant-pool-bypass, rls-test-fixture, structural-sql-sentinel, audit-log, refactor-extraction, ai-prompt-safety, llm-state-dedup) into the methodology package copy so they reach downstream projects.
+
+### Changed
+
+- **Non-TTY `voidforge init` without a flag** now exits with a clear error directing the user to `--browser` or `--headless`. Previously it silently launched a wizard server into a context where no browser would ever open — a latent bug.
+- **Surfer Gate orchestrator-contract bash commands** in `packages/methodology/CLAUDE.md` are now wrapped in `[ -x ... ] && ... || true` existence guards with documented fallback ("if the script does not exist, your project predates v23.10.0; pull the gate or re-run `npx voidforge-build init`"). Lets the methodology cleanly cover both pre-#317 and post-#317 projects.
+
+### Why this exists
+
+The init server-launch was the loudest "this CLI doesn't ask before doing things" surface in onboarding — first-run users got a server URL with no opportunity to choose CLI mode. Two flags (`--browser`, `--headless`) now span the choice; the bare command asks. Separately, the surfer-gate scripts had been documented as shipping in the methodology package since v23.11.0 changelog #317, but the scripts themselves were never copied into `packages/methodology/`. This release actually ships them.
+
+---
+
 ## [23.11.1] - 2026-05-10
 
 ### `/git` release-discipline patch — close the silent-release gap

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.1
+**Current:** 23.11.3
 
 ## Versioning Scheme
 
@@ -14,6 +14,8 @@ 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. |
 | 23.10.0 | 2026-04-20 | Field Report Triage — 6 reports closed (#303-#308). 33 approved fixes: SPEC_HANDOFF.md (new method doc), deploy-preflight.ts + post-deploy-probe.sh (new patterns), LEARNINGS LRN-5..10, Deploy Surface Boundary + Deployment Hygiene (field report #305 remediation), Step 2.5 pre-deploy secret scan + Step 4.5 post-deploy probe, TECH_DEBT SLA, npm-name pre-flight, ADR-050 Rename Verification Checklist, Silver Surfer HARD CONSTRAINT + 4 agent operational learnings. |

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/scripts/voidforge.d.ts

@@ -3,8 +3,10 @@
  * VoidForge CLI — v21.0 The Extraction
  *
  * npx voidforge                       Launch wizard (browser UI at :3141)
- * npx voidforge init                  Create new project (Gandalf flow)
- * npx voidforge init --headless       Create project without browser
+ * npx voidforge init                  Create new project — prompts: browser or CLI
+ * npx voidforge init --browser        Skip the prompt, go straight to the browser wizard
+ * npx voidforge init --headless       Create project without browser (CLI prompts for name/dir)
+ * npx voidforge init --headless --name "X"   Fully non-interactive CLI init
  * npx voidforge init --core           Minimal methodology (no Holocron, no patterns)
  * npx voidforge update                Update project methodology (Bombadil)
  * npx voidforge update --self         Update the wizard itself

package/dist/scripts/voidforge.js

@@ -3,8 +3,10 @@
  * VoidForge CLI — v21.0 The Extraction
  *
  * npx voidforge                       Launch wizard (browser UI at :3141)
- * npx voidforge init                  Create new project (Gandalf flow)
- * npx voidforge init --headless       Create project without browser
+ * npx voidforge init                  Create new project — prompts: browser or CLI
+ * npx voidforge init --browser        Skip the prompt, go straight to the browser wizard
+ * npx voidforge init --headless       Create project without browser (CLI prompts for name/dir)
+ * npx voidforge init --headless --name "X"   Fully non-interactive CLI init
  * npx voidforge init --core           Minimal methodology (no Holocron, no patterns)
  * npx voidforge update                Update project methodology (Bombadil)
  * npx voidforge update --self         Update the wizard itself
@@ -167,6 +169,41 @@ async function launchWizard(mode = 'init') {
     if (!isRemote && !isLan)
         await openBrowser(url);
 }
+function slugifyName(name) {
+    return name.replace(/[^a-zA-Z0-9-_ ]/g, '').replace(/\s+/g, '-').toLowerCase();
+}
+function defaultProjectDir(name) {
+    return join(process.env['HOME'] ?? process.env['USERPROFILE'] ?? '.', 'Projects', slugifyName(name));
+}
+async function prompt(question) {
+    const { createInterface } = await import('node:readline');
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((res) => {
+        rl.question(question, (answer) => { rl.close(); res(answer.trim()); });
+    });
+}
+/**
+ * Asks the user to pick browser vs headless mode for `voidforge init`.
+ * Requires a TTY — caller must guard with process.stdin.isTTY.
+ */
+async function promptInitMode() {
+    console.log('');
+    console.log('  VoidForge — init');
+    console.log('');
+    console.log('  How would you like to set up this project?');
+    console.log('    1) Browser wizard (Gandalf) — interactive, guided UI');
+    console.log('    2) CLI (headless)            — prompts here in the terminal');
+    console.log('');
+    // Loop until we get a valid answer.
+    for (;;) {
+        const answer = (await prompt('  Choice [1]: ')).toLowerCase();
+        if (answer === '' || answer === '1' || answer === 'b' || answer === 'browser')
+            return 'browser';
+        if (answer === '2' || answer === 'c' || answer === 'cli' || answer === 'h' || answer === 'headless')
+            return 'headless';
+        console.log('  Please enter 1 (browser) or 2 (CLI).');
+    }
+}
 async function cmdInitHeadless() {
     const nameFlag = args.find((a, i) => args[i - 1] === '--name');
     const dirFlag = args.find((a, i) => args[i - 1] === '--dir');
@@ -174,25 +211,61 @@ async function cmdInitHeadless() {
     const domainFlag = args.find((a, i) => args[i - 1] === '--domain');
     const repoFlag = args.find((a, i) => args[i - 1] === '--repo');
     const isCore = args.includes('--core');
-    if (!nameFlag) {
-        console.error('Error: --name is required for headless init.');
-        console.error('Usage: npx voidforge init --headless --name "My Project" [--dir path] [--oneliner "..."]');
-        process.exit(1);
+    let name = nameFlag;
+    let directory = dirFlag;
+    let oneliner = onelinerFlag;
+    let domain = domainFlag;
+    let repoUrl = repoFlag;
+    // If --name is missing, prompt interactively (TTY only).
+    if (!name) {
+        if (!process.stdin.isTTY) {
+            console.error('Error: --name is required for headless init in non-interactive contexts.');
+            console.error('Usage: npx voidforge init --headless --name "My Project" [--dir path] [--oneliner "..."]');
+            process.exit(1);
+        }
+        console.log('');
+        console.log('  VoidForge — Headless Init');
+        console.log('  Press Enter to accept defaults shown in [brackets]. Optional fields can be left blank.');
+        console.log('');
+        while (!name) {
+            const answer = await prompt('  Project name: ');
+            if (answer)
+                name = answer;
+            else
+                console.log('  Project name is required.');
+        }
+        const defaultDir = defaultProjectDir(name);
+        if (!directory) {
+            const answer = await prompt(`  Directory [${defaultDir}]: `);
+            directory = answer || defaultDir;
+        }
+        if (!oneliner) {
+            const answer = await prompt('  One-line description (optional): ');
+            oneliner = answer || undefined;
+        }
+        if (!domain) {
+            const answer = await prompt('  Domain (optional): ');
+            domain = answer || undefined;
+        }
+        if (!repoUrl) {
+            const answer = await prompt('  Repo URL (optional): ');
+            repoUrl = answer || undefined;
+        }
     }
-    const defaultDir = join(process.env['HOME'] ?? process.env['USERPROFILE'] ?? '.', 'Projects', nameFlag.replace(/[^a-zA-Z0-9-_ ]/g, '').replace(/\s+/g, '-').toLowerCase());
-    const directory = dirFlag ?? defaultDir;
+    if (!directory)
+        directory = defaultProjectDir(name);
     const { createProject } = await import('../wizard/lib/project-init.js');
     const result = await createProject({
-        name: nameFlag,
+        name,
         directory,
-        oneliner: onelinerFlag,
-        domain: domainFlag,
-        repoUrl: repoFlag,
+        oneliner,
+        domain,
+        repoUrl,
         core: isCore,
     });
     console.log('');
     console.log(`  VoidForge — Project Created`);
-    console.log(`  Name:      ${nameFlag}`);
+    console.log(`  Name:      ${name}`);
     console.log(`  Directory: ${result.projectDir}`);
     console.log(`  Files:     ${result.filesCreated} methodology files`);
     console.log(`  Marker:    ${result.markerId}`);
@@ -293,7 +366,8 @@ function showHelp() {
     console.log('  --help, -h         Show this help');
     console.log('  --remote           Launch in remote mode (0.0.0.0 + auth)');
     console.log('  --lan              Launch in LAN mode');
-    console.log('  --headless         CLI-only (no browser)');
+    console.log('  --browser          init: skip the mode prompt and launch the browser wizard');
+    console.log('  --headless         init: CLI-only flow (prompts for name/dir if not passed)');
     console.log('  --self             Deploy VoidForge itself');
     console.log('  --env-only         Write vault credentials to .env');
     console.log('');
@@ -536,14 +610,29 @@ async function main() {
                 console.log('  To rollback: restore from the backup directory.\n');
                 break;
             }
-            case 'init':
-                if (args.includes('--headless')) {
+            case 'init': {
+                const wantsHeadless = args.includes('--headless');
+                const wantsBrowser = args.includes('--browser');
+                if (wantsHeadless) {
                     await cmdInitHeadless();
                 }
-                else {
+                else if (wantsBrowser) {
                     await launchWizard('init');
                 }
+                else if (process.stdin.isTTY) {
+                    const mode = await promptInitMode();
+                    if (mode === 'headless')
+                        await cmdInitHeadless();
+                    else
+                        await launchWizard('init');
+                }
+                else {
+                    console.error('Error: `voidforge init` was run in a non-interactive context without a mode flag.');
+                    console.error('Pass --browser to launch the wizard UI, or --headless [--name "..."] for CLI init.');
+                    process.exit(1);
+                }
                 break;
+            }
             case 'heartbeat': {
                 const subCmd = args[1]; // start | stop | status
                 if (subCmd !== 'start') {

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.1",
+  "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"
   },