voidforge-build 23.11.3 → 23.11.4

package/dist/CHANGELOG.md

@@ -6,6 +6,35 @@ 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

package/dist/CLAUDE.md

@@ -120,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/VERSION.md

@@ -1,6 +1,6 @@
 # Version
 
-**Current:** 23.11.3
+**Current:** 23.11.4
 
 ## Versioning Scheme
 
@@ -14,6 +14,7 @@ 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. |

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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voidforge-build",
-  "version": "23.11.3",
+  "version": "23.11.4",
   "description": "From nothing, everything. A methodology framework for building with Claude Code.",
   "type": "module",
   "engines": {
@@ -45,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": "^23.11.3",
+    "voidforge-build-methodology": "^23.11.4",
     "node-pty": "^1.2.0-beta.12",
     "ws": "^8.19.0"
   },