@besales/ops-framework 0.1.13 → 0.1.14

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.14
+
+- Added initiative synthesis readiness gates for missing critical concepts, ADR/NFR coverage, scope/storage conflicts, apply-contract ambiguity, sequencing hints and stronger source-reference warnings.
+- Made `initiative-requirements-synthesis` block planning when source docs contain important concepts that synthesized requirements do not explicitly cover.
+
 ## 0.1.13
 
 - Fixed `ops-agent --version` to read the installed package version instead of printing a stale hardcoded value.

package/README.md

@@ -263,7 +263,7 @@ Raw docs
 
 `initiative-requirements <initiative>` turns those candidates into `REQ-*` rows in `requirements-map.md`, writes `requirements-review.md` approval cards and writes `coverage.md`. Human review is still required before treating candidates as approved or planned.
 
-`initiative-requirements-synthesis <initiative>` writes `requirements-synthesis.md`: the human/LLM synthesis pack for converting raw candidates into clean requirements with acceptance criteria. It highlights source coverage gaps, fragments, table rows, run-on blocks and candidate assumptions/questions that must be rewritten before planning.
+`initiative-requirements-synthesis <initiative>` writes `requirements-synthesis.md`: the human/LLM synthesis pack for converting raw candidates into clean requirements with acceptance criteria. It highlights source coverage gaps, fragments, table rows, run-on blocks and candidate assumptions/questions that must be rewritten before planning. It also runs synthesis readiness gates for missing critical concepts, ADR/NFR coverage, scope/storage conflicts, apply-contract ambiguity, sequencing hints and weak source references.
 
 ## Feedback Intake
 

package/bin/initiative.mjs

@@ -360,19 +360,24 @@ export function initiativeRequirementsSynthesis({
   const questionsPath = path.join(initiative.initiativeDir, 'intake', 'open-questions.md');
   const assumptions = fs.existsSync(assumptionsPath) ? fs.readFileSync(assumptionsPath, 'utf8') : '';
   const questions = fs.existsSync(questionsPath) ? fs.readFileSync(questionsPath, 'utf8') : '';
+  const sourceDocs = readIndexedSourceDocs({ projectRoot, sourceIndex });
+  const gates = buildSynthesisReadinessGates({ requirements, sourceDocs });
   const rewriteRequired = requirements.some((req) => requirementNeedsRewrite(req))
-    || Boolean(sourceIndex.sourceCoverage?.relevantExcludedSources?.length);
+    || Boolean(sourceIndex.sourceCoverage?.relevantExcludedSources?.length)
+    || gates.some((gate) => gate.blocking);
   const changes = [];
   writeFileIfAllowed(path.join(initiative.initiativeDir, 'requirements-synthesis.md'), renderRequirementsSynthesis({
     sourceCoverage: sourceIndex.sourceCoverage,
     requirements,
     assumptions,
     questions,
+    gates,
     rewriteRequired,
   }), { force: true, changes });
   return {
     initiativeId,
     requirements,
+    gates,
     rewriteRequired,
     changes,
   };
@@ -987,8 +992,151 @@ function parseRequirementsMap(content) {
   }).filter((req) => req.id && req.source && req.text);
 }
 
