voidforge-build 23.19.0 → 23.20.0

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;

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' },