@vibecompass/vibecompass 0.11.2 → 0.13.0

package/CHANGELOG.md

@@ -2,6 +2,63 @@
 
 ## Unreleased
 
+## 0.13.0 - 2026-07-11
+
+- Architecture docs are now explicitly current-state contracts (D-292/D-293):
+  generated context/README/workflow guidance, the docs-update recommendations,
+  close-session guidance, and the docs-review prompt all state that updates
+  fold into existing sections in place — work/ship chronology goes to session
+  notes, decisions record accepted choices, and the doc keeps the durable
+  plan, unresolved next steps, and rollout state.
+- New advisory changelog-shape detection: the shared scanner emits one
+  aggregated `architecture-changelog-smell` warning per doc (conjunctive
+  line-local signals; fenced/inline code, comments, and blockquotes masked),
+  and `docs-review --apply-output` emits the matching
+  `changelog_shaped_architecture_doc` warning. Optional frontmatter
+  `content_mode: chronological-ledger` suppresses only this advisory;
+  explicit unknown/non-string values warn. Advisory-only — never gates
+  close-session or read-model projection.
+- `docs-update` affected docs now carry a self-describing
+  `size: { byteLength, softLimitBytes, exceedsSoftLimit }` advisory (the
+  12000-byte soft budget is hoisted from docs-review into the shared
+  scanner); a session-scoped size advisory renders in the plan instead of a
+  standing status warning.
+- Local docs-review prompt is v8; local parser is `docs-review-parser-v2`
+  (new warning codes). `detectChangelogShapedLines` and
+  `ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES` are exported as public API for
+  hosted-parser parity consumers.
+
+## 0.12.0 - 2026-07-10
+
+- New `vibecompass bootstrap --bundle <file>` materializes a complete local
+  root from a hosted bootstrap-export bundle (fail-closed hash validation,
+  verbatim writes, sync-cursor seeding for local-primary bundles).
+- New `vibecompass sync-adopt [--accept-divergence]` re-baselines a root's
+  sync cursor onto the hosted head after a divergence preview (D-215) — the
+  recovery path for fresh clones and second devices.
+- New `vibecompass promote-hosted [--resume|--abort]` and
+  `vibecompass demote-hosted [--accept-divergence]` run the D-288 two-phase
+  hosting-mode cutover: fresh verified baseline, server-side transition
+  intent with a completeness report, local flip + promoted-root marker, and
+  confirm — resumable after any crash and fully reversible.
+- Promoted roots hard-refuse canonical write commands (override with
+  VIBECOMPASS_ALLOW_PROMOTED_ROOT_WRITES=1); `vibecompass status` now checks
+  the hosted mode and warns on local/hosted mode mismatches.
+- `apply-export` pre-validates every operation before writing and treats
+  already-applied operations as converged, so retries after partial failure
+  succeed. `docs-review --apply-decision-artifact` is idempotent and
+  crash-safe (provenance Source line, marker repair, post-write verification,
+  code-enforced append-only) and warns on hosted-only roots.
+
+- The missing-sync-token error now explains how to recover: re-export the bound
+  env var, persist it in a shell profile, or rotate the token from the hosted
+  dashboard (previously a bare "requires VIBECOMPASS_SYNC_TOKEN" with no
+  guidance). README documents the persistence recipe.
+- AGENTS.md gains a release checklist, including verifying that
+  `vibecompass-mcp`'s dependency range still spans the new version so core
+  releases stop stranding the MCP package (its `^0.1.0` pin had drifted 27
+  releases behind).
+
 ## 0.11.2 - 2026-07-06
 
 - Complete the remaining Phase 8 start-session overlap warnings: lanes can now

package/README.md

@@ -250,6 +250,17 @@ changed canonical project-memory files and the hosted dashboard should catch
 up. Hosted-only projects do not use a local authoritative push; update or
 refresh them through the hosted dashboard/proposal flow.
 
