voidforge-build 23.19.0 → 23.21.0

package/dist/scripts/statusline/context-awareness-hook.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# context-awareness-hook.sh — UserPromptSubmit hook that injects context-budget
+# awareness INTO Claude's own context as the window fills.
+#
+# The status-line meter is for the human; this hook is for the model. Claude
+# cannot see its own remaining context directly, so each turn (once usage crosses
+# a threshold) this prints a JSON object whose `hookSpecificOutput.additionalContext`
+# Claude receives — "you have ~X% left, checkpoint soon." Below the threshold it is
+# silent, so it adds zero noise until it matters.
+#
+# Cadence: Claude Code has no time/turn-interval hooks — UserPromptSubmit (once per
+# user turn) is the finest cadence available, which is exactly when fresh awareness
+# is useful. Threshold-gated so it behaves like a periodic warning that only speaks
+# near the limit.
+#
+# Requires jq; without it, no-op (exit 0). A hook must never break the turn.
+#
+# Env knobs:
+#   VOIDFORGE_CONTEXT_WINDOW    denominator (default 200000; auto-bumps to 1000000 when usage exceeds 200k)
+#   VOIDFORGE_CONTEXT_WARN_PCT  start warning at this % used (default 80)
+#   VOIDFORGE_CONTEXT_CRIT_PCT  escalate to "checkpoint NOW" at this % (default 92)
+set -uo pipefail
+
+input="$(cat 2>/dev/null || true)"
+command -v jq >/dev/null 2>&1 || exit 0
+
+transcript="$(printf '%s' "$input" | jq -r '.transcript_path // empty' 2>/dev/null)"
+[ -n "$transcript" ] && [ -f "$transcript" ] || exit 0
+
+usage="$(tail -n 400 "$transcript" | jq -c 'select(.message.usage != null) | .message.usage' 2>/dev/null | tail -1)"
+[ -n "$usage" ] || exit 0
+used="$(printf '%s' "$usage" | jq -r '((.input_tokens//0)+(.cache_read_input_tokens//0)+(.cache_creation_input_tokens//0))' 2>/dev/null)"
+used="${used%%.*}"
+[ -n "${used:-}" ] || exit 0
+
+if [ "$used" -gt 200000 ] 2>/dev/null; then window=1000000; else window="${VOIDFORGE_CONTEXT_WINDOW:-200000}"; fi
+[ "${window:-0}" -gt 0 ] 2>/dev/null || exit 0
+pct=$(( used * 100 / window ))
+
+warn="${VOIDFORGE_CONTEXT_WARN_PCT:-80}"
+crit="${VOIDFORGE_CONTEXT_CRIT_PCT:-92}"
+[ "$pct" -lt "$warn" ] && exit 0
+
+rem_k=$(( (window - used) / 1000 ))
+
+if [ "$pct" -ge "$crit" ]; then
+  msg="⚠️ CONTEXT CRITICAL: ~${pct}% of the ${window}-token window is used (~${rem_k}k left). Compaction is imminent — checkpoint NOW: run /vault (or /seal) to preserve session state before the context is summarized, and prefer finishing the current sub-task over starting new work."
+else
+  msg="Context monitor: ~${pct}% of the ${window}-token window is used (~${rem_k}k left). You are approaching the limit — wrap up open loops and consider /vault or /seal to checkpoint before compaction."
+fi
+
+jq -cn --arg m "$msg" '{hookSpecificOutput:{hookEventName:"UserPromptSubmit",additionalContext:$m}}'
+exit 0

package/dist/scripts/statusline/settings-snippet.json

@@ -0,0 +1,17 @@
+{
+  "statusLine": {
+    "type": "command",
+    "command": "bash scripts/statusline/voidforge-statusline.sh",
+    "padding": 0
+  },
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          { "type": "command", "command": "bash scripts/statusline/context-awareness-hook.sh" }
+        ]
+      }
+    ]
+  }
+}

