@jaimevalasek/aioson 1.9.2 → 1.16.0

package/src/commands/preflight.js

@@ -28,6 +28,7 @@ const {
   buildContextPackage,
   evaluateReadiness,
   detectStaleDevState,
+  detectStaleDevStateRich,
   extractSpecVersion,
   extractLastCheckpoint,
   GATE_NAMES
@@ -69,8 +70,11 @@ async function runPreflight({ args, options = {}, logger }) {
     ? manifest.path
     : (artifacts.implementation_plan.exists ? artifacts.implementation_plan.path : null);
 
-  // Stale dev-state detection (AC-SDLC-12)
-  const staleDevStateWarning = devState.exists ? detectStaleDevState(devState, slug) : null;
+  // Stale dev-state detection (AC-SDLC-12 + F1 workflow-handoff-integrity v1.9.7).
+  // Use rich variant: cross-references features.md (orphan/done detection) and applies 30d TTL.
+  const staleDevStateWarning = devState.exists
+    ? await detectStaleDevStateRich(devState, slug, targetDir)
+    : null;
 
   // Determine mode
   const mode = slug

package/src/commands/runtime.js

@@ -1222,6 +1222,9 @@ async function runAgentDone({ args, options = {}, logger, t }) {
         logger.log(`agent:done — ${normalizedAgent} | live session active, event logged | run: ${session.runKey} (${dbPath})`);
       }
 
+      // F2 (workflow-handoff-integrity v1.9.5) — best-effort auto-advance workflow pointer
+      await maybeAutoAdvanceWorkflow({ targetDir, normalizedAgent, options, logger, t });
+
       if (isDocCreatingAgent(normalizedAgent)) {
         backupAiosonDocs(targetDir).catch(() => {});
       }
@@ -1279,6 +1282,9 @@ async function runAgentDone({ args, options = {}, logger, t }) {
       logger.log(`agent:done — ${normalizedAgent} | task: ${taskKey} | run: ${runKey} (${dbPath})`);
     }
 
+    // F2 (workflow-handoff-integrity v1.9.5) — best-effort auto-advance workflow pointer
+    await maybeAutoAdvanceWorkflow({ targetDir, normalizedAgent, options, logger, t });
+
     if (isDocCreatingAgent(normalizedAgent)) {
       backupAiosonDocs(targetDir).catch(() => {});
     }
@@ -1299,6 +1305,150 @@ async function runAgentDone({ args, options = {}, logger, t }) {
 }
 
 
+/**
+ * maybeAutoAdvanceWorkflow — F2 (workflow-handoff-integrity v1.9.5)
+ *
+ * Best-effort: when a workflow is active for the project AND the calling
+ * agent has produced its canonical artifact on disk, internally invokes
+ * `runWorkflowNext({ complete: <agent> })` so the pointer advances without
+ * requiring every agent prompt to literal-call `aioson workflow:next`.
+ *
+ * Gating (DD-01 — workflow.state.json presence-detection):
+ *   - workflow.state.json absent OR `--no-auto-advance` flag → skip (backward-compat)
+ *   - workflow.state.json corrupt → log warning, skip (AC-F2-09 graceful degradation)
+ *   - agent unknown in handoff-contract CONTRACTS → log warning, skip (AC-F2-10)
+ *
+ * Idempotency (BR-01): `last_workflow_event_at` in workflow.state.json blocks
+ * re-emission within a 1s window.
+ *
+ * Side effects (best-effort, every failure is non-fatal):
+ *   - reads `.aioson/context/workflow.state.json`
+ *   - writes `last_workflow_event_at` back to that file on success
+ *   - calls `runWorkflowNext` with quiet logger + `--json` to suppress prose
+ *   - emits ONE concise stdout line on success when not in --json mode
+ *
+ * @param {object} ctx
+ * @param {string} ctx.targetDir       Project root.
+ * @param {string} ctx.normalizedAgent Agent name with leading `@`.
+ * @param {object} ctx.options         agent:done CLI options.
+ * @param {object} ctx.logger          Logger (logger.log + logger.error).
+ * @param {Function} [ctx.t]           Translation fn (passed through).
+ * @returns {Promise<{advanced: boolean, skipped?: string, error?: string}>}
+ */
+async function maybeAutoAdvanceWorkflow({ targetDir, normalizedAgent, options = {}, logger, t }) {
+  // DD-01 opt-out — explicit --no-auto-advance disables, regardless of state.
+  if (options['no-auto-advance'] || options.noAutoAdvance) {
+    return { advanced: false, skipped: 'opt-out' };
+  }
+
+  const statePath = path.join(targetDir, '.aioson', 'context', 'workflow.state.json');
+
+  // 1. Read workflow.state.json (graceful absent OR corrupt — AC-F2-02 / AC-F2-09).
+  let state;
+  try {
+    const raw = await fs.readFile(statePath, 'utf8');
+    state = JSON.parse(raw);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return { advanced: false, skipped: 'no_active_workflow' };
+    }
+    if (!options.json && logger?.error) {
+      logger.error(`[agent:done] workflow.state.json unreadable (${err.code || err.message}); fallback to backward-compat (no auto-advance)`);
+    }
+    return { advanced: false, skipped: 'state_corrupt', error: err.message };
+  }
+
+  // 2. Inactive workflow → skip.
+  if (!state || (!state.featureSlug && state.mode !== 'project') || state.current === null) {
+    return { advanced: false, skipped: 'inactive_workflow' };
+  }
+
+  // 3. Idempotency guard (BR-01 — 1s window).
+  const now = Date.now();
+  const lastEventAt = Number(state.last_workflow_event_at) || 0;
+  if (now - lastEventAt < 1000) {
+    return { advanced: false, skipped: 'idempotency_window' };
+  }
+
+  // 4. Lookup canonical artifact via handoff-contract (DPC-03 — reuse CONTRACTS map).
+  let artifacts;
+  try {
+    const { getCanonicalArtifactsForAgent } = require('../handoff-contract');
+    artifacts = await getCanonicalArtifactsForAgent(normalizedAgent, targetDir, {
+      mode: state.mode || 'feature',
+      featureSlug: state.featureSlug,
+      classification: state.classification
+    });
+  } catch (err) {
+    if (!options.json && logger?.error) {
+      logger.error(`[agent:done] handoff-contract lookup failed (${err.message}); skip auto-advance`);
+    }
+    return { advanced: false, skipped: 'contract_error', error: err.message };
+  }
+
+  // AC-F2-10 — agent not registered in CONTRACTS.
+  if (artifacts === null) {
+    if (!options.json && logger?.error) {
+      logger.error(`[agent:done] agent '${normalizedAgent}' not in handoff-contract CONTRACTS map; skip auto-advance`);
+    }
+    return { advanced: false, skipped: 'unknown_agent' };
+  }
+
+  // Empty array — agent legitimately produces no canonical artifact (e.g. @committer, @dev).
+  // Don't auto-advance; the workflow advances on explicit user action when needed.
+  if (artifacts.length === 0) {
+    return { advanced: false, skipped: 'no_canonical_artifact' };
+  }
+
+  // 5. At least one declared artifact must exist on disk before we trust auto-advance.
+  let anyExists = false;
+  for (const artifactPath of artifacts) {
+    try {
+      await fs.access(artifactPath);
+      anyExists = true;
+      break;
+    } catch { /* not found — try next */ }
+  }
+  if (!anyExists) {
+    return { advanced: false, skipped: 'artifact_missing' };
+  }
+
+  // 6. Internal invocation of runWorkflowNext (lazy require — circular safety).
+  let result;
+  try {
+    const { runWorkflowNext } = require('./workflow-next');
+    result = await runWorkflowNext({
+      args: [targetDir],
+      options: { complete: normalizedAgent.replace(/^@/, ''), json: true },
+      logger: { log: () => {}, error: () => {}, warn: () => {} },
+      t
+    });
+  } catch (err) {
+    if (!options.json && logger?.error) {
+      logger.error(`[agent:done] workflow:next failed (${err.message}); pointer unchanged`);
+    }
+    return { advanced: false, skipped: 'workflow_next_failed', error: err.message };
+  }
+
+  // 7. Persist last_workflow_event_at for idempotency (best-effort).
+  try {
+    const refreshedRaw = await fs.readFile(statePath, 'utf8').catch(() => null);
+    const refreshed = refreshedRaw ? JSON.parse(refreshedRaw) : state;
+    refreshed.last_workflow_event_at = now;
+    await fs.writeFile(statePath, `${JSON.stringify(refreshed, null, 2)}\n`);
+  } catch { /* non-fatal */ }
+
+  // 8. Surface concise outcome — single line, AFTER existing standard log (AC-F2-02 preserved).
+  if (!options.json && logger?.log && result?.ok) {
+    const nextStage = result.next || result.nextStage || null;
+    const tag = nextStage ? `→ ${nextStage}` : '(workflow complete)';
+    logger.log(`[agent:done] auto-advanced ${tag}`);
+  }
+
+  return { advanced: true, result };
+}
+
+
 async function runRuntimeSessionStart({ args, options = {}, logger, t }) {
   const targetDir = resolveTargetDir(args);
   const { db, dbPath, runtimeDir } = await openRuntimeDb(targetDir);
@@ -2074,6 +2224,7 @@ module.exports = {
   runRuntimeLog,
   runAgentDone,
   runAgentRecover,
+  maybeAutoAdvanceWorkflow,
   runRuntimeSessionStart,
   runRuntimeSessionLog,
   runRuntimeSessionFinish,

package/src/commands/state-save.js

@@ -212,8 +212,69 @@ async function runStateSave({ args, options = {}, logger }) {
   return result;
 }
 
+/**
+ * runStateReset — F1 (workflow-handoff-integrity v1.9.7)
+ *
+ * Clears `.aioson/context/dev-state.md`. Idempotent: no-op when file is absent.
+ *
+ * Behavior:
+ *   - Default: deletes the file outright.
+ *   - With `--archive`: moves to `.aioson/runtime/devstate-history/{ISO}.md` for audit trail.
+ *
+ * Usage:
+ *   aioson state:reset .
+ *   aioson state:reset . --archive
+ *   aioson state:reset . --archive --json
+ */
+async function runStateReset({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const statePath = path.join(contextDir(targetDir), 'dev-state.md');
+  const archive = Boolean(options.archive);
+
+  let archivedTo = null;
+  let removed = false;
+
+  try {
+    await fs.access(statePath);
+  } catch {
+    // AC-F1-03 — idempotent: no-op when absent.
+    const result = { ok: true, removed: false, archived: null, reason: 'no_state_file' };
+    if (options.json) return result;
+    logger.log('state:reset — no dev-state.md present; nothing to do.');
+    return result;
+  }
+
+  if (archive) {
+    const historyDir = path.join(targetDir, '.aioson', 'runtime', 'devstate-history');
+    await fs.mkdir(historyDir, { recursive: true });
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    archivedTo = path.join(historyDir, `${stamp}.md`);
+    const content = await fs.readFile(statePath, 'utf8');
+    await fs.writeFile(archivedTo, content, 'utf8');
+  }
+
+  await fs.unlink(statePath);
+  removed = true;
+
+  const result = {
+    ok: true,
+    removed,
+    archived: archivedTo ? path.relative(targetDir, archivedTo) : null
+  };
+
+  if (options.json) return result;
+
+  if (archivedTo) {
+    logger.log(`state:reset — dev-state.md archived to ${result.archived} and removed.`);
+  } else {
+    logger.log('state:reset — dev-state.md removed (no archive).');
+  }
+  return result;
+}
+
 module.exports = {
   runStateSave,
+  runStateReset,
   CONTEXT_TYPE_MAP,
   MAX_CONTEXT,
   parseContextFlag

package/src/commands/sync-agents-preflight.js

@@ -22,6 +22,7 @@ const path = require('node:path');
 
 const { CHAIN_AGENTS, FEATURE_DOSSIER_HEADER, extractSection } = require('./dossier-audit');
 const dossierTelemetry = require('../lib/dossier-telemetry');
+const { diffAgentFile } = require('../lib/agent-semantic-diff');
 
 // Active Learning Loop Phase 6 — workspace ↔ template parity checks for the
 // `.aioson/` artifacts this feature ships. Phase 1 dev's documented decision
@@ -105,6 +106,90 @@ function checkLearningLoopTemplateParity(projectRoot) {
   return issues;
 }
 
+/**
+ * checkSemanticParity — T5 (workflow-handoff-integrity v1.9.8)
+ *
+ * Detects semantic drift between `.aioson/agents/{agent}.md` and
+ * `template/.aioson/agents/{agent}.md`: headers (presence + order), section
+ * content (hash), and frontmatter fields. Catches 981a8fd-style migration
+ * incompleteness that the original Feature-dossier-length check misses.
+ *
+ * Mode-aware severity (per PMD-04 / DD-03):
+ *   - Default (local dev): returns issues with severity='warning' (caller is non-blocking).
+ *   - `AIOSON_PREPUBLISH=true`: returns issues with severity='error' (caller blocks publish).
+ *
+ * Returns array of issue objects.
+ */
+function checkSemanticParity(projectRoot) {
+  const issues = [];
+  const isPrepublish = process.env.AIOSON_PREPUBLISH === 'true';
+  const severity = isPrepublish ? 'error' : 'warning';
+
+  for (const agent of CHAIN_AGENTS) {
+    const workspacePath = path.join(projectRoot, '.aioson', 'agents', `${agent}.md`);
+    const templatePath = path.join(projectRoot, 'template', '.aioson', 'agents', `${agent}.md`);
+    const workspaceRaw = readFileOrEmpty(workspacePath);
+    const templateRaw = readFileOrEmpty(templatePath);
+
+    const diff = diffAgentFile(workspaceRaw, templateRaw);
+    if (!diff) continue;
+
+    if (diff.missingFile) {
+      // AC-T5-08 — file removed in one side, still present in the other.
+      issues.push({
+        agent,
+        kind: 'missing_file',
+        side: diff.missingFile,
+        severity,
+        hint: diff.missingFile === 'workspace'
+          ? `template/.aioson/agents/${agent}.md exists but workspace/.aioson/agents/${agent}.md does not — sync would create it (likely fine, unless workspace deletion was intentional)`
+          : `workspace/.aioson/agents/${agent}.md exists but template/.aioson/agents/${agent}.md does not — workspace edits are unpropagated; copy to template OR delete workspace file`
+      });
+      continue;
+    }
+
+    if (diff.missingInTemplate.length > 0) {
+      issues.push({
+        agent, kind: 'sections_missing_in_template', sections: diff.missingInTemplate, severity,
+        hint: `Workspace has sections not in template: ${diff.missingInTemplate.map((s) => `'${s}'`).join(', ')}. Likely unpropagated workspace edits (981a8fd pattern).`
+      });
+    }
+    if (diff.missingInWorkspace.length > 0) {
+      issues.push({
+        agent, kind: 'sections_missing_in_workspace', sections: diff.missingInWorkspace, severity,
+        hint: `Template has sections not in workspace: ${diff.missingInWorkspace.map((s) => `'${s}'`).join(', ')}. Workspace lost content OR template added new sections post-sync.`
+      });
+    }
+    if (diff.reordered) {
+      issues.push({
+        agent, kind: 'sections_reordered', severity,
+        hint: 'Section order differs between workspace and template — review for unintended structural drift.'
+      });
+    }
+    if (diff.divergedSections.length > 0) {
+      issues.push({
+        agent, kind: 'section_content_diverged', sections: diff.divergedSections.map((d) => d.header), severity,
+        hint: `Section content hash differs (not cosmetic): ${diff.divergedSections.map((d) => `'${d.header}'`).join(', ')}. Investigate before sync to avoid 981a8fd-style migration regression.`
+      });
+    }
+    if (diff.frontmatter) {
+      const fm = diff.frontmatter;
+      if (fm.missingInTemplate.length > 0) {
+        issues.push({ agent, kind: 'frontmatter_missing_in_template', fields: fm.missingInTemplate, severity });
+      }
+      if (fm.missingInWorkspace.length > 0) {
+        issues.push({ agent, kind: 'frontmatter_missing_in_workspace', fields: fm.missingInWorkspace, severity });
+      }
+      if (fm.valueChanged.length > 0) {
+        issues.push({ agent, kind: 'frontmatter_value_changed', changes: fm.valueChanged, severity });
+      }
+    }
+  }
+
+  return issues;
+}
+
+
 function checkParity(projectRoot) {
   const violations = [];
   for (const agent of CHAIN_AGENTS) {
@@ -132,8 +217,11 @@ function checkParity(projectRoot) {
 async function main(projectRoot = process.cwd()) {
   const violations = checkParity(projectRoot);
   const learningLoopIssues = checkLearningLoopTemplateParity(projectRoot);
+  // T5 (workflow-handoff-integrity v1.9.8) — semantic parity check on top of length check.
+  const semanticIssues = checkSemanticParity(projectRoot);
+  const isPrepublish = process.env.AIOSON_PREPUBLISH === 'true';
 
-  if (violations.length === 0 && learningLoopIssues.length === 0) {
+  if (violations.length === 0 && learningLoopIssues.length === 0 && semanticIssues.length === 0) {
     return 0;
   }
 
@@ -166,11 +254,37 @@ async function main(projectRoot = process.cwd()) {
     });
   }
 
-  return 1;
+  // T5 semantic drift — warning-only locally, error in pre-publish mode.
+  if (semanticIssues.length > 0) {
+    const banner = isPrepublish
+      ? '[sync:agents BLOCKED] Semantic parity drift detected (pre-publish hard fail — AIOSON_PREPUBLISH=true):'
+      : '[sync:agents WARN] Semantic parity drift detected (warning only — non-blocking for local dev):';
+    process.stderr.write(`${banner}\n`);
+    for (const issue of semanticIssues) {
+      const detail = issue.sections ? ` [${issue.sections.join(', ')}]`
+        : issue.fields ? ` [${issue.fields.join(', ')}]`
+        : issue.changes ? ` [${issue.changes.map((c) => c.key).join(', ')}]`
+        : '';
+      process.stderr.write(`  - @${issue.agent}: ${issue.kind}${detail}\n`);
+      if (issue.hint) process.stderr.write(`    → ${issue.hint}\n`);
+    }
+    await dossierTelemetry.emitDossierEvent(projectRoot, {
+      agent: 'sync-agents-preflight',
+      type: 'semantic_parity_violation',
+      summary: `${semanticIssues.length} semantic drift issue(s) (mode: ${isPrepublish ? 'prepublish-fail' : 'local-warn'})`,
+      meta: { issues: semanticIssues, prepublish: isPrepublish }
+    });
+  }
+
+  // Block only when there are HARD failures: length violations + learning-loop issues
+  // always block (existing behavior). Semantic drift blocks ONLY in pre-publish mode.
+  const hardBlock = violations.length > 0 || learningLoopIssues.length > 0
+    || (isPrepublish && semanticIssues.length > 0);
+  return hardBlock ? 1 : 0;
 }
 
 if (require.main === module) {
   main().then((code) => process.exit(code));
 }
 
-module.exports = { checkParity, checkLearningLoopTemplateParity, main };
+module.exports = { checkParity, checkLearningLoopTemplateParity, checkSemanticParity, main };

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
 };