@jaimevalasek/aioson 1.9.3 → 1.17.2

package/src/commands/op-reinforce.js

@@ -0,0 +1,73 @@
+'use strict';
+
+/**
+ * aioson op:reinforce <slug> — update last_reinforced without signal capture.
+ * Phase 5 (v1.16.0). User-driven action when decay prompt fires.
+ */
+
+const fs = require('node:fs');
+const { resolveIdentity } = require('../operator-memory/identity');
+const { ensureStorageTree } = require('../operator-memory/storage');
+const { readDecision, decisionPath, serializeDecision } = require('../operator-memory/decision');
+const { regenerateIndex } = require('../operator-memory/index-md');
+const { emitDossierEvent } = require('../lib/dossier-telemetry');
+
+async function runOpReinforce({ args = [], options = {}, logger }) {
+  const targetDir = process.cwd();
+  const positional = (args || []).filter((a) => typeof a === 'string' && !a.startsWith('-') && a !== '.');
+  const slug = positional[0];
+
+  if (options.help === true || args.includes('--help') || args.includes('-h')) {
+    if (logger) logger.log('op:reinforce <slug> — refresh a decision\'s last_reinforced timestamp without re-capturing the signal.');
+    return { ok: true };
+  }
+
+  if (!slug) {
+    const err = 'op:reinforce — required argument: <slug>. Usage: aioson op:reinforce <slug>';
+    if (options.json) return { ok: false, error: err };
+    if (logger && logger.error) logger.error(err);
+    return { ok: false, exitCode: 1, error: err };
+  }
+
+  const resolved = resolveIdentity();
+  ensureStorageTree(resolved.identity);
+  const decision = readDecision(resolved.identity, slug);
+  if (!decision) {
+    const err = `op:reinforce — decision '${slug}' not found for identity ${resolved.identity}.`;
+    if (options.json) return { ok: false, error: err };
+    if (logger && logger.error) logger.error(err);
+    return { ok: false, exitCode: 1, error: err };
+  }
+
+  const now = new Date().toISOString();
+  const previous = decision.last_reinforced;
+  const updated = {
+    ...decision,
+    slug,
+    last_reinforced: now,
+    reinforcement_count: Number(decision.reinforcement_count || 0) + 1
+  };
+  // serialize keeps quotes + body + frontmatter intact
+  const out = serializeDecision({ ...updated, body: decision.body, title: decision.body?.split('\n')[0]?.replace(/^# /, '') || slug });
+  const filePath = decisionPath(resolved.identity, slug);
+  const tmp = `${filePath}.tmp`;
+  fs.writeFileSync(tmp, out, 'utf8');
+  fs.renameSync(tmp, filePath);
+
+  try { regenerateIndex(resolved.identity); } catch { /* non-fatal */ }
+
+  await emitDossierEvent(targetDir, {
+    agent: 'op-reinforce',
+    type: 'op_reinforce',
+    summary: `reinforced ${slug}`,
+    meta: { identity_prefix: resolved.identity.slice(0, 8), slug, previous, now }
+  });
+
+  if (options.json) {
+    return { ok: true, slug, last_reinforced: now, previous, reinforcement_count: updated.reinforcement_count };
+  }
+  if (logger) logger.log(`op:reinforce — '${slug}' last_reinforced refreshed to ${now}.`);
+  return { ok: true, slug };
+}
+
+module.exports = { runOpReinforce };

package/src/commands/op-show.js

@@ -0,0 +1,71 @@
+'use strict';
+
+/**
+ * aioson op:show <slug> — print a single decision body + frontmatter (Phase 3, v1.14.0).
+ */
+
+const fs = require('node:fs');
+const { resolveIdentity } = require('../operator-memory/identity');
+const { ensureStorageTree } = require('../operator-memory/storage');
+const { readDecision, decisionPath } = require('../operator-memory/decision');
+const { readProposal } = require('../operator-memory/proposal');
+
+async function runOpShow({ args = [], options = {}, logger }) {
+  const positional = (args || []).filter((a) => typeof a === 'string' && !a.startsWith('-') && a !== '.');
+  const slug = positional[0];
+
+  if (options.help === true || args.includes('--help') || args.includes('-h')) {
+    if (logger) logger.log('op:show <slug> — print a single decision (frontmatter + body). --json for structured output.');
+    return { ok: true };
+  }
+
+  if (!slug) {
+    const err = 'op:show — required argument: <slug>. Usage: aioson op:show <slug>';
+    if (options.json) return { ok: false, error: err };
+    if (logger && logger.error) logger.error(err);
+    return { ok: false, exitCode: 1, error: err };
+  }
+
+  const resolved = resolveIdentity();
+  ensureStorageTree(resolved.identity);
+
+  const decision = readDecision(resolved.identity, slug);
+  if (decision) {
+    if (options.json) {
+      return { ok: true, kind: 'decision', identity: resolved.identity, slug, ...decision };
+    }
+    if (logger) {
+      const filePath = decisionPath(resolved.identity, slug);
+      const raw = fs.readFileSync(filePath, 'utf8');
+      logger.log(raw);
+    }
+    return { ok: true, kind: 'decision' };
+  }
+
+  const proposal = readProposal(resolved.identity, slug);
+  if (proposal) {
+    if (options.json) {
+      return { ok: true, kind: 'proposal', identity: resolved.identity, slug, ...proposal };
+    }
+    if (logger) {
+      logger.log(`# Proposal: ${slug}`);
+      logger.log('');
+      logger.log(`signal_type: ${proposal.signal_type}`);
+      logger.log(`detected_count: ${proposal.detected_count}`);
+      logger.log(`first_detected: ${proposal.first_detected}`);
+      logger.log(`last_detected: ${proposal.last_detected}`);
+      logger.log(`proposal: ${proposal.proposal}`);
+      logger.log('');
+      logger.log('## Quotes');
+      for (const q of (proposal.quotes || [])) logger.log(`- "${q}"`);
+    }
+    return { ok: true, kind: 'proposal' };
+  }
+
+  const err = `op:show — '${slug}' not found in decisions/ or proposals/ for identity ${resolved.identity}.`;
+  if (options.json) return { ok: false, error: err };
+  if (logger && logger.error) logger.error(err);
+  return { ok: false, exitCode: 1, error: err };
+}
+
+module.exports = { runOpShow };

package/src/commands/op-stubs.js

@@ -0,0 +1,67 @@
+'use strict';
+
+/**
+ * aioson op:* — Phase 1 stubs for commands shipped in later phases.
+ *
+ * Each stub emits a "Not yet implemented" stderr message + structured
+ * `op_command_stub` telemetry event, then exits non-zero. Replaced in
+ * Phases 2-5 with full implementations.
+ *
+ * AC-P1-07: six CLI commands respond with at least --help text; op:identity
+ * is fully functional in Phase 1; the other five are stubs until their
+ * respective phases ship.
+ */
+
+const { emitDossierEvent } = require('../lib/dossier-telemetry');
+
+const STUB_INFO = {
+  'op:capture':  { phase: 2, release: 'v1.13.0', summary: 'capture LLM-driven signal into proposals/ queue' },
+  'op:promote':  { phase: 2, release: 'v1.13.0', summary: 'manually promote a proposal to decisions/ (skip 2x threshold)' },
+  'op:forget':   { phase: 2, release: 'v1.13.0', summary: 'soft-delete a decision or proposal to history/' },
+  'op:list':     { phase: 3, release: 'v1.14.0', summary: 'list active decisions (and --include-archived)' },
+  'op:show':     { phase: 3, release: 'v1.14.0', summary: 'print a single decision body + frontmatter' }
+};
+
+function makeStub(commandName) {
+  const info = STUB_INFO[commandName];
+  if (!info) {
+    throw new Error(`makeStub: unknown command '${commandName}'`);
+  }
+
+  return async function runStub({ args = [], options = {}, logger } = {}) {
+    const targetDir = process.cwd();
+    const helpRequested = options.help === true || args.includes('--help') || args.includes('-h');
+
+    if (helpRequested) {
+      const msg = `${commandName} — ${info.summary}\n  Status: shipped in Phase ${info.phase} (${info.release}).\n  Phase 1 (v1.12.0) wires the command surface but defers logic to that release.`;
+      if (options.json) return { ok: true, stub: true, command: commandName, phase: info.phase, release: info.release, summary: info.summary };
+      if (logger) logger.log(msg);
+      return { ok: true, stub: true };
+    }
+
+    await emitDossierEvent(targetDir, {
+      agent: commandName,
+      type: 'op_command_stub',
+      summary: `${commandName} invoked before its release phase`,
+      meta: { command: commandName, phase: info.phase, release: info.release }
+    });
+
+    const errMsg = `${commandName} — Not yet implemented (ships in Phase ${info.phase} / ${info.release}). Run \`${commandName} --help\` for scope.`;
+    if (options.json) {
+      return { ok: false, stub: true, command: commandName, phase: info.phase, release: info.release, error: errMsg };
+    }
+    if (logger && logger.error) {
+      logger.error(errMsg);
+    }
+    return { ok: false, stub: true, exitCode: 1 };
+  };
+}
+
+module.exports = {
+  runOpCapture: makeStub('op:capture'),
+  runOpPromote: makeStub('op:promote'),
+  runOpForget:  makeStub('op:forget'),
+  runOpList:    makeStub('op:list'),
+  runOpShow:    makeStub('op:show'),
+  STUB_INFO
+};

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

@@ -22,6 +22,7 @@ const { runAutoDelivery } = require('../delivery-runner');
 const { writeHandoff, buildRuntimeLogHandoff } = require('../session-handoff');
 const { backupAiosonDocs, isDocCreatingAgent } = require('../backup-local');
 const { runMemoryReflectPrepare } = require('./memory-reflect-prepare');
+const { runChainHookOnAgentDone } = require('../neural-chain-agent-ingest');
 
 const ALLOWED_LAYOUTS = new Set(['document', 'tabs', 'accordion', 'stack', 'mixed']);
 const DEFAULT_TEXT_FIELDS = ['content', 'text', 'body', 'lyrics', 'markdown'];
@@ -1222,6 +1223,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(() => {});
       }
@@ -1235,6 +1239,19 @@ async function runAgentDone({ args, options = {}, logger, t }) {
         });
       } catch { /* ignore */ }
 
