voidforge-build 23.11.2 → 23.11.4

package/dist/CHANGELOG.md

@@ -6,6 +6,77 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ---
 
+## [23.11.4] - 2026-05-12
+
+### Wong promotion cluster + #260 closeout
+
+After v23.11.3 shipped, a fresh `/debrief --inbox` re-triage on all 9 open field reports produced 3 promotion-ready clusters (each backed by 3+ data points across different reports / different projects / different operators) plus the deferred remainder of #260.
+
+### Added
+
+- **`docs/patterns/autonomous-ops-triage-policy.md`** (pattern #48) — codifies the 4-bucket model (self-resolving / runbook-safe / operator-approval-required / hard-never) for ops-flavored projects (infrastructure repos, monitoring daemons, homelab automation). Two operators independently reinvented this exact model across three projects (#337 F3, #336 F7, #334 F5). Pattern includes SessionStart hook visibility rule (the hook output is context-only — assistant must `echo` it back to the operator to confirm the policy is live), JSON Lines log format, decision tree, and adoption checklist.
+- **CLAUDE.md Code Patterns table** — new row for `autonomous-ops-triage-policy.md` in both root and `packages/methodology/CLAUDE.md`.
+
+### Changed
+
+- **`docs/methods/BUILD_PROTOCOL.md` Principles #11 — Derived counts discipline.** Any user-facing numeric claim ("141+ pages", "Gated pages: 19", "6 missions completed", "1390 tests") must be derived from source truth at build time OR explicitly marked with `<!-- last-verified: YYYY-MM-DD -->` and tracked in the RELEASE_MANAGER Verification Checklist. No unverified scalar claims ship. Three independent projects (#336 F6, #334 F6, #332 hidden #5) drifted the same class — this is the scalar equivalent of the No Stubs doctrine.
+- **`docs/methods/CAMPAIGN.md` Planning Mode — Scope-adversary check for bug classes.** New Step 4 in `--plan` mode: when a mission documents a specific bug class, dispatch a verification agent (Riker, Feyd-Rautha, or Spock) with the explicit prompt "list all other surfaces this class touches that were NOT in the mission scope." voidforge-marketing-site (#332) deployed with a known bug class on two surfaces because the plan was scoped to one. #338 #2 independently demonstrated the same need.
+- **`docs/methods/PRODUCT_DESIGN_FRONTEND.md` Operating Rule #12 — Tutorial-context checklist for slash commands.** Standalone `/<command>` references in tutorial content must establish "inside Claude Code" context (preceding `claude` block, callout box, or contextual prose). First-touch user content with missing launch context is a Critical UX defect. Galadriel's Step 1.5 Usability Review now explicitly flags this. (#260 remainder.)
+- **`docs/methods/QA_ENGINEER.md` Operating Rule #13 — Tutorial smoke test for slash commands.** Batman's QA pass on tutorial/onboarding docs runs a grep-based check: every `/<command>` mention must have launch context within 5 lines or a callout block on the same page. Sister-rule to PRODUCT_DESIGN_FRONTEND.md #12. (#260 remainder.)
+- **`packages/voidforge/package.json`** methodology dep range `^23.11.3` → `^23.11.4` per ADR-062 discipline (always pin methodology dep to current version on every release).
+
+### Closes
+
+- **#260** — HOLOCRON preamble shipped in v23.11.3; PRODUCT_DESIGN_FRONTEND.md + QA_ENGINEER.md tutorial checklist proposals now ship in v23.11.4. Fully addressed.
+
+### Pipeline
+
+This release is the first Wong promotion-cluster pass executed end-to-end in one session: `/debrief --inbox` triaged all 9 field reports, identified the 3 ready-now clusters, and promoted them directly into method docs and pattern library. 11 field reports remain open as v23.12 methodology campaign scope (7 priority clusters identified by Bashir: security & declaration discipline, database migration patterns, PRD/release sync, architect protocol, build/CI gates, Plex pattern bundle, container/infra patterns).
+
+---
+
+## [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
 
@@ -128,6 +120,7 @@ Reference implementations in `/docs/patterns/`. Match these shapes when writing.
 - `refactor-extraction.md` — 8-commit per-entity large-refactor template with IDOR matrix discipline
 - `ai-prompt-safety.ts` — Type A (instructions, statistical) vs Type B (constraints, enforced); AUTHORITY-as-text caveat; defense-in-depth stack
 - `llm-state-dedup.ts` — LLM ids are display labels, not keys; content-hash dedup; lifecycle-state snapshot completeness
+- `autonomous-ops-triage-policy.md` — 4-bucket model (self-resolving / runbook-safe / operator-approval / hard-never) + SessionStart hook visibility rule for ops-flavored projects
 
 ## Slash Commands
 

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.4
 
 ## Versioning Scheme
 
@@ -14,6 +14,8 @@ This project uses [Semantic Versioning](https://semver.org/):
 
 | Version | Date | Summary |
 |---------|------|---------|
+| 23.11.4 | 2026-05-12 | Wong promotion cluster + #260 closeout. /debrief --inbox re-triage of all 9 open field-report issues produced 3 ready-now promotion clusters (3+ data points across different reports each). BUILD_PROTOCOL.md Principle #11 "Derived counts discipline" (from #336 F6, #334 F6, #332 hidden #5 — three projects independently drifted the same class). New pattern `docs/patterns/autonomous-ops-triage-policy.md` codifying the 4-bucket model + SessionStart hook visibility rule (from #337 F3, #336 F7, #334 F5 — two operators independently reinvented). CAMPAIGN.md Planning Mode Step 4 "Scope-adversary check for bug classes" (from #332, #338 #2 — voidforge-marketing-site missed `/patterns` because the bug class scope was narrowed). Also closes #260 remaining items: PRODUCT_DESIGN_FRONTEND.md Operating Rule #12 "Tutorial-context checklist for slash commands" + QA_ENGINEER.md Operating Rule #13 "Tutorial smoke test for slash commands." Dep range `^23.11.3` → `^23.11.4` per ADR-062 discipline. Pattern count 47 → 48. 11 field reports remain open for v23.12 methodology pass. |
+| 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/BUILD_PROTOCOL.md

@@ -453,3 +453,4 @@ Examples of batches that are too big:
 8. Test as you build. Write tests alongside features. Tests are a breaking gate.
 9. Skip what doesn't apply. Not every project needs every phase.
 10. Log everything. Decisions, test results, failures, handoffs. The journal is your memory.
+11. **Derived counts discipline.** Any user-facing numeric claim ("141+ pages", "Gated pages: 19", "6 missions completed", "1390 tests") must be derived from data the build can verify, never hardcoded. Either: (a) compute at build time from source truth (file counts, array lengths, manifest scans), or (b) explicitly mark the claim with `<!-- last-verified: YYYY-MM-DD -->` and add a maintenance task to `docs/methods/RELEASE_MANAGER.md` Verification Checklist. No unverified scalar claims ship in any release. This is the scalar equivalent of the No Stubs doctrine (CLAUDE.md Coding Standards). Three projects independently drifted the same class (#336 F6, #334 F6, #332 hidden #5) — the cost compounds because nobody knows which numbers are stale until somebody counts.

package/dist/docs/methods/CAMPAIGN.md

@@ -101,9 +101,10 @@ When the user passes `--plan [description]`, Sisko updates the plan instead of e
 1. Read the current PRD and ROADMAP.md
 2. Dax analyzes where the new idea fits — new feature (PRD), improvement (ROADMAP), or reprioritization
 3. Odo checks dependencies — does this depend on something not yet built?
-4. Present proposed changes for user review
-5. Write updates on confirmation
-6. Do NOT start building — planning only
+4. **Scope-adversary check for bug classes.** When the new idea is a bug fix OR documents a specific bug class, dispatch at least one verification agent (Riker, Feyd-Rautha, or Spock) with an explicit prompt: *"This mission fixes a [slug-array / render-time data / schema-constraint / IDOR / etc.] class. List all other surfaces in this codebase that this class touches but were NOT in the mission scope."* The plan must explicitly account for every class-instance found, or explicitly defer with rationale. (Field reports #332 + #338: voidforge-marketing-site planning missed `/patterns` because the bug was scoped to `/commands`; same class, both surfaces, only one fixed. Class-generalization is a briefing discipline that costs zero code and prevents whole categories of regressions.)
+5. Present proposed changes for user review
+6. Write updates on confirmation
+7. Do NOT start building — planning only
 
 This is how ideas get into the plan without breaking the execution flow. The user describes what they want in plain language; Dax figures out where it goes.
 

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/PRODUCT_DESIGN_FRONTEND.md

@@ -53,6 +53,7 @@ Adversarial UX/UI QA review. Identify usability issues, inconsistencies, broken
 9. **Confidence scoring:** All findings include a confidence score (0-100). High confidence (90+) skips re-verification in Step 7.5. Low confidence (<60) must be escalated to a second agent from a different universe before presenting — if the second agent disagrees, drop the finding. See GAUNTLET.md "Agent Confidence Scoring" for full ranges.
 10. **Slash command prompt convention:** In documentation and tutorials, slash commands use `>` prefix (Claude Code prompt), not `$` (shell prompt). `$ /build` is wrong — it implies a shell command. `> /build` or just `/build` is correct. (Field report #298.)
 11. **No version qualifiers in tutorial prose:** Tutorial text states facts without version references. "VoidForge supports 263 agents" — not "Since v23.0, VoidForge supports 263 agents." Readers don't care when a feature shipped; version tags make tutorials feel like changelogs. Version history belongs in CHANGELOG.md. (Field report #298.)
+12. **Tutorial-context checklist for slash commands.** When tutorial or documentation content shows a slash command (`/build`, `/blueprint`, `/campaign`, etc.) in a terminal/code block, that block — or the surrounding prose — MUST establish that the command runs *inside Claude Code*, not at the user's shell prompt. First mention of any `/` command in a tutorial page requires either: (a) a preceding block showing `claude` (or the user's Claude Code launch command), or (b) an inline callout explaining the convention, or (c) the prose context "inside Claude Code". Standalone slash commands in tutorial content with no launch context are a UX defect — new users will type them at their shell prompt and get `command not found`. Galadriel's Step 1.5 Usability Review (and any UX pass over tutorial/docs surfaces) must flag missing launch context as Critical for first-touch user-facing content. (Field report #260 — 5-week-old documentation friction.)
 
 ## Step 0 — Orient
 

package/dist/docs/methods/QA_ENGINEER.md

@@ -65,6 +65,7 @@ Find, reproduce, and fix real bugs (not theoretical). Improve reliability, error
 10. Double-pass: find → fix → re-verify. Fix-induced regressions are the #1 source of shipped bugs.
 11. **Dispatch-first QA:** For codebases with >10 files to review, dispatch Batman's team as sub-agents per `SUB_AGENTS.md` "Parallel Agent Standard." Oracle + Red Hood in one agent, Alfred + Lucius in another. Main thread triages findings. (Field report #270)
 12. **Confidence scoring:** All findings include a confidence score (0-100). High confidence (90+) skips re-verification in Pass 2. Low confidence (<60) must be escalated to a second agent from a different universe before presenting — if the second agent disagrees, drop the finding. See GAUNTLET.md "Agent Confidence Scoring" for full ranges.
+13. **Tutorial smoke test for slash commands.** When the project ships tutorial or onboarding documentation (marketing site, README walkthrough, getting-started guide, etc.), Batman's QA pass must include a verification: every `/<command>` reference in tutorial-context content is preceded by — or accompanied by — explicit "inside Claude Code" framing (a `claude` launch block, a callout, or contextual prose). Run a grep-based smoke check: list every `/<command>` mention in tutorial files, then for each one confirm the launch context is present within 5 lines or in a callout block on the same page. Missing launch context = Critical bug. (Field report #260 — every reviewing agent assumed the convention was obvious because they already knew it; new users did not. Sister-rule lives in PRODUCT_DESIGN_FRONTEND.md Operating Rule #12.)
 
 ## Step 0 — Orient
 

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/docs/patterns/autonomous-ops-triage-policy.md

@@ -0,0 +1,102 @@
+# Autonomous Operations Triage Policy
+
+**Scope:** Ops-flavored projects (infrastructure repos, monitoring daemons, homelab automation, scheduled-task systems) where the assistant is invoked autonomously and must decide whether to act, propose, or escalate without the operator present.
+
+**Status:** Pattern v1 (v23.11.4). Promoted by Wong from field reports #337, #336, #334.
+
+**Why this exists:** Two operators independently reinvented the same 4-bucket model across three projects (threadplex-ops, 1999collection M30-M32, 1999collection M20-M28). The pattern is reusable across all infrastructure repos. Codifying it stops the reinvention.
+
+## The 4-Bucket Model
+
+Classify every proposed autonomous action into exactly one bucket:
+
+| Bucket | Action | When | Logging | Operator Notification |
+|--------|--------|------|---------|----------------------|
+| **A — Self-resolving** | Auto-execute | Action is fully reversible, low-blast-radius, has a clear procedure, and was authorized in a durable instruction (CLAUDE.md, agent definition, prior issue) | Append to ops log | None unless asked |
+| **B — Runbook-safe** | Follow runbook procedure | Action is documented in a runbook, has been executed successfully before, and operator pre-approved the runbook | Append to ops log with runbook ID | Summary at next session start |
+| **C — Operator-approval required** | Propose via Telegram button / GitHub issue / explicit message; WAIT | Action has medium blast radius, irreversible side effects, OR runbook ambiguity | Log proposal + decision | Active notification (Telegram, Slack, email per project) |
+| **D — Hard-never** | Log + escalate; NEVER attempt | Action is on the forbidden list (e.g., production rollback without ticket, secret rotation without quorum, destructive migration without approval) | Log attempt + escalation | Active high-priority alert |
+
+## Pairing with SessionStart Hook
+
+Ops projects should pair this policy with a `.claude/settings.json` SessionStart hook that injects current state and a reminder of the policy:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "command": "bash .claude/hooks/session-start.sh",
+        "description": "Inject current ops state + triage policy reminder"
+      }
+    ]
+  }
+}
+```
+
+The hook script outputs the current pending-action set (read from `logs/pending-actions.json` or similar) plus a one-line reminder pointing at this policy file.
+
+### Visibility rule
+
+**SessionStart hook output is context-only — the assistant must `echo` the relevant portions back to the operator at session start.** Otherwise the operator has no visual confirmation that the hook fired and the policy is live. Both #337 and #336 documented operators discovering that hooks were silently running with no visibility — both reinvented an explicit echo step. Make it part of the policy from day one.
+
+## Decision Tree (Each Proposed Action)
+
+```
+Is the action on the forbidden list (D)?
+  Yes → Log attempt, raise high-priority alert, STOP.
+  No  → Continue.
+
+Does the action have an approved runbook (B)?
+  Yes → Execute runbook, log with runbook ID. STOP.
+  No  → Continue.
+
+Is the action fully reversible AND low blast radius AND pre-authorized in durable instructions (A)?
+  Yes → Execute, log. STOP.
+  No  → Bucket C: propose to operator, wait, do not execute until approved.
+```
+
+## Logging Format
+
+Each ops log entry should record:
+
+```jsonl
+{
+  "timestamp": "2026-05-12T19:42:00Z",
+  "bucket": "A|B|C|D",
+  "action": "short description",
+  "decision": "executed|proposed|escalated|skipped",
+  "rationale": "why this bucket",
+  "runbook_id": "RB-007 if applicable",
+  "operator_notified": false,
+  "outcome": "success|failed|pending"
+}
+```
+
+JSON Lines (one object per line) keeps the log greppable and append-only.
+
+## Adoption Checklist
+
+For a new ops-flavored project:
+
+- [ ] Pick the buckets that apply (most projects use all four)
+- [ ] Write the forbidden list (Bucket D) FIRST — concrete and exhaustive
+- [ ] Document each runbook (Bucket B) with a fixed ID, expected outcome, and rollback procedure
+- [ ] Set up the SessionStart hook + echo step
+- [ ] Configure the operator-notification channel (Telegram bot, GitHub issue, etc.)
+- [ ] Establish the ops log path and rotation policy
+- [ ] Add a one-line reminder of this policy to the project's `CLAUDE.md` Personality section
+
+## Non-Goals
+
+This pattern is NOT:
+
+- A replacement for `/campaign` or `/build` — those are user-driven workflows with human pacing
+- A general agent-permissioning model — settings.json `allow`/`deny` lists handle tool-level permissions
+- A substitute for tested code — Bucket A actions still need their own correctness verification
+
+## See Also
+
+- `docs/patterns/daemon-process.ts` — daemon lifecycle, PID management, signal handling
+- `docs/methods/HEARTBEAT.md` — long-running ops job scheduling
+- `docs/methods/FIELD_MEDIC.md` — post-mortem analysis for ops incidents

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.4",
   "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.4",
     "node-pty": "^1.2.0-beta.12",
     "ws": "^8.19.0"
   },