voidforge-build 23.18.0 → 23.20.0

package/dist/docs/patterns/multi-tenant-property-test.ts

@@ -34,6 +34,20 @@ declare const harness: {
   listAllReadEndpoints(): string[];
   listAllWriteEndpoints(): string[];
   resetDb(): Promise<void>;
+
+  // ── Handler-entry (HTTP-level) harness — field report #371 ──────────────
+  // Drives the REAL request entrypoint with a concrete credential, so the
+  // auth→uid wiring is exercised (not just the repository's WHERE org_id).
+  // `principal` is whatever the entrypoint actually authenticates with: a
+  // bearer token, a session cookie, an API key header — give two DISTINCT ones.
+  httpRequest(
+    principal: { headers: Record<string, string> },
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE',
+    path: string,
+    body?: unknown,
+  ): Promise<{ status: number; json: unknown }>;
+  // Two distinct, real principals for the SAME logical resource owner vs other.
+  principalForOrg(org: { apiKey: string; userId: string }): { headers: Record<string, string> };
 };
 
 // ── The Property ─────────────────────────────────────────────────────────
@@ -85,6 +99,43 @@ describe('multi-tenant isolation property', () => {
     const rowsB = await harness.readAsOrg(orgB, '/api/people');
     expect(rowsB.find((r) => r.org_id === orgA.id)).toBeUndefined();
   });