+      // Neural Chain: best-effort agent_event ingest + per-file audit telemetry.
+      // BR-NC-05 (per-session hook), BR-NC-10 (telemetry obligation), BR-NC-11
+      // (failure non-blocking), EC-NC-05 (no-edits skip path still emits event).
+      try {
+        runChainHookOnAgentDone({
+          db,
+          targetDir,
+          artifacts: artifactPaths,
+          agentName: normalizedAgent,
+          featureSlug: options.feature ? String(options.feature).trim() : null
+        });
+      } catch { /* ignore — never blocks agent_done */ }
+
       return { ok: true, targetDir, dbPath, agent: normalizedAgent, mode: 'live_event', runKey: session.runKey };
     }
 
@@ -1279,6 +1296,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(() => {});
     }
@@ -1292,6 +1312,19 @@ async function runAgentDone({ args, options = {}, logger, t }) {
       });
     } catch { /* ignore */ }
 
+    // Neural Chain: best-effort agent_event ingest + per-file audit telemetry.
+    // BR-NC-05 (per-session hook), BR-NC-10 (telemetry obligation), BR-NC-11
+    // (failure non-blocking), EC-NC-05 (no-edits skip path still emits event).
+    try {
+      runChainHookOnAgentDone({
+        db,
+        targetDir,
+        artifacts: artifactPaths,
+        agentName: normalizedAgent,
+        featureSlug: options.feature ? String(options.feature).trim() : null
+      });
+    } catch { /* ignore — never blocks agent_done */ }
+
     return { ok: true, targetDir, dbPath, agent: normalizedAgent, mode: 'standalone', runKey, taskKey };
   } finally {
     db.close();
@@ -1299,6 +1332,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 +2251,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 };