create-quiver 0.12.0 → 0.13.0

package/src/create-quiver/lib/actionable-error.js

@@ -0,0 +1,27 @@
+function formatActionableError({ failure, impact, fix, nextCommand } = {}) {
+  const lines = [`create-quiver: ${String(failure || 'operation failed').trim()}`];
+
+  if (impact) {
+    lines.push(`Impact: ${String(impact).trim()}`);
+  }
+  if (fix) {
+    lines.push(`Fix: ${String(fix).trim()}`);
+  }
+  if (nextCommand) {
+    lines.push(`Next command: ${String(nextCommand).trim()}`);
+  }
+
+  return lines.join('\n');
+}
+
+function createActionableError(code, fields = {}, details = {}) {
+  const error = new Error(formatActionableError(fields));
+  error.code = code;
+  error.details = details;
+  return error;
+}
+
+module.exports = {
+  createActionableError,
+  formatActionableError,
+};

package/src/create-quiver/lib/agent-profiles.js

@@ -4,7 +4,7 @@ const path = require('node:path');
 const { assertSupportedProvider, formatProviderList } = require('./ai/providers');
 const { quiverInternalPaths } = require('./init-layout');
 
-const AGENT_PROFILE_ROLES = Object.freeze(['planner', 'executor', 'reviewer', 'researcher']);
+const AGENT_PROFILE_ROLES = Object.freeze(['planner', 'executor', 'reviewer', 'doctor']);
 const PROFILE_STATE_VERSION = 1;
 
 function formatError(message) {
@@ -95,6 +95,16 @@ function listAgentProfiles(projectRoot) {
 }
 
 function setAgentProfile(projectRoot, role, options = {}) {
+  const next = buildAgentProfileState(projectRoot, role, options);
+
+  const filePath = writeAgentProfiles(projectRoot, next.state);
+  return {
+    filePath,
+    profile: next.profile,
+  };
+}
+
+function buildAgentProfileState(projectRoot, role, options = {}) {
   const normalizedRole = normalizeAgentProfileRole(role);
   const provider = assertSupportedProvider(options.provider);
   const model = normalizeOptionalText(options.model, 'model');
@@ -102,7 +112,7 @@ function setAgentProfile(projectRoot, role, options = {}) {
   const context = normalizeOptionalText(options.context, 'context');
   const state = readAgentProfiles(projectRoot);
   const current = state.profiles[normalizedRole] || {};
-  const now = new Date().toISOString();
+  const now = options.now instanceof Date ? options.now.toISOString() : new Date().toISOString();
   const profile = {
     role: normalizedRole,
     provider,
@@ -119,10 +129,11 @@ function setAgentProfile(projectRoot, role, options = {}) {
   };
   state.updated_at = now;
 
-  const filePath = writeAgentProfiles(projectRoot, state);
   return {
-    filePath,
+    action: current.provider ? 'update' : 'create',
+    filePath: agentProfilesPath(projectRoot),
     profile,
+    state,
   };
 }
 
@@ -139,6 +150,7 @@ module.exports = {
   PROFILE_STATE_VERSION,
   agentProfilesPath,
   formatProviderList,
+  buildAgentProfileState,
   getAgentProfile,
   listAgentProfiles,
   normalizeAgentProfileRole,

package/src/create-quiver/lib/ai/artifacts.js

@@ -0,0 +1,318 @@
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { redactSecrets } = require('../evidence');
+const { quiverInternalPaths } = require('../init-layout');
+
+const RAW_ARTIFACT_SCHEMA_VERSION = 1;
+const DEFAULT_MAX_PROVIDER_PROMPT_BYTES = 1024 * 1024;
+const DEFAULT_MAX_REVISION_INPUT_BYTES = 400 * 1024;
+const DEFAULT_COMPACTED_REVISION_INPUT_BYTES = 120 * 1024;
+
+const IMPORTANT_REVISION_LINE = /\b(acceptance|criteri[ao]s?|decision|decisi[o\u00f3]n|risk|riesgo|file|archivo|changed|cambio|scope|alcance|validation|validaci[o\u00f3]n|test|blocker|bloque|dependency|dependencia|assumption|supuesto|pending|pendiente|error|rollback|evidence|evidencia)\b/i;
+const PROVIDER_LOG_LINE = /^\s*(?:\[?(?:debug|info|notice|trace|warn|warning)\]?[:\s-]|(?:codex|claude|gemini)\b.*(?:provider|model|prompt|token|running|loading|thinking)|(?:using|loading)\s+(?:model|provider)\b|prompt\s+(?:length|transport)\s*:)/i;
+
+function formatError(message) {
+  return `create-quiver: ${message}`;
+}
+
+function byteLength(value) {
+  return Buffer.byteLength(String(value || ''), 'utf8');
+}
+
+function normalizeText(value) {
+  return String(value || '')
+    .replace(/\r\n/g, '\n')
+    .replace(/\r/g, '\n')
+    .replace(/\u001b\[[0-9;]*m/g, '');
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function redactSensitiveLocalValues(text, options = {}) {
+  let result = redactSecrets(text);
+  const replacements = [];
+
+  if (options.projectRoot) {
+    replacements.push({
+      value: path.resolve(options.projectRoot),
+      label: '[PROJECT_ROOT]',
+    });
+  }
+
+  if (os.homedir()) {
+    replacements.push({
+      value: os.homedir(),
+      label: '[HOME]',
+    });
+  }
+
+  for (const replacement of replacements) {
+    if (!replacement.value) {
+      continue;
+    }
+    result = result.replace(new RegExp(escapeRegExp(replacement.value), 'g'), replacement.label);
+  }
+
+  return result;
+}
+
+function normalizePositiveInteger(value, fallback) {
+  if (value === undefined || value === null || value === '') {
+    return fallback;
+  }
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback;
+  }
+  return Math.floor(parsed);
+}
+
+function resolveAiArtifactLimits(options = {}) {
+  return {
+    maxProviderPromptBytes: normalizePositiveInteger(
+      options.maxProviderPromptBytes ?? process.env.QUIVER_AI_MAX_PROMPT_BYTES,
+      DEFAULT_MAX_PROVIDER_PROMPT_BYTES,
+    ),
+    maxRevisionInputBytes: normalizePositiveInteger(
+      options.maxRevisionInputBytes ?? process.env.QUIVER_AI_MAX_REVISION_INPUT_BYTES,
+      DEFAULT_MAX_REVISION_INPUT_BYTES,
+    ),
+    compactedRevisionInputBytes: normalizePositiveInteger(
+      options.compactedRevisionInputBytes ?? process.env.QUIVER_AI_COMPACTED_REVISION_INPUT_BYTES,
+      DEFAULT_COMPACTED_REVISION_INPUT_BYTES,
+    ),
+  };
+}
+
+function stripPromptEcho(text, prompt) {
+  const normalizedText = normalizeText(text);
+  const normalizedPrompt = normalizeText(prompt).trim();
+
+  if (!normalizedPrompt || normalizedPrompt.length < 80) {
+    return normalizedText;
+  }
+
+  const directIndex = normalizedText.indexOf(normalizedPrompt);
+  if (directIndex >= 0) {
+    return `${normalizedText.slice(0, directIndex)}${normalizedText.slice(directIndex + normalizedPrompt.length)}`;
+  }
+
+  return normalizedText;
+}
+
+function stripProviderLogEdges(text) {
+  const lines = normalizeText(text).split('\n');
+
+  while (lines.length > 0 && (PROVIDER_LOG_LINE.test(lines[0]) || lines[0].trim() === '')) {
+    lines.shift();
+  }
+
+  while (lines.length > 0 && (PROVIDER_LOG_LINE.test(lines[lines.length - 1]) || lines[lines.length - 1].trim() === '')) {
+    lines.pop();
+  }
+
+  return lines.join('\n').trim();
+}
+
+function normalizeDraftOutput(text, sourceText = text) {
+  const value = normalizeText(text).trim();
+  if (!value) {
+    return '';
+  }
+  return /\n\s*$/.test(String(sourceText || '')) ? `${value}\n` : value;
+}
+
+function extractCleanProviderOutput(result, options = {}) {
+  const stdout = redactSensitiveLocalValues(result?.stdout || '', options);
+  const stderr = redactSensitiveLocalValues(result?.stderr || '', options);
+  const primary = stdout.trim() ? stdout : stderr;
+  const cleaned = stripProviderLogEdges(stripPromptEcho(primary, options.prompt || ''));
+  const cleanOutput = normalizeDraftOutput(cleaned, primary);
+
+  if (cleanOutput) {
+    return {
+      cleanOutput,
+      source: stdout.trim() ? 'stdout' : 'stderr',
+      strippedPromptEcho: primary !== stripPromptEcho(primary, options.prompt || ''),
+    };
+  }
+
+  return {
+    cleanOutput: normalizeDraftOutput(primary || [stdout, stderr].filter(Boolean).join('\n'), primary),
+    source: stdout.trim() ? 'stdout' : stderr.trim() ? 'stderr' : 'empty',
+    strippedPromptEcho: false,
+  };
+}
+
+function safeArtifactName(scope, now = new Date()) {
+  const slug = String(scope || 'provider-output')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'provider-output';
+  const stamp = now.toISOString()
+    .replace(/\.\d{3}Z$/, 'z')
+    .replace(/[^0-9a-z]+/gi, '-')
+    .toLowerCase()
+    .replace(/^-+|-+$/g, '');
+  return `${stamp}-${slug}.json`;
+}
+
+function toRelativePosix(root, filePath) {
+  return path.relative(root, filePath).split(path.sep).join('/');
+}
+
+function writeRawProviderArtifact(projectRoot, runId, scope, result, options = {}) {
+  if (!runId) {
+    throw new Error(formatError('missing AI run id for raw provider artifact'));
+  }
+
+  const now = options.now || new Date();
+  const rawDir = path.join(quiverInternalPaths(projectRoot).runsDir, String(runId), 'raw');
+  const rawPath = path.join(rawDir, safeArtifactName(scope, now));
+  const serializedError = result?.error
+    ? {
+        code: result.error.code || null,
+        message: result.error.message || String(result.error),
+        provider: result.error.provider || null,
+        command: result.error.command || null,
+      }
+    : null;
+  const artifact = {
+    schema_version: RAW_ARTIFACT_SCHEMA_VERSION,
+    kind: 'provider-output',
+    scope: String(scope || 'provider-output'),
+    created_at: now.toISOString(),
+    provider: result?.provider || null,
+    command: result?.command || null,
+    args: Array.isArray(result?.args) ? result.args.slice() : [],
+    cwd: result?.cwd ? redactSensitiveLocalValues(result.cwd, { projectRoot }) : null,
+    ok: Boolean(result?.ok),
+    dry_run: Boolean(result?.dryRun),
+    exit_code: typeof result?.exitCode === 'number' ? result.exitCode : null,
+    signal: result?.signal || null,
+    timeout_ms: typeof result?.timeoutMs === 'number' ? result.timeoutMs : null,
+    prompt_transport: result?.promptTransport || null,
+    stdout: redactSensitiveLocalValues(result?.stdout || '', { projectRoot }),
+    stderr: redactSensitiveLocalValues(result?.stderr || '', { projectRoot }),
+    error: serializedError ? JSON.parse(redactSensitiveLocalValues(JSON.stringify(serializedError), { projectRoot })) : null,
+    metadata: options.metadata || {},
+  };
+
+  fs.mkdirSync(rawDir, { recursive: true });
+  fs.writeFileSync(rawPath, `${JSON.stringify(artifact, null, 2)}\n`);
+
+  return {
+    filePath: rawPath,
+    path: toRelativePosix(projectRoot, rawPath),
+    artifact,
+  };
+}
+
+function compactTextToByteLimit(text, maxBytes) {
+  let value = normalizeText(text).trim();
+  if (byteLength(value) <= maxBytes) {
+    return value;
+  }
+
+  while (byteLength(value) > maxBytes && value.length > 0) {
+    value = value.slice(0, Math.max(0, value.length - Math.ceil((byteLength(value) - maxBytes) / 2) - 32)).trimEnd();
+  }
+
+  return value;
+}
+
+function compactRevisionInput(inputText, options = {}) {
+  const limits = resolveAiArtifactLimits(options);
+  const originalText = normalizeText(inputText);
+  const originalBytes = byteLength(originalText);
+
+  if (originalBytes <= limits.maxRevisionInputBytes) {
+    return {
+      text: originalText,
+      compaction: null,
+    };
+  }
+
+  const lines = originalText.split('\n');
+  const selected = [];
+  const seen = new Set();
+  const addLine = (line) => {
+    const key = line;
+    if (seen.has(key)) {
+      return;
+    }
+    seen.add(key);
+    selected.push(line);
+  };
+
+  lines.slice(0, 24).forEach(addLine);
+  for (const line of lines) {
+    if (/^\s*#{1,6}\s+/.test(line) || IMPORTANT_REVISION_LINE.test(line)) {
+      addLine(line);
+    }
+  }
+  lines.slice(-24).forEach(addLine);
+
+  const preface = [
+    `[Quiver compacted oversized revise input from ${originalBytes} bytes before provider execution.]`,
+    '[Preserved headings and lines mentioning decisions, risks, files, acceptance criteria, validation, blockers, dependencies, assumptions, pending work, rollback, and evidence.]',
+    '',
+  ].join('\n');
+  const compacted = `${preface}${selected.join('\n')}`;
+  const targetBytes = Math.min(limits.compactedRevisionInputBytes, limits.maxRevisionInputBytes);
+  const finalText = compactTextToByteLimit(compacted, targetBytes);
+  const compactedBytes = byteLength(finalText);
+
+  if (compactedBytes > limits.maxRevisionInputBytes) {
+    const error = new Error(formatError(`ai revise input is too large after compaction (${compactedBytes} bytes; limit ${limits.maxRevisionInputBytes}). Reduce feedback size and retry.`));
+    error.code = 'AI_INPUT_TOO_LARGE';
+    throw error;
+  }
+
+  return {
+    text: `${finalText.trimEnd()}\n`,
+    compaction: {
+      compacted: true,
+      original_bytes: originalBytes,
+      compacted_bytes: compactedBytes,
+      max_revision_input_bytes: limits.maxRevisionInputBytes,
+      preserved: ['headings', 'decisions', 'risks', 'files', 'acceptance criteria', 'validation', 'blockers', 'dependencies', 'assumptions', 'rollback', 'evidence'],
+    },
+  };
+}
+
+function assertProviderPromptWithinLimit(prompt, options = {}) {
+  const limits = resolveAiArtifactLimits(options);
+  const promptBytes = byteLength(prompt);
+
+  if (promptBytes <= limits.maxProviderPromptBytes) {
+    return {
+      prompt,
+      bytes: promptBytes,
+      maxProviderPromptBytes: limits.maxProviderPromptBytes,
+    };
+  }
+
+  const error = new Error(formatError(`provider prompt is too large (${promptBytes} bytes; limit ${limits.maxProviderPromptBytes}). Reduce the input, split the work, or run ai revise with focused feedback before invoking the provider.`));
+  error.code = 'AI_PROMPT_TOO_LARGE';
+  throw error;
+}
+
+module.exports = {
+  DEFAULT_COMPACTED_REVISION_INPUT_BYTES,
+  DEFAULT_MAX_PROVIDER_PROMPT_BYTES,
+  DEFAULT_MAX_REVISION_INPUT_BYTES,
+  RAW_ARTIFACT_SCHEMA_VERSION,
+  assertProviderPromptWithinLimit,
+  byteLength,
+  compactRevisionInput,
+  extractCleanProviderOutput,
+  redactSensitiveLocalValues,
+  resolveAiArtifactLimits,
+  writeRawProviderArtifact,
+};

package/src/create-quiver/lib/ai/context-packs.js

@@ -45,9 +45,13 @@ const DEFAULT_CONTEXT_PACK_BY_ROLE = Object.freeze({
 
 const PACK_ORDER = ['full', 'planning', 'slice', 'minimal'];
 const CONTEXT_PREPARED_DOC_PATHS = Object.freeze([
+  'docs/INDEX.md',
+  'docs/PROJECT_MAP.md',
   'docs/AI_CONTEXT.md',
   'docs/AI_ONBOARDING_PROMPT.md',
   'docs/CONTEXTO.md',
+  'docs/WORKFLOW.md',
+  'docs/ARCHITECTURE.md',
   'docs/STATUS.md',
   'docs/DECISIONS.md',
 ]);

package/src/create-quiver/lib/ai/execution-plan.js

@@ -3,6 +3,7 @@ const path = require('node:path');
 
 const { resolveProfileProvider } = require('../agent-profiles');
 const { branchDelete, runGit, statusPorcelain, worktreeAdd, worktreePrune, worktreeRemove } = require('../git');
+const { withLock } = require('../locks');
 const { safeBranchName, worktreesRootForRepo } = require('../slice');
 const { buildGraph, computeLevels, detectFileConflicts, isFoundationSliceId, readAllSlices, topoSort, SliceGraphError } = require('../slice-graph');
 const { runExecuteSlice } = require('./executor');
@@ -35,6 +36,9 @@ function summarizeSlice(node, repoRoot) {
     title: node.title || node.sliceId,
     status: node.status || 'draft',
     files: Array.isArray(node.files) ? node.files : [],
+    expected_read_paths: Array.isArray(node.expected_read_paths) ? node.expected_read_paths : [],
+    allowed_write_paths: Array.isArray(node.allowed_write_paths) ? node.allowed_write_paths : [],
+    validation_hints: Array.isArray(node.validation_hints) ? node.validation_hints : [],
     depends_on: Array.isArray(node.depends_on) ? node.depends_on : [],
     parallel_safe: node.parallel_safe || null,
     parallel_safe_reason: node.parallel_safe_reason || null,
@@ -274,7 +278,7 @@ function formatHumanExecutionPlan(report) {
 
   for (const level of report.ready_levels) {
     const modeLabel = level.parallel_ready ? 'parallel-ready' : 'sequential';
-    lines.push(`Level ${level.index} (${modeLabel})`);
+    lines.push(`Wave ${level.index} (${modeLabel})`);
     lines.push(`Worktree strategy: ${level.worktree_strategy.mode}`);
     if (level.fallback_reason) {
       lines.push(`Fallback: ${level.fallback_reason}`);
@@ -282,6 +286,7 @@ function formatHumanExecutionPlan(report) {
 
     for (const slice of level.slices) {
       lines.push(`- ${slice.ref} [${slice.status}]`);
+      lines.push(`  parallel_safe: ${slice.parallel_safe || 'unspecified'}${slice.parallel_safe_reason ? ` (${slice.parallel_safe_reason})` : ''}`);
     }
 
     if (level.conflicts.length > 0) {
@@ -454,6 +459,7 @@ async function runSequentialGroup(repoRoot, level, group, options = {}) {
         providerExplicit: options.providerExplicit,
         role: options.role,
         slice: slice.slice_path,
+        skipWorktreeBranchCheck: true,
         timeout: options.timeout,
       });
       results.push({
@@ -481,6 +487,13 @@ async function runParallelGroupInWorktrees(repoRoot, level, group, options = {})
   const slices = group.slice_refs.map((ref) => level.slices.find((item) => item.ref === ref));
   const workspaces = slices.map((slice, index) => buildDelegatedWorkspace(repoRoot, slice, runId, index, options));
 
+  return withLock(repoRoot, `execute-plan-${runId}`, {
+    command: 'ai execute-plan',
+    metadata: {
+      mode: 'delegated',
+      slices: group.slice_refs,
+    },
+  }, async () => {
   let runResults;
   try {
     worktreePrune(repoRoot);
@@ -498,6 +511,7 @@ async function runParallelGroupInWorktrees(repoRoot, level, group, options = {})
         providerExplicit: options.providerExplicit,
         role: options.role,
         slice: workspace.slice.slice_path,
+        skipWorktreeBranchCheck: true,
         timeout: options.timeout,
       });
       const commit = runGit(['rev-parse', 'HEAD'], workspace.worktreePath);
@@ -536,6 +550,7 @@ async function runParallelGroupInWorktrees(repoRoot, level, group, options = {})
     workspace: item.workspace.worktreePath,
     integratedCommit: item.commit,
   }));
+  });
 }
 
 async function runExecutePlan(repoRoot, options = {}) {