@vibecompass/vibecompass 0.2.1 → 0.3.1

package/src/generators/agent-files/template.js

@@ -35,14 +35,14 @@ export function renderSharedInstructionBody(context, options = {}) {
     '',
     '## Workflow Rules',
     '- VibeCompass active builder sessions are named lanes. Use one lane per active feature or workstream; finalized session notes are append-only history under `sessions/YYYY-MM-DD-N-title.md`.',
-    '- Use `start session` for builder work and `join as reviewer` for review work.',
+    '- Use `start session` for builder work, `join as reviewer` for review work, and `close session` / `end session` when the builder is ready to close the selected lane.',
     '- Use `vibecompass start-session --id <lane-id>` to open a named lane for every active feature or workstream.',
     '- Use `vibecompass list-sessions` and `vibecompass switch-session <lane-id>` to inspect or change the current lane.',
     '- Treat `sessions/active/index.yaml` as the current lane source of truth; tool-specific Current session blocks are continuity summaries.',
     '- Use optional planning mode for risky or ambiguous work: read the same context, propose scope, and record the agreed plan in the selected lane `wip.md` before implementation.',
     '- Use `review handoff` to ask a reviewer to inspect the active handoff.',
     '- Use `address review` to process reviewer feedback from the selected lane `wip.md` and `handoff.md`.',
-    '- End the active builder session with `vibecompass close-session --session <lane-id>`; `vibecompass end-session` is an accepted alias.',
+    '- End the active builder session with the `close session` prompt, which runs close-out and ends with `vibecompass close-session --session <lane-id>`; `end session` and `vibecompass end-session` are accepted aliases.',
     '- If stale scratch files block `start-session`, read them first, then close, recover, move, or delete them intentionally before retrying.',
     '- Keep decisions append-only in `decisions/`. Session notes may reference decisions, but decisions are the durable source of truth.',
     '- Treat generated agent files as views. Update canonical VibeCompass project memory instead of editing managed regions.',

package/src/index.js

@@ -1,5 +1,12 @@
 export { STATE_VERSION, generateStateManifest, writeStateManifest } from './manifest.js';
 export { initializeProjectMemory } from './init.js';
+export { preflightDocsReview } from './docs-review.js';
+export {
+  applyPullExport,
+  pullExportProjectMemory,
+  pullPreviewProjectMemory,
+  pushProjectMemory,
+} from './sync.js';
 export { scanProjectMemory } from './project-memory.js';
 export {
   closeProjectSession,

package/src/init.js

@@ -5,6 +5,7 @@ import { writeStateManifest } from './manifest.js';
 import { scaffoldInitFiles } from './scaffold.js';
 import { applyPlacementDefaults } from './setup.js';
 import { buildWorkflowMetadata } from './workflow.js';
+import { parseSimpleYaml } from './simple-yaml.js';
 
 const VALID_MODES = new Set(['local-only', 'local-primary', 'hosted-only']);
 
@@ -21,10 +22,10 @@ export async function initializeProjectMemory(options) {
 
   await writeProjectFile(projectFilePath, normalized.projectConfig, normalized.force);
   const gitignoreUpdated = await ensureStateIgnored(gitignorePath);
+  const scaffoldResult = await scaffoldInitFiles(normalized.bootstrap);
   const manifestResult = await writeStateManifest(normalized.rootDir, {
     generatedAt: normalized.generatedAt,
   });
-  const scaffoldResult = await scaffoldInitFiles(normalized.bootstrap);
 
   return {
     rootDir: normalized.rootDir,
@@ -41,6 +42,39 @@ export async function initializeProjectMemory(options) {
   };
 }
 
+export async function connectHostedProjectMemory(options) {
+  const cwd = options?.cwd ? path.resolve(options.cwd) : process.cwd();
+  const rootDir = path.resolve(cwd, options?.rootDir ?? '.compass');
+  const projectFilePath = path.join(rootDir, 'project.yaml');
+  let projectConfig;
+  try {
+    projectConfig = parseSimpleYaml(await readFile(projectFilePath, 'utf8'), {
+      sourceName: projectFilePath,
+    });
+  } catch (error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+      throw new Error(`No project.yaml found in ${rootDir}. Run "vibecompass init" first.`);
+    }
+
+    throw error;
+  }
+
+  if (!['local-primary', 'hosted-only'].includes(projectConfig.mode)) {
+    throw new Error('connect-hosted requires project.yaml mode to be local-primary or hosted-only.');
+  }
+
+  const sync = normalizeSyncOptions(options?.sync, projectConfig.mode);
+  projectConfig.sync = sync;
+  await writeFile(projectFilePath, serializeProjectConfig(projectConfig), 'utf8');
+
+  return {
+    rootDir,
+    projectFilePath,
+    mode: projectConfig.mode,
+    syncEnvVar: sync.credential_env_var,
+  };
+}
+
 function normalizeInitOptions(options) {
   if (!options || typeof options !== 'object') {
     throw new Error('initializeProjectMemory requires an options object.');
@@ -91,30 +125,9 @@ function normalizeInitOptions(options) {
     };
   });
 
-  const syncOptions = preparedOptions.sync ?? null;
-  let sync = undefined;
-  if (syncOptions) {
-    if (preparedOptions.mode !== 'local-primary') {
-      throw new Error('sync configuration is only supported when mode is local-primary.');
-    }
-
-    const requiredFields = ['apiUrl', 'projectId', 'credentialEnvVar'];
-    const missing = requiredFields.filter((field) => typeof syncOptions[field] !== 'string' || syncOptions[field].trim() === '');
-
-    if (missing.length > 0) {
-      throw new Error(
-        `sync configuration is incomplete. Missing: ${missing.join(', ')}.`,
-      );
-    }
-
-    sync = {
-      provider: 'vibecompass',
-      api_url: syncOptions.apiUrl,
-      project_id: syncOptions.projectId,
-      credential_source: 'env',
-      credential_env_var: syncOptions.credentialEnvVar,
-    };
-  }
+  const sync = preparedOptions.sync
+    ? normalizeSyncOptions(preparedOptions.sync, preparedOptions.mode)
+    : undefined;
 
   const projectConfig = {
     format_version: 1,
@@ -137,6 +150,7 @@ function normalizeInitOptions(options) {
     rootDir,
     toolingRootDir,
     projectConfig,
+    generatedAt: preparedOptions.generatedAt,
   });
 
   return {
@@ -148,6 +162,33 @@ function normalizeInitOptions(options) {
   };
 }
 
+function normalizeSyncOptions(syncOptions, mode) {
+  if (!syncOptions || typeof syncOptions !== 'object') {
+    throw new Error('sync configuration must be an object.');
+  }
+
+  if (!['local-primary', 'hosted-only'].includes(mode)) {
+    throw new Error('sync configuration is only supported when mode is local-primary or hosted-only.');
+  }
+
+  const requiredFields = ['apiUrl', 'projectId', 'credentialEnvVar'];
+  const missing = requiredFields.filter((field) => typeof syncOptions[field] !== 'string' || syncOptions[field].trim() === '');
+
+  if (missing.length > 0) {
+    throw new Error(
+      `sync configuration is incomplete. Missing: ${missing.join(', ')}.`,
+    );
+  }
+
+  return {
+    provider: 'vibecompass',
+    api_url: syncOptions.apiUrl,
+    project_id: syncOptions.projectId,
+    credential_source: 'env',
+    credential_env_var: syncOptions.credentialEnvVar,
+  };
+}
+
 function buildAgentFilesMetadata(metadata) {
   const existingAgentFiles = metadata?.agent_files && typeof metadata.agent_files === 'object'
     ? metadata.agent_files
@@ -182,6 +223,7 @@ function normalizeBootstrapOptions(bootstrap, context) {
     contextRelativeToToolingRoot: toPosix(
       path.relative(context.toolingRootDir, contextFilePath) || 'context.md',
     ),
+    generatedAt: context.generatedAt,
   };
 }
 

package/src/manifest.js

@@ -1,7 +1,8 @@
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { localRevisionFromManifestHash, stableHash } from './hash.js';
 import { scanProjectMemory } from './project-memory.js';
+import { listProjectSessions } from './session.js';
 
 export const STATE_VERSION = 1;
 
@@ -50,13 +51,22 @@ export function generateStateManifest(scanResult, options = {}) {
       warning_count: warningCount,
     },
     documents: manifestDocuments,
+    ...(options.activeSessions ? { active_sessions: options.activeSessions } : {}),
     ...(options.sync ? { sync: options.sync } : {}),
   };
 }
 
 export async function writeStateManifest(rootDir, options = {}) {
   const scanResult = await scanProjectMemory(rootDir);
-  const manifest = generateStateManifest(scanResult, options);
+  const activeSessions = await readActiveSessionsForManifest(rootDir);
+  const existingSync = Object.hasOwn(options, 'sync')
+    ? options.sync
+    : await readExistingSyncState(rootDir);
+  const manifest = generateStateManifest(scanResult, {
+    ...options,
+    ...(existingSync ? { sync: existingSync } : {}),
+    ...(activeSessions ? { activeSessions } : {}),
+  });
   const stateDir = path.join(rootDir, 'state');
   const manifestPath = path.join(stateDir, 'manifest.json');
 
@@ -70,6 +80,46 @@ export async function writeStateManifest(rootDir, options = {}) {
   };
 }
 
