@jaimevalasek/aioson 1.9.3 → 1.17.2

package/src/commands/workflow-next.js

@@ -967,6 +967,57 @@ async function activateStage(targetDir, state, locale, tool, explicitAgent = nul
   };
 }
 
+/**
+ * F3 (workflow-handoff-integrity v1.9.6) — pending-decisions guard.
+ *
+ * Reads `.aioson/plans/{slug}/manifest.md` frontmatter. If `status` matches
+ * `pending-<X>-decisions`, throws a hard error recommending the agent that
+ * resolves those decisions. `--force` overrides.
+ *
+ * Whitelist (DD-02): known agents are [architect, product, pm, qa]. Unknown
+ * captured groups still block but are flagged as unrecognized so typos don't
+ * silently route to nonexistent agents.
+ *
+ * Errors:
+ *   - WORKFLOW_NEXT_PENDING_DECISIONS — pending state detected, advance blocked.
+ *
+ * @param {string} targetDir   Project root.
+ * @param {string|null} slug   Feature slug (null in project mode → no-op).
+ * @param {boolean} force      When true, skip the check (--force override).
+ * @returns {Promise<void>}    Resolves silently when no pending decisions block; throws otherwise.
+ */
+const PENDING_STATE_WHITELIST = ['architect', 'product', 'pm', 'qa'];
+
+async function assertManifestNotPending(targetDir, slug, force) {
+  if (force) return; // AC-F3-03 — explicit override.
+  if (!slug) return; // AC-F3-04 — no feature context, nothing to guard.
+  const manifestPath = path.join(targetDir, '.aioson', 'plans', slug, 'manifest.md');
+  let content;
+  try {
+    content = await fs.readFile(manifestPath, 'utf8');
+  } catch {
+    return; // AC-F3-04 — no manifest (e.g. MICRO without Sheldon stage), skip.
+  }
+  const status = parseFrontmatterValue(content, 'status');
+  if (!status) return; // No status field → nothing to assert.
+  const match = String(status).match(/^pending-(.+)-decisions$/);
+  if (!match) return; // AC-F3-02 — only pending-*-decisions pattern blocks.
+  const captured = match[1].toLowerCase();
+  const known = PENDING_STATE_WHITELIST.includes(captured);
+  const recommendation = known
+    ? `Próximo agente recomendado: @${captured}.`
+    : `Estado desconhecido '${captured}' — whitelist atual: ${PENDING_STATE_WHITELIST.map((a) => `@${a}`).join(', ')}.`;
+  const err = new Error(
+    `[workflow:next] Gate blocked: ${slug} manifest tem status 'pending-${captured}-decisions'. ${recommendation} Use --force para override.`
+  );
+  err.code = 'WORKFLOW_NEXT_PENDING_DECISIONS';
+  err.slug = slug;
+  err.pendingState = captured;
+  err.knownState = known;
+  throw err;
+}
+
+
 async function runWorkflowNext({ args, options, logger, t }) {
   if (options.status || options.suggest) {
     const { runWorkflowStatus } = require('./workflow-status');
@@ -988,6 +1039,17 @@ async function runWorkflowNext({ args, options, logger, t }) {
   let completedStage = null;
 
   if (options.complete || options['complete-current']) {
+    // F3 (workflow-handoff-integrity v1.9.6) — pending-decisions guard.
+    // Hard error if sheldon manifest has unresolved decisions; --force overrides.
+    try {
+      await assertManifestNotPending(targetDir, state.featureSlug, Boolean(options.force));
+    } catch (err) {
+      if (err && err.code === 'WORKFLOW_NEXT_PENDING_DECISIONS') {
+        logErrorLine(err.message);
+      }
+      throw err;
+    }
+
     let finalized;
     try {
       finalized = await finalizeCurrentStage(
@@ -1274,6 +1336,8 @@ module.exports = {
   applySkip,
   activateStage,
   runWorkflowNext,
+  assertManifestNotPending,
+  PENDING_STATE_WHITELIST,
   shouldRouteToValidator,
   detectUnsubstantiatedCompletions
 };

package/src/handoff-contract.js

@@ -405,6 +405,30 @@ async function getBlockingRevisions(targetDir, featureSlug) {
   }
 }
 
+/**
+ * getCanonicalArtifactsForAgent
+ *
+ * Public lookup helper used by `runAgentDone` (F2 — workflow-handoff-integrity v1.9.5)
+ * to determine which artifact paths an agent is expected to produce. Returns the
+ * paths declared by the agent's contract in CONTRACTS, fully resolved against the
+ * workflow state.
+ *
+ * @param {string} agent       Agent name (with or without leading `@`).
+ * @param {string} targetDir   Project root path (absolute).
+ * @param {object} state       Workflow state: { mode, featureSlug, classification }.
+ * @returns {string[]|null}    Array of absolute artifact paths, or `null` when the
+ *                             agent is not registered in CONTRACTS. An empty array
+ *                             means the agent produces no canonical artifact (e.g.
+ *                             `@committer`, `@dev`) — auto-emit should be skipped.
+ */
+async function getCanonicalArtifactsForAgent(agent, targetDir, state) {
+  const normalizedAgent = String(agent || '').replace(/^@/, '').toLowerCase();
+  if (!normalizedAgent) return null;
+  const contract = CONTRACTS[normalizedAgent];
+  if (!contract) return null;
+  return await resolveArtifacts(contract, targetDir, state || {});
+}
+
 module.exports = {
   parseFrontmatterValue,
   readProjectClassification,
@@ -413,5 +437,6 @@ module.exports = {
   validateHandoffContract,
   formatContractError,
   getBlockingRevisions,
+  getCanonicalArtifactsForAgent,
   CONTRACTS
 };

package/src/i18n/messages/en.js

@@ -26,6 +26,15 @@ module.exports = {
       'aioson context:pack [path] [--agent=<agent>] [--goal=<text>] [--module=<module-or-folder>] [--max-files=8] [--json] [--locale=en]',
     help_context_load:
       'aioson context:load [path] --target=<rule|brain>:<slug> --agent=<name> [--batch="slug1,slug2"] [--feature=<slug>] [--classification=<MICRO|SMALL|MEDIUM>] [--verbose] [--json] [--locale=en]',
+    help_chain_audit:
+      'aioson chain:audit <file> [path] [--limit=N] [--feature=<slug>] [--json] [--locale=en]',
+    chain_audit: {
+      file_required: 'chain:audit requires a file path. Usage: aioson chain:audit <file> [--limit=N] [--feature=<slug>] [--json]',
+      runtime_unavailable: 'chain:audit runtime db unavailable: {error}',
+      query_failed: 'chain:audit failed to query chain_edges: {error}',
+      no_impacts: 'chain:audit {file} → no impacts detected ({duration}ms)',
+      results_header: 'chain:audit {file} → {count} impact(s) ({duration}ms):'
+    },
     context_load: {
       target_required: 'context:load requires --target=<rule|brain>:<slug>.',
       agent_required: 'context:load requires --agent=<name>.',

package/src/i18n/messages/es.js

@@ -27,6 +27,15 @@ module.exports = {
       'aioson context:pack [path] [--agent=<agente>] [--goal=<texto>] [--module=<modulo-o-carpeta>] [--max-files=8] [--json] [--locale=es]',
     help_context_load:
       'aioson context:load [path] --target=<rule|brain>:<slug> --agent=<nombre> [--batch="slug1,slug2"] [--feature=<slug>] [--classification=<MICRO|SMALL|MEDIUM>] [--verbose] [--json] [--locale=es]',
+    help_chain_audit:
+      'aioson chain:audit <archivo> [path] [--limit=N] [--feature=<slug>] [--json] [--locale=es]',
+    chain_audit: {
+      file_required: 'chain:audit requiere una ruta de archivo. Uso: aioson chain:audit <archivo> [--limit=N] [--feature=<slug>] [--json]',
+      runtime_unavailable: 'chain:audit runtime db no disponible: {error}',
+      query_failed: 'chain:audit falló al consultar chain_edges: {error}',
+      no_impacts: 'chain:audit {file} → ningún impacto detectado ({duration}ms)',
+      results_header: 'chain:audit {file} → {count} impacto(s) ({duration}ms):'
+    },
     context_load: {
       target_required: 'context:load requiere --target=<rule|brain>:<slug>.',
       agent_required: 'context:load requiere --agent=<nombre>.',

package/src/i18n/messages/fr.js

@@ -27,6 +27,15 @@ module.exports = {
       'aioson context:pack [path] [--agent=<agent>] [--goal=<texte>] [--module=<module-ou-dossier>] [--max-files=8] [--json] [--locale=fr]',
     help_context_load:
       'aioson context:load [path] --target=<rule|brain>:<slug> --agent=<nom> [--batch="slug1,slug2"] [--feature=<slug>] [--classification=<MICRO|SMALL|MEDIUM>] [--verbose] [--json] [--locale=fr]',
+    help_chain_audit:
+      'aioson chain:audit <fichier> [path] [--limit=N] [--feature=<slug>] [--json] [--locale=fr]',
+    chain_audit: {
+      file_required: 'chain:audit exige un chemin de fichier. Usage : aioson chain:audit <fichier> [--limit=N] [--feature=<slug>] [--json]',
+      runtime_unavailable: 'chain:audit runtime db indisponible : {error}',
+      query_failed: 'chain:audit échec de la requête chain_edges : {error}',
+      no_impacts: 'chain:audit {file} → aucun impact détecté ({duration}ms)',
+      results_header: 'chain:audit {file} → {count} impact(s) ({duration}ms) :'
+    },
     context_load: {
       target_required: 'context:load exige --target=<rule|brain>:<slug>.',
       agent_required: 'context:load exige --agent=<nom>.',

package/src/i18n/messages/pt-BR.js

@@ -27,6 +27,15 @@ module.exports = {
       'aioson context:pack [path] [--agent=<agente>] [--goal=<texto>] [--module=<modulo-ou-pasta>] [--max-files=8] [--json] [--locale=pt-BR]',
     help_context_load:
       'aioson context:load [path] --target=<rule|brain>:<slug> --agent=<nome> [--batch="slug1,slug2"] [--feature=<slug>] [--classification=<MICRO|SMALL|MEDIUM>] [--verbose] [--json] [--locale=pt-BR]',
+    help_chain_audit:
+      'aioson chain:audit <arquivo> [path] [--limit=N] [--feature=<slug>] [--json] [--locale=pt-BR]',
+    chain_audit: {
+      file_required: 'chain:audit exige um caminho de arquivo. Uso: aioson chain:audit <arquivo> [--limit=N] [--feature=<slug>] [--json]',
+      runtime_unavailable: 'chain:audit runtime db indisponível: {error}',
+      query_failed: 'chain:audit falhou ao consultar chain_edges: {error}',
+      no_impacts: 'chain:audit {file} → nenhum impacto detectado ({duration}ms)',
+      results_header: 'chain:audit {file} → {count} impacto(s) ({duration}ms):'
+    },
     context_load: {
       target_required: 'context:load exige --target=<rule|brain>:<slug>.',
       agent_required: 'context:load exige --agent=<nome>.',

package/src/lib/agent-semantic-diff.js

@@ -0,0 +1,199 @@
+'use strict';
+
+/**
+ * agent-semantic-diff — pure helpers for detecting semantic drift between
+ * workspace `.aioson/agents/{agent}.md` and template `template/.aioson/agents/{agent}.md`.
+ *
+ * F4 / T5 (workflow-handoff-integrity v1.9.8). Designed to catch the 981a8fd-style
+ * migration where the workspace agent prompt was updated but the template was not.
+ * The existing `sync-agents-preflight#checkParity` only inspects the `## Feature dossier`
+ * section length — this helper extends that lens to headers, section content, and
+ * frontmatter.
+ *
+ * Three diff strategies (per DD-03):
+ *   - diffHeaders        — section list (presence + order) at `##` and `###` levels
+ *   - diffSectionContent — hash-based diff of section bodies (catches content drift)
+ *   - diffFrontmatter    — field-level YAML-ish frontmatter comparison
+ *
+ * Plain text body diff is deliberately skipped — too noisy for typos/cosmetic edits.
+ */
+
+const crypto = require('node:crypto');
+
+// ─── Frontmatter ─────────────────────────────────────────────────────────────
+
+function extractFrontmatter(content) {
+  const match = String(content || '').match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return null;
+  const out = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    if (!key) continue;
+    out[key] = line.slice(idx + 1).trim().replace(/^["']|["']$/g, '');
+  }
+  return out;
+}
+
+function diffFrontmatter(workspaceContent, templateContent) {
+  const ws = extractFrontmatter(workspaceContent);
+  const tpl = extractFrontmatter(templateContent);
+  if (ws === null && tpl === null) return null; // both have no frontmatter
+  const missingInTemplate = [];
+  const missingInWorkspace = [];
+  const valueChanged = [];
+  const wsObj = ws || {};
+  const tplObj = tpl || {};
+  for (const key of Object.keys(wsObj)) {
+    if (!(key in tplObj)) {
+      missingInTemplate.push(key);
+    } else if (wsObj[key] !== tplObj[key]) {
+      valueChanged.push({ key, workspace: wsObj[key], template: tplObj[key] });
+    }
+  }
+  for (const key of Object.keys(tplObj)) {
+    if (!(key in wsObj)) missingInWorkspace.push(key);
+  }
+  if (missingInTemplate.length + missingInWorkspace.length + valueChanged.length === 0) return null;
+  return { missingInTemplate, missingInWorkspace, valueChanged };
+}
+
+// ─── Headers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Extract ## and ### headers in document order.
+ * Skips anything inside fenced code blocks.
+ */
+function extractHeaders(content) {
+  const lines = String(content || '').split(/\r?\n/);
+  const headers = [];
+  let inFence = false;
+  for (const line of lines) {
+    if (/^```/.test(line.trim())) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    const m = line.match(/^(##{1,2})\s+(.+?)\s*$/);
+    if (m) headers.push(m[2].trim());
+  }
+  return headers;
+}
+
+function diffHeaders(workspaceContent, templateContent) {
+  const ws = extractHeaders(workspaceContent);
+  const tpl = extractHeaders(templateContent);
+  const wsSet = new Set(ws);
+  const tplSet = new Set(tpl);
+  const missingInTemplate = ws.filter((h) => !tplSet.has(h));
+  const missingInWorkspace = tpl.filter((h) => !wsSet.has(h));
+  // Order check: of the headers present in both, do they appear in the same sequence?
+  const common = ws.filter((h) => tplSet.has(h));
+  const commonInTpl = tpl.filter((h) => wsSet.has(h));
+  const reordered = common.length === commonInTpl.length
+    && common.some((h, i) => h !== commonInTpl[i]);
+  if (missingInTemplate.length + missingInWorkspace.length === 0 && !reordered) return null;
+  return { missingInTemplate, missingInWorkspace, reordered };
+}
+
+// ─── Section content (hash-based) ────────────────────────────────────────────
+
+/**
+ * Split content into Map<header, body>. Body is normalized (trimmed lines,
+ * collapsed whitespace) before hashing to avoid cosmetic-only false positives.
+ */
+function extractSections(content) {
+  const lines = String(content || '').split(/\r?\n/);
+  const sections = new Map();
+  let current = '__preamble__';
+  let body = [];
+  let inFence = false;
+  for (const line of lines) {
+    if (/^```/.test(line.trim())) {
+      inFence = !inFence;
+      body.push(line);
+      continue;
+    }
+    const headerMatch = !inFence && line.match(/^(##{1,2})\s+(.+?)\s*$/);
+    if (headerMatch) {
+      sections.set(current, body.join('\n'));
+      current = headerMatch[2].trim();
+      body = [];
+      continue;
+    }
+    body.push(line);
+  }
+  sections.set(current, body.join('\n'));
+  return sections;
+}
+
+function normalizeBody(body) {
+  return String(body || '')
+    .split(/\r?\n/)
+    .map((l) => l.replace(/\s+/g, ' ').trim())
+    .filter(Boolean)
+    .join('\n');
+}
+
+function hashBody(body) {
+  return crypto.createHash('sha256').update(normalizeBody(body)).digest('hex').slice(0, 16);
+}
+
+function diffSectionContent(workspaceContent, templateContent) {
+  const ws = extractSections(workspaceContent);
+  const tpl = extractSections(templateContent);
+  const diverged = [];
+  for (const [header, wsBody] of ws.entries()) {
+    if (!tpl.has(header)) continue; // missing-header case handled by diffHeaders
+    const wsHash = hashBody(wsBody);
+    const tplHash = hashBody(tpl.get(header));
+    if (wsHash !== tplHash) {
+      diverged.push({ header, workspaceHash: wsHash, templateHash: tplHash });
+    }
+  }
+  return diverged.length > 0 ? diverged : null;
+}
+
+// ─── Aggregate runner ────────────────────────────────────────────────────────
+
+/**
+ * Run all three diff strategies on a single agent file pair.
+ * Returns null when no drift is detected, otherwise an issue object.
+ */
+function diffAgentFile(workspaceContent, templateContent) {
+  // AC-T5-08: missing-on-one-side detection.
+  if (!workspaceContent && !templateContent) return null;
+  if (!workspaceContent || !templateContent) {
+    return {
+      missingFile: !workspaceContent ? 'workspace' : 'template',
+      missingInTemplate: [], missingInWorkspace: [], reordered: false,
+      divergedSections: [],
+      frontmatter: null
+    };
+  }
+  const headers = diffHeaders(workspaceContent, templateContent);
+  const sections = diffSectionContent(workspaceContent, templateContent);
+  const frontmatter = diffFrontmatter(workspaceContent, templateContent);
+  if (!headers && !sections && !frontmatter) return null;
+  return {
+    missingFile: null,
+    missingInTemplate: headers?.missingInTemplate || [],
+    missingInWorkspace: headers?.missingInWorkspace || [],
+    reordered: headers?.reordered || false,
+    divergedSections: sections || [],
+    frontmatter: frontmatter || null
+  };
+}
+
+module.exports = {
+  extractFrontmatter,
+  extractHeaders,
+  extractSections,
+  diffFrontmatter,
+  diffHeaders,
+  diffSectionContent,
+  diffAgentFile,
+  hashBody,
+  normalizeBody
+};