+
+  // ── Handler-entry two-principal variant (field report #371) ──────────────
+  // The repository-layer property above can pass while a handler that hardcodes
+  // `uid = 1` leaks across tenants — the repo test never crosses the auth→uid
+  // seam. This variant drives the REAL HTTP entrypoint with TWO DISTINCT
+  // credentials and asserts isolation through the request path. It is the test
+  // that the planted-bug check below must turn red.
+  test('two distinct principals through the real handler do not cross tenants', async () => {
+    const orgA = await harness.createOrg();
+    const orgB = await harness.createOrg();
+    const pA = harness.principalForOrg(orgA);
+    const pB = harness.principalForOrg(orgB);
+
+    // A writes through the real entrypoint with A's own credential.
+    const created = await harness.httpRequest(pA, 'POST', '/api/people', { name: 'A-secret' });
+    expect(created.status).toBeLessThan(300);
+    const writtenId = (created.json as { id: string }).id;
+
+    // B reads every list endpoint through the real entrypoint with B's credential.
+    for (const readEndpoint of harness.listAllReadEndpoints()) {
+      const res = await harness.httpRequest(pB, 'GET', readEndpoint);
+      const rows = Array.isArray(res.json) ? (res.json as Array<{ id?: string }>) : [];
+      expect(rows.find((r) => r.id === writtenId)).toBeUndefined();
+    }
+
+    // Cross-principal direct fetch: B asking for A's row by id must 404, not 403
+    // (404 avoids leaking existence — see CLAUDE.md "Return 404, not 403").
+    const direct = await harness.httpRequest(pB, 'GET', `/api/people/${writtenId}`);
+    expect(direct.status).toBe(404);
+  });
+
+  // PLANTED-BUG RED-CHECK (field report #371): hardcoding `uid = <owner>` in the
+  // handler MUST turn the two-principal test above RED. If you can introduce
+  // that bug and the suite stays green, your isolation test is not crossing the
+  // auth→uid seam — it is asserting at the repository layer only. Run this once
+  // as a mutation check: patch the handler to ignore the authenticated principal
+  // and pin uid to org A's id; the test above must fail. Revert after proving it.
 });
 
 function randomPayload(): fc.Arbitrary<unknown> {
@@ -112,8 +163,21 @@ function randomPayload(): fc.Arbitrary<unknown> {
 //         assert not any(r['id'] == written['id'] for r in rows_b), \
 //             f"LEAK: {write_endpoint} -> {read_endpoint}"
 //
+// # Handler-entry two-principal variant (field report #371) — drive the real
+// # entrypoint (FastAPI TestClient / Django test Client) with two distinct
+// # credentials, NOT the repository:
+// #   ra = client.post('/api/people', json={'name': 'A'}, headers=princ_a)
+// #   rb = client.get(f"/api/people/{ra.json()['id']}", headers=princ_b)
+// #   assert rb.status_code == 404      # not 403 — don't leak existence
+// # Mutation check: pin uid=<owner> in the handler; this MUST go red.
+//
 // ── Anti-patterns ────────────────────────────────────────────────────────
 //
+// 0. Asserting isolation only at the repository layer. A handler that
+//    hardcodes uid=1 passes every repo-level test while leaking across
+//    tenants. The isolation test MUST drive the real request entrypoint with
+//    two distinct principals (field report #371). Prove it with the planted
+//    uid red-check.
 // 1. Testing isolation only on known endpoints. The bug is in the endpoint
 //    you forgot. Property tests enumerate the full surface.
 // 2. Using SUPERUSER fixtures. They silently bypass FORCE RLS at the engine

package/dist/docs/patterns/oauth-token-lifecycle.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)
  *
@@ -50,6 +64,13 @@ interface PlatformTokenConfig {
   revokeEndpoint?: string;
 }
 
+// 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: PlatformTokenConfig[] = [
   { 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/scripts/statusline/README.md

@@ -0,0 +1,38 @@
+# Context Meter — status line + awareness hook
+
+Two small scripts that surface how full the context window is — one for the human, one for the model.
+
+| Script | Wired to | Audience | What it does |
+|--------|----------|----------|--------------|
+| `voidforge-statusline.sh` | `statusLine` (settings.json) | you | Renders one line: model + a colored meter (`⟦████████░░⟧ 78%`) + tokens remaining. Green → yellow → red as the window fills. |
+| `context-awareness-hook.sh` | `UserPromptSubmit` hook | Claude | Once usage crosses a threshold, injects "you have ~X% left, checkpoint soon" into the model's own context each turn. Silent below the threshold. |
+
+The model can't see its own remaining context. The status line tells *you*; the hook tells *Claude* — so it can wrap up open loops and suggest `/vault` or `/seal` before compaction instead of being surprised by it.
+
+## Install
+
+**Default-on.** `npx voidforge-build init` already wires both scripts into a new project's `.claude/settings.json` (warn 80% / crit 92%). Nothing to do for a fresh project.
+
+To re-install, retune, or activate on a project that predates this feature, run **`/contextmeter`** — it chmods these scripts and merges the right block into `.claude/settings.json`. Or wire it by hand: merge `settings-snippet.json` into `.claude/settings.json`. Remove with `/contextmeter --uninstall`.
+
+## How it reads context
+
+- **Status line:** prefers the native `context_window` object Claude Code pipes on stdin (`used_percentage`, `context_window_size`). Falls back to deriving usage from the most recent assistant `message.usage` in `transcript_path` on older Claude Code that doesn't send the field.
+- **Hook:** the hook stdin has no `context_window` object, so it always derives from `transcript_path` (`input_tokens + cache_read_input_tokens + cache_creation_input_tokens`).
+- 1M-token sessions are detected automatically (usage above 200k ⇒ 1,000,000 denominator), or set `VOIDFORGE_CONTEXT_WINDOW`.
+
+## Tuning (env)
+
+| Var | Default | Effect |
+|-----|---------|--------|
+| `VOIDFORGE_CONTEXT_WINDOW` | `200000` | Denominator when the size field is absent. |
+| `VOIDFORGE_CONTEXT_WARN_PCT` | `80` | Hook starts speaking — and the meter turns yellow — at this % used. |
+| `VOIDFORGE_CONTEXT_CRIT_PCT` | `92` | Hook escalates to "checkpoint NOW" — and the meter turns red — at this %. |
+
+Both scripts read the same two thresholds, so the meter's yellow/red bands stay in lockstep with the hook's warn/critical bands. `/contextmeter --warn-pct N` / `--crit-pct N` bake these into the command strings in settings.json so they persist without a shell export.
+
+## Requirements & caveats
+
+- **`jq`** is required. Without it the status line prints a one-line "install jq" notice and the hook no-ops — neither ever breaks your session.
+- Only the **first line** of status-line stdout is shown by Claude Code, so the meter is deliberately single-line.
+- **Name:** this ships as `/contextmeter`, not `/statusline` — Claude Code's native `/statusline` and `/context` commands always shadow a same-named project command (see `docs/NATIVE_CAPABILITIES.md`).

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;