+async function readExistingSyncState(rootDir) {
+  try {
+    const existing = JSON.parse(
+      await readFile(path.join(rootDir, 'state', 'manifest.json'), 'utf8'),
+    );
+    return existing?.sync && typeof existing.sync === 'object'
+      ? existing.sync
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+async function readActiveSessionsForManifest(rootDir) {
+  const sessions = await listProjectSessions({ rootDir });
+  if (sessions.lanes.length === 0 && !sessions.current) {
+    return null;
+  }
+
+  return {
+    current: sessions.current,
+    lanes: sessions.lanes.map((lane) => ({
+      id: lane.id,
+      status: lane.status ?? 'active',
+      working_on: lane.workingOn,
+      feature_slugs: lane.features ?? [],
+      repos: lane.repos ?? [],
+      claimed_paths: lane.claims ?? [],
+      started_at: lane.startedAt ?? null,
+      ...(lane.decisionSnapshot
+        ? {
+          decision_snapshot: {
+            highest_decision_id: lane.decisionSnapshot.highestDecisionId ?? null,
+          },
+        }
+        : {}),
+    })),
+  };
+}
+
 function toIsoString(value) {
   return value instanceof Date ? value.toISOString() : new Date(value).toISOString();
 }

package/src/project-memory.js

@@ -5,7 +5,7 @@ import { sha256Text } from './hash.js';
 import { parseSimpleYaml } from './simple-yaml.js';
 
 const PROJECT_FILE = 'project.yaml';
-const NON_CANONICAL_DECISION_FILES = new Set(['INDEX.md', 'README.md']);
+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']);
 const VALID_MODES = new Set(['local-only', 'local-primary', 'hosted-only']);
@@ -468,8 +468,23 @@ function parseDecisionDocument(options) {
   const warnings = [];
   const errors = [];
   const entries = extractDecisionEntries(options.content);
+  const malformedHeadings = extractMalformedDecisionHeadings(options.content);
+
+  for (const heading of malformedHeadings) {
+    errors.push(
+      createError(
+        options.relativePath,
+        'decision-invalid-id',
+        `Decision heading "${heading}" must use zero-padded D-NNN or higher.`,
+      ),
+    );
+  }
 
   if (entries.length === 0) {
+    if (malformedHeadings.length > 0) {
+      return { kind: 'decision', extracted: null, warnings, errors };
+    }
+
     errors.push(
       createError(options.relativePath, 'decision-missing-entries', 'Decision files must contain at least one resolvable decision entry.'),
     );
@@ -479,7 +494,7 @@ function parseDecisionDocument(options) {
   const decisionIds = [];
   for (const entry of entries) {
     if (!entry.decisionId || entry.decisionId <= 0) {
-      errors.push(createError(options.relativePath, 'decision-invalid-id', 'Decision heading must include D-<positive integer>.'));
+      errors.push(createError(options.relativePath, 'decision-invalid-id', 'Decision heading must include zero-padded D-<NNN>.'));
       continue;
     }
 
@@ -576,7 +591,7 @@ function parseSessionDocument(options) {
 }
 
 function extractDecisionEntries(content) {
-  const matches = [...content.matchAll(/^###\s+D-(\d+)\b.*$/gm)];
+  const matches = [...content.matchAll(/^###\s+D-(\d{3,})\b.*$/gm)];
 
   return matches.map((match, index) => {
     const bodyStart = match.index ?? 0;
@@ -590,6 +605,10 @@ function extractDecisionEntries(content) {
   });
 }
 
+function extractMalformedDecisionHeadings(content) {
+  return [...content.matchAll(/^###\s+(D-\d{1,2})\b.*$/gm)].map((match) => match[1]);
+}
+
 function findDuplicateDecisionErrors(documents) {
   const seen = new Map();
   const errors = [];

package/src/read-model.js

@@ -5,7 +5,7 @@ import { generateStateManifest } from './manifest.js';
 import { scanProjectMemory } from './project-memory.js';
 
 const SECTION_PATTERN = /^##\s+(.+)$/gm;
-const DECISION_HEADING_PATTERN = /^###\s+D-(\d+)\s+—\s+(.+)$/gm;
+const DECISION_HEADING_PATTERN = /^###\s+D-(\d{3,})\s+—\s+(.+)$/gm;
 
 export async function loadProjectReadModel(rootDir) {
   const scanResult = await scanProjectMemory(rootDir);

package/src/scaffold.js

@@ -1,4 +1,4 @@
-import { access, mkdir, writeFile } from 'node:fs/promises';
+import { access, mkdir, readdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { resolveWorkflowSettings } from './workflow.js';
 
@@ -6,6 +6,45 @@ export async function scaffoldInitFiles(options) {
   const createdFiles = [];
   const skippedFiles = [];
 
+  await mkdir(path.join(options.rootDir, 'architecture'), { recursive: true });
+  await mkdir(path.join(options.rootDir, 'decisions'), { recursive: true });
+  await mkdir(path.join(options.rootDir, 'sessions'), { recursive: true });
+
+  const starterFiles = [
+    {
+      path: path.join(options.rootDir, 'decisions', 'EXAMPLE.md'),
+      content: generateDecisionExample(options.projectConfig),
+    },
+  ];
+
+  if (!(await hasCanonicalMarkdown(path.join(options.rootDir, 'architecture'), {
+    ignoredNames: new Set(['README.md']),
+  }))) {
+    starterFiles.push({
+      path: path.join(options.rootDir, 'architecture', 'overview', 'project-shape.md'),
+      content: generateStarterArchitectureDoc(options.projectConfig),
+    });
+  }
+
+  if (!(await hasCanonicalMarkdown(path.join(options.rootDir, 'sessions'), {
+    ignoredNames: new Set(['README.md', 'wip.md', 'handoff.md']),
+    ignoredDirectories: new Set(['active']),
+  }))) {
+    starterFiles.push({
+      path: path.join(options.rootDir, 'sessions', `${sessionDateFromGeneratedAt(options.generatedAt)}-1-project-memory-initialized.md`),
+      content: generateStarterSessionNote(options),
+    });
+  }
+
+  for (const file of starterFiles) {
+    const outcome = await writeIfMissing(file.path, file.content);
+    if (outcome.created) {
+      createdFiles.push(file.path);
+    } else {
+      skippedFiles.push(file.path);
+    }
+  }
+
   if (!options.workflow) {
     return {
       contextFilePath: null,
@@ -14,10 +53,6 @@ export async function scaffoldInitFiles(options) {
     };
   }
 
-  await mkdir(path.join(options.rootDir, 'architecture'), { recursive: true });
-  await mkdir(path.join(options.rootDir, 'decisions'), { recursive: true });
-  await mkdir(path.join(options.rootDir, 'sessions'), { recursive: true });
-
   const contextFilePath = path.join(options.rootDir, 'context.md');
   // context.md is a derived artifact owned by the package; regenerate it on rerun.
   await writeFile(contextFilePath, generateContextMarkdown(options), 'utf8');
@@ -97,6 +132,43 @@ async function fileExists(filePath) {
   }
 }
 
+async function hasCanonicalMarkdown(directoryPath, options = {}) {
+  const ignoredNames = options.ignoredNames ?? new Set();
+  const ignoredDirectories = options.ignoredDirectories ?? new Set();
+
+  try {
+    const entries = await readdir(directoryPath, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) {
+        continue;
+      }
+
+      if (entry.isDirectory()) {
+        if (ignoredDirectories.has(entry.name)) {
+          continue;
+        }
+
+        if (await hasCanonicalMarkdown(path.join(directoryPath, entry.name), options)) {
+          return true;
+        }
+        continue;
+      }
+
+      if (entry.isFile() && entry.name.endsWith('.md') && !ignoredNames.has(entry.name)) {
+        return true;
+      }
+    }
+  } catch (error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+      return false;
+    }
+
+    throw error;
+  }
+
+  return false;
+}
+
 function generateContextMarkdown(options) {
   const projectName = options.projectConfig.name;
   const rootRelativePath = options.rootRelativePath;
@@ -135,7 +207,7 @@ This workspace uses VibeCompass project memory rooted at \`${rootRelativePath}\`
 ${repos}
 
 ## Session roles
-| Trigger | Role | Owns session lifecycle? |
+| Entry trigger | Role | Owns session lifecycle? |
 |---|---|---|
 | "start session" | Builder | Yes — opens the session, keeps scratch files current, and writes the final session note |
 | "join as reviewer" | Reviewer | No — reviews the builder's work, appends findings, and updates handoff guidance |
@@ -146,14 +218,20 @@ ${repos}
 - \`planning mode\` — optional prompt-level mode for scoping work before implementation
 - \`review handoff\` — reviewer reads the selected lane's \`wip.md\`, \`handoff.md\`, latest finalized note, and relevant diffs before appending findings
 - \`address review\` — builder reads reviewer feedback in the selected lane's \`wip.md\` / \`handoff.md\`, responds inline, applies accepted changes, and refreshes the builder handoff
+- \`close session\` — builder runs the close-out checklist and ends with \`vibecompass close-session --session <lane-id>\`; \`end session\` is accepted as a synonym
 
 These are prompt commands for agent behavior, not \`vibecompass\` CLI subcommands.
-Reviewer handback is explicit: the reviewer ends the pass by updating the selected lane's \`wip.md\` + \`handoff.md\` and then stopping. Builder close-out uses \`vibecompass close-session --session <lane-id>\`, which follows the workflow defaults recorded in \`${rootRelativePath}/project.yaml\`.
+Reviewer handback is explicit: the reviewer ends the pass by updating the selected lane's \`wip.md\` + \`handoff.md\` and then stopping. The \`close session\` prompt runs builder close-out and ends with \`vibecompass close-session --session <lane-id>\`, which follows the workflow defaults recorded in \`${rootRelativePath}/project.yaml\`.
 \`vibecompass end-session\` is also accepted as an alias for \`vibecompass close-session\`; the canonical command name remains \`close-session\`.
 
 ## Workflow defaults
 ${renderWorkflowDefaults(workflow)}
 
+## Documentation coverage
+- The architecture, decision, and session files created by init are an initial scaffold, not a comprehensive codebase review.
+- Before risky implementation work, inspect the relevant code and update the affected architecture docs.
+- Run \`vibecompass docs-review --guided\` when you want a comprehensive documentation review. That command is explicit because it may inspect source files and use AI or hosted scan infrastructure.
+
 ## Session startup
 1. Read \`${rootRelativePath}/project.yaml\`.
 2. Read the latest finalized session note in \`${rootRelativePath}/sessions/\`.
@@ -240,6 +318,119 @@ automatically by package commands.
 `;
 }
 
+function generateStarterArchitectureDoc(projectConfig) {
+  const repos = projectConfig.repos.map((repo) => repo.id);
+  const repoLines = projectConfig.repos
+    .map((repo) => `- \`${repo.id}\` — ${repo.remote}${repo.default_branch ? ` (${repo.default_branch})` : ''}`)
+    .join('\n');
+  const repoEvidence = projectConfig.repos
+    .map((repo) => `- \`${repo.id}:/\` — declared repository root`)
+    .join('\n');
+
+  return `---
+domain: Project
+feature: Overview
+component: Project Shape
+status: In progress
+repos:
+${repos.map((repoId) => `  - ${quoteYamlString(repoId)}`).join('\n')}
+confidence: Initial scaffold
+coverage: Initial scaffold
+---
+
+## Description
+Initial project-memory scaffold for ${projectConfig.name}.
+
+${projectConfig.description ? `${projectConfig.description}\n` : ''}This document is a starting map, not a comprehensive architecture review.
+
+## Details
+- Mode: \`${projectConfig.mode}\`
+- Documentation coverage: initial scaffold
+- Repo inventory:
+${repoLines}
+
+## Coverage
+Confirmed:
+- Project identity and mode from \`project.yaml\`
+- Declared repository IDs and remotes from \`project.yaml\`
+- Project-memory root layout created by \`vibecompass init\`
+
+Not yet documented:
+- Runtime architecture and data flow
+- Auth/session model
+- Database or persistence ownership
+- External integrations
+- Deployment, jobs, and observability
+- Test strategy
+- Feature/domain/component map beyond this placeholder
+
+Before changing any undocumented area, inspect the relevant code and update or add architecture docs.
+
+## Next steps
+- Run \`vibecompass docs-review --guided\` for a comprehensive documentation review.
+- Replace this placeholder with domain/feature/component docs as the project map becomes evidence-backed.
+- Keep architecture docs aligned with implementation changes during each builder session.
+
+## Involved files
+- \`project.yaml\`
+${repoEvidence}
+`;
+}
+
+function generateDecisionExample(projectConfig) {
+  return `# Decision Examples
+
+This file is example-only guidance for ${projectConfig.name}. It is intentionally ignored by VibeCompass canonical decision parsing and must not be treated as a real decision log.
+
+Real decisions belong in domain-grouped files such as \`cross-cutting.md\`, with append-only entries:
+
+\`\`\`md
+### D-001 — Example decision title
+**Timestamp:** YYYY-MM-DD HH:MM TZ
+**Decision:** What was decided.
+**Rationale:** Why this was the correct tradeoff.
+\`\`\`
+
+Do not copy this example as-is. Allocate real decision IDs from the current canonical decision log when a decision is accepted.
+`;
+}
+
+function generateStarterSessionNote(options) {
+  const sessionDate = sessionDateFromGeneratedAt(options.generatedAt);
+  const projectConfig = options.projectConfig;
+  const repoLines = projectConfig.repos.map((repo) => `- \`${repo.id}\` — ${repo.remote}`).join('\n');
+
+  return `# Session — ${sessionDate}-1 — Project Memory Initialized
+
+Generated by \`vibecompass init\`; this is initialization history, not a builder/reviewer work session.
+
+## What we worked on
+Initialized VibeCompass project memory for ${projectConfig.name}.
+
+## Completed
+- Created the project-memory root and \`project.yaml\`.
+- Created lightweight starter architecture memory.
+- Created example-only decision guidance without seeding real decisions.
+- Generated local state manifest data from canonical files.
+
+## Decisions made
+- No real project decisions were seeded by init. Use \`decisions/EXAMPLE.md\` only as format guidance.
+
+## Models used
+- VibeCompass init scaffold.
+
+## Blockers / open questions
+- Comprehensive architecture documentation has not been reviewed yet.
+- Declared repos:
+${repoLines}
+
+## Next session should start with
+1. Run \`vibecompass docs-review --guided\` if you want a comprehensive documentation review.
+2. Inspect relevant code before making implementation changes in areas not covered by architecture docs.
+3. Replace starter placeholders with evidence-backed domain/feature/component docs.
+`;
+}
+
 function generateArchitectureGuide(projectConfig) {
   return `# Architecture
 
@@ -256,7 +447,7 @@ architecture/<domain-slug>/<feature-slug>/<component>.md
 - \`feature\`
 - \`component\`
 - \`status\`
-- optional \`repo\` or \`repos\`
+- \`repos\`: array of repo IDs, even for single-repo projects
 
 ## Recommended sections
 - \`## Description\`
@@ -328,7 +519,7 @@ Read \`${options.contextRelativeToToolingRoot}\` before doing substantive work.
 
 ## Session roles
 
-| Trigger | Role | Owns session lifecycle? |
+| Entry trigger | Role | Owns session lifecycle? |
 |---|---|---|
 | "start session" | Builder | Yes |
 | "join as reviewer" | Reviewer | No |
@@ -341,9 +532,10 @@ Read \`${options.contextRelativeToToolingRoot}\` before doing substantive work.
 - \`planning mode\` — optional prompt-level mode for scoping risky or ambiguous work before implementation
 - \`review handoff\` — reviewer reads the selected lane's \`wip.md\`, \`handoff.md\`, latest finalized note, and relevant diffs before appending findings
 - \`address review\` — builder reads reviewer feedback in the selected lane's \`wip.md\` / \`handoff.md\`, responds inline, applies accepted changes, and refreshes the builder handoff
+- \`close session\` — builder runs the close-out checklist and ends with \`vibecompass close-session --session <lane-id>\`; \`end session\` is accepted as a synonym
 
 These are prompt commands for agent behavior, not \`vibecompass\` CLI subcommands.
-Reviewer handback is explicit: the reviewer ends the pass by updating the selected lane's \`wip.md\` + \`handoff.md\` and then stopping. Builder close-out uses \`vibecompass close-session --session <lane-id>\`, which follows the workflow defaults recorded in \`${options.rootRelativePath}/project.yaml\`.
+Reviewer handback is explicit: the reviewer ends the pass by updating the selected lane's \`wip.md\` + \`handoff.md\` and then stopping. The \`close session\` prompt runs builder close-out and ends with \`vibecompass close-session --session <lane-id>\`, which follows the workflow defaults recorded in \`${options.rootRelativePath}/project.yaml\`.
 \`vibecompass end-session\` is accepted as an alias for \`vibecompass close-session\`; \`close-session\` remains the canonical command name.
 
 ## Current session
@@ -380,7 +572,7 @@ This workspace uses VibeCompass project memory rooted at \`${options.rootRelativ
 
 ## Session roles
 
-| Trigger | Role | Owns session lifecycle? |
+| Entry trigger | Role | Owns session lifecycle? |
 |---|---|---|
 | "start session" | Builder | Yes — opens and closes the session lifecycle |
 | "join as reviewer" | Reviewer | No — reviews the builder's work and updates the handoff |
@@ -393,9 +585,10 @@ This workspace uses VibeCompass project memory rooted at \`${options.rootRelativ
 - \`planning mode\` — optional prompt-level mode for scoping risky or ambiguous work before implementation
 - \`review handoff\` — reviewer reads the selected lane's \`wip.md\`, \`handoff.md\`, latest finalized note, and relevant diffs before appending findings
 - \`address review\` — builder reads reviewer feedback in the selected lane's \`wip.md\` / \`handoff.md\`, responds inline, applies accepted changes, and refreshes the builder handoff
+- \`close session\` — builder runs the close-out checklist and ends with \`vibecompass close-session --session <lane-id>\`; \`end session\` is accepted as a synonym
 
 These are prompt commands for agent behavior, not \`vibecompass\` CLI subcommands.
-Reviewer handback is explicit: the reviewer ends the pass by updating the selected lane's \`wip.md\` + \`handoff.md\` and then stopping. Builder close-out uses \`vibecompass close-session --session <lane-id>\`, which follows the workflow defaults recorded in \`${options.rootRelativePath}/project.yaml\`.
+Reviewer handback is explicit: the reviewer ends the pass by updating the selected lane's \`wip.md\` + \`handoff.md\` and then stopping. The \`close session\` prompt runs builder close-out and ends with \`vibecompass close-session --session <lane-id>\`, which follows the workflow defaults recorded in \`${options.rootRelativePath}/project.yaml\`.
 \`vibecompass end-session\` is accepted as an alias for \`vibecompass close-session\`; \`close-session\` remains the canonical command name.
 
 ## Startup
@@ -442,3 +635,16 @@ function describeReviewerHandback(workflow) {
 
   return workflow.reviewerHandback;
 }
+
+function sessionDateFromGeneratedAt(value) {
+  const date = value ? new Date(value) : new Date();
+  if (Number.isNaN(date.getTime())) {
+    return new Date().toISOString().slice(0, 10);
+  }
+
+  return date.toISOString().slice(0, 10);
+}
+
+function quoteYamlString(value) {
+  return JSON.stringify(value);
+}