@vibecompass/vibecompass 0.11.2 → 0.13.0

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,
@@ -717,6 +760,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/serialization.js

@@ -46,7 +46,33 @@ export function memoryRootLockPath(rootDir) {
  * Runs `fn` while holding the serialization lock for `rootDir`. Reentrant:
  * a nested call from inside the lock holder runs immediately.
  */
+// Commands that stay allowed on a promoted root: the transition flows
+// themselves, plus recovery tooling that must be able to repair state.
+const PROMOTED_ROOT_ALLOWED_COMMANDS = new Set([
+  'promote-hosted',
+  'demote-hosted',
+  'bootstrap',
+]);
+
+async function assertNotPromotedRoot(rootDir, label) {
+  if (PROMOTED_ROOT_ALLOWED_COMMANDS.has(label)) return;
+  if (process.env.VIBECOMPASS_ALLOW_PROMOTED_ROOT_WRITES === '1') return;
+  const markerPath = path.join(rootDir, 'state', 'promoted-root.json');
+  let marker;
+  try {
+    marker = JSON.parse(await readFile(markerPath, 'utf8'));
+  } catch {
+    return;
+  }
+  throw new Error(
+    `This root was promoted to hosted-only${marker?.promoted_at ? ` on ${marker.promoted_at}` : ''}: the hosted app is canonical and local writes here can never sync back (D-288). `
+    + 'Make changes on the hosted dashboard, run vibecompass demote-hosted to make this root canonical again, '
+    + 'or set VIBECOMPASS_ALLOW_PROMOTED_ROOT_WRITES=1 to override deliberately.',
+  );
+}
+
 export async function withMemoryRootLock(rootDir, label, fn, options = {}) {
+  await assertNotPromotedRoot(rootDir, label);
   const key = await canonicalizeMemoryRootKey(rootDir);
   const held = heldRoots.getStore();
   if (await findHeldMemoryRootKey(held, key)) {

package/src/status.js

@@ -4,6 +4,7 @@ import { inspectProjectCompatibility } from './compatibility.js';
 import { sha256Text } from './hash.js';
 import { resolveLaneMarkerContext } from './lane-marker.js';
 import { parseSimpleYaml } from './simple-yaml.js';
+import { resolveSyncBinding } from './sync-binding.js';
 import { inferToolingRootForMemoryRoot, listProjectSessions } from './session.js';
 import { syncAgentInstructionFiles } from './generators/agent-files/index.js';
 import { scanProjectMemory } from './project-memory.js';
@@ -30,12 +31,18 @@ export async function getProjectStatus(options = {}) {
     readAgentFileStatus(rootDir, toolingRootDir),
     readProjectMemoryStatus(rootDir),
   ]);
+  const hostedSync = await readHostedModeCheck(
+    compatibility.projectFilePath,
+    project.mode ?? null,
+    options,
+  );
 
   return {
     generatedAt: new Date().toISOString(),
     rootDir,
     toolingRootDir,
     project,
+    hostedSync,
     compatibility: {
       cliPackageVersion: compatibility.cliPackageVersion,
       package: compatibility.package,
@@ -111,6 +118,13 @@ export function renderStatusText(status) {
     `Generated: ${status.generatedAt}`,
     `Project: ${status.project.name ?? 'Unknown'}`,
     `Mode: ${status.project.mode ?? 'Unknown'}`,
+    ...(status.hostedSync?.status === 'ok' && status.hostedSync.mismatch
+      ? [
+          `WARNING: mode mismatch — local project.yaml says "${status.hostedSync.localMode}" but the hosted project is "${status.hostedSync.hostedMode}". The two mode records are unreconciled: sync and dashboard actions will refuse until they agree. Do not hand-edit mode; a supported promote/demote flow flips both records together.`,
+        ]
+      : status.hostedSync?.status === 'unreachable'
+        ? [`Hosted mode check: unreachable (${status.hostedSync.detail}).`]
+        : []),
     `Root: ${status.rootDir}`,
     `Repos: ${status.project.repos.length > 0 ? status.project.repos.map((repo) => repo.id).join(', ') : 'None recorded'}`,
     `Active lanes: ${formatActiveLanes(status.sessions)}`,
@@ -162,6 +176,7 @@ export function toStatusJson(status) {
   return {
     generatedAt: status.generatedAt,
     rootDir: status.rootDir,
+    hostedSync: status.hostedSync ?? null,
     toolingRootDir: status.toolingRootDir,
     project: status.project,
     compatibility: status.compatibility,
@@ -173,6 +188,69 @@ export function toStatusJson(status) {
   };
 }
 
+/**
+ * Mode-mismatch diagnostic (plan 3.8): compares the local project.yaml mode
+ * against the hosted project's mode via the side-effect-free sync status
+ * endpoint. A hand-edited mode previously wedged a project with opaque 409s
+ * on both sides and no diagnostic anywhere. Network problems degrade to an
+ * "unreachable" note — status stays offline-safe.
+ */
+async function readHostedModeCheck(projectFilePath, localMode, options = {}) {
+  let binding;
+  try {
+    const config = parseSimpleYaml(await readFile(projectFilePath, 'utf8'), {
+      sourceName: projectFilePath,
+    });
+    binding = resolveSyncBinding(config, null);
+  } catch {
+    return { status: 'not-configured' };
+  }
+  if (!binding) return { status: 'not-configured' };
+
+  const env = options.env ?? process.env;
+  const credential = typeof env[binding.credentialEnvVar] === 'string'
+    ? env[binding.credentialEnvVar].trim()
+    : '';
+  if (!credential) {
+    return { status: 'no-credential', credentialEnvVar: binding.credentialEnvVar };
+  }
+
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== 'function') return { status: 'not-configured' };
+
+  const baseUrl = binding.apiUrl.endsWith('/') ? binding.apiUrl : `${binding.apiUrl}/`;
+  const endpoint = new URL(
+    `api/sync/projects/${encodeURIComponent(binding.projectId)}/status`,
+    baseUrl,
+  );
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 5000);
+  try {
+    const response = await fetchImpl(endpoint.href, {
+      headers: {
+        accept: 'application/json',
+        authorization: `Bearer ${credential}`,
+      },
+      signal: controller.signal,
+    });
+    if (!response.ok) {
+      return { status: 'unreachable', detail: `HTTP ${response.status}` };
+    }
+    const data = typeof response.json === 'function' ? await response.json() : {};
+    const hostedMode = typeof data.mode === 'string' ? data.mode : null;
+    return {
+      status: 'ok',
+      hostedMode,
+      localMode,
+      mismatch: Boolean(hostedMode && localMode && hostedMode !== localMode),
+    };
+  } catch (error) {
+    return { status: 'unreachable', detail: error?.message ?? 'network error' };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 async function readProjectSummary(projectFilePath) {
   try {
     const config = parseSimpleYaml(await readFile(projectFilePath, 'utf8'), {