voidforge-build 23.18.0 → 23.20.0

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;

package/dist/wizard/lib/marker.js

@@ -5,10 +5,12 @@
  * The CLI walks up from cwd to find it, determining the project root.
  */
 import { readFile, writeFile } from 'node:fs/promises';
-import { existsSync, statSync } from 'node:fs';
+import { existsSync, statSync, readFileSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
+/** Safe default when a marker omits `claudeMd`. Never silently clobber. */
+export const DEFAULT_CLAUDE_MD_STRATEGY = 'preserve';
 // ── Constants ────────────────────────────────────────────
 export const MARKER_FILE = '.voidforge';
 // ── Read / Write ─────────────────────────────────────────
@@ -31,13 +33,14 @@ export async function writeMarker(dir, marker) {
     const markerPath = join(dir, MARKER_FILE);
     await writeFile(markerPath, JSON.stringify(marker, null, 2) + '\n', 'utf-8');
 }
-export function createMarker(version, tier = 'full', extensions = []) {
+export function createMarker(version, tier = 'full', extensions = [], claudeMd = DEFAULT_CLAUDE_MD_STRATEGY) {
     return {
         id: randomUUID(),
         version,
         created: new Date().toISOString(),
         tier,
         extensions,
+        claudeMd,
     };
 }
 // ── Project Detection ────────────────────────────────────
@@ -89,6 +92,59 @@ export function requireProjectRoot(startDir = process.cwd()) {
     }
     return root;
 }
+/**
+ * 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 function detectLegacyConsumer(dir = process.cwd()) {
+    const root = resolve(dir);
+    // If a valid marker is already present anywhere up the tree, it is not legacy.
+    if (findProjectRoot(root) !== null)
+        return null;
+    const hasVersion = existsSync(join(root, 'VERSION.md'));
+    const hasCommands = isDir(join(root, '.claude', 'commands'));
+    const hasMethods = isDir(join(root, 'docs', 'methods'));
+    if (!(hasVersion && hasCommands && hasMethods))
+        return null;
+    const inferredTier = isDir(join(root, 'wizard'))
+        ? 'full'
+        : 'methodology';
+    return { dir: root, inferredTier };
+}
+/** Read the methodology version from a project's VERSION.md, or 'unknown'. */
+export function readVersionFile(dir) {
+    const versionPath = join(resolve(dir), 'VERSION.md');
+    if (!existsSync(versionPath))
+        return 'unknown';
+    try {
+        const raw = readFileSync(versionPath, 'utf-8');
+        const match = raw.match(/(\d+\.\d+\.\d+)/);
+        return match ? match[1] : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function isDir(p) {
+    try {
+        return existsSync(p) && statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 // ── Global Config ────────────────────────────────────────
 export function getGlobalDir() {
     const home = process.env['HOME'] ?? process.env['USERPROFILE'] ?? homedir();

package/dist/wizard/lib/patterns/oauth-token-lifecycle.d.ts

@@ -8,6 +8,20 @@
  * - Failure escalation: retry 3x → pause platform → alert → requires_reauth
  * - Token stored as encrypted blob in vault, keyed by platform name
  * - Session token (daemon) rotates every 24 hours (§9.19.15)
+ * - VERIFY EXPIRY + REFRESH-GRANT BEHAVIOR AGAINST THE PROVIDER'S LIVE DOCS AT
+ *   INTEGRATION TIME. The PLATFORM_CONFIGS TTLs below are STARTING ASSUMPTIONS,
+ *   not ground truth — providers change them and "no refresh token / never
+ *   expires" is a common false assumption. Field report #373: a Todoist
+ *   integration shipped on "tokens don't expire," but the modern API issues
+ *   ~1h access tokens WITH a refresh token; the code discarded the refresh
+ *   token + expiry and registered no refresher, so it died ~1h after every
+ *   connect across four sessions — looking exactly like intermittent
+ *   revocation. At integration time: (1) read the provider's OAuth docs and
+ *   quote the verified access-token TTL + whether a refresh_token is issued;
+ *   (2) if a refresh_token exists, PERSIST it and register a refresher — never
+ *   discard it; (3) distinguish "expired" from "revoked" via the API's OWN
+ *   error body, not by inference (an expired token that mimics revocation will
+ *   send you reauth-hunting instead of refreshing).
  *
  * Agents: Breeze (platform relations), Dockson (vault)
  *

package/dist/wizard/lib/patterns/oauth-token-lifecycle.js

@@ -8,11 +8,32 @@
  * - Failure escalation: retry 3x → pause platform → alert → requires_reauth
  * - Token stored as encrypted blob in vault, keyed by platform name
  * - Session token (daemon) rotates every 24 hours (§9.19.15)
+ * - VERIFY EXPIRY + REFRESH-GRANT BEHAVIOR AGAINST THE PROVIDER'S LIVE DOCS AT
+ *   INTEGRATION TIME. The PLATFORM_CONFIGS TTLs below are STARTING ASSUMPTIONS,
+ *   not ground truth — providers change them and "no refresh token / never
+ *   expires" is a common false assumption. Field report #373: a Todoist
+ *   integration shipped on "tokens don't expire," but the modern API issues
+ *   ~1h access tokens WITH a refresh token; the code discarded the refresh
+ *   token + expiry and registered no refresher, so it died ~1h after every
+ *   connect across four sessions — looking exactly like intermittent
+ *   revocation. At integration time: (1) read the provider's OAuth docs and
+ *   quote the verified access-token TTL + whether a refresh_token is issued;
+ *   (2) if a refresh_token exists, PERSIST it and register a refresher — never
+ *   discard it; (3) distinguish "expired" from "revoked" via the API's OWN
+ *   error body, not by inference (an expired token that mimics revocation will
+ *   send you reauth-hunting instead of refreshing).
  *
  * Agents: Breeze (platform relations), Dockson (vault)
  *
  * PRD Reference: §9.5 (token refresh strategy), §9.18 (vault session), §9.19.15
  */
+// ASSUMPTIONS, NOT GROUND TRUTH (field report #373). These TTLs and the
+// "refreshTokenTtlDays: 0 = never expires" entries are starting points. At
+// integration time, VERIFY each value against the provider's current OAuth
+// docs and the live token response (`expires_in`, presence of `refresh_token`)
+// — a provider that "doesn't expire" today may issue ~1h tokens tomorrow, and
+// a missing refresher then surfaces as recurring prod token-death that mimics
+// revocation. Treat any new platform here the same way before shipping.
 const PLATFORM_CONFIGS = [
     { platform: 'meta', accessTokenTtlHours: 1440, refreshTokenTtlDays: 0, refreshEndpoint: 'https://graph.facebook.com/v19.0/oauth/access_token' },
     { platform: 'google', accessTokenTtlHours: 1, refreshTokenTtlDays: 0, refreshEndpoint: 'https://oauth2.googleapis.com/token' },

package/dist/wizard/lib/project-init.js

@@ -89,6 +89,15 @@ async function copyMethodology(methodologyRoot, projectDir, core) {
     if (existsSync(agentsSrc)) {
         count += await copyDir(agentsSrc, join(projectDir, '.claude', 'agents'));
     }
+    // Dynamic Workflow scripts (ADR-067 — gauntlet/assemble review skeletons).
+    // gauntlet.md / assemble.md reference `.claude/workflows/*.workflow.js`; without this
+    // a fresh `npx voidforge-build init` ships the command docs but NOT the scripts they
+    // invoke. prepack.sh + copy-assets.sh ship them to the npm package and dist/, but this
+    // CLI init copy path (methodologyRoot = the installed package) was missed in v23.18.0.
+    const workflowsSrc = join(methodologyRoot, '.claude', 'workflows');
+    if (existsSync(workflowsSrc)) {
+        count += await copyDir(workflowsSrc, join(projectDir, '.claude', 'workflows'));
+    }
     // Methods
     const methodsSrc = join(methodologyRoot, 'docs', 'methods');
     if (existsSync(methodsSrc)) {
@@ -108,6 +117,15 @@ async function copyMethodology(methodologyRoot, projectDir, core) {
         await cp(registrySrc, join(projectDir, 'docs', 'NAMING_REGISTRY.md'));
         count++;
     }
+    // Agent classification — single source of truth for agent counts (v23.7.0). Command
+    // docs derive their counts from it; prepack ships it to the npm package, but this init
+    // path omitted it, so init'd projects couldn't resolve the count SSOT.
+    const classificationSrc = join(methodologyRoot, 'docs', 'AGENT_CLASSIFICATION.md');
+    if (existsSync(classificationSrc)) {
+        await mkdir(join(projectDir, 'docs'), { recursive: true });
+        await cp(classificationSrc, join(projectDir, 'docs', 'AGENT_CLASSIFICATION.md'));
+        count++;
+    }
     // Thumper scripts
     const thumperSrc = join(methodologyRoot, 'scripts', 'thumper');
     if (existsSync(thumperSrc)) {
@@ -123,6 +141,16 @@ async function copyMethodology(methodologyRoot, projectDir, core) {
         await chmodShellScripts(join(projectDir, 'scripts', 'surfer-gate'));
         await mergeSettingsHook(projectDir);
     }
+    // Context-meter status line (/contextmeter) — default-on. Ship the scripts AND wire
+    // the statusLine + UserPromptSubmit awareness hook into settings.json, the same way the
+    // surfer-gate hook is wired. Defaults: warn 80% / crit 92% (baked into the scripts).
+    // Opt out per project with `/contextmeter --uninstall`.
+    const statuslineSrc = join(methodologyRoot, 'scripts', 'statusline');
+    if (existsSync(statuslineSrc)) {
+        count += await copyDir(statuslineSrc, join(projectDir, 'scripts', 'statusline'));
+        await chmodShellScripts(join(projectDir, 'scripts', 'statusline'));
+        await mergeStatuslineSettings(projectDir);
+    }
     return count;
 }
 async function chmodShellScripts(dir) {
@@ -172,6 +200,55 @@ async function mergeSettingsHook(projectDir) {
     };
     await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
 }
+/**
+ * Wire the /contextmeter status line + awareness hook into settings.json (default-on).
+ * Mirrors mergeSettingsHook: set `statusLine` only when the project doesn't already have
+ * one (never clobber a user's), and append the UserPromptSubmit awareness hook unless an
+ * equivalent is already present (idempotent). Defaults (warn 80 / crit 92) live in the
+ * scripts, so the wired commands carry no env prefix.
+ */
+async function mergeStatuslineSettings(projectDir) {
+    const snippetPath = join(projectDir, 'scripts', 'statusline', 'settings-snippet.json');
+    const settingsPath = join(projectDir, '.claude', 'settings.json');
+    if (!existsSync(snippetPath))
+        return;
+    const snippet = JSON.parse(await readFile(snippetPath, 'utf-8'));
+    const snippetStatusLine = snippet?.statusLine;
+    const snippetUserPrompt = (snippet?.hooks?.UserPromptSubmit ?? []);
+    if (!snippetStatusLine && snippetUserPrompt.length === 0)
+        return;
+    let settings = {};
+    if (existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(await readFile(settingsPath, 'utf-8'));
+        }
+        catch {
+            // Existing settings.json is unreadable — leave it alone.
+            return;
+        }
+    }
+    else {
+        await mkdir(join(projectDir, '.claude'), { recursive: true });
+    }
+    // statusLine: never clobber a project's existing one.
+    if (snippetStatusLine && !settings.statusLine) {
+        settings.statusLine = snippetStatusLine;
+    }
+    // UserPromptSubmit: append the awareness hook unless an equivalent is already present.
+    const existingHooks = (settings.hooks ?? {});
+    const existingUserPrompt = (existingHooks.UserPromptSubmit ?? []);
+    const alreadyHasMeter = existingUserPrompt.some((entry) => {
+        const hooks = (entry?.hooks ?? []);
+        return hooks.some((h) => typeof h?.command === 'string' && h.command.includes('context-awareness-hook'));
+    });
+    if (!alreadyHasMeter && snippetUserPrompt.length > 0) {
+        settings.hooks = {
+            ...existingHooks,
+            UserPromptSubmit: [...existingUserPrompt, ...snippetUserPrompt],
+        };
+    }
+    await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+}
 // ── Identity Injection ───────────────────────────────────
 async function injectIdentity(projectDir, config) {
     const claudePath = join(projectDir, 'CLAUDE.md');

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

@@ -2,17 +2,36 @@
  * Update mechanisms — methodology update (replaces /void git-fetch),
  * self-update, and extension update.
  */
+import type { ClaudeMdAction } from './claude-md-strategy.js';
 export interface UpdatePlan {
     added: string[];
     modified: string[];
     removed: string[];
     unchanged: number;
+    /** Non-destructive CLAUDE.md handling (issue #368). */
+    claudeMd?: {
+        action: ClaudeMdAction;
+        droppedSections: string[];
+        warnings: string[];
+        /** Side file written instead of CLAUDE.md, relative to project root. */
+        sideFile?: string;
+    };
 }
 export interface UpdateResult {
     applied: boolean;
     plan: UpdatePlan;
     newVersion: string;
 }
+export type UpdateMode = 'help' | 'self' | 'extensions' | 'methodology';
+/**
+ * Decide which `update` mode the given argv selects. Pure — no I/O, no exit.
+ *
+ * Help MUST win over every action flag (issue #368): `update --help` printed
+ * usage but the OLD router fell through and EXECUTED the (destructive) update.
+ * Centralizing the precedence here makes that ordering testable and keeps the
+ * CLI from re-introducing the bug.
+ */
+export declare function resolveUpdateMode(args: string[]): UpdateMode;
 /**
  * Diff methodology source against project files.
  * Returns a plan showing what would change.