package/dist/scripts/statusline/voidforge-statusline.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# voidforge-statusline.sh — Context-usage meter for the Claude Code status line.
+#
+# Reads the status-line JSON on stdin and prints ONE line:
+#   <model>  ⟦████████░░⟧ 78% ctx · 44k left
+# The meter is colored green → yellow → red as the context window fills.
+#
+# Source of truth: the native `.context_window` object Claude Code pipes to the
+# status line (`used_percentage`, `context_window_size`). When that field is
+# absent (older Claude Code), it falls back to deriving usage from the most
+# recent assistant `message.usage` in `.transcript_path`.
+#
+# Requires jq. Without jq it prints a minimal line and exits 0 — a status line
+# must NEVER hard-fail (that would blank the bar).
+#
+# Env knobs (shared with the awareness hook so colors and warnings stay in lockstep):
+#   VOIDFORGE_CONTEXT_WINDOW    denominator when the size field is absent (default 200000)
+#   VOIDFORGE_CONTEXT_WARN_PCT  meter turns yellow at this % used (default 80)
+#   VOIDFORGE_CONTEXT_CRIT_PCT  meter turns red at this % used (default 92)
+set -uo pipefail
+
+input="$(cat 2>/dev/null || true)"
+
+if ! command -v jq >/dev/null 2>&1; then
+  printf 'VoidForge · ctx meter needs jq (brew install jq)\n'
+  exit 0
+fi
+
+j() { printf '%s' "$input" | jq -r "$1" 2>/dev/null; }
+
+model="$(j '.model.display_name // .model.id // "Claude"')"
+pct="$(j '.context_window.used_percentage // empty')"
+window="$(j '.context_window.context_window_size // empty')"
+
+# Fallback: derive from the transcript when the native field is absent.
+if [ -z "$pct" ]; then
+  transcript="$(j '.transcript_path // empty')"
+  if [ -n "$transcript" ] && [ -f "$transcript" ]; then
+    usage="$(tail -n 400 "$transcript" | jq -c 'select(.message.usage != null) | .message.usage' 2>/dev/null | tail -1)"
+    if [ -n "$usage" ]; then
+      used="$(printf '%s' "$usage" | jq -r '((.input_tokens//0)+(.cache_read_input_tokens//0)+(.cache_creation_input_tokens//0))' 2>/dev/null)"
+      used="${used%%.*}"
+      if [ -z "$window" ]; then
+        if [ "${used:-0}" -gt 200000 ] 2>/dev/null; then window=1000000; else window="${VOIDFORGE_CONTEXT_WINDOW:-200000}"; fi
+      fi
+      if [ -n "${used:-}" ] && [ "${window:-0}" -gt 0 ] 2>/dev/null; then
+        pct=$(( used * 100 / window ))
+      fi
+    fi
+  fi
+fi
+
+# Coerce to integer; bail to model-only if we still have nothing.
+pct="${pct%%.*}"
+if [ -z "$pct" ]; then
+  printf '%s\n' "$model"
+  exit 0
+fi
+[ -z "$window" ] && window="${VOIDFORGE_CONTEXT_WINDOW:-200000}"
+window="${window%%.*}"
+
+[ "$pct" -lt 0 ] 2>/dev/null && pct=0
+[ "$pct" -gt 100 ] 2>/dev/null && pct=100
+
+remaining=$(( window - window * pct / 100 ))
+if [ "$remaining" -ge 1000 ]; then rem_h="$(( remaining / 1000 ))k"; else rem_h="${remaining}"; fi
+
+# Color band — defaults align with the awareness-hook thresholds (warn 80 → yellow,
+# crit 92 → red) so the meter turns red exactly when the hook goes critical. Both
+# honor the same env vars, so retuning one retunes the other.
+yellow_at="${VOIDFORGE_CONTEXT_WARN_PCT:-80}"
+red_at="${VOIDFORGE_CONTEXT_CRIT_PCT:-92}"
+if   [ "$pct" -ge "$red_at" ];    then color=$'\033[31m'   # red    — checkpoint now
+elif [ "$pct" -ge "$yellow_at" ]; then color=$'\033[33m'   # yellow — getting full
+else                                   color=$'\033[32m'   # green  — healthy
+fi
+reset=$'\033[0m'
+dim=$'\033[2m'
+
+# 10-cell meter, rounded.
+filled=$(( (pct + 5) / 10 ))
+[ "$filled" -gt 10 ] && filled=10
+[ "$filled" -lt 0 ] && filled=0
+bar=""
+i=0
+while [ "$i" -lt 10 ]; do
+  if [ "$i" -lt "$filled" ]; then bar="${bar}█"; else bar="${bar}░"; fi
+  i=$(( i + 1 ))
+done
+
+printf '%s %s⟦%s⟧ %d%%%s %sctx · %s left%s\n' "$model" "$color" "$bar" "$pct" "$reset" "$dim" "$rem_h" "$reset"

