scriveno 2.0.8 → 2.0.10

package/lib/auto-invoke-engine.js

@@ -1,4 +1,5 @@
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 
 const DEFAULT_RUNTIME_SUPPORT = {
@@ -91,6 +92,229 @@ const REVIEW_KEYWORDS = [
   'CONTINUITY',
 ];
 
+const CORE_PROJECT_FILES = [
+  'WORK.md',
+  'OUTLINE.md',
+  'STYLE-GUIDE.md',
+  'RECORD.md',
+  'config.json',
+];
+
+const DEFAULT_AGENT_NAMES = [
+  'continuity-checker',
+  'drafter',
+  'plan-checker',
+  'researcher',
+  'translator',
+  'voice-checker',
+];
+
+const ROUTE_PRIORITY_FIXTURES = [
+  {
+    name: 'empty workspace',
+    setup: 'no .manuscript directory',
+    expectedCommand: '/scr:new-work',
+    reason: 'start or import before lifecycle routing',
+  },
+  {
+    name: 'scanned project without drafts',
+    setup: 'STATE.md and CONTEXT.md exist, drafts are absent',
+    expectedCommand: '/scr:plan',
+    reason: 'planning comes before drafting when no plan is ready',
+  },
+  {
+    name: 'planned work without draft',
+    setup: 'plan files exist and drafts are absent',
+    expectedCommand: '/scr:draft',
+    reason: 'connected plan evidence should route to drafting',
+  },
+  {
+    name: 'draft without review coverage',
+    setup: 'draft files exist and reviews are absent',
+    expectedCommand: '/scr:editor-review',
+    reason: 'review should precede export and packaging',
+  },
+  {
+    name: 'revision proposal waiting',
+    setup: 'proposal files exist in .manuscript/proposals',
+    expectedCommand: '/scr:editor-review --proposal',
+    reason: 'proposal review is more urgent than general notes',
+  },
+  {
+    name: 'translation follow-up',
+    setup: 'translation folders or target languages exist after review coverage',
+    expectedCommand: '/scr:back-translate',
+    reason: 'translation needs verification before multi-publish',
+  },
+  {
+    name: 'publishing prerequisite gap',
+    setup: 'reviewed drafts exist without front matter, back matter, blurb, or cover handoff',
+    expectedCommand: '/scr:front-matter',
+    reason: 'specific packaging prerequisites come before final publish',
+  },
+];
+
+const RUNTIME_INSTALL_SURFACES = {
+  'claude-code': {
+    commands: (homeDir) => path.join(homeDir, '.claude', 'commands'),
+    agents: (homeDir) => path.join(homeDir, '.claude', 'agents'),
+    commandLayout: 'flat',
+  },
+  cursor: {
+    commands: (homeDir) => path.join(homeDir, '.cursor', 'commands', 'scr'),
+    agents: (homeDir) => path.join(homeDir, '.cursor', 'agents'),
+    commandLayout: 'nested',
+  },
+  'gemini-cli': {
+    commands: (homeDir) => path.join(homeDir, '.gemini', 'commands', 'scr'),
+    agents: (homeDir) => path.join(homeDir, '.gemini', 'agents'),
+    commandLayout: 'nested',
+  },
+  codex: {
+    commands: (homeDir) => path.join(homeDir, '.codex', 'commands', 'scr'),
+    skills: (homeDir) => path.join(homeDir, '.codex', 'skills'),
+    agents: (homeDir) => path.join(homeDir, '.codex', 'agents'),
+    commandLayout: 'nested',
+    metadata: 'toml',
+  },
+  opencode: {
+    commands: (homeDir) => path.join(homeDir, '.config', 'opencode', 'commands', 'scr'),
+    agents: (homeDir) => path.join(homeDir, '.config', 'opencode', 'agents'),
+    commandLayout: 'nested',
+  },
+  copilot: {
+    commands: (homeDir) => path.join(homeDir, '.github', 'commands', 'scr'),
+    agents: (homeDir) => path.join(homeDir, '.github', 'agents'),
+    commandLayout: 'nested',
+  },
+  windsurf: {
+    commands: (homeDir) => path.join(homeDir, '.windsurf', 'commands', 'scr'),
+    agents: (homeDir) => path.join(homeDir, '.windsurf', 'agents'),
+    commandLayout: 'nested',
+  },
+  antigravity: {
+    commands: (homeDir) => path.join(homeDir, '.gemini', 'antigravity', 'commands', 'scr'),
+    agents: (homeDir) => path.join(homeDir, '.gemini', 'antigravity', 'agents'),
+    commandLayout: 'nested',
+  },
+  manus: {
+    skills: (homeDir) => path.join(homeDir, '.manus', 'skills', 'scriveno'),
+    agents: (homeDir) => path.join(homeDir, '.manus', 'skills', 'scriveno', 'agents'),
+    commandLayout: 'skill-bundle',
+  },
+  'perplexity-desktop': {
+    guide: (homeDir) => path.join(homeDir, '.scriveno', 'perplexity'),
+    commandLayout: 'guided-mcp',
+  },
+  generic: {
+    skills: (homeDir) => path.join(homeDir, '.scriveno', 'skills'),
+    agents: (homeDir) => path.join(homeDir, '.scriveno', 'skills', 'agents'),
+    commandLayout: 'skill-bundle',
+  },
+};
+
+const AGENT_ROUTE_POLICIES = {
+  '/scr:plan': {
+    agents: ['plan-checker'],
+    reason: 'planning can validate unit plans before drafting',
+  },
+  '/scr:draft': {
+    agents: ['drafter', 'voice-checker'],
+    reason: 'drafting uses fresh-context prose generation and voice checks',
+  },
+  '/scr:editor-review': {
+    agents: ['diagnostic worker'],
+    reason: 'editor review can isolate flagged issue groups',
+  },
+  '/scr:voice-check': {
+    agents: ['voice-checker'],
+    reason: 'voice review compares drafts against STYLE-GUIDE.md',
+  },
+  '/scr:continuity-check': {
+    agents: ['continuity-checker'],
+    reason: 'continuity review checks contradictions and timeline drift',
+  },
+  '/scr:translate': {
+    agents: ['translator'],
+    reason: 'translation runs one fresh-context translation pass per unit',
+  },
+  '/scr:back-translate': {
+    agents: ['translator'],
+    reason: 'back-translation verifies target-language drift',
+  },
+  '/scr:beta-reader': {
+    agents: ['beta-reader worker'],
+    reason: 'beta review benefits from isolated reader perspectives',
+  },
+  '/scr:quick-write': {
+    agents: ['drafter', 'voice-checker'],
+    reason: 'quick writing still benefits from voice-aware isolation',
+  },
+  '/scr:map-manuscript': {
+    agents: ['voice analyst', 'structure analyst', 'character analyst', 'theme analyst', 'world analyst', 'pacing analyst'],
+    reason: 'manuscript import uses parallel analysis workers when available',
+  },
+};
+
+const LOCAL_ROUTE_POLICIES = {
+  '/scr:save': 'refresh CONTEXT.md, HISTORY.log, and project checkpoint state',
+  '/scr:scan': 'reconcile STATE.md and disk evidence',
+  '/scr:health': 'diagnose project and runtime health',
+  '/scr:sync': 'compare and refresh installed runtime surfaces',
+  '/scr:validate': 'run project validation checks',
+  '/scr:check-notes': 'surface unresolved writer notes',
+  '/scr:progress': 'compute read-only project progress',
+  '/scr:session-report': 'compute read-only session metrics',
+};
+
+const MANUAL_ROUTE_POLICIES = {
+  '/scr:publish': 'publication packaging can overwrite deliverables and needs writer choices',
+  '/scr:export': 'export writes output artifacts and may overwrite packages',
+  '/scr:track merge': 'merging revision tracks is a writer-owned decision',
+  '/scr:undo': 'undo changes state and should stay explicit',
+};
+
+const CATEGORY_ROUTE_POLICIES = {
+  core: { lane: 'mixed', level: 3, reason: 'core lifecycle routes may read, write, or spawn depending on the current stage' },
+  navigation: { lane: 'read-only', level: 1, reason: 'navigation routes should inspect and recommend by default' },
+  quality: { lane: 'agent-or-local', level: 3, reason: 'quality routes may run bounded diagnostics or text transforms' },
+  character_world: { lane: 'local-helper', level: 2, reason: 'character and world routes update project knowledge files' },
+  structure: { lane: 'local-helper', level: 2, reason: 'structure routes update maps, outlines, and state evidence' },
+  structure_management: { lane: 'manual-gated', level: 4, reason: 'structure management can rename, remove, or reorder manuscript units' },
+  review: { lane: 'agent-or-local', level: 3, reason: 'review routes may invoke bounded diagnostic workers' },
+  illustration: { lane: 'local-helper', level: 2, reason: 'illustration routes generate prompts and asset briefs' },
+  publishing: { lane: 'manual-gated', level: 4, reason: 'publishing routes write deliverables and package outputs' },
+  translation: { lane: 'agent-or-local', level: 3, reason: 'translation routes use translator agents or verification helpers' },
+  sacred_exclusive: { lane: 'agent-or-local', level: 3, reason: 'sacred routes perform specialized consistency and reference work' },
+  utility: { lane: 'local-helper', level: 2, reason: 'utility routes perform deterministic diagnostics or project updates' },
+  session: { lane: 'local-helper', level: 2, reason: 'session routes save, compare, resume, or report project state' },
+  collaboration: { lane: 'manual-gated', level: 4, reason: 'collaboration routes change revision tracks and require writer control' },
+};
+
+function normalizeCommandRef(commandName) {
+  if (commandName.startsWith('/scr:')) return commandName;
+  return `/scr:${commandName}`;
+}
+
+function getCommandAutomationPolicy(commandName, command = {}) {
+  const ref = normalizeCommandRef(commandName);
+  if (AGENT_ROUTE_POLICIES[ref]) {
+    return { ref, lane: 'agent-ready', level: 3, reason: AGENT_ROUTE_POLICIES[ref].reason };
+  }
+  if (LOCAL_ROUTE_POLICIES[ref]) {
+    return { ref, lane: 'local-helper', level: 2, reason: LOCAL_ROUTE_POLICIES[ref] };
+  }
+  if (MANUAL_ROUTE_POLICIES[ref]) {
+    return { ref, lane: 'manual-gated', level: 4, reason: MANUAL_ROUTE_POLICIES[ref] };
+  }
+  const categoryPolicy = CATEGORY_ROUTE_POLICIES[command.category] || {
+    lane: 'read-only',
+    level: 1,
+    reason: 'unclassified routes should only suggest until a category policy is added',
+  };
+  return { ref, ...categoryPolicy };
+}
+
 function pathExists(filePath) {
   try {
     fs.accessSync(filePath);
@@ -156,11 +380,124 @@ function countMarkdownFiles(dir) {
   return listFiles(dir, { extensions: ['.md'], recursive: true }).length;
 }
 
+function countFiles(dir, extensions = null) {
+  return listFiles(dir, { extensions, recursive: true }).length;
+}
+
+function anyPathExists(paths) {
+  return paths.some(pathExists);
+}
+
 function containsAny(text, keywords) {
   const haystack = text.toUpperCase();
   return keywords.some((keyword) => haystack.includes(keyword.toUpperCase()));
 }
 
+function detectProjectReadiness(manuscriptDir) {
+  const missing = CORE_PROJECT_FILES.filter((file) => !pathExists(path.join(manuscriptDir, file)));
+  return {
+    state: missing.length ? 'incomplete' : 'ready',
+    missing,
+    suggest: missing.length ? '/scr:scan' : null,
+  };
+}
+
+function detectPlanSignal(manuscriptDir, draftFiles) {
+  const files = listFiles(path.join(manuscriptDir, 'plans'), { extensions: ['.md'], recursive: true });
+  if (files.length === 0) {
+    return { state: 'missing', count: 0, suggest: '/scr:plan' };
+  }
+  if (draftFiles.length === 0) {
+    return { state: 'ready-to-draft', count: files.length, suggest: '/scr:draft' };
+  }
+  if (files.length > draftFiles.length) {
+    return { state: 'partially-drafted', count: files.length, suggest: '/scr:draft' };
+  }
+  return { state: 'covered', count: files.length, suggest: null };
+}
+
+function detectReviewCoverage(draftFiles, reviewFiles) {
+  if (draftFiles.length === 0) {
+    return { state: 'none', suggest: null };
+  }
+  if (reviewFiles.length === 0) {
+    return { state: 'missing', suggest: '/scr:editor-review' };
+  }
+  if (reviewFiles.length < draftFiles.length) {
+    return { state: 'partial', suggest: '/scr:editor-review' };
+  }
+  return { state: 'covered', suggest: null };
+}
+
+function detectNotesSignal(manuscriptDir) {
+  const noteFiles = [
+    ...listFiles(path.join(manuscriptDir, 'notes'), { extensions: ['.md', '.txt'], recursive: true }),
+    path.join(manuscriptDir, 'NOTES.md'),
+    path.join(manuscriptDir, 'TODO.md'),
+  ].filter(pathExists);
+  const pending = noteFiles.filter((file) => containsAny(readText(file), ['TODO', 'FIXME', 'UNRESOLVED', 'QUESTION:', 'NOTE:']));
+  return {
+    state: pending.length ? 'pending' : 'none',
+    count: pending.length,
+    files: pending.map((file) => path.relative(manuscriptDir, file)),
+    suggest: pending.length ? '/scr:check-notes' : null,
+  };
+}
+
+function detectTrackSignal(manuscriptDir) {
+  const tracks = readJson(path.join(manuscriptDir, 'tracks.json'));
+  const proposals = listFiles(path.join(manuscriptDir, 'proposals'), { extensions: ['.md'], recursive: true });
+  const activeTracks = Array.isArray(tracks?.tracks)
+    ? tracks.tracks.filter((track) => track && track.status !== 'merged')
+    : [];
+  let state = 'none';
+  let suggest = null;
+  if (proposals.length > 0) {
+    state = 'proposal-ready';
+    suggest = '/scr:editor-review --proposal';
+  } else if (activeTracks.length > 0) {
+    state = 'active';
+    suggest = '/scr:track';
+  }
+  return {
+    state,
+    activeCount: activeTracks.length,
+    proposalCount: proposals.length,
+    suggest,
+  };
+}
+
+function detectPublishingSignal(manuscriptDir, draftFiles) {
+  const frontMatter = countMarkdownFiles(path.join(manuscriptDir, 'front-matter'));
+  const backMatter = countMarkdownFiles(path.join(manuscriptDir, 'back-matter'));
+  const blurb = pathExists(path.join(manuscriptDir, 'output', 'blurb.md'));
+  const ebookCover = anyPathExists([
+    path.join(manuscriptDir, 'build', 'ebook-cover.jpg'),
+    path.join(manuscriptDir, 'build', 'ebook-cover.png'),
+  ]);
+  const printCover = anyPathExists([
+    path.join(manuscriptDir, 'build', 'paperback-cover.pdf'),
+    path.join(manuscriptDir, 'build', 'hardcover-cover.pdf'),
+  ]);
+  const promptFiles = countFiles(path.join(manuscriptDir, 'illustrations', 'cover'), ['.md']);
+  const gaps = [];
+  if (draftFiles.length > 0 && frontMatter === 0) gaps.push('front-matter');
+  if (draftFiles.length > 0 && backMatter === 0) gaps.push('back-matter');
+  if (draftFiles.length > 0 && !blurb) gaps.push('blurb');
+  if (draftFiles.length > 0 && !ebookCover && promptFiles === 0) gaps.push('cover-art');
+  return {
+    state: gaps.length ? 'gaps' : draftFiles.length ? 'ready' : 'not-started',
+    frontMatter,
+    backMatter,
+    blurb,
+    ebookCover,
+    printCover,
+    coverPrompts: promptFiles,
+    gaps,
+    suggest: gaps.length ? `/scr:${gaps[0]}` : null,
+  };
+}
+
 function scanReviewSignals(manuscriptDir) {
   const reviewDirs = [
     'reviews',
@@ -290,6 +627,13 @@ function chooseRecommendation(signals, counts) {
       alternatives: ['/scr:progress', '/scr:resume-work'],
     };
   }
+  if (signals.tracks?.state === 'proposal-ready') {
+    return {
+      command: signals.tracks.suggest,
+      reason: `${signals.tracks.proposalCount} revision proposal(s) are waiting for review.`,
+      alternatives: ['/scr:track', '/scr:compare', '/scr:progress'],
+    };
+  }
   if (signals.reviews.count > 0) {
     return {
       command: '/scr:editor-review',
@@ -297,6 +641,20 @@ function chooseRecommendation(signals, counts) {
       alternatives: ['/scr:voice-check', '/scr:continuity-check', '/scr:progress'],
     };
   }
+  if (signals.notes?.count > 0) {
+    return {
+      command: signals.notes.suggest,
+      reason: `${signals.notes.count} note file(s) contain unresolved items.`,
+      alternatives: ['/scr:progress', '/scr:scan', '/scr:next'],
+    };
+  }
+  if (signals.plan?.state === 'ready-to-draft' || signals.plan?.state === 'partially-drafted') {
+    return {
+      command: signals.plan.suggest,
+      reason: `${signals.plan.count} plan file(s) exist and drafting is the next connected step.`,
+      alternatives: ['/scr:plan', '/scr:voice-test', '/scr:progress'],
+    };
+  }
   if (counts.drafts === 0) {
     return {
       command: '/scr:plan',
@@ -304,6 +662,13 @@ function chooseRecommendation(signals, counts) {
       alternatives: ['/scr:discuss', '/scr:draft', '/scr:voice-test'],
     };
   }
+  if (signals.reviewCoverage?.state === 'missing' || signals.reviewCoverage?.state === 'partial') {
+    return {
+      command: signals.reviewCoverage.suggest,
+      reason: `Drafts exist but review coverage is ${signals.reviewCoverage.state}.`,
+      alternatives: ['/scr:voice-check', '/scr:continuity-check', '/scr:progress'],
+    };
+  }
   if (signals.translation.state !== 'none') {
     return {
       command: '/scr:back-translate',
@@ -311,6 +676,13 @@ function chooseRecommendation(signals, counts) {
       alternatives: ['/scr:cultural-adaptation', '/scr:multi-publish', '/scr:progress'],
     };
   }
+  if (signals.publishing?.state === 'gaps' && signals.export.state === 'missing') {
+    return {
+      command: signals.publishing.suggest || '/scr:publish',
+      reason: `Publishing prerequisites have gaps: ${signals.publishing.gaps.join(', ')}.`,
+      alternatives: ['/scr:publish', '/scr:export', '/scr:progress'],
+    };
+  }
   if (signals.export.state === 'stale' || signals.export.state === 'missing') {
     return {
       command: signals.export.suggest || '/scr:export',
@@ -332,6 +704,90 @@ function chooseRecommendation(signals, counts) {
   };
 }
 
+function dedupeByCommand(items) {
+  const seen = new Set();
+  return items.filter((item) => {
+    if (seen.has(item.command)) return false;
+    seen.add(item.command);
+    return true;
+  });
+}
+
+function buildAutomationPlan(signals, recommendation) {
+  const spawnPolicy = AGENT_ROUTE_POLICIES[recommendation.command];
+  const localPolicy = LOCAL_ROUTE_POLICIES[recommendation.command];
+  const manualPolicy = MANUAL_ROUTE_POLICIES[recommendation.command];
+  const spawnCandidates = [];
+  const localCandidates = [];
+  const manualGates = [];
+
+  if (spawnPolicy) {
+    spawnCandidates.push({
+      command: recommendation.command,
+      agents: spawnPolicy.agents,
+      reason: spawnPolicy.reason,
+    });
+  }
+  if (signals.plan?.state === 'ready-to-draft' || signals.plan?.state === 'partially-drafted') {
+    spawnCandidates.push({
+      command: '/scr:draft',
+      agents: AGENT_ROUTE_POLICIES['/scr:draft'].agents,
+      reason: 'planned units can be drafted by the drafter route',
+    });
+  }
+  if (signals.reviewCoverage?.state === 'missing' || signals.reviewCoverage?.state === 'partial') {
+    spawnCandidates.push({
+      command: '/scr:editor-review',
+      agents: AGENT_ROUTE_POLICIES['/scr:editor-review'].agents,
+      reason: 'drafts without review coverage should enter the review route',
+    });
+  }
+  if (signals.translation?.state !== 'none') {
+    spawnCandidates.push({
+      command: '/scr:back-translate',
+      agents: AGENT_ROUTE_POLICIES['/scr:back-translate'].agents,
+      reason: 'translation work needs a verification pass',
+    });
+  }
+
+  if (localPolicy) {
+    localCandidates.push({ command: recommendation.command, reason: localPolicy });
+  }
+  if (signals.context?.state === 'stale') {
+    localCandidates.push({ command: signals.context.suggest || '/scr:scan', reason: 'refresh stale context before chaining work' });
+  }
+  if (signals.notes?.count > 0) {
+    localCandidates.push({ command: '/scr:check-notes', reason: 'surface unresolved notes before the next writing route' });
+  }
+  if (signals.save?.state !== 'clean') {
+    localCandidates.push({ command: signals.save.suggest || '/scr:save', reason: 'save manuscript changes before branching or packaging' });
+  }
+
+  if (manualPolicy) {
+    manualGates.push({ command: recommendation.command, reason: manualPolicy });
+  }
+  if (signals.publishing?.state === 'gaps') {
+    manualGates.push({
+      command: '/scr:publish',
+      reason: `publishing still needs ${signals.publishing.gaps.join(', ')}`,
+    });
+  }
+  if (signals.tracks?.state === 'active' || signals.tracks?.state === 'proposal-ready') {
+    manualGates.push({
+      command: signals.tracks.suggest || '/scr:track',
+      reason: 'revision-track decisions belong to the writer',
+    });
+  }
+
+  const recommendationIsManual = manualGates.some((gate) => gate.command === recommendation.command);
+  return {
+    mode: recommendationIsManual ? 'manual-gated' : spawnCandidates.length ? 'agent-ready' : localCandidates.length ? 'local-helper' : 'read-only',
+    spawnCandidates: dedupeByCommand(spawnCandidates),
+    localCandidates: dedupeByCommand(localCandidates),
+    manualGates: dedupeByCommand(manualGates),
+  };
+}
+
 function analyzeProject(projectRoot = process.cwd(), options = {}) {
   const root = path.resolve(projectRoot);
   const manuscriptDir = options.manuscriptDir || path.join(root, '.manuscript');
@@ -346,11 +802,18 @@ function analyzeProject(projectRoot = process.cwd(), options = {}) {
       context: { state: 'none', suggest: null },
       history: { state: 'none', lastFailed: false },
       reviews: { state: 'none', count: 0, files: [] },
+      reviewCoverage: { state: 'none', suggest: null },
+      readiness: { state: 'none', missing: [], suggest: null },
+      plan: { state: 'none', count: 0, suggest: null },
+      notes: { state: 'none', count: 0, files: [], suggest: null },
+      tracks: { state: 'none', activeCount: 0, proposalCount: 0, suggest: null },
       translation: { state: 'none', count: 0, configuredTargets: [] },
       export: { state: 'none', suggest: null },
+      publishing: { state: 'not-started', gaps: [], suggest: null },
       save: { state: 'clean', suggest: null },
     };
     const recommendation = chooseRecommendation(signals, { drafts: 0 });
+    const automation = buildAutomationPlan(signals, recommendation);
     return {
       projectRoot: root,
       manuscriptDir,
@@ -359,12 +822,13 @@ function analyzeProject(projectRoot = process.cwd(), options = {}) {
       counts: { drafts: 0, plans: 0, reviews: 0 },
       signals,
       recommendation,
+      automation,
     };
   }
 
   const draftFiles = listFiles(path.join(manuscriptDir, 'drafts'), { extensions: ['.md'], recursive: true });
-  const planCount = countMarkdownFiles(path.join(manuscriptDir, 'plans'));
   const reviewFiles = scanReviewSignals(manuscriptDir);
+  const allReviewFiles = listFiles(path.join(manuscriptDir, 'reviews'), { extensions: ['.md', '.txt'], recursive: true });
   const historySignal = detectHistorySignal(manuscriptDir);
   const sourceFiles = [
     statePath,
@@ -379,21 +843,28 @@ function analyzeProject(projectRoot = process.cwd(), options = {}) {
     hasState: pathExists(statePath),
     context: detectContextSignal(manuscriptDir, draftFiles),
     history: historySignal,
+    readiness: detectProjectReadiness(manuscriptDir),
+    plan: detectPlanSignal(manuscriptDir, draftFiles),
     reviews: {
       state: reviewFiles.length ? 'pending' : 'none',
       count: reviewFiles.length,
       files: reviewFiles,
     },
+    reviewCoverage: detectReviewCoverage(draftFiles, allReviewFiles),
+    notes: detectNotesSignal(manuscriptDir),
+    tracks: detectTrackSignal(manuscriptDir),
     translation: detectTranslationSignal(manuscriptDir, config),
     export: detectExportSignal(manuscriptDir, sourceFiles),
+    publishing: detectPublishingSignal(manuscriptDir, draftFiles),
     save: detectSaveSignal(historySignal, draftFiles),
   };
   const counts = {
     drafts: draftFiles.length,
-    plans: planCount,
+    plans: signals.plan.count,
     reviews: reviewFiles.length,
   };
   const recommendation = chooseRecommendation(signals, counts);
+  const automation = buildAutomationPlan(signals, recommendation);
   return {
     projectRoot: root,
     manuscriptDir,
@@ -402,6 +873,7 @@ function analyzeProject(projectRoot = process.cwd(), options = {}) {
     counts,
     signals,
     recommendation,
+    automation,
   };
 }
 
@@ -413,9 +885,15 @@ function formatProactiveChecks(analysis) {
   return [
     'Proactive checks:',
     stateLine,
+    `  Readiness: ${signals.readiness?.state || 'none'}${signals.readiness?.missing?.length ? `, missing ${signals.readiness.missing.join(', ')}` : ''}`,
     `  Session: ${signals.context.state}${signals.context.suggest ? `, suggest ${signals.context.suggest}` : ''}`,
+    `  Plans: ${signals.plan?.state || 'none'}${signals.plan?.suggest ? `, suggest ${signals.plan.suggest}` : ''}`,
     `  Reviews: ${signals.reviews.count ? `${signals.reviews.count} pending, suggest /scr:editor-review` : 'none'}`,
+    `  Review coverage: ${signals.reviewCoverage?.state || 'none'}${signals.reviewCoverage?.suggest ? `, suggest ${signals.reviewCoverage.suggest}` : ''}`,
+    `  Notes: ${signals.notes?.count ? `${signals.notes.count} pending, suggest ${signals.notes.suggest}` : 'none'}`,
+    `  Tracks: ${signals.tracks?.state || 'none'}${signals.tracks?.suggest ? `, suggest ${signals.tracks.suggest}` : ''}`,
     `  Translation: ${signals.translation.state}`,
+    `  Publishing: ${signals.publishing?.state || 'none'}${signals.publishing?.gaps?.length ? `, gaps ${signals.publishing.gaps.join(', ')}` : ''}`,
     `  Export: ${signals.export.state}${signals.export.suggest ? `, suggest ${signals.export.suggest}` : ''}`,
     `  Save: ${signals.save.state}${signals.save.suggest ? `, suggest ${signals.save.suggest}` : ''}`,
   ].join('\n');
@@ -425,14 +903,31 @@ function formatAutomationStatus(analysis, options = {}) {
   const trigger = options.trigger || '/scr:next';
   const localOperation = options.localOperation || 'auto-invoke engine: read-only';
   const autoInvoked = options.autoInvoked || `${analysis.recommendation.command}: no`;
+  const automation = analysis.automation || { mode: 'read-only', spawnCandidates: [], localCandidates: [], manualGates: [] };
+  const candidateAgentLines = automation.spawnCandidates.length
+    ? automation.spawnCandidates.map((candidate) => `- ${candidate.command}: ${candidate.agents.join(', ')} (${candidate.reason})`)
+    : ['- none'];
+  const localCandidateLines = automation.localCandidates.length
+    ? automation.localCandidates.map((candidate) => `- ${candidate.command}: ${candidate.reason}`)
+    : ['- none'];
+  const manualGateLines = automation.manualGates.length
+    ? automation.manualGates.map((gate) => `- ${gate.command}: ${gate.reason}`)
+    : ['- none'];
   return [
     'Automation status:',
     `Trigger: ${trigger}`,
+    `Mode: ${automation.mode}`,
     'Spawned agents:',
     '- none',
+    'Candidate agents:',
+    ...candidateAgentLines,
     'Local operations:',
     `- ${localOperation}`,
     `- state route computed: ${analysis.signals.hasProject ? 'yes' : 'no project'}`,
+    'Candidate local helpers:',
+    ...localCandidateLines,
+    'Manual gates:',
+    ...manualGateLines,
     'Auto-invoked:',
     `- ${autoInvoked}`,
     `Why: ${analysis.recommendation.reason}`,
@@ -474,6 +969,381 @@ function listRuntimeAgentSupport() {
   }));
 }
 
+function getPackageRoot() {
+  return path.resolve(__dirname, '..');
+}
+
+function loadConstraints(options = {}) {
+  const constraintsPath = options.constraintsPath || path.join(getPackageRoot(), 'data', 'CONSTRAINTS.json');
+  const constraints = readJson(constraintsPath);
+  return constraints && constraints.commands ? constraints : { commands: {}, command_intents: {}, dependencies: {} };
+}
+
+function expectedCommandCount(options = {}) {
+  return Object.keys(loadConstraints(options).commands || {}).length;
+}
+
+function getExpectedAgentNames(options = {}) {
+  if (Array.isArray(options.agentNames) && options.agentNames.length > 0) {
+    return options.agentNames.slice().sort();
+  }
+  const agentsRoot = options.agentsRoot || path.join(getPackageRoot(), 'agents');
+  const files = listFiles(agentsRoot, { extensions: ['.md'], recursive: false })
+    .map((file) => path.basename(file, '.md'))
+    .sort();
+  return files.length ? files : DEFAULT_AGENT_NAMES.slice().sort();
+}
+
+function collectSafeApplyActions(projectRoot = process.cwd(), options = {}) {
+  const analysis = options.analysis || analyzeProject(projectRoot);
+  const actions = [
+    {
+      name: 'status sweep',
+      command: 'scriveno status',
+      status: 'ran',
+      mutation: false,
+      reason: 'computed the current route, local-helper, agent, and manual-gate state',
+    },
+  ];
+
+  const readOnlyHelpers = new Set(['/scr:progress', '/scr:session-report', '/scr:check-notes', '/scr:health', '/scr:validate']);
+  const writeOrInstallHelpers = new Set(['/scr:save', '/scr:scan', '/scr:sync']);
+
+  for (const candidate of analysis.automation.localCandidates || []) {
+    const command = candidate.command;
+    if (readOnlyHelpers.has(command)) {
+      actions.push({
+        name: command.replace('/scr:', ''),
+        command,
+        status: 'ready',
+        mutation: false,
+        reason: candidate.reason,
+      });
+    } else if (writeOrInstallHelpers.has(command)) {
+      actions.push({
+        name: command.replace('/scr:', ''),
+        command,
+        status: 'skipped',
+        mutation: true,
+        reason: `${candidate.reason}; safe apply reports this instead of writing files`,
+      });
+    } else {
+      actions.push({
+        name: command.replace('/scr:', ''),
+        command,
+        status: 'suggested',
+        mutation: null,
+        reason: candidate.reason,
+      });
+    }
+  }
+
+  for (const candidate of analysis.automation.spawnCandidates || []) {
+    actions.push({
+      name: candidate.command.replace('/scr:', ''),
+      command: candidate.command,
+      status: 'agent-candidate',
+      mutation: null,
+      reason: `${candidate.agents.join(', ')}: ${candidate.reason}`,
+    });
+  }
+
+  for (const gate of analysis.automation.manualGates || []) {
+    actions.push({
+      name: gate.command.replace('/scr:', ''),
+      command: gate.command,
+      status: 'manual-gate',
+      mutation: true,
+      reason: gate.reason,
+    });
+  }
+
+  return {
+    projectRoot: analysis.projectRoot,
+    trigger: options.trigger || 'scriveno status --apply-safe',
+    appliedCount: actions.filter((action) => action.status === 'ran').length,
+    skippedCount: actions.filter((action) => action.status === 'skipped' || action.status === 'manual-gate').length,
+    safeToRunCount: actions.filter((action) => action.status === 'ready').length,
+    agentCandidateCount: actions.filter((action) => action.status === 'agent-candidate').length,
+    actions,
+  };
+}
+
+function formatSafeApplyReport(result) {
+  const actionLines = result.actions.length
+    ? result.actions.map((action) => {
+      const mutation = action.mutation === false ? 'read-only' : action.mutation === true ? 'writes or external action' : 'host-dependent';
+      return `- ${action.command}: ${action.status} (${mutation}) - ${action.reason}`;
+    })
+    : ['- none'];
+  return [
+    'Safe apply status:',
+    `Trigger: ${result.trigger}`,
+    `Project: ${result.projectRoot}`,
+    `Read-only checks run: ${result.appliedCount}`,
+    `Safe helpers ready: ${result.safeToRunCount}`,
+    `Agent candidates: ${result.agentCandidateCount}`,
+    `Manual or write-gated actions: ${result.skippedCount}`,
+    'Actions:',
+    ...actionLines,
+  ].join('\n');
+}
+
+function runtimeSurfacePaths(runtimeKey, options = {}) {
+  const homeDir = options.homeDir || os.homedir();
+  const surface = RUNTIME_INSTALL_SURFACES[runtimeKey];
+  if (!surface) return null;
+  const out = { runtimeKey };
+  for (const [key, value] of Object.entries(surface)) {
+    if (typeof value === 'function') out[key] = value(homeDir);
+  }
+  out.commandLayout = surface.commandLayout;
+  out.metadata = surface.metadata || 'none';
+  return out;
+}
+
+function inspectAgentAvailability(options = {}) {
+  const runtimeKeys = options.runtimeKeys || Object.keys(DEFAULT_RUNTIME_SUPPORT);
+  const agentNames = getExpectedAgentNames(options);
+  const runtimes = [];
+
+  for (const runtimeKey of runtimeKeys) {
+    const support = getRuntimeAgentSupport(runtimeKey);
+    const paths = runtimeSurfacePaths(runtimeKey, options);
+    if (!support || !paths) continue;
+
+    if (runtimeKey === 'perplexity-desktop') {
+      const guideReady = pathExists(path.join(paths.guide || '', 'SETUP.md'));
+      runtimes.push({
+        runtime: runtimeKey,
+        label: support.label,
+        status: guideReady ? 'guided-ready' : 'guided-missing',
+        nativeSpawn: support.nativeSpawn,
+        fallback: support.fallback,
+        agentsDir: null,
+        promptCount: 0,
+        missingPrompts: agentNames,
+        metadataCount: 0,
+        missingMetadata: [],
+      });
+      continue;
+    }
+
+    const agentsDir = paths.agents || path.join(paths.skills || '', 'agents');
+    const promptFiles = agentNames.map((name) => `${name}.md`);
+    const missingPrompts = promptFiles
+      .filter((fileName) => !pathExists(path.join(agentsDir, fileName)))
+      .map((fileName) => path.basename(fileName, '.md'));
+    const metadataFiles = support.metadata === 'toml'
+      ? agentNames.map((name) => `${name}.toml`)
+      : [];
+    const missingMetadata = metadataFiles
+      .filter((fileName) => !pathExists(path.join(agentsDir, fileName)))
+      .map((fileName) => path.basename(fileName, '.toml'));
+    const promptCount = promptFiles.length - missingPrompts.length;
+    const metadataCount = metadataFiles.length - missingMetadata.length;
+    let status = 'missing';
+    if (missingPrompts.length === 0 && missingMetadata.length === 0 && support.metadata === 'toml') {
+      status = 'metadata-ready';
+    } else if (missingPrompts.length === 0) {
+      status = 'prompt-fallback-ready';
+    }
+
+    runtimes.push({
+      runtime: runtimeKey,
+      label: support.label,
+      status,
+      nativeSpawn: support.nativeSpawn,
+      fallback: support.fallback,
+      agentsDir,
+      promptCount,
+      missingPrompts,
+      metadataCount,
+      missingMetadata,
+    });
+  }
+
+  return {
+    checkedAt: new Date().toISOString(),
+    expectedAgents: agentNames,
+    runtimes,
+  };
+}
+
+function formatAgentAvailabilityReport(report) {
+  const lines = [
+    'Agent availability:',
+    `Expected agents: ${report.expectedAgents.join(', ')}`,
+  ];
+  for (const runtime of report.runtimes) {
+    lines.push(`- ${runtime.label}: ${runtime.status}`);
+    if (runtime.agentsDir) lines.push(`  Agents: ${runtime.agentsDir}`);
+    lines.push(`  Prompts: ${runtime.promptCount}/${report.expectedAgents.length}`);
+    if (runtime.missingPrompts.length) lines.push(`  Missing prompts: ${runtime.missingPrompts.join(', ')}`);
+    if (runtime.missingMetadata.length) lines.push(`  Missing metadata: ${runtime.missingMetadata.join(', ')}`);
+    lines.push(`  Fallback: ${runtime.fallback}`);
+  }
+  return lines.join('\n');
+}
+
+function countInstalledCommands(paths) {
+  if (!paths) return 0;
+  if (paths.commandLayout === 'flat') {
+    return listFiles(paths.commands, { extensions: ['.md'], recursive: false })
+      .filter((file) => /^scr-/.test(path.basename(file)))
+      .length;
+  }
+  if (paths.commandLayout === 'skill-bundle') {
+    return countMarkdownFiles(path.join(paths.skills || '', 'commands', 'scr'));
+  }
+  if (paths.commandLayout === 'guided-mcp') {
+    return pathExists(path.join(paths.guide || '', 'SETUP.md')) ? 1 : 0;
+  }
+  return countMarkdownFiles(paths.commands || '');
+}
+
+function inspectRuntimeSmoke(options = {}) {
+  const runtimeKeys = options.runtimeKeys || Object.keys(DEFAULT_RUNTIME_SUPPORT);
+  const expectedCommands = options.expectedCommands || expectedCommandCount(options);
+  const expectedAgents = getExpectedAgentNames(options);
+  const dataDir = options.dataDir || path.join(options.homeDir || os.homedir(), '.scriveno');
+  const enginePath = path.join(dataDir, 'lib', 'auto-invoke-engine.js');
+  const results = [];
+
+  for (const runtimeKey of runtimeKeys) {
+    const support = getRuntimeAgentSupport(runtimeKey);
+    const paths = runtimeSurfacePaths(runtimeKey, options);
+    if (!support || !paths) continue;
+    const commandCount = countInstalledCommands(paths);
+    const skillCount = runtimeKey === 'codex' && pathExists(paths.skills || '')
+      ? fs.readdirSync(paths.skills, { withFileTypes: true }).filter((entry) => entry.isDirectory() && entry.name.startsWith('scr-')).length
+      : paths.skills && pathExists(path.join(paths.skills, 'SKILL.md')) ? 1 : 0;
+    const agentsDir = paths.agents || (paths.skills ? path.join(paths.skills, 'agents') : null);
+    const promptCount = countFiles(agentsDir, ['.md']);
+    const metadataCount = runtimeKey === 'codex' ? countFiles(agentsDir, ['.toml']) : 0;
+    const commandReady = runtimeKey === 'perplexity-desktop' ? commandCount === 1 : commandCount >= expectedCommands;
+    const skillReady = runtimeKey === 'codex' ? skillCount >= expectedCommands : !paths.skills || skillCount >= 1;
+    const agentReady = runtimeKey === 'perplexity-desktop' ? true : promptCount >= expectedAgents.length;
+    const metadataReady = runtimeKey === 'codex' ? metadataCount >= expectedAgents.length : true;
+    const engineReady = pathExists(enginePath);
+    const ok = commandReady && skillReady && agentReady && metadataReady && engineReady;
+
+    results.push({
+      runtime: runtimeKey,
+      label: support.label,
+      ok,
+      commands: commandCount,
+      expectedCommands: runtimeKey === 'perplexity-desktop' ? 1 : expectedCommands,
+      skills: skillCount,
+      agents: promptCount,
+      expectedAgents: runtimeKey === 'perplexity-desktop' ? 0 : expectedAgents.length,
+      metadata: metadataCount,
+      expectedMetadata: runtimeKey === 'codex' ? expectedAgents.length : 0,
+      engineReady,
+      paths,
+    });
+  }
+
+  return {
+    checkedAt: new Date().toISOString(),
+    dataDir,
+    enginePath,
+    expectedCommands,
+    expectedAgents,
+    ok: results.every((result) => result.ok),
+    runtimes: results,
+  };
+}
+
+function formatRuntimeSmokeReport(report) {
+  const lines = [
+    'Runtime smoke status:',
+    `Shared engine: ${report.enginePath} (${report.runtimes.some((runtime) => runtime.engineReady) ? 'present' : 'missing'})`,
+    `Overall: ${report.ok ? 'pass' : 'needs attention'}`,
+  ];
+  for (const runtime of report.runtimes) {
+    lines.push(`- ${runtime.label}: ${runtime.ok ? 'pass' : 'needs attention'}`);
+    lines.push(`  Commands: ${runtime.commands}/${runtime.expectedCommands}`);
+    if (runtime.skills) lines.push(`  Skills: ${runtime.skills}`);
+    if (runtime.expectedAgents) lines.push(`  Agent prompts: ${runtime.agents}/${runtime.expectedAgents}`);
+    if (runtime.expectedMetadata) lines.push(`  Agent metadata: ${runtime.metadata}/${runtime.expectedMetadata}`);
+    lines.push(`  Shared engine: ${runtime.engineReady ? 'present' : 'missing'}`);
+  }
+  return lines.join('\n');
+}
+
+function buildRouteGraph(options = {}) {
+  const constraints = options.commands ? options : loadConstraints(options);
+  const commands = constraints.commands || {};
+  const categories = {};
+  const lanes = {};
+  const nodes = Object.entries(commands).map(([name, command]) => {
+    const policy = getCommandAutomationPolicy(name, command);
+    categories[command.category || 'uncategorized'] = (categories[command.category || 'uncategorized'] || 0) + 1;
+    lanes[policy.lane] = (lanes[policy.lane] || 0) + 1;
+    return {
+      id: `/scr:${name}`,
+      name,
+      category: command.category || 'uncategorized',
+      lane: policy.lane,
+      level: policy.level,
+      available: command.available || [],
+      reason: policy.reason,
+    };
+  });
+
+  const edges = [];
+  for (const [intent, names] of Object.entries(constraints.command_intents || {})) {
+    for (let i = 0; i < names.length - 1; i++) {
+      if (commands[names[i]] && commands[names[i + 1]]) {
+        edges.push({ from: `/scr:${names[i]}`, to: `/scr:${names[i + 1]}`, type: 'intent-order', label: intent });
+      }
+    }
+  }
+  for (const [chainName, entries] of Object.entries(constraints.dependencies || {})) {
+    if (!Array.isArray(entries)) continue;
+    const commandEntries = entries.filter((entry) => entry && typeof entry === 'object' && entry.command);
+    for (let i = 0; i < commandEntries.length - 1; i++) {
+      const from = commandEntries[i].command;
+      const to = commandEntries[i + 1].command;
+      if (commands[from] && commands[to]) {
+        edges.push({ from: `/scr:${from}`, to: `/scr:${to}`, type: 'dependency-chain', label: chainName });
+      }
+    }
+  }
+
+  return {
+    generatedAt: new Date().toISOString(),
+    commandCount: nodes.length,
+    edgeCount: edges.length,
+    categories,
+    lanes,
+    agentRoutes: nodes.filter((node) => node.lane === 'agent-ready' || node.lane === 'agent-or-local').length,
+    localRoutes: nodes.filter((node) => node.lane === 'local-helper').length,
+    manualRoutes: nodes.filter((node) => node.lane === 'manual-gated').length,
+    readOnlyRoutes: nodes.filter((node) => node.lane === 'read-only').length,
+    nodes,
+    edges,
+  };
+}
+
+function formatRouteGraphReport(graph) {
+  const laneLines = Object.entries(graph.lanes)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([lane, count]) => `- ${lane}: ${count}`);
+  return [
+    'Route graph audit:',
+    `Commands: ${graph.commandCount}`,
+    `Edges: ${graph.edgeCount}`,
+    `Agent-capable routes: ${graph.agentRoutes}`,
+    `Local-helper routes: ${graph.localRoutes}`,
+    `Manual-gated routes: ${graph.manualRoutes}`,
+    `Read-only routes: ${graph.readOnlyRoutes}`,
+    'Automation lanes:',
+    ...laneLines,
+  ].join('\n');
+}
+
 function parseCliArgs(argv) {
   const out = {
     projectRoot: process.cwd(),
@@ -508,13 +1378,30 @@ if (require.main === module) {
 }
 
 module.exports = {
+  AGENT_ROUTE_POLICIES,
+  CATEGORY_ROUTE_POLICIES,
   DEFAULT_RUNTIME_SUPPORT,
+  DEFAULT_AGENT_NAMES,
+  LOCAL_ROUTE_POLICIES,
+  MANUAL_ROUTE_POLICIES,
+  ROUTE_PRIORITY_FIXTURES,
   analyzeProject,
+  buildRouteGraph,
+  collectSafeApplyActions,
+  expectedCommandCount,
+  formatAgentAvailabilityReport,
+  formatRouteGraphReport,
   formatProactiveChecks,
   formatAutomationStatus,
   formatRecommendation,
   formatReport,
+  formatRuntimeSmokeReport,
+  formatSafeApplyReport,
+  getCommandAutomationPolicy,
+  getExpectedAgentNames,
   getRuntimeAgentSupport,
+  inspectAgentAvailability,
+  inspectRuntimeSmoke,
   listRuntimeAgentSupport,
   parseCliArgs,
 };