@jaimevalasek/aioson 1.22.0 → 1.23.1

package/src/commands/workflow-status.js

@@ -268,20 +268,33 @@ function buildSuggestion({
   };
 }
 
-function timeSince(isoString) {
-  const now = Date.now();
-  const then = new Date(isoString).getTime();
-  const diffMs = now - then;
+function timeSince(isoString) {
+  const now = Date.now();
+  const then = new Date(isoString).getTime();
+  const diffMs = now - then;
   const minutes = Math.floor(diffMs / 60000);
   if (minutes < 1) return 'just now';
   if (minutes < 60) return `${minutes}m`;
   const hours = Math.floor(minutes / 60);
   if (hours < 24) return `${hours}h`;
   const days = Math.floor(hours / 24);
-  return `${days}d`;
-}
-
-async function runWorkflowStatus({ args, options, logger, t }) {
+  return `${days}d`;
+}
+
+function handoffMatchesState(handoff, state) {
+  if (!handoff || !state) return false;
+  const stateMode = state.mode || null;
+  const handoffMode = handoff.workflow_mode || null;
+  if (stateMode && handoffMode && stateMode !== handoffMode) return false;
+
+  const stateFeature = state.featureSlug || null;
+  const handoffFeature = handoff.feature_slug || null;
+  if (stateFeature || handoffFeature) return stateFeature === handoffFeature;
+
+  return true;
+}
+
+async function runWorkflowStatus({ args, options, logger, t }) {
   const targetDir = path.resolve(process.cwd(), args[0] || '.');
   const tool = options.tool || 'codex';
 
@@ -311,8 +324,15 @@ async function runWorkflowStatus({ args, options, logger, t }) {
   const focusStage = getFocusStage(state);
   const queuedNextStage = getQueuedNextStage(state);
 
-  const handoff = await readHandoff(targetDir);
-  const handoffProtocol = await readHandoffProtocol(targetDir);
+  const rawHandoff = await readHandoff(targetDir);
+  const handoff = handoffMatchesState(rawHandoff, state) ? rawHandoff : null;
+  const rawHandoffProtocol = await readHandoffProtocol(targetDir);
+  const handoffProtocol = handoffMatchesState({
+    workflow_mode: rawHandoffProtocol && rawHandoffProtocol.workflow_mode,
+    feature_slug: rawHandoffProtocol && rawHandoffProtocol.feature_slug
+  }, state)
+    ? rawHandoffProtocol
+    : null;
   const artifacts = await buildKeyArtifacts(targetDir, state);
   const squads = await scanSquads(targetDir);
   const genomeCount = await scanGenomes(targetDir);

package/src/constants.js

@@ -225,7 +225,7 @@ const AGENT_DEFINITIONS = [
     command: '@analyst',
     path: '.aioson/agents/analyst.md',
     dependsOn: ['.aioson/context/project.context.md'],
-    output: '.aioson/context/discovery.md'
+    output: '.aioson/context/discovery.md or .aioson/context/requirements-{slug}.md + .aioson/context/spec-{slug}.md'
   },
   {
     id: 'scope-check',
@@ -246,10 +246,10 @@ const AGENT_DEFINITIONS = [
     description: 'Project structure and technical decisions (SMALL/MEDIUM)',
     command: '@architect',
     path: '.aioson/agents/architect.md',
-    dependsOn: [
-      '.aioson/context/project.context.md',
-      '.aioson/context/discovery.md'
-    ],
+    dependsOn: [
+      '.aioson/context/project.context.md',
+      '.aioson/context/discovery.md or .aioson/context/requirements-{slug}.md + .aioson/context/spec-{slug}.md'
+    ],
     output: '.aioson/context/architecture.md'
   },
   {
@@ -272,14 +272,16 @@ const AGENT_DEFINITIONS = [
     description: 'Backlog and user stories (MEDIUM only)',
     command: '@pm',
     path: '.aioson/agents/pm.md',
-    dependsOn: [
-      '.aioson/context/project.context.md',
-      '.aioson/context/prd.md or .aioson/context/prd-{slug}.md',
-      '.aioson/context/discovery.md',
-      '.aioson/context/architecture.md',
-      '.aioson/context/ui-spec.md (when present)'
-    ],
-    output: '.aioson/context/prd.md or prd-{slug}.md (enriched with delivery plan and acceptance criteria)'
+    dependsOn: [
+      '.aioson/context/project.context.md',
+      '.aioson/context/prd.md or .aioson/context/prd-{slug}.md',
+      '.aioson/context/requirements-{slug}.md + .aioson/context/spec-{slug}.md (feature mode)',
+      '.aioson/context/discovery.md',
+      '.aioson/context/architecture.md',
+      '.aioson/context/design-doc-{slug}.md + .aioson/context/readiness-{slug}.md (feature mode, when present)',
+      '.aioson/context/ui-spec.md (when present)'
+    ],
+    output: '.aioson/context/prd.md or prd-{slug}.md (enriched with acceptance criteria) + .aioson/context/implementation-plan-{slug}.md for MEDIUM features'
   },
   {
     id: 'dev',

package/src/context-memory.js

@@ -790,9 +790,10 @@ async function writeDerivedContextMemory({
   };
 }
 
-async function collectActiveDossiers(targetDir) {
-  const featuresDir = path.join(targetDir, CONTEXT_DIR, 'features');
-  let slugs = [];
+async function collectActiveDossiers(targetDir) {
+  const featuresDir = path.join(targetDir, CONTEXT_DIR, 'features');
+  const activeFeatureSlugs = await readActiveFeatureSlugs(targetDir);
+  let slugs = [];
   try {
     const entries = await fs.readdir(featuresDir, { withFileTypes: true });
     slugs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
@@ -809,10 +810,11 @@ async function collectActiveDossiers(targetDir) {
       const updatedMatch = raw.match(/^last_updated_at:\s*(\S+)\s*$/m);
       if (!statusMatch || statusMatch[1] !== 'active') continue;
       const relPath = `${CONTEXT_DIR}/features/${slug}/dossier.md`;
-      active.push({
-        relPath,
-        slug,
-        lastUpdatedAt: updatedMatch ? updatedMatch[1] : null,
+      active.push({
+        relPath,
+        slug,
+        isPointedActive: activeFeatureSlugs.has(slug),
+        lastUpdatedAt: updatedMatch ? updatedMatch[1] : null,
         title: `Feature Dossier (${slug})`,
         group: 'dossier',
         readWhen: `active feature "${slug}" synthesis — why, what, code map, agent trail`,
@@ -832,24 +834,47 @@ async function collectActiveDossiers(targetDir) {
     return b.lastUpdatedAt.localeCompare(a.lastUpdatedAt);
   });
 
-  return active;
-}
-
-function rankDossier(dossier, { agent, goal }, rank) {
-  // Base score: between PRD (45) and bootstrap (65). Most recent dossier gets 60.
-  let score = 60 - rank * 5;
-  const reasons = [`active feature dossier (${dossier.slug})`];
-  const lookupText = `${normalizeForLookup(agent)} ${normalizeForLookup(goal)}`.trim();
-  if (lookupText.includes(dossier.slug.replace(/-/g, ' '))) {
-    score += 15;
-    reasons.push('matches active feature slug');
-  }
-  if (/(dev|architect|qa|implement|feature|dossier)/.test(lookupText)) {
-    score += 10;
-    reasons.push('agent/goal matches dossier context');
-  }
-  return { score: Math.max(score, 0), reasons };
-}
+  return active;
+}
+
+function extractFrontmatterValue(content, key) {
+  const re = new RegExp(`^${key}:\\s*(.+?)\\s*$`, 'm');
+  const match = String(content || '').match(re);
+  if (!match) return '';
+  return match[1].trim().replace(/^["']|["']$/g, '');
+}
+
+function normalizeFeaturePointer(value) {
+  const raw = String(value || '').trim();
+  if (!raw || raw === '(none)' || raw.toLowerCase() === 'none' || raw === '-') return '';
+  return raw;
+}
+
+async function readActiveFeatureSlugs(targetDir) {
+  const out = new Set();
+  const pulse = await readTextIfExists(path.join(targetDir, CONTEXT_DIR, 'project-pulse.md'));
+  const devState = await readTextIfExists(path.join(targetDir, CONTEXT_DIR, 'dev-state.md'));
+  const pulseFeature = normalizeFeaturePointer(extractFrontmatterValue(pulse, 'active_feature'));
+  const devFeature = normalizeFeaturePointer(extractFrontmatterValue(devState, 'active_feature'));
+  if (pulseFeature) out.add(pulseFeature);
+  if (devFeature) out.add(devFeature);
+  return out;
+}
+
+function rankDossier(dossier, { agent, goal }, rank) {
+  let score = 0;
+  const reasons = [];
+  const lookupText = `${normalizeForLookup(agent)} ${normalizeForLookup(goal)}`.trim();
+  if (dossier.isPointedActive) {
+    score += 70 - rank * 2;
+    reasons.push(`active feature pointer (${dossier.slug})`);
+  }
+  if (lookupText.includes(dossier.slug.replace(/-/g, ' '))) {
+    score += 75;
+    reasons.push(`matches feature slug (${dossier.slug})`);
+  }
+  return { score: Math.max(score, 0), reasons };
+}
 
 // SF-project-11: paths under these prefixes are NEVER returned in a context
 // pack, regardless of catalog score. This enforces the dev.md HARD RULE

package/src/context-selector.js

@@ -0,0 +1,394 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const {
+  parseFrontmatter,
+  parseAgentList,
+  appliesToAgent,
+  readFileSafe,
+  readProjectPulse,
+  readDevState
+} = require('./preflight-engine');
+
+const VALID_MODES = new Set(['planning', 'executing']);
+
+const SURFACES = [
+  { key: 'rules', dir: path.join('.aioson', 'rules'), recursive: false, defaultTier: 'trigger' },
+  { key: 'docs', dir: path.join('.aioson', 'docs'), recursive: true, defaultTier: 'trigger' },
+  { key: 'design_governance', dir: path.join('.aioson', 'design-docs'), recursive: false, defaultTier: 'trigger' },
+  { key: 'context', dir: path.join('.aioson', 'context'), recursive: false, defaultTier: 'trigger' },
+  { key: 'bootstrap', dir: path.join('.aioson', 'context', 'bootstrap'), recursive: false, defaultTier: 'trigger' },
+  { key: 'feature_dossier', dir: path.join('.aioson', 'context', 'features'), recursive: true, defaultTier: 'trigger' }
+];
+
+const FOUNDATION_CONTEXT_BASENAMES = new Set([
+  'project.context.md',
+  'project-pulse.md',
+  'dev-state.md',
+  'memory-index.md'
+]);
+
+const UNIVERSAL_ALWAYS_CONTEXT_BASENAMES = new Set([
+  'project.context.md',
+  'project-pulse.md'
+]);
+
+const AGENT_ALWAYS_CONTEXT_BASENAMES = new Map([
+  ['dev', new Set(['dev-state.md', 'memory-index.md'])],
+  ['deyvin', new Set(['dev-state.md', 'memory-index.md'])]
+]);
+
+function normalizeSlashes(value) {
+  return String(value || '').replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function normalizeToken(value) {
+  return String(value || '')
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[`*_]/g, '')
+    .replace(/[^a-z0-9/-]+/g, ' ')
+    .trim();
+}
+
+function normalizeFeaturePointer(value) {
+  const normalized = normalizeToken(value).replace(/\s+/g, '-');
+  if (!normalized || normalized === 'none' || normalized === '-none-' || normalized === '-') return '';
+  return normalized;
+}
+
+function parseListValue(value) {
+  if (value === undefined || value === null) return [];
+  const raw = String(value).trim();
+  if (!raw || raw === '[]') return [];
+  if (raw.startsWith('[') && raw.endsWith(']')) {
+    return raw
+      .slice(1, -1)
+      .split(',')
+      .map((item) => item.trim().replace(/^["']|["']$/g, ''))
+      .filter(Boolean);
+  }
+  return raw
+    .split(',')
+    .map((item) => item.trim().replace(/^["']|["']$/g, ''))
+    .filter(Boolean);
+}
+
+function modeFromOptions(mode) {
+  const normalized = normalizeToken(mode || 'planning');
+  return VALID_MODES.has(normalized) ? normalized : 'planning';
+}
+
+function escapeRegex(value) {
+  return String(value).replace(/[|\\{}()[\]^$+?.]/g, '\\$&');
+}
+
+function globToRegex(glob) {
+  const normalized = normalizeSlashes(glob);
+  let out = '^';
+  for (let i = 0; i < normalized.length; i += 1) {
+    const char = normalized[i];
+    const next = normalized[i + 1];
+    if (char === '*' && next === '*') {
+      out += '.*';
+      i += 1;
+    } else if (char === '*') {
+      out += '[^/]*';
+    } else {
+      out += escapeRegex(char);
+    }
+  }
+  out += '$';
+  return new RegExp(out);
+}
+
+function pathMatchesPattern(filePath, pattern) {
+  const file = normalizeSlashes(filePath);
+  const normalizedPattern = normalizeSlashes(pattern);
+  if (!file || !normalizedPattern) return false;
+  if (normalizedPattern.endsWith('/**')) {
+    const prefix = normalizedPattern.slice(0, -3);
+    return file === prefix || file.startsWith(`${prefix}/`);
+  }
+  if (!normalizedPattern.includes('*')) {
+    return file === normalizedPattern || file.startsWith(`${normalizedPattern}/`);
+  }
+  return globToRegex(normalizedPattern).test(file);
+}
+
+function splitOptionList(value) {
+  if (Array.isArray(value)) return value.map(String).filter(Boolean);
+  return String(value || '')
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+async function walkMarkdown(rootDir, relDir, recursive) {
+  const absDir = path.join(rootDir, relDir);
+  const out = [];
+  let entries;
+  try {
+    entries = await fs.readdir(absDir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    const childRel = path.join(relDir, entry.name);
+    if (entry.isDirectory()) {
+      if (recursive) out.push(...await walkMarkdown(rootDir, childRel, recursive));
+      continue;
+    }
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    if (entry.name.toLowerCase() === 'readme.md') continue;
+    out.push(normalizeSlashes(childRel));
+  }
+  return out.sort();
+}
+
+function inferContextMetadata(relPath, fm) {
+  const base = path.basename(relPath);
+  const slugMatch = base.match(/^(prd|requirements|spec|design-doc|readiness|implementation-plan|ui-spec|scope-check)-(.+)\.md$/);
+  const tags = [];
+  let featureSlug = fm.feature_slug || fm.feature || '';
+  let loadTier = fm.load_tier || 'trigger';
+
+  if (FOUNDATION_CONTEXT_BASENAMES.has(base)) {
+    if (UNIVERSAL_ALWAYS_CONTEXT_BASENAMES.has(base)) {
+      loadTier = fm.load_tier || 'always';
+    }
+    tags.push('foundation');
+  }
+  if (slugMatch) {
+    tags.push(slugMatch[1], 'feature');
+    if (!featureSlug) featureSlug = slugMatch[2];
+  }
+  if (base === 'discovery.md') tags.push('discovery', 'project-memory', 'entities', 'business-rules');
+  if (base === 'architecture.md') tags.push('architecture', 'technical-design', 'module-boundary');
+  if (base === 'ui-spec.md') tags.push('ui-spec', 'ui', 'ux', 'frontend', 'visual-design');
+  if (base === 'scope-check.md') tags.push('scope-check', 'alignment', 'pre-dev');
+  if (relPath.includes('/bootstrap/')) tags.push('bootstrap');
+  if (relPath.includes('/features/') && base === 'dossier.md') {
+    tags.push('feature', 'dossier');
+    if (!featureSlug) {
+      const parts = relPath.split('/');
+      const index = parts.indexOf('features');
+      if (index !== -1) featureSlug = parts[index + 1] || '';
+    }
+  }
+
+  return { tags, featureSlug, loadTier };
+}
+
+async function collectCandidates(targetDir) {
+  const candidates = [];
+
+  for (const surface of SURFACES) {
+    const relPaths = await walkMarkdown(targetDir, surface.dir, surface.recursive);
+    for (const relPath of relPaths) {
+      if (surface.key === 'feature_dossier' && !relPath.endsWith('/dossier.md')) continue;
+      const absPath = path.join(targetDir, relPath);
+      const content = await readFileSafe(absPath);
+      if (!content) continue;
+      const stat = await fs.stat(absPath).catch(() => null);
+      const fm = parseFrontmatter(content);
+      const inferred = inferContextMetadata(relPath, fm);
+      const description = fm.description || fm.name || path.basename(relPath, '.md');
+      candidates.push({
+        path: relPath,
+        surface: surface.key,
+        size: stat ? stat.size : content.length,
+        frontmatter: fm,
+        description,
+        agents: parseAgentList(fm.agents),
+        modes: parseListValue(fm.modes),
+        taskTypes: parseListValue(fm.task_types || fm.taskTypes),
+        triggers: parseListValue(fm.triggers),
+        pathPatterns: parseListValue(fm.paths || fm.globs),
+        scope: fm.scope || '',
+        featureSlug: fm.feature_slug || fm.feature || inferred.featureSlug || '',
+        tags: [...new Set([...parseListValue(fm.tags), ...inferred.tags])],
+        loadTier: fm.load_tier || inferred.loadTier || surface.defaultTier
+      });
+    }
+  }
+
+  return candidates;
+}
+
+function keywordMatches(haystack, needles) {
+  const normalizedHaystack = normalizeToken(haystack);
+  const haystackWords = new Set(normalizedHaystack.split(/\s+/).flatMap(wordVariants));
+  return needles.filter((needle) => {
+    const normalizedNeedle = normalizeToken(needle);
+    if (!normalizedNeedle) return false;
+    if (normalizedHaystack.includes(normalizedNeedle)) return true;
+    const words = normalizedNeedle.split(/\s+/).filter((word) => word.length >= 4);
+    if (words.length === 0) return false;
+    const hits = words.filter((word) => wordVariants(word).some((variant) => haystackWords.has(variant))).length;
+    return hits >= Math.min(2, words.length);
+  });
+}
+
+function wordVariants(word) {
+  const raw = String(word || '').trim();
+  if (!raw) return [];
+  const variants = new Set([raw]);
+  if (raw.endsWith('ing') && raw.length > 5) {
+    const stem = raw.slice(0, -3);
+    variants.add(stem);
+    variants.add(`${stem}e`);
+  }
+  if (raw.endsWith('s') && raw.length > 4) variants.add(raw.slice(0, -1));
+  return [...variants];
+}
+
+function scoreCandidate(candidate, context) {
+  const reasons = [];
+  let score = 0;
+  let effectiveLoadTier = candidate.loadTier;
+  const base = path.basename(candidate.path);
+
+  if (!appliesToAgent(candidate.frontmatter, context.agent)) return null;
+
+  if (candidate.modes.length > 0 && !candidate.modes.map(normalizeToken).includes(context.mode)) {
+    return null;
+  }
+  if (candidate.modes.length > 0) {
+    score += 5;
+    reasons.push(`mode:${context.mode}`);
+  }
+
+  const agentAlways = AGENT_ALWAYS_CONTEXT_BASENAMES.get(context.agent);
+  if (agentAlways && agentAlways.has(base)) {
+    effectiveLoadTier = 'always';
+    score += 100;
+    reasons.push('load_tier:always');
+  } else if (candidate.loadTier === 'always') {
+    score += 100;
+    reasons.push('load_tier:always');
+  }
+
+  const matchedPaths = [];
+  for (const requestedPath of context.paths) {
+    for (const pattern of candidate.pathPatterns) {
+      if (pathMatchesPattern(requestedPath, pattern)) matchedPaths.push(`${requestedPath}~${pattern}`);
+    }
+  }
+  if (matchedPaths.length > 0) {
+    score += 10;
+    reasons.push(`paths:${matchedPaths.slice(0, 3).join(',')}`);
+  }
+
+  const activeFeature = context.feature || context.activeFeature || '';
+  if (candidate.featureSlug && activeFeature && candidate.featureSlug === activeFeature) {
+    score += 45;
+    reasons.push(`feature:${candidate.featureSlug}`);
+  }
+
+  if (candidate.featureSlug && context.lookup.includes(normalizeToken(candidate.featureSlug).replace(/-/g, ' '))) {
+    score += 45;
+    reasons.push(`feature-mentioned:${candidate.featureSlug}`);
+  }
+
+  const matchedTaskTypes = keywordMatches(context.lookup, candidate.taskTypes);
+  if (matchedTaskTypes.length > 0) {
+    score += 40;
+    reasons.push(`task_types:${matchedTaskTypes.slice(0, 3).join(',')}`);
+  }
+
+  const matchedTriggers = keywordMatches(context.lookup, candidate.triggers);
+  if (matchedTriggers.length > 0) {
+    score += 40;
+    reasons.push(`triggers:${matchedTriggers.slice(0, 3).join(',')}`);
+  }
+
+  const matchedTags = keywordMatches(context.lookup, candidate.tags);
+  if (matchedTags.length > 0) {
+    score += 20;
+    reasons.push(`tags:${matchedTags.slice(0, 3).join(',')}`);
+  }
+
+  const descriptionHits = keywordMatches(context.lookup, [
+    candidate.description,
+    candidate.scope,
+    path.basename(candidate.path, '.md').replace(/-/g, ' ')
+  ]);
+  if (descriptionHits.length > 0) {
+    score += 20;
+    reasons.push(`description:${descriptionHits.slice(0, 2).join(',')}`);
+  }
+
+  const threshold = effectiveLoadTier === 'justified' ? 50 : 30;
+  if (score < threshold) return null;
+
+  return {
+    path: candidate.path,
+    surface: candidate.surface,
+    load_tier: effectiveLoadTier,
+    size: candidate.size,
+    score,
+    reason: reasons.join('; ')
+  };
+}
+
+async function selectContext(targetDir, options = {}) {
+  const agent = normalizeToken(options.agent || 'dev');
+  const mode = modeFromOptions(options.mode);
+  const task = String(options.task || options.goal || '').trim();
+  const paths = splitOptionList(options.paths || options.path).map(normalizeSlashes);
+  const feature = normalizeFeaturePointer(options.feature || options.slug || '');
+
+  const pulse = await readProjectPulse(targetDir);
+  const devState = await readDevState(targetDir);
+  const activeFeature = normalizeFeaturePointer(
+    feature || pulse.active_feature || devState.active_feature || ''
+  );
+
+  const lookup = normalizeToken([
+    agent,
+    mode,
+    task,
+    paths.join(' '),
+    activeFeature
+  ].filter(Boolean).join(' '));
+
+  const candidates = await collectCandidates(targetDir);
+  const selected = [];
+  for (const candidate of candidates) {
+    const scored = scoreCandidate(candidate, {
+      agent,
+      mode,
+      task,
+      paths,
+      feature,
+      activeFeature,
+      lookup
+    });
+    if (scored) selected.push(scored);
+  }
+
+  selected.sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
+
+  return {
+    ok: true,
+    agent,
+    mode,
+    task,
+    paths,
+    feature: feature || null,
+    active_feature: activeFeature || null,
+    selected
+  };
+}
+
+module.exports = {
+  selectContext,
+  collectCandidates,
+  parseListValue,
+  pathMatchesPattern
+};

package/src/harness/preview-artifact.js

@@ -0,0 +1,85 @@
+'use strict';
+
+/**
+ * `previewArtifact` — preview + ponteiro para outputs grandes (requirements §3.3,
+ * REQ-10). Tema 2 (should-have) da Harness Retrospective Optimization.
+ *
+ *   previewArtifact(content, { maxBytes = 8192, artifactPath, label, persist })
+ *     → { preview, truncated, fullPath, totalBytes }
+ *
+ * - Persist-first: quando `artifactPath` é dado e `persist !== false`, grava o
+ *   conteúdo INTEGRAL em disco ANTES de gerar o preview.
+ * - `content` ≤ maxBytes → preview = conteúdo integral, `truncated: false`.
+ * - `content` > maxBytes → preview = primeiros maxBytes cortados em boundary
+ *   UTF-8 seguro + linha-ponteiro padrão.
+ * - Falha de escrita NÃO lança: retorna preview truncado + `fullPath: null` +
+ *   aviso (best-effort, mesmo padrão de `attempt-artifacts.js`).
+ * - `persist: false` referencia um arquivo já persistido sem reescrevê-lo
+ *   (modo leitura de `harness:preview`).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DEFAULT_MAX_BYTES = 8192;
+
+/** Corta um Buffer UTF-8 em `maxBytes` sem quebrar caractere multi-byte (edge 10). */
+function safeUtf8Slice(buf, maxBytes) {
+  if (buf.length <= maxBytes) return buf.toString('utf8');
+  let end = maxBytes;
+  // Recua enquanto estiver no meio de uma sequência (bytes de continuação 10xxxxxx).
+  while (end > 0 && (buf[end] & 0xc0) === 0x80) end -= 1;
+  return buf.slice(0, end).toString('utf8');
+}
+
+function previewArtifact(content, options = {}) {
+  // Coerção segura: content não-string vira string ('' para null/undefined).
+  let text;
+  if (typeof content === 'string') {
+    text = content;
+  } else if (content === null || content === undefined) {
+    text = '';
+  } else {
+    try {
+      text = String(content);
+    } catch {
+      return { preview: '', truncated: false, fullPath: null, totalBytes: 0, warning: 'content não coercível' };
+    }
+  }
+
+  let maxBytes = Number(options.maxBytes);
+  if (!Number.isInteger(maxBytes) || maxBytes <= 0) maxBytes = DEFAULT_MAX_BYTES;
+
+  const artifactPath = options.artifactPath || null;
+  const persist = options.persist !== false;
+
+  const buf = Buffer.from(text, 'utf8');
+  const totalBytes = buf.length;
+
+  // Persist-first: grava integral antes de qualquer preview.
+  let fullPath = artifactPath;
+  let warning = null;
+  if (artifactPath && persist) {
+    try {
+      fs.mkdirSync(path.dirname(artifactPath), { recursive: true });
+      fs.writeFileSync(artifactPath, text, 'utf8');
+    } catch (err) {
+      fullPath = null;
+      warning = `falha ao persistir ${artifactPath}: ${err.message}`;
+    }
+  }
+
+  if (totalBytes <= maxBytes) {
+    return { preview: text, truncated: false, fullPath, totalBytes, ...(warning ? { warning } : {}) };
+  }
+
+  const cut = safeUtf8Slice(buf, maxBytes);
+  const pointer = fullPath
+    ? `[preview: primeiros ${maxBytes} de ${totalBytes} bytes — completo em ${fullPath}]`
+    : `[preview: primeiros ${maxBytes} de ${totalBytes} bytes — conteúdo completo não persistido]`;
+  const preview = `${cut}\n${pointer}`;
+
+  return { preview, truncated: true, fullPath, totalBytes, ...(warning ? { warning } : {}) };
+}
+
+module.exports = { previewArtifact, DEFAULT_MAX_BYTES, _internal: { safeUtf8Slice } };