package/dist/scripts/voidforge.js

@@ -345,6 +345,21 @@ async function cmdMigrateTreasury() {
     console.log('  Per-project logs start fresh (genesis hash). Global data preserved in archive.');
     console.log('  To rollback: move archive back to ~/.voidforge/treasury/\n');
 }
+function showUpdateHelp() {
+    console.log('voidforge update — update project methodology (Bombadil)\n');
+    console.log('Usage: npx voidforge update [options]\n');
+    console.log('Options:');
+    console.log('  --self             Update the wizard/CLI itself instead of the project');
+    console.log('  --extensions       Update all installed extensions across registered projects');
+    console.log('  --no-self-update   Skip the automatic CLI self-upgrade check');
+    console.log('  --help, -h         Show this help (does NOT run the update)');
+    console.log('');
+    console.log('CLAUDE.md is updated per the `.voidforge` marker `claudeMd` policy:');
+    console.log('  preserve (default) Never overwrite in place — write CLAUDE.md.upstream + warn');
+    console.log('  merge              Replace only the VOIDFORGE methodology fences, keep project sections');
+    console.log('  skip               Never touch CLAUDE.md');
+    console.log('');
+}
 function showHelp() {
     console.log('VoidForge — From nothing, everything.\n');
     console.log('Usage: npx voidforge <command> [options]\n');
@@ -464,7 +479,16 @@ async function main() {
                 break;
             }
             case 'update': {
-                if (args.includes('--self')) {
+                const { resolveUpdateMode } = await import('../wizard/lib/updater.js');
+                const updateMode = resolveUpdateMode(args);
+                // Help guard (issue #368): `update --help` / `-h` must PRINT usage and
+                // exit — never execute the (potentially destructive) update. Help wins
+                // over every action flag, checked before any work happens.
+                if (updateMode === 'help') {
+                    showUpdateHelp();
+                    break;
+                }
+                if (updateMode === 'self') {
                     const { selfUpdate } = await import('../wizard/lib/updater.js');
                     const result = selfUpdate();
                     console.log(result.message);
@@ -510,7 +534,7 @@ async function main() {
                         // npm view failed — offline or registry issue. Continue with local version.
                     }
                 }
-                if (args.includes('--extensions')) {
+                if (updateMode === 'extensions') {
                     const { readRegistry } = await import('../wizard/lib/project-registry.js');
                     const { readMarker: readMkr } = await import('../wizard/lib/marker.js');
                     const { getExtension } = await import('../wizard/lib/extensions.js');
@@ -537,11 +561,42 @@ async function main() {
                     break;
                 }
                 // Methodology update
-                const { findProjectRoot: findProjRoot } = await import('../wizard/lib/marker.js');
-                const projRoot = findProjRoot();
+                const { findProjectRoot: findProjRoot, detectLegacyConsumer, readVersionFile, createMarker: makeMarker, writeMarker: saveMarker, } = await import('../wizard/lib/marker.js');
+                let projRoot = findProjRoot();
                 if (!projRoot) {
-                    console.error('Not a VoidForge project — run `npx voidforge init` first.');
-                    process.exit(1);
+                    // Issue #369: a project that consumed methodology via git (pre-marker)
+                    // has no `.voidforge` but IS a real consumer. Offer to create the
+                    // marker instead of sending the user to `init` (which scaffolds).
+                    const legacy = detectLegacyConsumer();
+                    if (legacy) {
+                        const version = readVersionFile(legacy.dir);
+                        console.log('\n  No .voidforge marker found, but this looks like a legacy');
+                        console.log('  VoidForge methodology consumer:');
+                        console.log(`    dir:     ${legacy.dir}`);
+                        console.log(`    tier:    ${legacy.inferredTier} (inferred)`);
+                        console.log(`    version: ${version} (from VERSION.md)`);
+                        console.log('');
+                        let createIt = true;
+                        if (process.stdin.isTTY) {
+                            const answer = (await prompt('  Create the .voidforge marker now? [Y/n]: ')).toLowerCase();
+                            createIt = answer === '' || answer === 'y' || answer === 'yes';
+                        }
+                        else {
+                            console.log('  Non-interactive: creating the marker automatically.');
+                        }
+                        if (!createIt) {
+                            console.log('\n  Aborted — no marker created. Update skipped.\n');
+                            break;
+                        }
+                        const newMarker = makeMarker(version, legacy.inferredTier);
+                        await saveMarker(legacy.dir, newMarker);
+                        console.log(`  Created .voidforge marker (${newMarker.id}).\n`);
+                        projRoot = legacy.dir;
+                    }
+                    else {
+                        console.error('Not a VoidForge project — run `npx voidforge init` first.');
+                        process.exit(1);
+                    }
                 }
                 const { diffMethodology, applyUpdate } = await import('../wizard/lib/updater.js');
                 const plan = await diffMethodology(projRoot);
@@ -566,6 +621,14 @@ async function main() {
                         console.log(`    - ${f} (kept locally)`);
                 }
                 console.log(`  Unchanged: ${plan.unchanged} files\n`);
+                // CLAUDE.md non-destructive handling (issue #368) — surface the policy,
+                // any dropped-section warning, and the side-file path before applying.
+                if (plan.claudeMd && plan.claudeMd.warnings.length > 0) {
+                    console.log('  CLAUDE.md:');
+                    for (const w of plan.claudeMd.warnings)
+                        console.log(`    ${w}`);
+                    console.log('');
+                }
                 const result = await applyUpdate(projRoot);
                 console.log(`  Updated to v${result.newVersion}. ${plan.added.length + plan.modified.length} files changed.\n`);
                 break;

package/dist/wizard/lib/claude-md-strategy.d.ts

@@ -0,0 +1,87 @@
+/**
+ * CLAUDE.md update strategy — the single mechanism the updater uses to decide
+ * how an `update` may touch a project's CLAUDE.md (issue #368).
+ *
+ * CLAUDE.md is the file Claude Code loads every session; it carries the
+ * project's operational knowledge. The old updater preserved only the first ~10
+ * lines and overwrote the rest, silently discarding every project-specific
+ * section. That is the same bug class as #331 (silent destruction of user
+ * content). This module makes the update NON-DESTRUCTIVE by default and gives
+ * projects a precise, opt-in lossless merge via sentinel fences.
+ *
+ * Three strategies (from the `.voidforge` marker's `claudeMd` field):
+ *   - 'preserve' (default): never overwrite in place. If upstream differs, the
+ *      new methodology is written to a side file (`CLAUDE.md.upstream`) and the
+ *      operator is warned. The original CLAUDE.md is left untouched.
+ *   - 'merge': replace ONLY the content between the sentinel fences
+ *      `<!-- VOIDFORGE:BEGIN methodology -->` / `<!-- VOIDFORGE:END methodology -->`,
+ *      leaving everything outside them verbatim. Falls back to 'preserve'
+ *      (side-file + warning) when the fences are absent in either document —
+ *      there is no lossless in-place merge without an explicit fenced block.
+ *   - 'skip': do not read or write CLAUDE.md at all.
+ *
+ * In every strategy, section-loss detection runs and surfaces a warning so an
+ * update can never silently drop project sections.
+ */
+import type { ClaudeMdStrategy } from './marker.js';
+export declare const FENCE_BEGIN = "<!-- VOIDFORGE:BEGIN methodology -->";
+export declare const FENCE_END = "<!-- VOIDFORGE:END methodology -->";
+/** Side file written when an in-place merge would be destructive. */
+export declare const UPSTREAM_SUFFIX = ".upstream";
+export type ClaudeMdAction = 'unchanged' | 'skip' | 'overwrite' | 'merge-fenced' | 'side-file';
+export interface ClaudeMdMergeResult {
+    action: ClaudeMdAction;
+    /**
+     * New content to write to CLAUDE.md itself, or null if CLAUDE.md must NOT be
+     * touched (skip / unchanged / side-file paths).
+     */
+    claudeMdContent: string | null;
+    /**
+     * Content to write to the side file, or null if no side file is needed.
+     * When set, the caller writes it to `<CLAUDE.md path>.upstream`.
+     */
+    sideFileContent: string | null;
+    /** Project headings present locally but absent upstream — would be dropped by a naive overwrite. */
+    droppedSections: string[];
+    /** Human-readable warnings to surface to the operator. */
+    warnings: string[];
+}
+/**
+ * Extract top-level-ish markdown headings (#, ##) used as section identities.
+ * Code fences are skipped so a `#` inside a ```bash block is not a heading.
+ * Normalized (trimmed, leading hashes stripped) for stable comparison.
+ */
+export declare function extractSections(content: string): string[];
+/**
+ * Sections present in `current` but missing from `incoming` — i.e. content that
+ * a naive whole-file overwrite would silently destroy.
+ */
+export declare function findDroppedSections(current: string, incoming: string): string[];
+/**
+ * Normalize away the project-identity region so two CLAUDE.md files that differ
+ * ONLY in their `## Project` block (name/one-liner/domain/repo, or the
+ * `[PROJECT_NAME]` placeholders) compare equal.
+ *
+ * This is why a freshly-`init`ed project — whose `## Project` block has the real
+ * name injected while the upstream template still carries `[PROJECT_NAME]` —
+ * does not register as a spurious "change" on the very next `update`. It is a
+ * comparison-only transform; we never write the normalized form.
+ */
+export declare function stripIdentity(content: string): string;
+export declare function hasFences(content: string): boolean;
+/**
+ * Replace the fenced methodology block in `current` with the fenced block from
+ * `upstream`. Everything outside the fences in `current` is preserved verbatim.
+ * Returns null if either document lacks a well-formed fence pair.
+ */
+export declare function mergeFenced(current: string, upstream: string): string | null;
+/**
+ * Decide how to update CLAUDE.md given the current project content, the incoming
+ * upstream content, and the configured strategy. Pure function — performs no
+ * I/O. The caller performs the writes described by the returned result.
+ *
+ * @param current  Existing project CLAUDE.md (null/undefined if the file is absent).
+ * @param upstream Incoming methodology CLAUDE.md.
+ * @param strategy Marker `claudeMd` field (defaults applied by the caller).
+ */
+export declare function planClaudeMdUpdate(current: string | null | undefined, upstream: string, strategy: ClaudeMdStrategy): ClaudeMdMergeResult;

package/dist/wizard/lib/claude-md-strategy.js

@@ -0,0 +1,198 @@
+/**
+ * CLAUDE.md update strategy — the single mechanism the updater uses to decide
+ * how an `update` may touch a project's CLAUDE.md (issue #368).
+ *
+ * CLAUDE.md is the file Claude Code loads every session; it carries the
+ * project's operational knowledge. The old updater preserved only the first ~10
+ * lines and overwrote the rest, silently discarding every project-specific
+ * section. That is the same bug class as #331 (silent destruction of user
+ * content). This module makes the update NON-DESTRUCTIVE by default and gives
+ * projects a precise, opt-in lossless merge via sentinel fences.
+ *
+ * Three strategies (from the `.voidforge` marker's `claudeMd` field):
+ *   - 'preserve' (default): never overwrite in place. If upstream differs, the
+ *      new methodology is written to a side file (`CLAUDE.md.upstream`) and the
+ *      operator is warned. The original CLAUDE.md is left untouched.
+ *   - 'merge': replace ONLY the content between the sentinel fences
+ *      `<!-- VOIDFORGE:BEGIN methodology -->` / `<!-- VOIDFORGE:END methodology -->`,
+ *      leaving everything outside them verbatim. Falls back to 'preserve'
+ *      (side-file + warning) when the fences are absent in either document —
+ *      there is no lossless in-place merge without an explicit fenced block.
+ *   - 'skip': do not read or write CLAUDE.md at all.
+ *
+ * In every strategy, section-loss detection runs and surfaces a warning so an
+ * update can never silently drop project sections.
+ */
+// ── Constants ────────────────────────────────────────────
+export const FENCE_BEGIN = '<!-- VOIDFORGE:BEGIN methodology -->';
+export const FENCE_END = '<!-- VOIDFORGE:END methodology -->';
+/** Side file written when an in-place merge would be destructive. */
+export const UPSTREAM_SUFFIX = '.upstream';
+// ── Heading extraction ───────────────────────────────────
+/**
+ * Extract top-level-ish markdown headings (#, ##) used as section identities.
+ * Code fences are skipped so a `#` inside a ```bash block is not a heading.
+ * Normalized (trimmed, leading hashes stripped) for stable comparison.
+ */
+export function extractSections(content) {
+    const sections = [];
+    let inFence = false;
+    for (const rawLine of content.split('\n')) {
+        const line = rawLine.trimEnd();
+        const fenceToggle = /^\s*(```|~~~)/.test(line);
+        if (fenceToggle) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        const m = line.match(/^(#{1,2})\s+(.+?)\s*$/);
+        if (m)
+            sections.push(m[2].trim());
+    }
+    return sections;
+}
+/**
+ * Sections present in `current` but missing from `incoming` — i.e. content that
+ * a naive whole-file overwrite would silently destroy.
+ */
+export function findDroppedSections(current, incoming) {
+    const incomingSet = new Set(extractSections(incoming).map((s) => s.toLowerCase()));
+    const seen = new Set();
+    const dropped = [];
+    for (const s of extractSections(current)) {
+        const key = s.toLowerCase();
+        if (!incomingSet.has(key) && !seen.has(key)) {
+            seen.add(key);
+            dropped.push(s);
+        }
+    }
+    return dropped;
+}
+// ── Fences ───────────────────────────────────────────────
+// ── Identity normalization ───────────────────────────────
+/**
+ * Normalize away the project-identity region so two CLAUDE.md files that differ
+ * ONLY in their `## Project` block (name/one-liner/domain/repo, or the
+ * `[PROJECT_NAME]` placeholders) compare equal.
+ *
+ * This is why a freshly-`init`ed project — whose `## Project` block has the real
+ * name injected while the upstream template still carries `[PROJECT_NAME]` —
+ * does not register as a spurious "change" on the very next `update`. It is a
+ * comparison-only transform; we never write the normalized form.
+ */
+export function stripIdentity(content) {
+    let out = content;
+    // Drop the monorepo template comment fences around the Project block.
+    out = out.replace(/<!--\s*REMOVE-FOR-NPM-PUBLISH:[\s\S]*?-->\n?/g, '');
+    out = out.replace(/<!--\s*END-REMOVE-FOR-NPM-PUBLISH\s*-->\n?/g, '');
+    // Drop a leading `## Project` block: from the `## Project` heading up to (but
+    // not including) the next `## ` heading.
+    out = out.replace(/^##\s+Project[ \t]*\n[\s\S]*?(?=^##\s)/m, '');
+    return out.trim();
+}
+export function hasFences(content) {
+    const begin = content.indexOf(FENCE_BEGIN);
+    const end = content.indexOf(FENCE_END);
+    return begin !== -1 && end !== -1 && end > begin;
+}
+/**
+ * Replace the fenced methodology block in `current` with the fenced block from
+ * `upstream`. Everything outside the fences in `current` is preserved verbatim.
+ * Returns null if either document lacks a well-formed fence pair.
+ */
+export function mergeFenced(current, upstream) {
+    if (!hasFences(current) || !hasFences(upstream))
+        return null;
+    const upBegin = upstream.indexOf(FENCE_BEGIN);
+    const upEnd = upstream.indexOf(FENCE_END) + FENCE_END.length;
+    const upstreamBlock = upstream.slice(upBegin, upEnd);
+    const curBegin = current.indexOf(FENCE_BEGIN);
+    const curEnd = current.indexOf(FENCE_END) + FENCE_END.length;
+    return current.slice(0, curBegin) + upstreamBlock + current.slice(curEnd);
+}
+// ── Core decision ────────────────────────────────────────
+/**
+ * Decide how to update CLAUDE.md given the current project content, the incoming
+ * upstream content, and the configured strategy. Pure function — performs no
+ * I/O. The caller performs the writes described by the returned result.
+ *
+ * @param current  Existing project CLAUDE.md (null/undefined if the file is absent).
+ * @param upstream Incoming methodology CLAUDE.md.
+ * @param strategy Marker `claudeMd` field (defaults applied by the caller).
+ */
+export function planClaudeMdUpdate(current, upstream, strategy) {
+    // New project (no existing CLAUDE.md): just write upstream. Nothing to lose.
+    if (current == null) {
+        return {
+            action: 'overwrite',
+            claudeMdContent: upstream,
+            sideFileContent: null,
+            droppedSections: [],
+            warnings: [],
+        };
+    }
+    // Identical already — never write. Identity-normalized so a fresh project
+    // (real name injected vs upstream `[PROJECT_NAME]` placeholder) is not treated
+    // as a spurious change on its first update.
+    if (current === upstream || stripIdentity(current) === stripIdentity(upstream)) {
+        return {
+            action: 'unchanged',
+            claudeMdContent: null,
+            sideFileContent: null,
+            droppedSections: [],
+            warnings: [],
+        };
+    }
+    if (strategy === 'skip') {
+        return {
+            action: 'skip',
+            claudeMdContent: null,
+            sideFileContent: null,
+            droppedSections: [],
+            warnings: ['CLAUDE.md left untouched (claudeMd: "skip"). Upstream changes were NOT applied.'],
+        };
+    }
+    const dropped = findDroppedSections(current, upstream);
+    if (strategy === 'merge') {
+        const merged = mergeFenced(current, upstream);
+        if (merged !== null) {
+            // Fenced merge is lossless for everything outside the fences. Re-check loss
+            // against the merged result, not the raw upstream, so project sections
+            // preserved by the fence are NOT reported as dropped.
+            const residualLoss = findDroppedSections(current, merged);
+            const warnings = merged === current
+                ? ['CLAUDE.md fenced methodology block already current — no change.']
+                : ['CLAUDE.md updated within VOIDFORGE methodology fences; project sections preserved.'];
+            if (residualLoss.length > 0) {
+                warnings.push(`WARNING: fenced merge still drops ${residualLoss.length} section(s): ${residualLoss.join(', ')}.`);
+            }
+            return {
+                action: merged === current ? 'unchanged' : 'merge-fenced',
+                claudeMdContent: merged === current ? null : merged,
+                sideFileContent: null,
+                droppedSections: residualLoss,
+                warnings,
+            };
+        }
+        // 'merge' requested but no fences — fall through to safe side-file behavior.
+    }
+    // 'preserve' (default), OR 'merge' without fences: never overwrite in place.
+    // Write upstream to the side file and warn; leave the original intact.
+    const warnings = [
+        `CLAUDE.md was NOT overwritten. Incoming methodology written to CLAUDE.md${UPSTREAM_SUFFIX} — review and merge deliberately.`,
+    ];
+    if (strategy === 'merge') {
+        warnings.unshift(`claudeMd: "merge" requested but no ${FENCE_BEGIN} / ${FENCE_END} fences found in CLAUDE.md — falling back to safe side-file.`);
+    }
+    if (dropped.length > 0) {
+        warnings.push(`An in-place overwrite would have dropped ${dropped.length} project section(s): ${dropped.join(', ')}.`);
+    }
+    return {
+        action: 'side-file',
+        claudeMdContent: null,
+        sideFileContent: upstream,
+        droppedSections: dropped,
+        warnings,
+    };
+}

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

@@ -4,17 +4,40 @@
  * Every VoidForge project has a `.voidforge` JSON file at root.
  * The CLI walks up from cwd to find it, determining the project root.
  */
+/**
+ * How `update` is allowed to touch the project's CLAUDE.md (issue #368):
+ *   - 'preserve' (default, safest): never overwrite in place. If upstream
+ *      differs, write it to `CLAUDE.md.upstream` and warn — the operator merges
+ *      deliberately. CLAUDE.md is the file Claude Code loads every session and
+ *      carries project-specific operational knowledge; clobbering it is the same
+ *      bug class as #331 (silent destruction of user content).
+ *   - 'merge': update only the content between the sentinel fences
+ *      `<!-- VOIDFORGE:BEGIN methodology -->` / `<!-- VOIDFORGE:END methodology -->`,
+ *      leaving every project section outside the fences verbatim. Falls back to
+ *      'preserve' (side-file) when fences are absent — there is no lossless
+ *      in-place merge without them.
+ *   - 'skip': the updater never reads or writes CLAUDE.md at all.
+ */
+export type ClaudeMdStrategy = 'preserve' | 'merge' | 'skip';
 export interface VoidForgeMarker {
     id: string;
     version: string;
     created: string;
     tier: 'full' | 'methodology';
     extensions: string[];
+    /**
+     * Optional CLAUDE.md update policy (issue #368). Absent on legacy markers;
+     * callers MUST default to 'preserve' when undefined so the safe-by-default
+     * behavior applies to projects created before this field existed.
+     */
+    claudeMd?: ClaudeMdStrategy;
 }
+/** Safe default when a marker omits `claudeMd`. Never silently clobber. */
+export declare const DEFAULT_CLAUDE_MD_STRATEGY: ClaudeMdStrategy;
 export declare const MARKER_FILE = ".voidforge";
 export declare function readMarker(dir: string): Promise<VoidForgeMarker | null>;
 export declare function writeMarker(dir: string, marker: VoidForgeMarker): Promise<void>;
-export declare function createMarker(version: string, tier?: VoidForgeMarker['tier'], extensions?: string[]): VoidForgeMarker;
+export declare function createMarker(version: string, tier?: VoidForgeMarker['tier'], extensions?: string[], claudeMd?: ClaudeMdStrategy): VoidForgeMarker;
 /**
  * Walk up from `startDir` to find the nearest `.voidforge` marker.
  * Returns the directory containing the marker, or null if none found.
@@ -31,5 +54,29 @@ export declare function findProjectRoot(startDir?: string): string | null;
  * Like findProjectRoot but throws with a user-friendly message.
  */
 export declare function requireProjectRoot(startDir?: string): string;
+export interface LegacyConsumer {
+    dir: string;
+    /** Tier inferred from the project shape: 'full' if a wizard/ dir is present. */
+    inferredTier: VoidForgeMarker['tier'];
+}
+/**
+ * Detect a legacy methodology consumer that predates the `.voidforge` marker.
+ *
+ * Such projects originally consumed methodology via git (before the marker
+ * convention) and so `update` hard-errors them toward `init` — which is the
+ * wrong remedy on an existing project (issue #369). The signature of a real
+ * consumer is the methodology footprint: `VERSION.md` + `.claude/commands/` +
+ * `docs/methods/` all present. When that holds and NO marker exists, the CLI
+ * should OFFER to create the marker rather than send the user to `init`.
+ *
+ * Tier is inferred from `wizard/` presence (full-tier projects embed/embedded
+ * the wizard), mirroring the workaround in the field report.
+ *
+ * Returns null when the dir already has a marker (not legacy) or does not look
+ * like a methodology consumer (genuinely not a VoidForge project).
+ */
+export declare function detectLegacyConsumer(dir?: string): LegacyConsumer | null;
+/** Read the methodology version from a project's VERSION.md, or 'unknown'. */
+export declare function readVersionFile(dir: string): string;
 export declare function getGlobalDir(): string;
 export declare function getVaultPath(): string;