@jaimevalasek/aioson 1.30.2 → 1.36.0

package/src/handoff-contract.js

@@ -8,9 +8,10 @@
  * sessions early instead of discovering missing artifacts later.
  */
 
-const path = require('node:path');
-const { readFileSafe, fileExists } = require('./preflight-engine');
-const { auditAcceptanceCriteriaTests } = require('./lib/ac-test-audit');
+const path = require('node:path');
+const { readFileSafe, fileExists } = require('./preflight-engine');
+const { auditAcceptanceCriteriaTests } = require('./lib/ac-test-audit');
+const { evaluateContractIntegrityGate } = require('./harness/contract-integrity-gate');
 
 // Contract definitions per agent stage
 const CONTRACTS = {
@@ -29,48 +30,68 @@ const CONTRACTS = {
     gates: [],
     contextUpdates: ['.aioson/context/project-pulse.md']
   },
-  analyst: {
-    artifacts: (targetDir, state) => {
-      if (state.mode === 'feature' && state.featureSlug) {
-        return [
-          `.aioson/context/requirements-${state.featureSlug}.md`,
+  sheldon: {
+    artifacts: (targetDir, state) => {
+      if (state.mode !== 'feature' || !state.featureSlug) {
+        return ['.aioson/context/sheldon-enrichment.md'];
+      }
+      const slug = state.featureSlug;
+      const base = [`.aioson/context/sheldon-enrichment-${slug}.md`];
+      if (!isLeanSheldonState(state)) return base;
+      return [
+        ...base,
+        `.aioson/context/requirements-${slug}.md`,
+        `.aioson/context/spec-${slug}.md`,
+        `.aioson/context/design-doc-${slug}.md`,
+        `.aioson/context/readiness-${slug}.md`,
+        `.aioson/context/implementation-plan-${slug}.md`
+      ];
+    },
+    gates: [],
+    contextUpdates: []
+  },
+  analyst: {
+    artifacts: (targetDir, state) => {
+      if (state.mode === 'feature' && state.featureSlug) {
+        return [
+          `.aioson/context/requirements-${state.featureSlug}.md`,
           `.aioson/context/spec-${state.featureSlug}.md`
         ];
       }
       return ['.aioson/context/discovery.md'];
     },
-    gates: ['A'], // Gate A must be approved
-    contextUpdates: ['.aioson/context/project-pulse.md']
-  },
-  'scope-check': {
-    artifacts: (targetDir, state) => {
-      if (state.mode === 'feature' && state.featureSlug) {
-        return [`.aioson/context/scope-check-${state.featureSlug}.md`];
-      }
-      return ['.aioson/context/scope-check.md'];
-    },
-    gates: [],
-    contextUpdates: ['.aioson/context/project-pulse.md']
-  },
-  architect: {
-    artifacts: ['.aioson/context/architecture.md'],
-    gates: ['B'],
-    contextUpdates: ['.aioson/context/project-pulse.md']
-  },
-  'discovery-design-doc': {
-    artifacts: (targetDir, state) => {
-      if (state.mode === 'feature' && state.featureSlug) {
-        return [
-          `.aioson/context/design-doc-${state.featureSlug}.md`,
-          `.aioson/context/readiness-${state.featureSlug}.md`
-        ];
-      }
-      return ['.aioson/context/design-doc.md', '.aioson/context/readiness.md'];
-    },
-    gates: [],
-    contextUpdates: ['.aioson/context/project-pulse.md']
-  },
-  'ux-ui': {
+    gates: ['A'], // Gate A must be approved
+    contextUpdates: ['.aioson/context/project-pulse.md']
+  },
+  'scope-check': {
+    artifacts: (targetDir, state) => {
+      if (state.mode === 'feature' && state.featureSlug) {
+        return [`.aioson/context/scope-check-${state.featureSlug}.md`];
+      }
+      return ['.aioson/context/scope-check.md'];
+    },
+    gates: [],
+    contextUpdates: ['.aioson/context/project-pulse.md']
+  },
+  architect: {
+    artifacts: ['.aioson/context/architecture.md'],
+    gates: ['B'],
+    contextUpdates: ['.aioson/context/project-pulse.md']
+  },
+  'discovery-design-doc': {
+    artifacts: (targetDir, state) => {
+      if (state.mode === 'feature' && state.featureSlug) {
+        return [
+          `.aioson/context/design-doc-${state.featureSlug}.md`,
+          `.aioson/context/readiness-${state.featureSlug}.md`
+        ];
+      }
+      return ['.aioson/context/design-doc.md', '.aioson/context/readiness.md'];
+    },
+    gates: [],
+    contextUpdates: ['.aioson/context/project-pulse.md']
+  },
+  'ux-ui': {
     artifacts: ['.aioson/context/ui-spec.md'],
     gates: ['B'],
     contextUpdates: ['.aioson/context/project-pulse.md']
@@ -87,7 +108,22 @@ const CONTRACTS = {
     contextUpdates: ['.aioson/context/project-pulse.md']
   },
   orchestrator: {
-    artifacts: ['.aioson/context/parallel'],
+    artifacts: (targetDir, state) => {
+      // Maestro lane (MEDIUM, orchestrator → dev): the orchestrator produces the
+      // gated spec package via fan-out, so expect those artifacts. Otherwise it is
+      // the parallel-implementation coordinator and owns the lane workspace.
+      if (state && state.mode === 'feature' && state.featureSlug && isMaestroOrchestratorState(state)) {
+        const slug = state.featureSlug;
+        return [
+          `.aioson/context/requirements-${slug}.md`,
+          `.aioson/context/spec-${slug}.md`,
+          `.aioson/context/design-doc-${slug}.md`,
+          `.aioson/context/readiness-${slug}.md`,
+          `.aioson/context/implementation-plan-${slug}.md`
+        ];
+      }
+      return ['.aioson/context/parallel'];
+    },
     gates: [],
     contextUpdates: ['.aioson/context/project-pulse.md']
   },
@@ -123,6 +159,27 @@ const CONTRACTS = {
   }
 };
 
+function normalizeAgentName(input) {
+  return String(input || '')
+    .trim()
+    .toLowerCase()
+    .replace(/^@/, '');
+}
+
+function isLeanSheldonState(state) {
+  const sequence = Array.isArray(state?.sequence) ? state.sequence.map(normalizeAgentName) : [];
+  const sheldonIndex = sequence.indexOf('sheldon');
+  return sheldonIndex !== -1 && sequence[sheldonIndex + 1] === 'dev';
+}
+
+// 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?.sequence) ? state.sequence.map(normalizeAgentName) : [];
+  const idx = sequence.indexOf('orchestrator');
+  return idx !== -1 && sequence[idx + 1] === 'dev';
+}
+
 async function readSecurityFindings(findingsPath) {
   try {
     const content = await readFileSafe(findingsPath);
@@ -173,48 +230,48 @@ function getFindingIdentifier(finding) {
   return 'unknown-finding';
 }
 
-async function resolveArtifacts(contract, targetDir, state) {
-  const raw = typeof contract.artifacts === 'function'
-    ? contract.artifacts(targetDir, state)
-    : contract.artifacts;
-  return raw.map((p) => path.join(targetDir, p));
-}
-
-async function validateDiscoveryDesignDocArtifacts(targetDir, state) {
-  const slug = state?.mode === 'feature' && state?.featureSlug ? state.featureSlug : null;
-  const pairs = slug
-    ? [
-        [
-          `.aioson/context/design-doc-${slug}.md`,
-          `.aioson/context/readiness-${slug}.md`
-        ],
-        [
-          '.aioson/context/design-doc.md',
-          '.aioson/context/readiness.md'
-        ]
-      ]
-    : [
-        [
-          '.aioson/context/design-doc.md',
-          '.aioson/context/readiness.md'
-        ]
-      ];
-
-  for (const pair of pairs) {
-    const [designDoc, readiness] = pair;
-    if (
-      await fileExists(path.join(targetDir, designDoc)) &&
-      await fileExists(path.join(targetDir, readiness))
-    ) {
-      return [];
-    }
-  }
-
-  const expected = slug
-    ? `.aioson/context/design-doc-${slug}.md + .aioson/context/readiness-${slug}.md`
-    : '.aioson/context/design-doc.md + .aioson/context/readiness.md';
-  return [`missing artifact: ${expected}`];
-}
+async function resolveArtifacts(contract, targetDir, state) {
+  const raw = typeof contract.artifacts === 'function'
+    ? contract.artifacts(targetDir, state)
+    : contract.artifacts;
+  return raw.map((p) => path.join(targetDir, p));
+}
+
+async function validateDiscoveryDesignDocArtifacts(targetDir, state) {
+  const slug = state?.mode === 'feature' && state?.featureSlug ? state.featureSlug : null;
+  const pairs = slug
+    ? [
+        [
+          `.aioson/context/design-doc-${slug}.md`,
+          `.aioson/context/readiness-${slug}.md`
+        ],
+        [
+          '.aioson/context/design-doc.md',
+          '.aioson/context/readiness.md'
+        ]
+      ]
+    : [
+        [
+          '.aioson/context/design-doc.md',
+          '.aioson/context/readiness.md'
+        ]
+      ];
+
+  for (const pair of pairs) {
+    const [designDoc, readiness] = pair;
+    if (
+      await fileExists(path.join(targetDir, designDoc)) &&
+      await fileExists(path.join(targetDir, readiness))
+    ) {
+      return [];
+    }
+  }
+
+  const expected = slug
+    ? `.aioson/context/design-doc-${slug}.md + .aioson/context/readiness-${slug}.md`
+    : '.aioson/context/design-doc.md + .aioson/context/readiness.md';
+  return [`missing artifact: ${expected}`];
+}
 
 function parseFrontmatterValue(markdown, key) {
   const fmMatch = String(markdown || '').match(/^---\r?\n([\s\S]*?)\r?\n---/);
@@ -288,49 +345,49 @@ async function checkGateApproval(targetDir, gateLetter, slug, classification, pr
     return { ok: false, reason: 'spec_missing' };
   }
 
-  const gateNames = { A: 'requirements', B: 'design', C: 'plan', D: 'execution' };
-  const gateName = gateNames[gateLetter];
-
-  // Parse frontmatter when present. Explicit gate fields take precedence over
-  // free-text gate lines so `gate_requirements: pending` cannot be overridden
-  // accidentally by stale prose elsewhere in the spec.
-  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (fmMatch) {
-    const fm = {};
-    for (const line of fmMatch[1].split(/\r?\n/)) {
-      const idx = line.indexOf(':');
-      if (idx === -1) continue;
-      const key = line.slice(0, idx).trim();
-      const val = line.slice(idx + 1).trim().replace(/^["']|["']$/g, '');
-      if (key) fm[key] = val;
-    }
-
-    // Check explicit gate field
-    const gateVal = fm[`gate_${gateName}`] || fm[`gate${gateLetter}`] || fm[`gate_${gateLetter}`];
-    if (gateVal) {
-      return gateVal.toLowerCase() === 'approved'
-        ? { ok: true }
-        : { ok: false, reason: `gate_${gateName}_not_approved` };
-    }
-
-    // Check phase_gates JSON
-    if (fm.phase_gates) {
-      try {
-        const parsed = JSON.parse(fm.phase_gates.replace(/'/g, '"'));
-        if (parsed[gateName]) {
-          return parsed[gateName] === 'approved'
-            ? { ok: true }
-            : { ok: false, reason: `gate_${gateName}_not_approved` };
-        }
-      } catch {
-        // ignore
-      }
-    }
-  }
-
-  // Check content for gate approval lines
-  const gateLineRe = new RegExp(`gate\\s+${gateLetter}[^:]*:\\s*approved`, 'i');
-  if (gateLineRe.test(content)) {
+  const gateNames = { A: 'requirements', B: 'design', C: 'plan', D: 'execution' };
+  const gateName = gateNames[gateLetter];
+
+  // Parse frontmatter when present. Explicit gate fields take precedence over
+  // free-text gate lines so `gate_requirements: pending` cannot be overridden
+  // accidentally by stale prose elsewhere in the spec.
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (fmMatch) {
+    const fm = {};
+    for (const line of fmMatch[1].split(/\r?\n/)) {
+      const idx = line.indexOf(':');
+      if (idx === -1) continue;
+      const key = line.slice(0, idx).trim();
+      const val = line.slice(idx + 1).trim().replace(/^["']|["']$/g, '');
+      if (key) fm[key] = val;
+    }
+
+    // Check explicit gate field
+    const gateVal = fm[`gate_${gateName}`] || fm[`gate${gateLetter}`] || fm[`gate_${gateLetter}`];
+    if (gateVal) {
+      return gateVal.toLowerCase() === 'approved'
+        ? { ok: true }
+        : { ok: false, reason: `gate_${gateName}_not_approved` };
+    }
+
+    // Check phase_gates JSON
+    if (fm.phase_gates) {
+      try {
+        const parsed = JSON.parse(fm.phase_gates.replace(/'/g, '"'));
+        if (parsed[gateName]) {
+          return parsed[gateName] === 'approved'
+            ? { ok: true }
+            : { ok: false, reason: `gate_${gateName}_not_approved` };
+        }
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  // Check content for gate approval lines
+  const gateLineRe = new RegExp(`gate\\s+${gateLetter}[^:]*:\\s*approved`, 'i');
+  if (gateLineRe.test(content)) {
     return { ok: true };
   }
 
@@ -340,12 +397,12 @@ async function checkGateApproval(targetDir, gateLetter, slug, classification, pr
       const passMatch = content.match(/\*\*Verdict:\*\*\s*(PASS)/i);
       if (passMatch) {
         return { ok: true };
-      }
-    }
-  }
-
-  return { ok: false, reason: fmMatch ? `gate_${gateName}_not_approved` : 'no_frontmatter' };
-}
+      }
+    }
+  }
+
+  return { ok: false, reason: fmMatch ? `gate_${gateName}_not_approved` : 'no_frontmatter' };
+}
 
 async function validateHandoffContract(targetDir, state, stageName) {
   const contract = CONTRACTS[stageName];
@@ -362,19 +419,19 @@ async function validateHandoffContract(targetDir, state, stageName) {
   const projectClassification = await readProjectClassification(targetDir);
 
   // 1. Artifacts
-  if (stageName === 'discovery-design-doc') {
-    missing.push(...await validateDiscoveryDesignDocArtifacts(targetDir, state));
-  } else {
-    const artifactPaths = await resolveArtifacts(contract, targetDir, state);
-    for (const p of artifactPaths) {
-      if (!(await fileExists(p))) {
-        missing.push(`missing artifact: ${path.relative(targetDir, p)}`);
-      }
-    }
-  }
+  if (stageName === 'discovery-design-doc') {
+    missing.push(...await validateDiscoveryDesignDocArtifacts(targetDir, state));
+  } else {
+    const artifactPaths = await resolveArtifacts(contract, targetDir, state);
+    for (const p of artifactPaths) {
+      if (!(await fileExists(p))) {
+        missing.push(`missing artifact: ${path.relative(targetDir, p)}`);
+      }
+    }
+  }
 
   // 2. Gates
-  for (const gateLetter of contract.gates) {
+  for (const gateLetter of contract.gates) {
     const gateCheck = await checkGateApproval(
       targetDir,
       gateLetter,
@@ -385,16 +442,54 @@ async function validateHandoffContract(targetDir, state, stageName) {
     if (!gateCheck.ok) {
       missing.push(`gate ${gateLetter} not approved (${gateCheck.reason})`);
     }
-  }
-
-  if (stageName === 'qa' && state.featureSlug) {
-    const acAudit = await auditAcceptanceCriteriaTests(targetDir, state.featureSlug);
-    if (!acAudit.ok) {
-      missing.push(`AC test audit failed: missing tests for ${acAudit.missing.join(', ')}`);
-    }
-  }
-
-  // 3. Context updates (soft check — just warn if completely missing)
+  }
+
+  // Single-spec-authority lanes that route straight to @dev — lean @sheldon (SMALL)
+  // and maestro @orchestrator (MEDIUM) — collapse Gates A/B/C + the plan into one
+  // hop, so re-check them here instead of at the (absent) per-hop stages.
+  const isSingleSpecAuthorityToDev = Boolean(state.featureSlug) && (
+    (stageName === 'sheldon' && isLeanSheldonState(state)) ||
+    (stageName === 'orchestrator' && isMaestroOrchestratorState(state))
+  );
+  if (isSingleSpecAuthorityToDev) {
+    for (const gateLetter of ['A', 'B', 'C']) {
+      const gateCheck = await checkGateApproval(
+        targetDir,
+        gateLetter,
+        state.featureSlug,
+        classification,
+        projectClassification
+      );
+      if (!gateCheck.ok) {
+        missing.push(`gate ${gateLetter} not approved (${gateCheck.reason})`);
+      }
+    }
+
+    const planPath = path.join(targetDir, '.aioson', 'context', `implementation-plan-${state.featureSlug}.md`);
+    const planContent = await readFileSafe(planPath);
+    const planStatus = planContent ? parseFrontmatterValue(planContent, 'status') : null;
+    if (String(planStatus || '').toLowerCase() !== 'approved') {
+      missing.push(`implementation-plan-${state.featureSlug}.md status is ${planStatus || 'missing'} — @${stageName} must approve the collapsed Gate C plan`);
+    }
+
+    const integrityGate = await evaluateContractIntegrityGate(targetDir, state.featureSlug, {
+      runChecks: false
+    });
+    if (!integrityGate.ok) {
+      missing.push(...integrityGate.errors.map((err) =>
+        `harness contract integrity failed (${err.code}): ${err.message}`
+      ));
+    }
+  }
+
+  if (stageName === 'qa' && state.featureSlug) {
+    const acAudit = await auditAcceptanceCriteriaTests(targetDir, state.featureSlug);
+    if (!acAudit.ok) {
+      missing.push(`AC test audit failed: missing tests for ${acAudit.missing.join(', ')}`);
+    }
+  }
+
+  // 3. Context updates (soft check — just warn if completely missing)
   for (const p of contract.contextUpdates) {
     const abs = path.join(targetDir, p);
     if (!(await fileExists(abs))) {
@@ -488,10 +583,10 @@ 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, plus accepted fallback
- * candidates for contracts that support legacy artifact names, fully resolved
- * against the workflow state.
+ * to determine which artifact paths an agent is expected to produce. Returns the
+ * paths declared by the agent's contract in CONTRACTS, plus accepted fallback
+ * candidates for contracts that support legacy artifact names, fully resolved
+ * against the workflow state.
  *
  * @param {string} agent       Agent name (with or without leading `@`).
  * @param {string} targetDir   Project root path (absolute).
@@ -501,21 +596,21 @@ async function getBlockingRevisions(targetDir, featureSlug) {
  *                             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;
-  if (normalizedAgent === 'discovery-design-doc' && state?.mode === 'feature' && state?.featureSlug) {
-    return [
-      `.aioson/context/design-doc-${state.featureSlug}.md`,
-      `.aioson/context/readiness-${state.featureSlug}.md`,
-      '.aioson/context/design-doc.md',
-      '.aioson/context/readiness.md'
-    ].map((p) => path.join(targetDir, p));
-  }
-  return await resolveArtifacts(contract, targetDir, state || {});
-}
+async function getCanonicalArtifactsForAgent(agent, targetDir, state) {
+  const normalizedAgent = String(agent || '').replace(/^@/, '').toLowerCase();
+  if (!normalizedAgent) return null;
+  const contract = CONTRACTS[normalizedAgent];
+  if (!contract) return null;
+  if (normalizedAgent === 'discovery-design-doc' && state?.mode === 'feature' && state?.featureSlug) {
+    return [
+      `.aioson/context/design-doc-${state.featureSlug}.md`,
+      `.aioson/context/readiness-${state.featureSlug}.md`,
+      '.aioson/context/design-doc.md',
+      '.aioson/context/readiness.md'
+    ].map((p) => path.join(targetDir, p));
+  }
+  return await resolveArtifacts(contract, targetDir, state || {});
+}
 
 module.exports = {
   parseFrontmatterValue,