-function renderRequirementsSynthesis({ sourceCoverage, requirements, assumptions, questions, rewriteRequired }) {
+function readIndexedSourceDocs({ projectRoot, sourceIndex }) {
+  return (sourceIndex.sources || []).map((source) => {
+    const filePath = path.join(projectRoot, source.path);
+    return {
+      ...source,
+      content: fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '',
+    };
+  });
+}
+
+function buildSynthesisReadinessGates({ requirements, sourceDocs }) {
+  const sourceText = sourceDocs.map((source) => source.content).join('\n');
+  const requirementText = requirements.map((req) => [
+    req.text,
+    req.acceptance,
+    req.notes,
+    req.workPackage,
+  ].filter(Boolean).join('\n')).join('\n');
+  const gates = [];
+  addMissingConceptGate({
+    gates,
+    sourceText,
+    requirementText,
+    id: 'critical-concept-speaker-resolution',
+    title: 'Speaker identity resolution and person aliases',
+    sourcePattern: /(speaker[_ -]?resolution|single[- ]label|person_aliases|speaker_resolution_status|committed_by_person|alias(?:es)?)/i,
+    requirementPattern: /(speaker[_ -]?resolution|person_aliases|speaker_resolution_status|speaker identity|alias(?:es)?)/i,
+    severity: 'critical',
+    action: 'Add a Phase 1 requirement for speaker identity resolution and include alias storage/schema fields before planning meeting extraction.',
+  });
+  addMissingConceptGate({
+    gates,
+    sourceText,
+    requirementText,
+    id: 'nfr-attribution-audit-access',
+    title: 'Attribution, audit and access contract',
+    sourcePattern: /(created_by|app\.current_user_id|owner_id|entity_history|enforcement[- ]deferred|audit|attribution)/i,
+    requirementPattern: /(created_by|app\.current_user_id|owner_id|entity_history|enforcement[- ]deferred|audit|attribution|access)/i,
+    severity: 'critical',
+    action: 'Add an explicit Phase 1 platform/NFR requirement for write attribution, owner assignment, audit history and deferred enforcement.',
+  });
+  addScopeStorageConflictGate({ gates, sourceText, requirementText });
+  addApplyContractGate({ gates, sourceText, requirementText });
+  addSequencingGate({ gates, sourceText, requirementText });
+  addStrongerSourceRefGate({ gates, sourceDocs, requirements });
+  return gates;
+}
+
+function addMissingConceptGate({
+  gates,
+  sourceText,
+  requirementText,
+  id,
+  title,
+  sourcePattern,
+  requirementPattern,
+  severity,
+  action,
+}) {
+  if (sourcePattern.test(sourceText) && !requirementPattern.test(requirementText)) {
+    gates.push({
+      id,
+      severity,
+      blocking: true,
+      title,
+      issue: 'Source docs mention this concept, but synthesized requirements do not cover it explicitly.',
+      action,
+    });
+  }
+}
+
+function addScopeStorageConflictGate({ gates, sourceText, requirementText }) {
+  const mentionsWideTrackTaxonomy = /(tracker|advisor[_ -]?network|investor|grant[_ -]?funding)/i.test(requirementText);
+  const defersFactStorage = /(commitments?|decisions?|risks?|related_person_id).{0,120}(phase\s*2|future|defer|отлож)/is.test(`${requirementText}\n${sourceText}`)
+    || /(phase\s*2|future|defer|отлож).{0,120}(commitments?|decisions?|risks?|related_person_id)/is.test(`${requirementText}\n${sourceText}`);
+  const hasExplicitTrackScopeDecision = /(client\s*\+\s*internal|client and internal|только client|только клиент|only client|track[- ]scope|6 tracks?.{0,80}(phase\s*2|future|defer))/i.test(requirementText);
+  if (mentionsWideTrackTaxonomy && defersFactStorage && !hasExplicitTrackScopeDecision) {
+    gates.push({
+      id: 'scope-storage-track-conflict',
+      severity: 'needs_decision',
+      blocking: true,
+      title: 'Track taxonomy conflicts with deferred fact storage',
+      issue: 'Requirements mention non-client/internal tracks while storage for commitments/decisions/risks or related-person facts appears deferred.',
+      action: 'Decide explicitly: Phase 1 taxonomy is client+internal only, or Phase 1 includes minimal fact storage for the wider track set.',
+    });
+  }
+}
+
+function addApplyContractGate({ gates, sourceText, requirementText }) {
+  const hasApplyFlow = /(apply|approval|proposedchange|proposed change|process-meeting|process meeting|\/process-meeting)/i.test(requirementText);
+  const hasDeferredFacts = /(commitments?|decisions?|risks?|projects?).{0,120}(phase\s*2|future|defer|отлож)/is.test(`${requirementText}\n${sourceText}`)
+    || /(phase\s*2|future|defer|отлож).{0,120}(commitments?|decisions?|risks?|projects?)/is.test(`${requirementText}\n${sourceText}`);
+  const definesDraftOnlyContract = /(draft|proposed only|not applied|не применяется|чернов|только proposed|only proposed)/i.test(requirementText);
+  if (hasApplyFlow && hasDeferredFacts && !definesDraftOnlyContract) {
+    gates.push({
+      id: 'apply-contract-ambiguous',
+      severity: 'needs_decision',
+      blocking: true,
+      title: 'Phase apply contract is ambiguous',
+      issue: 'Apply/approval flow exists, but some extracted fact domains are deferred. Requirements do not say what is applied versus kept as draft/proposed.',
+      action: 'State acceptance for Phase 1 apply: which entities are written, which outputs remain draft ProposedChange, and which domains are out of scope.',
+    });
+  }
+}
+
+function addSequencingGate({ gates, sourceText, requirementText }) {
+  const hasGoldenSet = /(golden set|golden-set|regression baseline|baseline regression)/i.test(`${sourceText}\n${requirementText}`);
+  const hasMeetingExtraction = /(process-meeting|process meeting|\/process-meeting|meeting extraction)/i.test(requirementText);
+  const hasOrdering = /(golden set|golden-set).{0,120}(before|parallel|перед|раньше|параллель)/is.test(requirementText)
+    || /(before|parallel|перед|раньше|параллель).{0,120}(golden set|golden-set)/is.test(requirementText);
+  if (hasGoldenSet && hasMeetingExtraction && !hasOrdering) {
+    gates.push({
+      id: 'sequencing-golden-set-before-extraction',
+      severity: 'planning_hint',
+      blocking: false,
+      title: 'Golden set should baseline meeting extraction',
+      issue: 'Sources mention golden set/regression baseline and requirements mention meeting extraction, but sequencing is not explicit.',
+      action: 'Plan golden set before or parallel to /process-meeting implementation so quality has a baseline.',
+    });
+  }
+}
+
+function addStrongerSourceRefGate({ gates, sourceDocs, requirements }) {
+  const feedbackSources = sourceDocs.filter((source) => /feedback/i.test(source.path));
+  if (!feedbackSources.length) {
+    return;
+  }
+  const feedbackText = feedbackSources.map((source) => source.content).join('\n');
+  for (const req of requirements) {
+    if (/backfill/i.test(req.text) && /backfill/i.test(feedbackText) && !/feedback/i.test(req.source)) {
+      gates.push({
+        id: `stronger-source-ref-${req.id}`,
+        severity: 'traceability',
+        blocking: false,
+        title: `Stronger source reference available for ${req.id}`,
+        issue: 'Requirement mentions backfill, and feedback docs also document backfill decisions, but the requirement source is not a feedback log.',
+        action: 'Add feedback-log source refs or derived-from references before approval.',
+      });
+    }
+  }
+}
+
+function renderRequirementsSynthesis({ sourceCoverage, requirements, assumptions, questions, gates = [], rewriteRequired }) {
   const rewriteCandidates = requirements.filter((req) => requirementNeedsRewrite(req));
+  const blockingGates = gates.filter((gate) => gate.blocking);
   return [
     '# Requirements Synthesis Pack',
     '',
@@ -996,6 +1144,7 @@ function renderRequirementsSynthesis({ sourceCoverage, requirements, assumptions
     `- Requirement candidates: ${requirements.length}`,
     `- Candidates needing rewrite: ${rewriteCandidates.length}`,
     `- Relevant sources still missing: ${sourceCoverage?.relevantExcludedSources?.length || 0}`,
+    `- Blocking readiness gates: ${blockingGates.length}`,
     '',
     '## Source Coverage Gate',
     '',
@@ -1009,6 +1158,21 @@ function renderRequirementsSynthesis({ sourceCoverage, requirements, assumptions
       ? rewriteCandidates.map((req) => `- ${req.id} (${req.quality}): ${req.qualityIssue || 'Rewrite into a clean requirement with acceptance.'}`)
       : ['- None.']),
     '',
+    '## Synthesis Readiness Gates',
+    '',
+    ...(gates.length
+      ? gates.map((gate) => [
+        `### ${gate.id}`,
+        '',
+        `- Severity: \`${gate.severity}\``,
+        `- Blocking: \`${gate.blocking ? 'yes' : 'no'}\``,
+        `- Title: ${gate.title}`,
+        `- Issue: ${gate.issue}`,
+        `- Required action: ${gate.action}`,
+        '',
+      ].join('\n'))
+      : ['- None.']),
+    '',
     '## Synthesis Instructions',
     '',
     'Create final requirements only after human/LLM synthesis. Each final requirement must have:',

package/bin/initiative.test.mjs

@@ -375,6 +375,76 @@ describe('initiative framework', () => {
     expect(pack).toContain('Requirements Synthesis Pack');
     expect(pack).toContain('Synthesized requirement');
   });
+
+  it('adds synthesis readiness gates for missing concepts, scope conflicts and sequencing', () => {
+    const root = makeProject();
+    const docsDir = path.join(root, 'docs', 'delivery-os');
+    fs.mkdirSync(docsDir, { recursive: true });
+    fs.writeFileSync(path.join(docsDir, '06-roadmap.md'), [
+      '# Phase 1',
+      '',
+      '- MVP taxonomy must cover client, internal, tracker, advisor_network, investor, grant_funding.',
+      '- System must implement /process-meeting approval and apply.',
+      '- Golden set baseline Week 1-2 for meeting extraction regression.',
+      '- Migration 001b: person_aliases. Meeting fields: meeting_track, series_id, asr_quality, speaker_resolution_status.',
+      '- Analysis found single-label exports, alias zoo, committed_by_person attribution risk.',
+      '- Phase 2 defers commitments decisions risks related_person_id storage.',
+    ].join('\n'));
+    fs.writeFileSync(path.join(docsDir, '07-adrs.md'), [
+      '# ADR-6',
+      '',
+      '- Schema-ready enforcement-deferred: created_by, app.current_user_id, owner_id, entity_history.',
+    ].join('\n'));
+    fs.writeFileSync(path.join(docsDir, '05-skills-catalog.md'), [
+      '# Skills',
+      '',
+      '- Backfill must stay split from Phase 1 rollout.',
+    ].join('\n'));
+    fs.writeFileSync(path.join(docsDir, '99-feedback-log.md'), [
+      '# Feedback',
+      '',
+      '- Decision: backfill split is documented here with the stronger source reference.',
+    ].join('\n'));
+    createInitiative({
+      projectRoot: root,
+      initiativeId: 'delivery-os-mvp',
+      title: 'Delivery OS MVP',
+    });
+
+    initiativeIntake({
+      projectRoot: root,
+      initiativeId: 'delivery-os-mvp',
+      docsDir: 'docs/delivery-os',
+      phase: 'phase-1',
+    });
+    initiativeRequirements({
+      projectRoot: root,
+      initiativeId: 'delivery-os-mvp',
+      phase: 'phase-1',
+    });
+    const synthesis = initiativeRequirementsSynthesis({
+      projectRoot: root,
+      initiativeId: 'delivery-os-mvp',
+    });
+
+    const gateIds = synthesis.gates.map((gate) => gate.id);
+    expect(synthesis.rewriteRequired).toBe(true);
+    expect(gateIds).toContain('critical-concept-speaker-resolution');
+    expect(gateIds).toContain('nfr-attribution-audit-access');
+    expect(gateIds).toContain('scope-storage-track-conflict');
+    expect(gateIds).toContain('apply-contract-ambiguous');
+    expect(gateIds).toContain('sequencing-golden-set-before-extraction');
+    expect(gateIds.some((id) => id.startsWith('stronger-source-ref-'))).toBe(true);
+
+    const initiativeDir = path.join(root, 'ops', 'agent-pipeline', 'initiatives', 'delivery-os-mvp');
+    const pack = fs.readFileSync(path.join(initiativeDir, 'requirements-synthesis.md'), 'utf8');
+    expect(pack).toContain('Synthesis Readiness Gates');
+    expect(pack).toContain('Speaker identity resolution and person aliases');
+    expect(pack).toContain('Track taxonomy conflicts with deferred fact storage');
+    expect(pack).toContain('Phase apply contract is ambiguous');
+    expect(pack).toContain('Golden set should baseline meeting extraction');
+    expect(pack).toContain('Stronger source reference available');
+  });
 });
 
 function makeProject() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@besales/ops-framework",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "type": "module",
   "bin": {
     "ops-agent": "bin/ops-agent.mjs"