@vibecompass/vibecompass 0.12.0 → 0.13.1

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 ## Unreleased
 
+## 0.13.1 - 2026-09-11
+
+- Add strict backward compatibility for intentional legacy recovery checkpoints
+  at root `sessions/YYYY-MM-DD.md` paths with an exact
+  `# Recovery checkpoint — YYYY-MM-DD — <title>` H1; project them with their
+  matching `session_date`, title, and
+  `session_number: null` without inventing numbered-session chronology.
+- Preserve fail-closed behavior for malformed, mismatched, untitled, or nested
+  recovery checkpoints and all existing numbered-session behavior, with focused
+  parser, manifest, read-model, and session-lifecycle regression coverage.
+
+## 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

package/README.md

@@ -294,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.12.0",
+  "version": "0.13.1",
   "description": "Local-first project-memory core for VibeCompass",
   "type": "module",
   "bin": {

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']);
@@ -1496,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;
@@ -2333,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',
@@ -2532,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.',
@@ -2550,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

@@ -15,7 +15,11 @@ export {
   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,

package/src/project-memory.js

@@ -5,6 +5,15 @@ import { sha256Text } from './hash.js';
 import { parseSimpleYaml } from './simple-yaml.js';
 
 const PROJECT_FILE = 'project.yaml';
+// Shared soft size budget for architecture docs (docs-review apply and the
+// docs-update affected-doc advisory read the same threshold).
+export const ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES = 12000;
+const KNOWN_ARCHITECTURE_CONTENT_MODES = new Set(['chronological-ledger']);
+const ISO_DATE_PATTERN = /\b\d{4}-\d{2}-\d{2}\b/;
+const HEADING_CHRONOLOGY_CUES = /\b(audit deepening|updated|fixes|fixed|shipped|done|completed|activation gate)\b/i;
+// ATX heading start: 1-6 hashes followed by space, tab, or end of line
+// (CommonMark permits bare `#`..`######`); deliberately not broad \s.
+const ATX_HEADING_START = /^#{1,6}([ \t]|$)/;
 const NON_CANONICAL_DECISION_FILES = new Set(['EXAMPLE.md', 'INDEX.md', 'README.md']);
 const NON_CANONICAL_SESSION_FILES = new Set(['wip.md', 'handoff.md', 'README.md']);
 const NON_CANONICAL_ARCHITECTURE_FILES = new Set(['README.md']);
@@ -462,6 +471,24 @@ function parseArchitectureDocument(options) {
       );
     }
 
+    // Only an absent content_mode key means current-state; any explicit value
+    // that is not the exact string "chronological-ledger" warns (D-292).
+    let contentMode = null;
+    if (Object.hasOwn(data, 'content_mode')) {
+      const rawContentMode = data.content_mode;
+      contentMode = typeof rawContentMode === 'string' ? rawContentMode.trim() : null;
+      if (!contentMode || !KNOWN_ARCHITECTURE_CONTENT_MODES.has(contentMode)) {
+        const rendered = typeof rawContentMode === 'string' ? `"${rawContentMode}"` : JSON.stringify(rawContentMode) ?? 'undefined';
+        warnings.push(
+          createWarning(
+            'architecture-unknown-content-mode',
+            `Unknown architecture content_mode ${rendered}; the recognized value is "chronological-ledger" (absence means current-state).`,
+          ),
+        );
+        contentMode = null;
+      }
+    }
+
     const sections = extractLevelTwoSections(frontmatter.body);
     for (const section of RECOMMENDED_ARCHITECTURE_SECTIONS) {
       if (!sections.has(section.toLowerCase())) {
@@ -508,6 +535,21 @@ function parseArchitectureDocument(options) {
       );
     }
 
+    // D-292: architecture docs are current-state contracts; one aggregated
+    // advisory per doc, suppressed only by content_mode: chronological-ledger.
+    if (contentMode !== 'chronological-ledger') {
+      const changelogLines = detectChangelogShapedLines(frontmatter.body);
+      if (changelogLines.length > 0) {
+        const example = changelogLines[0].length > 80 ? `${changelogLines[0].slice(0, 77)}...` : changelogLines[0];
+        warnings.push(
+          createWarning(
+            'architecture-changelog-smell',
+            `Architecture doc contains ${changelogLines.length} changelog-shaped line(s) (e.g. "${example}"). Architecture docs are current-state contracts (D-292): fold the change into the existing sections, keep the durable plan and rollout state in the doc, and move work/ship chronology to the session note — decisions record accepted choices (D-293). Intentionally dated ledgers/reports can declare content_mode: chronological-ledger.`,
+          ),
+        );
+      }
+    }
+
     return {
       kind: 'architecture',
       extracted: {
@@ -515,6 +557,7 @@ function parseArchitectureDocument(options) {
         feature: typeof data.feature === 'string' ? data.feature : null,
         component: typeof data.component === 'string' ? data.component : null,
         status: typeof data.status === 'string' ? data.status : null,
+        content_mode: contentMode,
         repo_ids: repoIds,
       },
       warnings,
@@ -622,11 +665,34 @@ function parseSessionDocument(options) {
   const h1Match = options.content.match(/^#\s+Session(?:\s+—\s+(.+))?$/m);
 
   if (!filenameMatch && !h1Match) {
+    const recoveryCheckpoint = parseRecoveryCheckpointIdentity(options);
+    if (recoveryCheckpoint.candidate) {
+      if (recoveryCheckpoint.error) {
+        errors.push(recoveryCheckpoint.error);
+        return { kind: 'session', extracted: null, warnings, errors };
+      }
+
+      warnings.push(
+        createWarning(
+          'session-filename-mismatch',
+          'Recovery checkpoint uses the supported legacy sessions/YYYY-MM-DD.md filename instead of the recommended YYYY-MM-DD-N-display-title.md pattern.',
+        ),
+      );
+      appendMissingSessionSectionWarnings(options.content, warnings);
+
+      return {
+        kind: 'session',
+        extracted: recoveryCheckpoint.extracted,
+        warnings,
+        errors,
+      };
+    }
+
     errors.push(
       createError(
         options.relativePath,
         'session-unrecognized',
-        'Session note must use the session filename pattern or a "# Session" heading.',
+        'Session note must use the session filename pattern, a "# Session" heading, or the strict legacy recovery-checkpoint form.',
       ),
     );
     return { kind: 'session', extracted: null, warnings, errors };
@@ -641,14 +707,7 @@ function parseSessionDocument(options) {
     );
   }
 
-  const sections = extractLevelTwoSections(options.content);
-  for (const section of RECOMMENDED_SESSION_SECTIONS) {
-    if (!sections.has(section.toLowerCase())) {
-      warnings.push(
-        createWarning('session-missing-section', `Session note is missing recommended section "## ${section}".`),
-      );
-    }
-  }
+  appendMissingSessionSectionWarnings(options.content, warnings);
 
   const title = extractSessionTitle(options.content, filenameMatch);
 
@@ -664,6 +723,98 @@ function parseSessionDocument(options) {
   };
 }
 
+function parseRecoveryCheckpointIdentity(options) {
+  const filenameMatch = options.relativePath.match(/^sessions\/(\d{4}-\d{2}-\d{2})\.md$/);
+  const firstLine = options.content.split(/\r?\n/, 1)[0];
+  const headingCandidate = /^# Recovery checkpoint(?:\s|$)/.test(firstLine);
+  const candidate = Boolean(filenameMatch) || headingCandidate;
+
+  if (!candidate) {
+    return { candidate: false, extracted: null, error: null };
+  }
+
+  if (!filenameMatch) {
+    return {
+      candidate: true,
+      extracted: null,
+      error: createError(
+        options.relativePath,
+        'session-recovery-checkpoint-path-invalid',
+        'Legacy recovery checkpoints must be root session files named sessions/YYYY-MM-DD.md.',
+      ),
+    };
+  }
+
+  const headingMatch = firstLine.match(
+    /^# Recovery checkpoint — (\d{4}-\d{2}-\d{2}) — (\S(?:.*\S)?)$/,
+  );
+  if (!headingMatch) {
+    return {
+      candidate: true,
+      extracted: null,
+      error: createError(
+        options.relativePath,
+        'session-recovery-checkpoint-heading-invalid',
+        'Legacy recovery checkpoints require "# Recovery checkpoint — YYYY-MM-DD — <nonempty title>".',
+      ),
+    };
+  }
+
+  const filenameDate = filenameMatch[1];
+  const headingDate = headingMatch[1];
+  if (!isValidIsoCalendarDate(filenameDate) || !isValidIsoCalendarDate(headingDate)) {
+    return {
+      candidate: true,
+      extracted: null,
+      error: createError(
+        options.relativePath,
+        'session-recovery-checkpoint-date-invalid',
+        'Legacy recovery checkpoint dates must be valid ISO calendar dates.',
+      ),
+    };
+  }
+
+  if (filenameDate !== headingDate) {
+    return {
+      candidate: true,
+      extracted: null,
+      error: createError(
+        options.relativePath,
+        'session-recovery-checkpoint-date-mismatch',
+        `Legacy recovery checkpoint filename date ${filenameDate} does not match heading date ${headingDate}.`,
+      ),
+    };
+  }
+
+  return {
+    candidate: true,
+    extracted: {
+      title: headingMatch[2].trim(),
+      session_date: filenameDate,
+      // A checkpoint records continuity inside an open lane; assigning a
+      // number would invent a close-session chronology that never occurred.
+      session_number: null,
+    },
+    error: null,
+  };
+}
+
+function appendMissingSessionSectionWarnings(content, warnings) {
+  const sections = extractLevelTwoSections(content);
+  for (const section of RECOMMENDED_SESSION_SECTIONS) {
+    if (!sections.has(section.toLowerCase())) {
+      warnings.push(
+        createWarning('session-missing-section', `Session note is missing recommended section "## ${section}".`),
+      );
+    }
+  }
+}
+
+function isValidIsoCalendarDate(value) {
+  const parsed = new Date(`${value}T00:00:00.000Z`);
+  return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
+}
+
 function extractDecisionEntries(content) {
   const matches = [...content.matchAll(/^###\s+D-(\d{3,})\b.*$/gm)];
 
@@ -717,6 +868,385 @@ function extractLevelTwoSections(content) {
   return sections;
 }
 
+// D-292 changelog-shape detector, shared by the scanner and the docs-review
+// apply validator. Signals are deliberately conjunctive and line-local so
+// legitimate content never trips it: bare dates, Track/Phase plan headings,
+// lane/session vocabulary, completion words in prose, and strikethrough alone
+// must not trigger. Frontmatter is expected to be stripped by the caller;
+// fenced code, inline code, and HTML comments are masked here because dates
+// inside artifact names (migration filenames, example blocks) are legitimate.
+export function detectChangelogShapedLines(body) {
+  // Block-aware masking approximating CommonMark, deliberately short of a
+  // full tokenizer. Modeled exactly: fenced code (character + run length,
+  // whitespace-only closers within 3 columns relative to the containing
+  // block), 4+ column indented code with tab-stop arithmetic (never
+  // interrupting an open paragraph), block-level HTML comments, ATX headings
+  // interrupting paragraphs, single-level list containers
+  // (marker-width/padding-derived content indent, lazy item-paragraph
+  // continuation until a blank or block interrupter, container exit with
+  // line reprocessing, list-contained fences and comments, and the
+  // paragraph-interruption rule: only non-empty bullets or ordered markers
+  // with start value 1 interrupt), and source-ordered escape-aware inline
+  // masking of code spans and comments. Known approximations, guarded by the
+  // checked-in nine-doc calibration fixture matrix plus the separately rerun
+  // three-root live calibration: nested containers, setext headings,
+  // thematic-break paragraph boundaries, and lazy blockquote continuation.
+  const hits = [];
+  // fence/htmlComment carry `container` when opened inside a list item;
+  // `container` alone means an active list item with no open child block.
+  // `container.paragraphOpen` tracks whether the item has an open paragraph
+  // eligible for lazy continuation by under-indented lines.
+  let fence = null;
+  let htmlComment = null;
+  let container = null;
+  let paragraph = [];
+
+  const evaluateLeadIn = (maskedLine, rawLine) => {
+    const trimmed = maskedLine.trim();
+    if (trimmed === '') {
+      return;
+    }
+    // Blockquoted lines are quoted examples, not the doc's own lead-ins.
+    const isListItem = /^([-*+]|\d+[.)])\s/.test(trimmed);
+    const isBlockquote = trimmed.startsWith('>');
+    if (
+      !isListItem &&
+      !isBlockquote &&
+      trimmed.endsWith(':') &&
+      trimmed.length <= 160 &&
+      ISO_DATE_PATTERN.test(trimmed) &&
+      /\bupdated\b/i.test(trimmed)
+    ) {
+      hits.push(rawLine.trim());
+    }
+  };
+
+  const flushParagraph = () => {
+    if (paragraph.length === 0) {
+      return;
+    }
+    const maskedLines = maskInlineConstructs(paragraph.map((entry) => entry.raw).join('\n')).split('\n');
+    for (let index = 0; index < paragraph.length; index += 1) {
+      evaluateLeadIn(maskedLines[index], paragraph[index].raw);
+    }
+    paragraph = [];
+  };
+
+  const openContainerBlock = (rest) => {
+    const opener = /^(`{3,}|~{3,})(.*)$/.exec(rest);
+    if (opener && !(opener[1][0] === '`' && opener[2].includes('`'))) {
+      fence = { char: opener[1][0], length: opener[1].length, container };
+      return true;
+    }
+    if (rest.startsWith('<!--') && !rest.slice(4).includes('-->')) {
+      htmlComment = { container };
+      return true;
+    }
+    return false;
+  };
+
+  // Lines at valid root position (columns 0-3) that start a new block and
+  // therefore end lazy paragraph continuation. Any valid list marker —
+  // empty or not, of any type — closes the current item here: marker type
+  // only decides whether the reprocessed line joins the old list or starts
+  // a new one. The empty/start-number paragraph-interruption limits apply
+  // only where a document-level paragraph itself is open.
+  const interruptsLazyContinuation = (content) => {
+    if (ATX_HEADING_START.test(content) || content.startsWith('>') || content.startsWith('<!--')) {
+      return true;
+    }
+    const opener = /^(`{3,}|~{3,})(.*)$/.exec(content);
+    if (opener && !(opener[1][0] === '`' && opener[2].includes('`'))) {
+      return true;
+    }
+    return /^([-*+]|\d{1,9}[.)])([ \t]+\S|[ \t]*$)/.test(content);
+  };
+
+  // Whether a container content line is item PARAGRAPH text (eligible for
+  // lazy continuation) as opposed to a non-persistent child block: an ATX
+  // heading (with content or bare), blockquote, complete one-line HTML
+  // comment, or nested list marker occupies the line without leaving a
+  // paragraph open.
+  const startsContainerParagraph = (rest) => {
+    if (ATX_HEADING_START.test(rest) || rest.startsWith('>') || rest.startsWith('<!--')) {
+      return false;
+    }
+    return !/^([-*+]|\d{1,9}[.)])([ \t]+\S|[ \t]*$)/.test(rest);
+  };
+
+  // Normalize CRLF and lone CR at ingress: the exported helper's contract is
+  // "frontmatter-stripped body text", and end-anchored block predicates
+  // (bare ATX, fence closers, bare markers) break on trailing \r.
+  const lines = (body ?? '').split(/\r\n?|\n/);
+  let index = 0;
+  while (index < lines.length) {
+    const rawLine = lines[index];
+    const blank = rawLine.trim() === '';
+    const indent = expandedIndentColumns(rawLine);
+
+    if (fence) {
+      if (blank) {
+        index += 1;
+        continue;
+      }
+      if (fence.container && indent < fence.container.contentIndent) {
+        // Container exit ends the child fence with its enclosing item; the
+        // exiting line is reprocessed at document level.
+        fence = null;
+        container = null;
+        continue;
+      }
+      const baseIndent = fence.container ? fence.container.contentIndent : 0;
+      const closer = /^[ \t]*(`{3,}|~{3,})[ \t]*$/.exec(rawLine);
+      if (
+        closer &&
+        closer[1][0] === fence.char &&
+        closer[1].length >= fence.length &&
+        indent - baseIndent <= 3
+      ) {
+        fence = null;
+      }
+      index += 1;
+      continue;
+    }
+
+    if (htmlComment) {
+      if (!blank && htmlComment.container && indent < htmlComment.container.contentIndent) {
+        htmlComment = null;
+        container = null;
+        continue;
+      }
+      if (rawLine.includes('-->')) {
+        htmlComment = null;
+      }
+      index += 1;
+      continue;
+    }
+
+    if (container) {
+      if (blank) {
+        container.paragraphOpen = false;
+        index += 1;
+        continue;
+      }
+      if (indent < container.contentIndent) {
+        // A lazy continuation of the item's open paragraph stays inside the
+        // item (item text is non-signal); a valid root block start (columns
+        // 0-3 only — at 4+ columns nothing can start a root block, and
+        // indented code cannot interrupt the open paragraph) exits the
+        // container and is reprocessed at document level.
+        if (
+          container.paragraphOpen &&
+          (indent >= 4 || !interruptsLazyContinuation(rawLine.trimStart()))
+        ) {
+          index += 1;
+          continue;
+        }
+        container = null;
+        continue;
+      }
+      // Container content: only child fences/comments matter for masking;
+      // item text (including nested lists, an out-of-scope approximation)
+      // never produces signals itself. 4+ relative columns is indented code
+      // within the item, not a fence opener. Non-persistent child blocks
+      // (headings, one-line comments, blockquotes, nested markers) close the
+      // item paragraph rather than opening one.
+      if (indent - container.contentIndent <= 3) {
+        const rest = rawLine.trimStart();
+        container.paragraphOpen = openContainerBlock(rest) ? false : startsContainerParagraph(rest);
+      }
+      index += 1;
+      continue;
+    }
+
+    const content = rawLine.trimStart();
+
+    if (blank) {
+      flushParagraph();
+      index += 1;
+      continue;
+    }
+    if (indent >= 4) {
+      // Indented code cannot interrupt an open paragraph (CommonMark): an
+      // indented line after prose is paragraph continuation text.
+      if (paragraph.length > 0) {
+        paragraph.push({ raw: rawLine });
+      }
+      index += 1;
+      continue;
+    }
+
+    const listMarker = /^([-*+]|\d{1,9}[.)])(?:([ \t]+)(.*)|[ \t]*)$/.exec(content);
+    if (listMarker) {
+      const rest = listMarker[3] ?? '';
+      const orderedDigits = /^(\d{1,9})[.)]$/.exec(listMarker[1]);
+      // Interrupting an open paragraph requires a non-empty item, and for
+      // ordered lists a start VALUE of 1 (so `01.` may interrupt while `2.`
+      // may not).
+      const canInterrupt =
+        rest.trim() !== '' && (!orderedDigits || Number.parseInt(orderedDigits[1], 10) === 1);
+      if (paragraph.length > 0 && !canInterrupt) {
+        paragraph.push({ raw: rawLine });
+        index += 1;
+        continue;
+      }
+      flushParagraph();
+      const markerWidth = listMarker[1].length;
+      let paddingColumns = 0;
+      if (listMarker[2]) {
+        let column = indent + markerWidth;
+        for (const character of listMarker[2]) {
+          column += character === '\t' ? 4 - (column % 4) : 1;
+        }
+        paddingColumns = column - indent - markerWidth;
+      }
+      const contentIndent =
+        rest === '' || paddingColumns === 0 || paddingColumns > 4
+          ? indent + markerWidth + 1
+          : indent + markerWidth + paddingColumns;
+      container = { contentIndent, paragraphOpen: false };
+      if (rest !== '') {
+        // Residual logical indentation of the marker line's own content: with
+        // more than four padding columns, one column is list padding and the
+        // remainder is a child INDENTED CODE block (CommonMark), so no item
+        // paragraph opens and the text is never a fence/comment/heading.
+        const restRelativeIndent = indent + markerWidth + paddingColumns - contentIndent;
+        if (restRelativeIndent >= 4) {
+          container.paragraphOpen = false;
+        } else {
+          container.paragraphOpen = openContainerBlock(rest) ? false : startsContainerParagraph(rest);
+        }
+      }
+      index += 1;
+      continue;
+    }
+
+    const opener = /^(`{3,}|~{3,})(.*)$/.exec(content);
+    if (opener && !(opener[1][0] === '`' && opener[2].includes('`'))) {
+      flushParagraph();
+      fence = { char: opener[1][0], length: opener[1].length, container: null };
+      index += 1;
+      continue;
+    }
+
+    if (content.startsWith('<!--')) {
+      flushParagraph();
+      if (!content.slice(4).includes('-->')) {
+        htmlComment = { container: null };
+      }
+      index += 1;
+      continue;
+    }
+
+    if (ATX_HEADING_START.test(content)) {
+      flushParagraph();
+      if (/^#{2,3}\s/.test(content)) {
+        const masked = maskInlineConstructs(content);
+        if (ISO_DATE_PATTERN.test(masked) && HEADING_CHRONOLOGY_CUES.test(masked)) {
+          hits.push(rawLine.trim());
+        }
+      }
+      index += 1;
+      continue;
+    }
+
+    paragraph.push({ raw: rawLine });
+    index += 1;
+  }
+  flushParagraph();
+
+  return hits;
+}
+
+// Source-ordered inline masking: scans left to right so the first valid
+// construct wins (a comment containing a backtick masks before that backtick
+// can pair with later code), backslash-escaped backticks are not code
+// delimiters, an unmatched backtick run or unterminated `<!--` is literal
+// text, and closer runs inside an open code span count regardless of
+// backslashes (escapes are literal inside code). Masked spans preserve
+// newlines so paragraph line mapping stays exact.
+function maskInlineConstructs(text) {
+  let result = '';
+  let position = 0;
+
+  while (position < text.length) {
+    const character = text[position];
+
+    if (character === '\\' && position + 1 < text.length) {
+      result += text.slice(position, position + 2);
+      position += 2;
+      continue;
+    }
+
+    if (character === '`') {
+      let runEnd = position;
+      while (runEnd < text.length && text[runEnd] === '`') {
+        runEnd += 1;
+      }
+      const runLength = runEnd - position;
+      let closerStart = -1;
+      let scan = runEnd;
+      while (scan < text.length) {
+        if (text[scan] === '`') {
+          let scanEnd = scan;
+          while (scanEnd < text.length && text[scanEnd] === '`') {
+            scanEnd += 1;
+          }
+          if (scanEnd - scan === runLength) {
+            closerStart = scan;
+            break;
+          }
+          scan = scanEnd;
+        } else {
+          scan += 1;
+        }
+      }
+      if (closerStart !== -1) {
+        const spanEnd = closerStart + runLength;
+        result += text.slice(position, spanEnd).replace(/[^\n]/g, ' ');
+        position = spanEnd;
+      } else {
+        result += text.slice(position, runEnd);
+        position = runEnd;
+      }
+      continue;
+    }
+
+    if (text.startsWith('<!--', position)) {
+      const commentEnd = text.indexOf('-->', position + 4);
+      if (commentEnd !== -1) {
+        const spanEnd = commentEnd + 3;
+        result += text.slice(position, spanEnd).replace(/[^\n]/g, ' ');
+        position = spanEnd;
+      } else {
+        result += '<!--';
+        position += 4;
+      }
+      continue;
+    }
+
+    result += character;
+    position += 1;
+  }
+
+  return result;
+}
+
+// CommonMark column arithmetic: a tab advances to the next 4-column stop.
+function expandedIndentColumns(line) {
+  let columns = 0;
+  for (const character of line) {
+    if (character === ' ') {
+      columns += 1;
+    } else if (character === '\t') {
+      columns += 4 - (columns % 4);
+    } else {
+      break;
+    }
+  }
+  return columns;
+}
+
 function extractSessionTitle(content, filenameMatch) {
   const h1WithNumber = content.match(/^#\s+Session\s+—\s+\d{4}-\d{2}-\d{2}-\d+\s+—\s+(.+)$/m);
   if (h1WithNumber) {

package/src/scaffold.js

@@ -215,7 +215,7 @@ This workspace uses VibeCompass project memory rooted at \`${rootRelativePath}\`
 
 ## Canonical files
 - \`${rootRelativePath}/project.yaml\` — machine-oriented project metadata
-- \`${rootRelativePath}/architecture/\` — canonical architecture docs
+- \`${rootRelativePath}/architecture/\` — canonical architecture docs; the mutable current-state layer, rewritten in place as contracts change (D-292)
 - \`${rootRelativePath}/decisions/\` — append-only decision log for this project-memory root
 - \`${rootRelativePath}/sessions/\` — finalized session notes
 
@@ -240,6 +240,7 @@ This workspace uses VibeCompass project memory rooted at \`${rootRelativePath}\`
 - Every lane gets a per-lane runtime assignment at start (D-282): a lane port and temp dir recorded in \`session.yaml\` and exported with \`eval "$(vibecompass lane-env)"\` (includes conventional \`PORT\`/\`TMPDIR\` aliases), so parallel lanes never fight over dev-server ports or temp paths. Defaults are configurable under \`project.yaml\` \`runtime:\`; \`close-session\` removes the lane temp dir under guards.
 - Finalized sessions are append-only notes named \`${rootRelativePath}/sessions/YYYY-MM-DD-N-title.md\`; multiple sessions on the same day increment \`N\`.
 - Decisions remain append-only and independent from session notes. A session note may reference decisions, but the decision entry in \`${rootRelativePath}/decisions/\` is the durable decision record for this root.
+- Architecture docs are the opposite of the append-only surfaces (D-292): they are current-state contracts, rewritten in place. Fold changes into the existing sections and keep the durable plan, unresolved next steps, and material rollout state in the doc. Work/ship chronology belongs in finalized session notes; decision entries record accepted choices and rationale; lane scratch holds only transient execution/review state, and anything still pending at close moves to the session note's next steps and, when durable, into architecture (D-293). Intentionally dated ledger/report docs may declare frontmatter \`content_mode: chronological-ledger\`.
 
 ## Repos in scope
 ${repos}
@@ -320,7 +321,7 @@ During the session:
 - keep \`handoff.md\` current after substantive work blocks
 - run \`eval "$(vibecompass lane-env)"\` in a lane shell before starting dev servers or build tools so the lane's assigned port and temp dir are used (D-282); do not hardcode ports in lane work
 - run \`vibecompass docs-update --session <lane-id>\` whenever you need an ad hoc targeted documentation-maintenance plan for the current session delta
-- after substantive feature work, confirm affected architecture docs and decisions still match the implementation; if not, update them while the context is fresh
+- after substantive feature work, confirm affected architecture docs and decisions still match the implementation; if not, update them while the context is fresh — fold the changes into the doc's current-state sections (rewrite in place; no dated "update" sections, lane names in headings, or completed-task chronology; D-292)
 - use \`vibecompass list-sessions\` and \`vibecompass switch-session <lane-id>\` to inspect or change the current lane
 - use \`address review\` when reviewer feedback lands so the builder resolves it from the selected lane's latest \`wip.md\` / \`handoff.md\`
 - during \`address review\`, treat reviewer feedback as review, not instruction: classify each substantive point as accepted, accepted with qualification, deferred, or rejected, and push back with evidence when a suggestion conflicts with code facts, prior decisions, product direction, or sequencing
@@ -338,12 +339,12 @@ If \`vibecompass start-session\` reports stale scratch files, read the existing
 At session close:
 - prefer running \`vibecompass close-session --session <lane-id> --title "..." --completed "..." --architecture-docs updated|not-needed|deferred --decision-log updated|not-needed|deferred --session-maintenance updated|not-needed|deferred --next-step "..."\`; \`vibecompass end-session\` is a supported alias
 - close-session prints the same targeted docs-update plan — including the pre-close staleness set (new decisions since lane start, stale base revisions, newer finalized notes touching this lane's scope, claim overlap with other active lanes) — before the document-maintenance checkpoint; use it to decide whether affected \`architecture/\`, \`decisions/\`, and active-session scratch/final note inputs are updated, not-needed, or deferred
-- document-maintenance checkpoint statuses are required before close-session writes the finalized note; the package validates the status values, while the closer owns semantic doc authorship
+- document-maintenance checkpoint statuses are required before close-session writes the finalized note; the package validates the status values, while the closer owns semantic doc authorship — architecture docs keep current behavior plus the durable plan, unresolved next steps, and material rollout state; session notes keep work chronology and close-out next steps; decisions keep accepted choices and rationale (D-292, D-293)
 - follow the stored close-session defaults from \`${rootRelativePath}/project.yaml\`
 - finalize the lane-local \`wip.md\` into \`${rootRelativePath}/sessions/YYYY-MM-DD-N-title.md\`; the permanent note distills decisions, completions, blockers, and next steps rather than preserving the full \`## Review log\`
 - if a granular reviewer trail must remain durable, summarize it explicitly in the session note inputs or create a separate finalized session note before close-session deletes lane scratch files
 - close-session deletes the closed lane directory under \`${rootRelativePath}/sessions/active/<lane-id>/\` and cleans up provisioned worktrees, the lane marker, the container, and the lane temp dir when they are safely removable; leftover pieces come with printed guidance
-- refresh any affected architecture/decision docs
+- refresh any affected architecture/decision docs by folding changes into their current-state contract prose — do not append session chronology; distill anything still pending from lane scratch into the session note's next steps and, when durable, into the docs (D-292, D-293)
 - for local-primary roots with hosted sync configured, run \`vibecompass push --root ${rootRelativePath}\` after canonical docs/session files are finalized when the hosted dashboard should reflect the session; pass \`--sync-target <name>\` when using a non-default or named target
 - for hosted-only projects, there is no local authoritative push; confirm hosted dashboard/proposal/Understanding state was updated or record the refresh/apply work as deferred
 
@@ -523,6 +524,7 @@ architecture/<domain-slug>/<feature-slug>/<component>.md
 - Retrieval guidance should say when to consult the doc, what it does not cover, and which related docs or decisions matter.
 - Details should distinguish confirmed behavior from known gaps or open follow-up.
 - Involved files should use concrete \`repo:path\` references that match the affected implementation surface.
+- Docs are mutable current-state contracts (D-292): fold updates into the existing sections by rewriting them in place, keeping the durable plan, unresolved next steps, and material rollout state in the doc. Dated session headings, lane names, and completed-task chronology belong in session notes; decision entries record accepted choices and rationale (D-293). Docs whose artifact itself is dated (migration ledgers, incident/upstream reports) may declare frontmatter \`content_mode: chronological-ledger\` to suppress the changelog-shape advisory.
 
 Each component doc is canonical. This README is only a convenience guide.
 `;
@@ -635,7 +637,7 @@ function renderWorkflowDefaults(workflow) {
   const lines = [
     `- reviewer handback: ${describeReviewerHandback(workflow)}`,
     '- close-session: require document-maintenance checkpoint statuses for architecture docs, decision log, and session handoff/scratch',
-    '- close-session: refresh any relevant architecture docs before finalizing the session',
+    '- close-session: refresh any relevant architecture docs before finalizing the session, folding changes into their current-state contract prose (D-292)',
     '- close-session: refresh any relevant decision files before finalizing the session',
   ];
 

package/src/workflow.js

@@ -83,6 +83,9 @@ export function buildCloseSessionGuidance(workflowSettings, options = {}) {
 
   guidance.push('Reviewer handback stays in the selected sessions/active/<lane-id>/wip.md and handoff.md before close-session runs.');
   guidance.push('Close-session requires document-maintenance checkpoint statuses for architecture docs, decision log, and session handoff/scratch: updated, not-needed, or deferred.');
+  // D-292/D-293: unconditional — the authorship rule holds even when the
+  // refresh-architecture-docs workflow step is disabled.
+  guidance.push('Architecture docs keep current behavior plus the durable plan, unresolved next steps, and material rollout state — fold changes in place, never dated session sections; session notes keep work chronology and close-out next steps; decisions keep accepted choices and rationale; transient lane scratch drains into the session note at close (D-292, D-293).');
 
   if (workflowSettings.closeSession.refreshArchitectureDocs) {
     guidance.push('Refresh any relevant architecture docs before finalizing the session.');

package/src/workflows/registry.js

@@ -122,7 +122,7 @@ The first pass is breadth-first: establish an honest project denominator, compac
 3. Run \`vibecompass docs-review --guided --llm <tool-name> --model <model-name>\` to record the review marker and print the canonical docs-review contract. Use the current AI tool name and model when known.
 4. Present the evidence inventory, completeness inventory with accepted/deferred/missing accounting, topology, chosen taxonomy axis, prior-doc reuse/update/split/merge/defer/replace classifications, coverage plan, backbone outputs (core feature inventory, user journey map, project systems map, coverage/quality summary), proposed architecture docs, blindspots, token-budget risks, quality report, and any decision candidates before generating accepted output. At this gate, ask whether to apply the compact baseline now, adjust the plan, or spend a follow-up pass deepening specific high-risk areas. If you stop here for user approval, state clearly that no architecture docs have been applied yet and do not label proposed areas as accepted.
 5. Draft only output the user accepts. After approval, the accepted plan must be fenced as \`vibecompass-coverage-plan version=1\` and should preserve each area's \`run_scope\` as \`baseline\` or \`deepening\`. Accepted architecture docs must be fenced as \`vibecompass-architecture-doc path=architecture/domain/feature/component.md\` blocks and must include required frontmatter: \`domain\`, \`feature\`, \`component\`, and \`status\`. Feature docs may include compact prose-only surface matrices; surface/platform ownership docs stay under the existing \`architecture/platform/<surface>/<component>.md\` shape rather than a new top-level systems tree. The accepted \`architecture/overview/project-shape.md\` doc should include compact backbone sections and exactly one \`vibecompass-project-map version=1\` JSON block with journey-facing features, entry points, evidence-backed relationships, and minimal optional derived \`systems[]\` metadata. Accepted local decisions may be fenced as \`vibecompass-decision-recommendation target=decisions/domain.md\` blocks without D-numbers.
-6. Keep each generated architecture doc focused and retrieval-oriented. Soft budget: under 12000 bytes per doc unless the extra detail is necessary and called out in review metadata or retrieval guidance.
+6. Keep each generated architecture doc focused and retrieval-oriented. Soft budget: under 12000 bytes per doc unless the extra detail is necessary and called out in review metadata or retrieval guidance. Write every doc as a current-state contract (D-292): updates rewrite the affected sections in place or create a new focused doc — never append dated session/audit sections. Keep the durable plan and rollout state in the doc; work/ship chronology belongs in session notes, and decision entries record accepted choices (D-293).
 7. Write the accepted fenced blocks verbatim to \`${outputPath}\`.
 8. Run \`${applyCommand}\` to validate and apply the accepted blocks. If \`vibecompass\` is not installed on PATH, run \`${npxApplyCommand}\` instead. Only report docs-review as applied after this command succeeds. If accepted docs were written manually outside the output file, run \`vibecompass docs-review --root ${rootRelativePath} --complete\` after confirming the marker should be completed.
 9. Run \`vibecompass status\` to confirm the docs-review marker is complete and not drifted. Report the applied architecture paths, coverage projection, baseline/deepening split, decision recommendations, parser warnings such as oversized docs or missing review metadata, and any blindspots or deepening candidates documented in the accepted docs-review output.