@jaimevalasek/aioson 1.33.1 → 1.37.0

package/src/commands/workflow-next.js

@@ -16,6 +16,7 @@ const { logError, buildHealingPrompt } = require('../self-healing');
 const { validateHandoffProtocol } = require('../handoff-validator');
 const { readAutonomyProtocol, resolveEffectiveMode } = require('../autonomy-policy');
 const { readAgentManifest, buildAgentCapabilitySummary } = require('../agent-manifests');
+const { resolveAutopilotSignal } = require('../autopilot-signal');
 const { runMemoryReflectPrepare } = require('./memory-reflect-prepare');
 const { inspectStagedChanges } = require('../lib/git-commit-guard');
 const { emitSecurityRuntimeEvent } = require('../lib/security/runtime-events');
@@ -26,6 +27,11 @@ const { emitDossierEvent } = require('../lib/dossier-telemetry');
 const { parseVerificationReport } = require('../verification/report-parser');
 const { applyPolicy } = require('../verification/policy-engine');
 const { normalizePolicy } = require('../verification/result');
+const {
+  evaluateContractIntegrityGate,
+  formatContractIntegrityGateError
+} = require('../harness/contract-integrity-gate');
+const { runSpecAnalyze } = require('./spec-analyze');
 const {
   validateFeatureSlug,
   featureContextDir,
@@ -40,22 +46,34 @@ const SCOPE_CHECK_MODES = new Set(['pre-dev', 'post-dev', 'post-fix', 'final']);
 
 const DEFAULT_FEATURE_WORKFLOW_BY_CLASSIFICATION = {
   MICRO: ['product', 'dev', 'qa'],
-  SMALL: ['product', 'analyst', 'scope-check', 'architect', 'discovery-design-doc', 'dev', 'qa'],
-  // MEDIUM routes through @pm after discovery-design-doc (mirrors the
-  // project-mode position): Gate C requires implementation-plan-{slug}.md and
-  // @pm is its canonical owner (AC-SDLC-15/16) — without the stage, the
-  // sequence dead-ends at @dev preflight with no agent to produce the plan.
-  MEDIUM: ['product', 'analyst', 'architect', 'discovery-design-doc', 'pm', 'scope-check', 'dev', 'pentester', 'qa']
+  // SMALL defaults to the lean lane: @sheldon is the single spec authority
+  // (requirements + spec + design-doc + readiness + plan + harness-contract in
+  // one pass), replacing analyst/scope-check/architect/discovery-design-doc.
+  // Those agents remain available as opt-in detours (allowDetours: true).
+  SMALL: ['product', 'sheldon', 'dev', 'qa'],
+  // MEDIUM collapses the spec phase into @orchestrator — the maestro that fans out
+  // to @analyst + @architect + @pm (+ @ux-ui when UI-heavy) as sub-agents, then
+  // consolidates/verifies/redoes their output into the gated spec package
+  // (requirements + spec[A/B/C approved] + design-doc + readiness + implementation-
+  // plan + harness-contract) and hands to @dev. SMALL = @sheldon solo (vertical),
+  // MEDIUM = @orchestrator fan-out (horizontal). The scope drift check is enforced at
+  // the dev/qa done gate (finalizeCurrentStage). @pentester stays as the post-dev
+  // security stage. analyst/architect/pm/ddd/scope-check/ux-ui remain opt-in detours.
+  MEDIUM: ['product', 'orchestrator', 'dev', 'pentester', 'qa']
 };
 
-// Stages eligible for autopilot handoff (auto_handoff: true in project.context.md).
-// Two segments — see .aioson/docs/autopilot-handoff.md:
-//   1. analyst -> dev: deterministic pre-dev chain. Prompt-only clients stop
-//      before the first @dev entry; workflow:execute --agentic may resume it
-//      through a fresh checkpointed activation.
-//   2. post-dev review cycle: @dev → @qa → @tester/@pentester (when their @qa triggers
-//      fire) → @validator → STOPS before feature:close (human approves the close).
+// Stages eligible for autopilot handoff — the FULL feature chain (see
+// .aioson/docs/autopilot-handoff.md). Activation = auto_handoff: true in
+// project.context.md OR the seeded scheme (resolveAutopilotSignal). Two segments:
+//   1. spec → dev chain: @product seeds the agentic scheme and invokes the spec
+//      authority (@sheldon lean / @orchestrator maestro), which crosses into
+//      @dev via the dev-state.md cold-start packet once its own gates/decisions
+//      are settled. Detour agents (analyst/architect/pm/...) chain only when an
+//      opt-in detour adds them to the active sequence.
+//   2. post-dev review cycle: @dev → @qa → @tester/@pentester (when their @qa
+//      triggers fire) → @validator → STOPS before feature:close (human gate).
 const AUTOPILOT_HANDOFF_STAGES = new Set([
+  'product', 'sheldon', 'orchestrator',
   'analyst', 'scope-check', 'architect', 'discovery-design-doc', 'pm',
   'dev', 'qa', 'tester', 'pentester', 'validator'
 ]);
@@ -73,13 +91,29 @@ function normalizeClassification(value, fallback = 'MICRO') {
   return fallback;
 }
 
+// MEDIUM maestro lane: @orchestrator routes straight to @dev (it is the single
+// spec authority that fans out to analyst/architect/pm sub-agents and consolidates).
+function isMaestroOrchestratorState(state) {
+  const sequence = Array.isArray(state && state.sequence) ? state.sequence.map(normalizeAgentName) : [];
+  const idx = sequence.indexOf('orchestrator');
+  return idx !== -1 && sequence[idx + 1] === 'dev';
+}
+
+// Lean lane (SMALL, sheldon → dev): @sheldon is the single spec authority.
+// Mirrors isLeanSheldonState in handoff-contract.js.
+function isLeanSheldonState(state) {
+  const sequence = Array.isArray(state && state.sequence) ? state.sequence.map(normalizeAgentName) : [];
+  const idx = sequence.indexOf('sheldon');
+  return idx !== -1 && sequence[idx + 1] === 'dev';
+}
+
 function buildDefaultWorkflowConfig() {
   return {
     version: 1,
     project: {
       MICRO: ['setup', 'dev'],
-      SMALL: ['setup', 'product', 'analyst', 'scope-check', 'architect', 'discovery-design-doc', 'dev', 'qa'],
-      MEDIUM: ['setup', 'product', 'analyst', 'architect', 'discovery-design-doc', 'ux-ui', 'pm', 'orchestrator', 'scope-check', 'dev', 'qa']
+      SMALL: ['setup', 'product', 'sheldon', 'dev', 'qa'],
+      MEDIUM: ['setup', 'product', 'orchestrator', 'dev', 'qa']
     },
     feature: DEFAULT_FEATURE_WORKFLOW_BY_CLASSIFICATION,
     rules: {
@@ -350,7 +384,43 @@ async function validateStageArtifacts(targetDir, state, stage) {
     return true;
   }
 
+  if (stage === 'sheldon') {
+    // Lean lane (SMALL, sheldon → dev): @sheldon is the single spec authority —
+    // "done" once the collapsed spec package exists (mirrors the orchestrator
+    // maestro branch below; the handoff contract re-checks Gates A/B/C). Without
+    // this branch nothing ever marks the sheldon stage resolved, and a later
+    // `--complete=dev` computes `next: sheldon` — the state machine walking
+    // BACKWARDS into the spec agent after implementation.
+    if (state.mode === 'feature' && slug && isLeanSheldonState(state)) {
+      const designDoc = [path.join(base, `design-doc-${slug}.md`), path.join(base, 'design-doc.md')];
+      const readiness = [path.join(base, `readiness-${slug}.md`), path.join(base, 'readiness.md')];
+      return (await exists(path.join(base, `sheldon-enrichment-${slug}.md`)))
+        && (await exists(path.join(base, `requirements-${slug}.md`)))
+        && (await exists(path.join(base, `spec-${slug}.md`)))
+        && (await exists(path.join(base, `implementation-plan-${slug}.md`)))
+        && (await anyExists(designDoc))
+        && (await anyExists(readiness));
+    }
+    if (state.mode === 'feature' && slug) {
+      return await exists(path.join(base, `sheldon-enrichment-${slug}.md`));
+    }
+    return await exists(path.join(base, 'sheldon-enrichment.md'));
+  }
+
   if (stage === 'orchestrator') {
+    // Maestro lane (MEDIUM, orchestrator → dev): the orchestrator is the single
+    // spec authority — "done" once the gated spec package exists (mirrors how the
+    // per-hop stages were inferred). Otherwise it is the parallel-impl coordinator
+    // and owns the lane workspace.
+    if (state.mode === 'feature' && slug && isMaestroOrchestratorState(state)) {
+      const designDoc = [path.join(base, `design-doc-${slug}.md`), path.join(base, 'design-doc.md')];
+      const readiness = [path.join(base, `readiness-${slug}.md`), path.join(base, 'readiness.md')];
+      return (await exists(path.join(base, `requirements-${slug}.md`)))
+        && (await exists(path.join(base, `spec-${slug}.md`)))
+        && (await exists(path.join(base, `implementation-plan-${slug}.md`)))
+        && (await anyExists(designDoc))
+        && (await anyExists(readiness));
+    }
     return await exists(path.join(base, 'parallel'));
   }
 
@@ -480,7 +550,10 @@ function isInferableStage(stage) {
   // could never infer scope-check as completed during stale-state recovery.
   // pm is inferable from implementation-plan-{slug}.md for the same reason:
   // it sits before scope-check in the MEDIUM feature sequence.
-  return ['setup', 'product', 'analyst', 'scope-check', 'architect', 'discovery-design-doc', 'ux-ui', 'pm', 'orchestrator'].includes(
+  // sheldon (lean lane) and orchestrator (maestro lane) are the single spec
+  // authorities — both inferable from their collapsed spec package so stale-state
+  // recovery and mid-lane seeding never re-activate a finished spec stage.
+  return ['setup', 'product', 'analyst', 'scope-check', 'architect', 'discovery-design-doc', 'ux-ui', 'pm', 'sheldon', 'orchestrator'].includes(
     normalizeAgentName(stage)
   );
 }
@@ -767,9 +840,94 @@ async function finalizeCurrentStage(targetDir, config, state, stageName) {
   if (!normalizedStage) {
     throw new Error('No stage is active to complete.');
   }
+  let auditCodeSummary = null;
 
   // ── Harness Done Gate ───────────────────────────────────────────────────
   if (state.mode === 'feature' && state.featureSlug) {
+    if (normalizedStage === 'dev' || normalizedStage === 'qa') {
+      const integrityGate = await evaluateContractIntegrityGate(targetDir, state.featureSlug, {
+        runChecks: true
+      });
+      if (!integrityGate.ok) {
+        const errMsg = formatContractIntegrityGateError(integrityGate, normalizedStage);
+        await logError(targetDir, normalizedStage, errMsg, 'harness-contract');
+        throw new Error(errMsg);
+      }
+
+      // ── Scope drift gate (absorbs @scope-check's deterministic spec:analyze) ──
+      // scope-check is no longer a default stage; preserve its drift check so a
+      // dev/qa completion still blocks on real drift — a design-doc/readiness that
+      // declares `readiness: blocked`, or a malformed/invalid harness-contract.json.
+      // Non-strict spec:analyze only raises error-severity findings for those
+      // genuine problems (never for merely-absent artifacts), so this never
+      // false-blocks an artifact-light feature. Defensive: never crashes the run.
+      try {
+        const drift = await runSpecAnalyze({
+          args: [targetDir],
+          options: { feature: state.featureSlug },
+          logger: { log() {}, error() {} }
+        });
+        if (drift && Array.isArray(drift.findings) && drift.summary && drift.summary.errors > 0) {
+          const errs = drift.findings
+            .filter((f) => f.severity === 'error')
+            .map((f) => `  - ${f.check}: ${f.message}`)
+            .join('\n');
+          const driftMsg = `[Scope Drift Gate] @${normalizedStage} blocked — spec:analyze found ${drift.summary.errors} drift error(s):\n${errs}\nResolve the drift (or run @scope-check) before completing this stage.`;
+          await logError(targetDir, normalizedStage, driftMsg, 'scope-drift');
+          throw new Error(driftMsg);
+        }
+      } catch (driftErr) {
+        if (driftErr && driftErr.message && driftErr.message.includes('[Scope Drift Gate]')) throw driftErr;
+        // spec:analyze unavailable or non-analyzable — non-blocking
+      }
+
+      // ── Code-quality gate (deterministic audit:code) ───────────────────────
+      // Build-free scan of the changed files for the non-security categories
+      // (anti-patterns / TODOs / dead code / duplication). Unlike the integrity
+      // and drift gates above — which enforce the feature's DECLARED contract /
+      // spec — audit:code is a heuristic opinion, so it defaults to ADVISORY: the
+      // report is persisted (.aioson/context/audit-code.json), a guard event is
+      // emitted, and a summary rides the finalize result, but the stage is NOT
+      // blocked. Set verification.json `audit_code.tracked_gate: "block"` to make a
+      // HIGH finding in scope a hard gate, or "off" to skip. Defensive: only a
+      // deliberate block-mode throw escapes; any other error is swallowed.
+      try {
+        const { readVerificationConfig, getAuditCodePolicy } = require('../verification-policy');
+        const auditPolicy = getAuditCodePolicy(await readVerificationConfig(targetDir));
+        if (auditPolicy.tracked_gate !== 'off') {
+          const { runAuditCode } = require('./audit-code');
+          const codeAudit = await runAuditCode({
+            args: [targetDir],
+            options: { changed: auditPolicy.scope !== 'full', json: true, suppressExitCode: true },
+            logger: { log() {}, error() {} }
+          });
+          const high = codeAudit && codeAudit.by_severity ? (codeAudit.by_severity.HIGH || 0) : 0;
+          const med = codeAudit && codeAudit.by_severity ? (codeAudit.by_severity.MED || 0) : 0;
+          const categories = Object.keys((codeAudit && codeAudit.by_category) || {});
+          auditCodeSummary = { gate: auditPolicy.tracked_gate, scope: auditPolicy.scope, high, med, categories };
+          if (high > 0 && auditPolicy.tracked_gate === 'block') {
+            const msg = `[Code-Quality Gate] @${normalizedStage} blocked — audit:code found ${high} HIGH finding(s) in the ${auditPolicy.scope} files (${categories.join(', ')}). Fix them, or relax verification.json audit_code.tracked_gate to "advisory"/"off". See .aioson/context/audit-code.json`;
+            await logError(targetDir, normalizedStage, msg, 'audit-code');
+            throw new Error(msg);
+          }
+          if (high > 0) {
+            try {
+              const { emitGuardEvent } = require('../harness/guard-events');
+              await emitGuardEvent(targetDir, {
+                eventType: 'audit_code_findings',
+                agent: normalizedStage,
+                message: `${high} HIGH / ${med} MED in ${auditPolicy.scope} files (${categories.join(', ')}) — advisory`,
+                payload: { slug: state.featureSlug, high, med, scope: auditPolicy.scope }
+              });
+            } catch { /* telemetry best-effort */ }
+          }
+        }
+      } catch (auditErr) {
+        if (auditErr && auditErr.message && auditErr.message.includes('[Code-Quality Gate]')) throw auditErr;
+        // audit:code unavailable / non-git — non-blocking
+      }
+    }
+
     const contractPath = path.join(targetDir, '.aioson', 'plans', state.featureSlug, 'harness-contract.json');
     const progressPath = path.join(targetDir, '.aioson', 'plans', state.featureSlug, 'progress.json');
     
@@ -869,7 +1027,18 @@ async function finalizeCurrentStage(targetDir, config, state, stageName) {
     detour: null
   });
 
-  return { state: nextState, completedStage: normalizedStage };
+  // Reconcile eagerly: completing a later stage must never leave `next` pointing
+  // at an earlier unresolved stage (e.g. lean-lane sheldon that only chained via
+  // prompt). Without this, `--complete=dev` re-activated the spec agent and the
+  // reconcile only healed on the NEXT load — after the backwards activation had
+  // already been printed and persisted.
+  const reconciled = reconcileWorkflowState(nextState);
+
+  return {
+    state: reconciled.changed ? reconciled.state : nextState,
+    completedStage: normalizedStage,
+    ...(auditCodeSummary ? { auditCode: auditCodeSummary } : {})
+  };
 }
 
 /**
@@ -1432,9 +1601,12 @@ async function activateStage(
     state.mode === 'feature' &&
     (state.classification === 'SMALL' || state.classification === 'MEDIUM')
   ) {
+    // Frontmatter flag OR the seeded scheme (slug-scoped) — the per-feature
+    // "Autopilot" choice only seeds workflow-execute.json and never writes
+    // auto_handoff, so reading the frontmatter alone silently disabled it.
     try {
-      const projectContext = await validateProjectContextFile(targetDir);
-      autoHandoff = Boolean(projectContext && projectContext.data && projectContext.data.auto_handoff === true);
+      const signal = await resolveAutopilotSignal(targetDir, { slug: state.featureSlug });
+      autoHandoff = signal.enabled;
     } catch {
       autoHandoff = false;
     }
@@ -1608,7 +1780,8 @@ async function runWorkflowNext({ args, options, logger, t }) {
       const autoHeal = Boolean(options['auto-heal'] || options.autoHeal);
       const isHealabled = autoHeal && (
         err.message.includes('[Technical Gate BLOCKED]') ||
-        err.message.includes('[Handoff Contract BLOCKED]')
+        err.message.includes('[Handoff Contract BLOCKED]') ||
+        err.message.includes('[Harness Contract Gate BLOCKED]')
       );
       if (isHealabled) {
         const failedStage = normalizeAgentName(options.complete === true ? state.current || state.next : options.complete);

package/src/commands/workflow-plan.js

@@ -3,11 +3,11 @@
 const path = require('node:path');
 const { validateProjectContextFile } = require('../context');
 
-const WORKFLOW_BY_CLASSIFICATION = {
-  MICRO: ['setup', 'dev'],
-  SMALL: ['setup', 'product', 'analyst', 'scope-check', 'architect', 'dev', 'qa'],
-  MEDIUM: ['setup', 'product', 'analyst', 'architect', 'ux-ui', 'pm', 'orchestrator', 'scope-check', 'dev', 'qa']
-};
+const WORKFLOW_BY_CLASSIFICATION = {
+  MICRO: ['setup', 'dev'],
+  SMALL: ['setup', 'product', 'sheldon', 'dev', 'qa'],
+  MEDIUM: ['setup', 'product', 'orchestrator', 'dev', 'qa']
+};
 
 function normalizeClassification(value, fallback = 'MICRO') {
   const text = String(value || '').trim().toUpperCase();

package/src/constants.js

@@ -47,6 +47,7 @@ const MANAGED_FILES = [
   '.aioson/docs/squad/genome-bindings.md',
   '.aioson/docs/feature-expansion-taxonomy.md',
   '.aioson/docs/prototype-contract.md',
+  '.aioson/docs/reference-identity.md',
   '.aioson/docs/product/conversation-playbook.md',
   '.aioson/docs/product/research-loop.md',
   '.aioson/docs/product/quality-lens.md',
@@ -83,6 +84,7 @@ const MANAGED_FILES = [
   '.aioson/skills/process/product-scope-expansion/SKILL.md',
   '.aioson/skills/process/sheldon-expansion-audit/SKILL.md',
   '.aioson/skills/process/prototype-forge/SKILL.md',
+  '.aioson/skills/process/reference-identity-extract/SKILL.md',
   '.aioson/skills/static/laravel-conventions.md',
   '.aioson/skills/static/tall-stack-patterns.md',
   '.aioson/skills/static/jetstream-setup.md',

package/src/doctor.js

@@ -228,8 +228,10 @@ async function runDoctor(targetDir) {
   }
 
   // Autopilot handoff: protocol doc installed but flag never declared in the
-  // context frontmatter — autopilot stays silently inactive (absent = manual
-  // handoffs). An explicit true/false is a deliberate choice and passes.
+  // context frontmatter. Absent is no longer "silently manual" — @product asks
+  // the run mode on screen at each feature kickoff. Declaring an explicit
+  // true/false sets a project default (skip the kickoff question) and passes;
+  // the advisory just surfaces that a default can be set.
   const autopilotDocExists = await exists(path.join(targetDir, '.aioson/docs/autopilot-handoff.md'));
   if (autopilotDocExists && contextValidation.exists && contextValidation.data) {
     const autoHandoffDeclared = Object.prototype.hasOwnProperty.call(contextValidation.data, 'auto_handoff');

package/src/gateway-pointer-merge.js

@@ -31,6 +31,12 @@ function buildBlock(templateContent) {
   return `${MARKER_BEGIN}\n${BLOCK_NOTICE}\n\n${body}${MARKER_END}\n`;
 }
 
+function trimBlankLinesAfterBlock(content, rangeEnd) {
+  let end = rangeEnd;
+  while (content[end] === '\n' || content[end] === '\r') end += 1;
+  return end;
+}
+
 function findBlockRange(content) {
   const start = content.indexOf(MARKER_BEGIN);
   if (start === -1) return null;
@@ -71,7 +77,7 @@ async function mergeGatewayPointer({ templatePath, targetPath, backupRoot, targe
   let action;
   if (range) {
     const before = stripLegacyUnmanagedGateway(existing.slice(0, range.start));
-    const after = existing.slice(range.end);
+    const after = existing.slice(trimBlankLinesAfterBlock(existing, range.end));
     const cleanBefore = before.length === 0 || before.endsWith('\n') ? before : `${before}\n`;
     next = `${cleanBefore}${block}${after}`;
     action = 'block_updated';