+The sync token is read from the environment variable you bind (for example
+`VIBECOMPASS_SYNC_TOKEN`). One-off `export`s do not survive new terminals —
+persist the token in your shell profile (`~/.zshenv` or `~/.bashrc`):
+
+```bash
+echo 'export VIBECOMPASS_SYNC_TOKEN="<your sync token>"' >> ~/.zshenv
+```
+
+If the token is lost, rotate it on the hosted dashboard under Setup -> Hosted
+sync and export the new value.
+
 ### Multiple environments
 
 One project can have named sync targets (for example a local dev server and
@@ -283,12 +294,21 @@ import {
   scanProjectMemory,
   loadProjectReadModel,
   getProjectContext,
+  detectChangelogShapedLines,
+  ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES,
 } from "@vibecompass/vibecompass";
 ```
 
 Use the JavaScript API when building tools that need to inspect or manage a
 local VibeCompass project-memory root.
 
+`detectChangelogShapedLines(body)` takes architecture-doc body text (frontmatter
+already stripped) and returns the changelog-shaped lines it matched — the same
+D-292 advisory detector the scanner and `docs-review --apply-output` use, shared
+so external validators (for example the hosted proposal parser) stay in parity.
+`ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES` is the byte-valued soft size budget
+(12000) both docs-review apply warnings and the docs-update size advisory read.
+
 ## More Documentation
 
 - Developer guide: https://vibecompass.dev/developers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibecompass/vibecompass",
-  "version": "0.11.2",
+  "version": "0.13.0",
   "description": "Local-first project-memory core for VibeCompass",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -17,8 +17,11 @@ import { getProjectStatus, renderStatusText, toStatusJson } from './status.js';
 import { refreshWorkflow } from './refresh-workflow.js';
 import { inspectProjectCompatibility, formatCompatibilityWarnings } from './compatibility.js';
 import { PACKAGE_VERSION } from './version.js';
+import { demoteHosted, promoteHosted } from './mode-transition.js';
 import {
+  adoptRemoteHead,
   applyPullExport,
+  bootstrapFromBundle,
   pullExportProjectMemory,
   pullPreviewProjectMemory,
   pushProjectMemory,
@@ -437,6 +440,71 @@ export async function runCli(argv, io = createDefaultIo(), runtime = {}) {
     return 0;
   }
 
+  if (parsed.command === 'promote-hosted' || parsed.command === 'demote-hosted') {
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
+    const run = parsed.command === 'promote-hosted' ? promoteHosted : demoteHosted;
+    const result = await run(parsed.options, {
+      cwd: runtime.cwd,
+      env: runtime.env,
+      runtime,
+    });
+    io.stdout.write(`Mode transition: ${result.status}\n`);
+    if (result.completeness) {
+      io.stdout.write(`Carries over: ${result.completeness.carries_over}\n`);
+      for (const [kind, total] of Object.entries(result.completeness.documents_by_kind ?? {})) {
+        io.stdout.write(`  ${kind}: ${total}\n`);
+      }
+      io.stdout.write('Does not carry over:\n');
+      for (const item of result.completeness.does_not_carry_over ?? []) {
+        io.stdout.write(`  - ${item}\n`);
+      }
+    }
+    for (const warning of result.warnings) {
+      io.stdout.write(`Note: ${warning}\n`);
+    }
+    io.stdout.write(`${result.message}\n`);
+    return 0;
+  }
+
+  if (parsed.command === 'sync-adopt') {
+    await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
+    const result = await adoptRemoteHead(parsed.options, {
+      cwd: runtime.cwd,
+      env: runtime.env,
+      runtime,
+    });
+    io.stdout.write(`Sync adopt: ${result.status}\n`);
+    io.stdout.write(`Adopted head: ${result.remoteRevisionId}\n`);
+    io.stdout.write(`Recorded ${result.manifestPath}\n`);
+    for (const warning of result.warnings) {
+      io.stdout.write(`Warning: ${warning}\n`);
+    }
+    io.stdout.write(`${result.message}\n`);
+    return 0;
+  }
+
+  if (parsed.command === 'bootstrap') {
+    const result = await bootstrapFromBundle(parsed.options, {
+      cwd: runtime.cwd,
+      env: runtime.env,
+      runtime,
+    });
+    io.stdout.write(`Bootstrap: ${result.status}\n`);
+    io.stdout.write(`Root: ${result.rootDir}\n`);
+    io.stdout.write(`Documents: ${result.documentCount}\n`);
+    if (result.mode) {
+      io.stdout.write(`Mode: ${result.mode}\n`);
+    }
+    if (result.manifestPath) {
+      io.stdout.write(`Recorded ${result.manifestPath}\n`);
+    }
+    for (const warning of result.warnings) {
+      io.stdout.write(`Warning: ${warning}\n`);
+    }
+    io.stdout.write(`${result.message}\n`);
+    return 0;
+  }
+
   if (parsed.command === 'pull-preview') {
     await writeCompatibilityPreflightWarnings(io, parsed.options, runtime);
     const result = await pullPreviewProjectMemory(parsed.options, {
@@ -708,6 +776,18 @@ export function parseCliArgs(argv) {
       return parsePushArgs(rest);
     }
 
+    if (command === 'promote-hosted' || command === 'demote-hosted') {
+      return parseModeTransitionArgs(command, rest);
+    }
+
+    if (command === 'sync-adopt') {
+      return parseSyncAdoptArgs(rest);
+    }
+
+    if (command === 'bootstrap') {
+      return parseBootstrapArgs(rest);
+    }
+
     if (command === 'pull-preview') {
       return parsePullPreviewArgs(rest);
     }
@@ -1776,6 +1856,122 @@ function parseDocsReviewArgs(argv) {
   };
 }
 
+function parseModeTransitionArgs(command, argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith('--')) {
+      throw new Error(`Unexpected argument "${token}".`);
+    }
+
+    if (token === '--resume') {
+      parsed.resume = true;
+      continue;
+    }
+    if (token === '--abort') {
+      parsed.abort = true;
+      continue;
+    }
+    if (token === '--accept-divergence') {
+      parsed.acceptDivergence = true;
+      continue;
+    }
+
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw new Error(`Flag "${token}" requires a value.`);
+    }
+    index += 1;
+
+    switch (token) {
+      case '--root':
+        parsed.rootDir = value;
+        break;
+      case '--sync-target':
+        parsed.syncTarget = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}" for ${command}.`);
+    }
+  }
+
+  return { command, options: parsed };
+}
+
+function parseSyncAdoptArgs(argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith('--')) {
+      throw new Error(`Unexpected argument "${token}".`);
+    }
+
+    if (token === '--accept-divergence') {
+      parsed.acceptDivergence = true;
+      continue;
+    }
+
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw new Error(`Flag "${token}" requires a value.`);
+    }
+    index += 1;
+
+    switch (token) {
+      case '--root':
+        parsed.rootDir = value;
+        break;
+      case '--sync-target':
+        parsed.syncTarget = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}" for sync-adopt.`);
+    }
+  }
+
+  return {
+    command: 'sync-adopt',
+    options: parsed,
+  };
+}
+
+function parseBootstrapArgs(argv) {
+  const parsed = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith('--')) {
+      throw new Error(`Unexpected argument "${token}".`);
+    }
+    const value = argv[index + 1];
+    if (value === undefined) {
+      throw new Error(`Flag "${token}" requires a value.`);
+    }
+    index += 1;
+
+    switch (token) {
+      case '--root':
+        parsed.rootDir = value;
+        break;
+      case '--bundle':
+        parsed.bundlePath = value;
+        break;
+      case '--sync-target':
+        parsed.syncTarget = value;
+        break;
+      default:
+        throw new Error(`Unknown flag "${token}" for bootstrap.`);
+    }
+  }
+
+  return {
+    command: 'bootstrap',
+    options: parsed,
+  };
+}
+
 function parsePushArgs(argv) {
   return {
     command: 'push',
@@ -2183,6 +2379,10 @@ function usageText() {
     '  vibecompass next-decision-id [options]',
     '  vibecompass sync-agents [options]',
     '  vibecompass push [options]',
+    '  vibecompass bootstrap --bundle <file> [--root <dir>]',
+    '  vibecompass sync-adopt [--accept-divergence] [options]',
+    '  vibecompass promote-hosted [--resume|--abort] [options]',
+    '  vibecompass demote-hosted [--accept-divergence] [options]',
     '  vibecompass pull-preview [options]',
     '  vibecompass pull-export [options]',
     '  vibecompass apply-export [options]',

package/src/docs-review.js

@@ -4,7 +4,11 @@ import { createInterface } from 'node:readline/promises';
 import { parseFrontmatter } from './frontmatter.js';
 import { sha256Text } from './hash.js';
 import { writeStateManifest } from './manifest.js';
-import { scanProjectMemory } from './project-memory.js';
+import {
+  ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES,
+  detectChangelogShapedLines,
+  scanProjectMemory,
+} from './project-memory.js';
 import { parseSimpleYaml } from './simple-yaml.js';
 import {
   buildDocsReviewSourceInventory,
@@ -20,12 +24,11 @@ import { withMemoryRootLock } from './serialization.js';
 import { listDecisionFileNames, readNextDecisionId } from './decisions.js';
 import { looksLikeGroupedDecisionIndex } from './decision-index.js';
 
-const DOCS_REVIEW_PROMPT_VERSION = 'VibeCompass Docs Review Prompt v7';
-const DOCS_REVIEW_PARSER_VERSION = 'docs-review-parser-v1';
+const DOCS_REVIEW_PROMPT_VERSION = 'VibeCompass Docs Review Prompt v8';
+const DOCS_REVIEW_PARSER_VERSION = 'docs-review-parser-v2';
 const DOCS_REVIEW_ACCEPTED_OUTPUT_CONTRACT_VERSION = 'docs-review-accepted-output-v7';
 const DOCS_REVIEW_DOCUMENTATION_PLAN_PROJECTION_VERSION = 'docs-review-documentation-plan-v1';
 const DOCUMENTATION_PLAN_STATE_VERSION = 1;
-const ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES = 12000;
 const COVERAGE_PLAN_OUTPUT_VERSION = 1;
 const COVERAGE_PLAN_STATUSES = new Set(['accepted', 'deferred', 'missing']);
 const COVERAGE_LEVELS = new Set(['comprehensive', 'partial', 'initial', 'missing']);
@@ -434,6 +437,15 @@ async function applyDecisionArtifactLocked(options) {
     throw new Error(`Decision artifact ${artifactId} must include a non-empty rationale before it can be appended locally.`);
   }
 
+  // Idempotency guard: never append the same artifact twice. The marker is
+  // the fast path; the file-content check covers a crash between the file
+  // write and the marker update.
+  if (artifact.local_status === 'applied') {
+    throw new Error(
+      `Decision artifact ${artifactId} is already applied locally as ${artifact.local_decision_id ? `decision ${artifact.local_decision_id}` : 'a decision entry'}. Re-applying would append a duplicate entry.`,
+    );
+  }
+
   const nextDecisionId = await readNextDecisionId(options.rootDir);
   const targetFilePath = path.join(options.rootDir, targetPath);
   await mkdir(path.dirname(targetFilePath), { recursive: true });
@@ -446,27 +458,99 @@ async function applyDecisionArtifactLocked(options) {
     existingContent = `# ${path.basename(targetPath, '.md')} decisions\n`;
   }
 
-  const entry = renderDecisionEntry({
-    decisionId: nextDecisionId,
-    title,
-    decision,
-    rationale,
-    context,
-    artifactId,
-  });
-  await writeFile(targetFilePath, `${existingContent.trimEnd()}\n\n${entry}`, 'utf8');
-  const indexResult = options.refreshIndex
-    ? await refreshDecisionIndex(options.rootDir)
-    : {
+  const applyWarnings = [];
+  const alreadyInFile = existingContent.includes(
+    `hosted docs-review artifact ${artifactId}`,
+  );
+  let appliedDecisionIdForMarker = nextDecisionId;
+
+  if (alreadyInFile) {
+    // A previous apply wrote the file but crashed before recording the
+    // marker. Repair the marker instead of appending a duplicate.
+    applyWarnings.push(
+      `Artifact ${artifactId} was already present in ${targetPath}; repaired the marker without appending a duplicate entry.`,
+    );
+    const existingIdMatch = existingContent.match(
+      new RegExp(
+        `### (D-\\d+)[^\\n]*(?:\\n(?!### ).*)*hosted docs-review artifact ${artifactId.replaceAll(/[.*+?^${}()|[\\]\\\\]/g, '\\$&')}`,
+      ),
+    );
+    appliedDecisionIdForMarker = existingIdMatch
+      ? Number.parseInt(existingIdMatch[1].slice(2), 10)
+      : nextDecisionId;
+  } else {
+    const entry = renderDecisionEntry({
+      decisionId: nextDecisionId,
+      title,
+      decision,
+      rationale,
+      context,
+      artifactId,
+    });
+    const nextContent = `${existingContent.trimEnd()}\n\n${entry}`;
+    // Append-only enforced in code, not just convention: the previous file
+    // content must survive verbatim as a prefix of what we write.
+    if (!nextContent.startsWith(existingContent.trimEnd())) {
+      throw new Error(
+        `Refusing to apply artifact ${artifactId}: the write would not preserve the existing content of ${targetPath} (decisions are append-only).`,
+      );
+    }
+    await writeFile(targetFilePath, nextContent, 'utf8');
+
+    // Post-write verification: the canonical write must be durable and
+    // intact before the marker records the artifact as applied.
+    const verification = await readFile(targetFilePath, 'utf8');
+    if (verification !== nextContent) {
+      throw new Error(
+        `Post-write verification failed for ${targetPath}: the file on disk does not match the appended content. The marker was NOT updated; inspect the file and retry.`,
+      );
+    }
+  }
+
+  // Hosted-only roots can apply locally but can never push the result back
+  // until the project is demoted to local-primary — say so instead of letting
+  // the user discover it at push time.
+  try {
+    const projectConfig = parseSimpleYaml(
+      await readFile(path.join(options.rootDir, 'project.yaml'), 'utf8'),
+      { sourceName: 'project.yaml' },
+    );
+    if (projectConfig?.mode === 'hosted-only') {
+      applyWarnings.push(
+        'This is a hosted-only project: the locally applied decision cannot be pushed back to the hosted canonical store. The hosted copy was already recorded when the artifact was accepted; treat this local root as a working copy.',
+      );
+    }
+  } catch {
+    // Unreadable project.yaml is surfaced by other commands; not fatal here.
+  }
+
+  let indexResult;
+  if (options.refreshIndex) {
+    try {
+      indexResult = await refreshDecisionIndex(options.rootDir);
+    } catch (error) {
+      // An index-refresh failure after a verified canonical write must not
+      // strand the marker (a retry would duplicate the entry): degrade to a
+      // warning and keep going.
+      indexResult = {
+        refreshed: false,
+        warnings: [
+          `decisions/INDEX.md refresh failed after the entry was appended: ${error.message}. Run vibecompass refresh-decision-index manually.`,
+        ],
+      };
+    }
+  } else {
+    indexResult = {
       refreshed: false,
       warnings: [
         'decisions/INDEX.md was not refreshed. Run again with --refresh-index if this root uses the package-generated flat index, or update the project-specific index manually.',
       ],
     };
+  }
 
   const appliedDecisionArtifact = {
     artifact_id: artifactId,
-    decision_id: nextDecisionId,
+    decision_id: appliedDecisionIdForMarker,
     target_path: targetPath,
     applied_at: new Date().toISOString(),
     refreshed_index: indexResult.refreshed,
@@ -478,7 +562,7 @@ async function applyDecisionArtifactLocked(options) {
       ...current.hosted,
       artifacts: (current.hosted?.artifacts ?? []).map((item) =>
         item?.artifact_id === artifactId
-          ? { ...item, local_status: 'applied', local_decision_id: nextDecisionId }
+          ? { ...item, local_status: 'applied', local_decision_id: appliedDecisionIdForMarker }
           : item,
       ),
     },
@@ -494,8 +578,10 @@ async function applyDecisionArtifactLocked(options) {
     hosted: current.hosted ?? null,
     appliedDecisionArtifact,
     reviewPrompt: null,
-    warnings: indexResult.warnings,
-    message: `Applied decision artifact ${artifactId} as D-${String(nextDecisionId).padStart(3, '0')} in ${targetPath}.`,
+    warnings: [...applyWarnings, ...indexResult.warnings],
+    message: alreadyInFile
+      ? `Repaired the marker for decision artifact ${artifactId} (already present in ${targetPath} as D-${String(appliedDecisionIdForMarker).padStart(3, '0')}).`
+      : `Applied decision artifact ${artifactId} as D-${String(appliedDecisionIdForMarker).padStart(3, '0')} in ${targetPath}.`,
   };
 }
 
@@ -1413,6 +1499,24 @@ function createArchitectureDocQualityWarnings(blocks) {
     ) {
       warnings.push(`missing_repo_scope: ${block.path} should declare repo or repos in frontmatter when implementation-scoped.`);
     }
+
+    let contentMode = null;
+    if (Object.hasOwn(data, 'content_mode')) {
+      const rawContentMode = data.content_mode;
+      contentMode = typeof rawContentMode === 'string' ? rawContentMode.trim() : null;
+      if (contentMode !== 'chronological-ledger') {
+        const rendered = typeof rawContentMode === 'string' ? `"${rawContentMode}"` : JSON.stringify(rawContentMode) ?? 'undefined';
+        warnings.push(`unknown_content_mode: ${block.path} declares content_mode ${rendered}; the recognized value is "chronological-ledger" (absence means current-state).`);
+        contentMode = null;
+      }
+    }
+    if (contentMode !== 'chronological-ledger') {
+      const changelogLines = detectChangelogShapedLines(body);
+      if (changelogLines.length > 0) {
+        const example = changelogLines[0].length > 80 ? `${changelogLines[0].slice(0, 77)}...` : changelogLines[0];
+        warnings.push(`changelog_shaped_architecture_doc: ${block.path} contains ${changelogLines.length} changelog-shaped line(s) (e.g. "${example}"); architecture docs are current-state contracts (D-292) — fold the content into the existing sections and move work/ship chronology to the session note; decisions record accepted choices (D-293). Intentionally dated ledgers/reports declare content_mode: chronological-ledger.`);
+      }
+    }
   }
 
   return warnings;
@@ -1972,6 +2076,10 @@ function renderDecisionEntry(options) {
     `**Decision:** ${options.decision}`,
     `**Rationale:** ${options.rationale}`,
     ...(options.context ? [`**Context:** ${options.context}`] : []),
+    // Provenance makes re-application detectable from the file itself, so a
+    // crash between the file write and the marker update can never cause a
+    // silent duplicate append on retry.
+    ...(options.artifactId ? [`**Source:** hosted docs-review artifact ${options.artifactId}`] : []),
     '',
   ].join('\n');
 }
@@ -2246,7 +2354,7 @@ function renderAnchorContext(anchors) {
     '',
     'Required prior-doc classifications for Stage 2:',
     '- `reuse`: keep path/frontmatter identity and update only if needed',
-    '- `update`: keep path/frontmatter identity but refresh content or coverage',
+    '- `update`: keep path/frontmatter identity but refresh content or coverage by rewriting the affected sections in place — deepening or audit findings fold into the current contract, never an appended dated section',
     '- `split`: replace one broad prior doc with multiple focused docs',
     '- `merge`: combine overlapping prior docs',
     '- `defer`: leave prior area documented but out of the accepted generation scope',
@@ -2445,7 +2553,7 @@ function renderReviewPrompt(options) {
     '- Propose the smallest useful architecture-doc set that will let future agents understand the project and retrieve targeted context.',
     '- The minimum useful set must cover: user journey, project/system map (frontend/backend/API/data/integration structure and connections), and summaries of the core journey-facing features.',
     '- Treat Stage 2 as a documentation-plan gate: each proposed doc needs a title, target path, purpose, parent/backbone grouping, linked inventory ids, evidence set, expected coverage level, prior-anchor action, and `baseline` or `deepening` run scope.',
-    '- Keep baseline docs breadth-first and compact. Use `deepening` only for scoped follow-up docs that should not block the first project-understanding baseline.',
+    '- Keep baseline docs breadth-first and compact. Use `deepening` only for scoped follow-up docs that should not block the first project-understanding baseline. Deepening output still rewrites existing docs in place or creates new focused docs; it never appends dated audit/session sections to an existing doc.',
     '- Prioritize entry points, user-flow/gating relationships, data ownership, external integrations, jobs/async boundaries, auth/security boundaries, and test surfaces.',
     '- Account for each completeness-inventory item in the coverage plan as accepted, deferred, or missing. Do not inflate coverage by omitting large discovered subsystems; honest deferred/missing entries are expected when the first pass cannot cover everything.',
     '- Before generating prose, self-check that every `completeness_inventory[].coverage_area_ids[]` value points to an `areas[].id` in the same accepted plan. Fix all dangling ids together at the plan gate.',
@@ -2463,6 +2571,7 @@ function renderReviewPrompt(options) {
     '- Ensure `architecture/overview/project-shape.md` includes compact backbone sections for topology, core feature inventory, user journey map, project systems map, and coverage/quality summary.',
     '- Ensure `architecture/overview/project-shape.md` includes exactly one `vibecompass-project-map version=1` JSON fence that lists journey-facing features, supported feature relationships, and minimal optional derived `systems[]` metadata.',
     '- Keep docs concise and retrieval-oriented: explain contracts, flows, invariants, and ownership; do not rewrite source code or produce file-by-file walkthroughs.',
+    '- Write every doc as a current-state contract (D-292): when updating an existing doc, rewrite the affected sections in place or propose a new focused doc — never append dated session/audit sections (for example "Audit deepening — YYYY-MM-DD"). Keep the durable plan, unresolved next steps, and material rollout state in the doc; work/ship chronology belongs in session notes, and decision entries record accepted choices (D-293). Intentionally dated ledgers/reports declare frontmatter `content_mode: chronological-ledger`.',
     `- Soft size budget: keep each generated architecture doc under ${ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES} bytes unless the extra detail is necessary and called out in Blindspots or Retrieval guidance.`,
     '- Include only the most important involved files; prefer representative entry points and owned contracts over exhaustive file lists.',
     '- Do not put transient apply-state instructions inside architecture docs, such as "this artifact has not been applied". Apply state belongs in the chat response and package marker, not canonical docs.',

package/src/docs-update.js

@@ -5,7 +5,7 @@ import { promisify } from 'node:util';
 import { parseFrontmatter } from './frontmatter.js';
 import { readCurrentRepoHead, resolveRepoSourceDir } from './git-binding.js';
 import { resolveLaneMarkerContext, resolveLaneSelection } from './lane-marker.js';
-import { scanProjectMemory } from './project-memory.js';
+import { ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES, scanProjectMemory } from './project-memory.js';
 import { parseSimpleYaml } from './simple-yaml.js';
 
 const execFileAsync = promisify(execFile);
@@ -140,6 +140,9 @@ export function renderDocsUpdatePlan(plan) {
       if (doc.qualityWarnings.length > 0) {
         lines.push(`  - quality warnings: ${doc.qualityWarnings.map((warning) => warning.code).join(', ')}`);
       }
+      if (doc.size?.exceedsSoftLimit) {
+        lines.push(`  - size advisory: ${doc.size.byteLength} bytes exceeds the ${doc.size.softLimitBytes}-byte soft budget; this session is about to edit the doc — split it into focused component docs or trim low-value detail while folding in changes.`);
+      }
     }
   }
 
@@ -817,6 +820,7 @@ function summarizeArchitectureDocument(document) {
     feature: normalizeOptionalString(data.feature),
     component: normalizeOptionalString(data.component),
     involvedFiles: extractInvolvedFiles(frontmatter.body),
+    byteLength: document.byteLength,
     warnings: document.warnings,
   };
 }
@@ -853,6 +857,14 @@ function findAffectedArchitectureDocs(docs, delta) {
         path: doc.path,
         reasons: Array.from(new Set(reasons)),
         qualityWarnings: doc.warnings,
+        // Session-scoped size advisory (D-292): surfaced only for docs the
+        // session is about to touch, deliberately not a standing status
+        // check. Self-describing so every renderer reads the same values.
+        size: {
+          byteLength: typeof doc.byteLength === 'number' ? doc.byteLength : null,
+          softLimitBytes: ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES,
+          exceedsSoftLimit: typeof doc.byteLength === 'number' && doc.byteLength > ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES,
+        },
       };
     })
     .filter((doc) => doc.reasons.length > 0)
@@ -906,9 +918,9 @@ function buildRecommendations(options) {
   const recommendations = [];
 
   if (options.affectedArchitectureDocs.length > 0) {
-    recommendations.push('Review and update the affected architecture docs listed above, then close with --architecture-docs updated.');
+    recommendations.push('Fold the session changes into the affected architecture docs as current-state contracts — rewrite sections in place, keep the durable plan/next steps/rollout state in the doc, and move work/ship chronology to the session note (D-292, D-293) — then close with --architecture-docs updated.');
   } else if (options.changedFiles.length > 0 && options.affectedArchitectureDocs.length === 0) {
-    recommendations.push('No matching architecture doc was found for the session delta; create a focused doc, mark docs not-needed with evidence, or defer explicitly.');
+    recommendations.push('No matching architecture doc was found for the session delta; create a focused doc written as a current-state contract, mark docs not-needed with evidence, or defer explicitly.');
   } else {
     recommendations.push('No architecture doc update is indicated by the current delta; close with --architecture-docs not-needed if that remains true.');
   }

package/src/index.js

@@ -6,13 +6,20 @@ export { getProjectStatus, renderStatusText, toStatusJson } from './status.js';
 export { initializeProjectMemory } from './init.js';
 export { preflightDocsReview } from './docs-review.js';
 export { planDocsUpdate, renderDocsUpdatePlan } from './docs-update.js';
+export { demoteHosted, promoteHosted } from './mode-transition.js';
 export {
+  adoptRemoteHead,
   applyPullExport,
+  bootstrapFromBundle,
   pullExportProjectMemory,
   pullPreviewProjectMemory,
   pushProjectMemory,
 } from './sync.js';
-export { scanProjectMemory } from './project-memory.js';
+export {
+  ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES,
+  detectChangelogShapedLines,
+  scanProjectMemory,
+} from './project-memory.js';
 export {
   closeProjectSession,
   listProjectSessions,