@besales/ops-framework 0.1.16 → 0.1.18

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.1.18
+
+- Added work-package dependency metadata (`Depends on`, `Unblocks`, `Can run parallel with`, `Sequencing notes`) to new initiative work packages.
+- Made `initiative-next` dependency-aware and prevented materialization when pending work packages are blocked by unmet dependencies.
+- Added a work-package readiness gate that blocks materialization when a work package covers `REQ-*` items but has only process-level acceptance.
+
+## 0.1.17
+
+- Broadened the schema compatibility gate so it blocks any schema/foundation requirement that omits fields required by approved dependent requirements, even when the schema text is not written as an explicit closed list.
+- Expanded the schema gate action to call out `person_aliases` or alias storage plus required `meetings.*` fields for track classification and speaker resolution.
+
 ## 0.1.16
 
 - Added a schema compatibility readiness gate that blocks planning when a closed/minimal schema requirement does not support dependent approved requirements such as speaker resolution, aliases and meeting track classification.

package/README.md

@@ -249,6 +249,8 @@ Initiative
 
 Work packages are materialized as normal tasks, so `brief/research/plan/check/execute/verify/retrospective/learning` still works at the audit boundary. Slices are not separate tasks; they use fast execution, micro-verify and slice evidence inside the work-package task. Create a separate task only when a slice triggers scope, risk, architecture or human-approval escalation.
 
+Work packages can declare `Depends on`, `Unblocks`, `Can run parallel with` and `Sequencing notes`. `initiative-next` uses `Depends on` to avoid materializing a package before required packages are completed. If a work package lists `REQ-*` coverage, its `Acceptance` must include requirement-level done criteria or explicit `REQ-*` acceptance references; process-only acceptance blocks materialization.
+
 For source docs, use intake before work-package planning:
 
 ```text

package/bin/initiative.mjs

@@ -202,12 +202,14 @@ export function initiativeNext({
   force = false,
 } = {}) {
   const status = initiativeStatus({ projectRoot, initiativeId });
-  const next = status.workPackages.find((wp) => ['pending', 'ready'].includes(wp.status));
+  const readiness = buildWorkPackageReadiness(status.workPackages);
+  const next = readiness.find((item) => item.ready)?.workPackage || null;
   if (!next) {
     return {
       initiativeId,
       next: null,
       materializedTask: null,
+      readiness,
     };
   }
   let materializedTask = null;
@@ -229,6 +231,7 @@ export function initiativeNext({
     initiativeId,
     next,
     materializedTask,
+    readiness,
   };
 }
 
@@ -1126,14 +1129,15 @@ function addSchemaCompatibilityGate({ gates, sourceText, requirements }) {
   if (!schemaSupportsMeetingOperationalFields) {
     missing.push('meeting operational fields mentioned by sources, such as `series_id` and `asr_quality`');
   }
-  if (missing.length && schemaLooksClosed) {
+  if (missing.length) {
+    const schemaShape = schemaLooksClosed ? 'closed/minimal schema list' : 'schema/foundation contract';
     gates.push({
       id: 'schema-supports-derived-requirements',
       severity: 'critical',
       blocking: true,
       title: 'Schema requirement does not support dependent requirements',
-      issue: `Schema requirement ${schemaReq.id} is written as a closed/minimal schema list but omits ${missing.join(', ')}.`,
-      action: 'Update the schema requirement before WP planning: add the missing schema support, or explicitly state the alternative Phase 1 storage contract and defer the dependent behavior.',
+      issue: `Schema requirement ${schemaReq.id} is written as a ${schemaShape} but omits ${missing.join(', ')}.`,
+      action: 'Update the schema requirement before WP planning: add the missing schema support, or explicitly state the alternative Phase 1 storage contract and defer the dependent behavior. For meeting extraction this usually means `person_aliases` or documented alias storage plus `meetings.meeting_track`, `meetings.series_id`, `meetings.asr_quality`, `meetings.speaker_resolution_status` and `meetings.raw_speaker_labels` when those behaviors are approved.',
     });
   }
 }
@@ -1326,6 +1330,7 @@ function listWorkPackages(initiativeDir) {
 
 function readWorkPackage(filePath, fallbackId) {
   const content = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+  const dependencies = readWorkPackageDependencies(content);
   return {
     id: readInlineField(content, 'ID') || fallbackId,
     title: readInlineField(content, 'Title') || humanizeSlug(fallbackId.replace(/^WP-\d{3}-/, '')),
@@ -1333,11 +1338,89 @@ function readWorkPackage(filePath, fallbackId) {
     task: readInlineField(content, 'Task') || '',
     mode: readInlineField(content, 'Mode') || 'standard_work_package',
     goal: readSection(content, 'Goal') || '',
+    requirementsCoverage: readBulletsFromSection(content, 'Requirements Coverage'),
     slices: readBulletsFromSection(content, 'Slices'),
+    acceptance: readBulletsFromSection(content, 'Acceptance'),
+    dependencies,
     path: filePath,
   };
 }
 
+function readWorkPackageDependencies(content) {
+  const section = readSection(content, 'Dependencies');
+  return {
+    dependsOn: readDependencyField(section, 'Depends on'),
+    unblocks: readDependencyField(section, 'Unblocks'),
+    parallelWith: readDependencyField(section, 'Can run parallel with'),
+    sequencingNotes: readDependencyField(section, 'Sequencing notes'),
+  };
+}
+
+function readDependencyField(section, field) {
+  if (!section) {
+    return [];
+  }
+  const match = new RegExp(`^-\\s+${escapeRegExp(field)}:\\s*(.*)$`, 'im').exec(section);
+  if (!match) {
+    return [];
+  }
+  return splitDependencyRefs(match[1]);
+}
+
+function splitDependencyRefs(value) {
+  return String(value || '')
+    .split(/[,;]/)
+    .map((item) => item.trim())
+    .filter((item) => item && !/^\(?none\)?$/i.test(item) && !/^\[?fill in\]?$/i.test(item));
+}
+
+function buildWorkPackageReadiness(workPackages) {
+  const byId = new Map(workPackages.map((wp) => [wp.id, wp]));
+  return workPackages
+    .filter((wp) => ['pending', 'ready'].includes(wp.status))
+    .map((wp) => {
+      const blockers = [];
+      for (const dependencyId of wp.dependencies.dependsOn) {
+        const dependency = byId.get(dependencyId);
+        if (!dependency) {
+          blockers.push(`Dependency ${dependencyId} is missing.`);
+          continue;
+        }
+        if (!workPackageDependencySatisfied(dependency)) {
+          blockers.push(`Dependency ${dependencyId} is ${dependency.status || 'unknown'}, not completed.`);
+        }
+      }
+      if (workPackageAcceptanceIsProcessOnly(wp)) {
+        blockers.push('Acceptance is process-only while Requirements Coverage is present; add requirement-level done criteria before materialize.');
+      }
+      return {
+        workPackage: wp,
+        ready: blockers.length === 0,
+        blockers,
+      };
+    });
+}
+
+function workPackageDependencySatisfied(workPackage) {
+  return /^(done|complete|completed|verified|closed)$/i.test(workPackage.status || '');
+}
+
+function workPackageAcceptanceIsProcessOnly(workPackage) {
+  const coverageText = workPackage.requirementsCoverage.join('\n');
+  if (!/\bREQ-\d{3}\b/.test(coverageText)) {
+    return false;
+  }
+  const acceptance = workPackage.acceptance;
+  if (!acceptance.length) {
+    return true;
+  }
+  const acceptanceText = acceptance.join('\n');
+  if (/\bREQ-\d{3}\b/.test(acceptanceText)) {
+    return false;
+  }
+  return acceptance.every((item) => /(verify completed|completed verify|slice ledger|learning closeout|task closeout|execution\.md)/i.test(item));
+}
+
 function updateWorkPackageStatus({ workPackagePath, status, taskId }) {
   const content = fs.readFileSync(workPackagePath, 'utf8');
   let updated = content
@@ -1437,6 +1520,17 @@ function buildWorkPackageMarkdown({ initiativeId, workPackageId, title, goal, mo
     '- Excluded:',
     '- Escalate to separate task if:',
     '',
+    '## Requirements Coverage',
+    '',
+    '- REQ-000: Add covered requirement and keep acceptance aligned with requirement-level done criteria.',
+    '',
+    '## Dependencies',
+    '',
+    '- Depends on: (none)',
+    '- Unblocks: (none)',
+    '- Can run parallel with: (none)',
+    '- Sequencing notes: (none)',
+    '',
     '## Slices',
     '',
     '- Slice 1: Define the first implementation slice.',
@@ -1445,6 +1539,7 @@ function buildWorkPackageMarkdown({ initiativeId, workPackageId, title, goal, mo
     '',
     '## Acceptance',
     '',
+    '- Covered REQ-* acceptance criteria are satisfied or explicitly deferred with human approval.',
     '- Work-package task has completed Verify.',
     '- Slice ledger is recorded in execution.md.',
     '- Learning closeout is completed before task closeout.',
@@ -1561,6 +1656,13 @@ function printInitiativeNext(result) {
   console.log(`Initiative next: ${result.initiativeId}`);
   if (!result.next) {
     console.log('- no pending work packages');
+    const blocked = (result.readiness || []).filter((item) => !item.ready);
+    for (const item of blocked) {
+      console.log(`- blocked: ${item.workPackage.id}`);
+      for (const blocker of item.blockers) {
+        console.log(`  - ${blocker}`);
+      }
+    }
     return;
   }
   console.log(`- workPackage: ${result.next.id}`);

package/bin/initiative.test.mjs

@@ -76,6 +76,110 @@ describe('initiative framework', () => {
     expect(workPackage).toContain('Task: TASK-001-foundation');
   });
 
+  it('selects the next work package with dependency readiness', () => {
+    const root = makeProject();
+    createInitiative({
+      projectRoot: root,
+      initiativeId: 'delivery-os-mvp',
+      title: 'Delivery OS MVP',
+    });
+    addWorkPackage({
+      projectRoot: root,
+      initiativeId: 'delivery-os-mvp',
+      workPackageId: 'WP-001-foundation',
+      title: 'Foundation',
+    });
+    addWorkPackage({
+      projectRoot: root,
+      initiativeId: 'delivery-os-mvp',
+      workPackageId: 'WP-003-process-meeting',
+      title: 'Process Meeting',
+    });
+    const wp3Path = path.join(root, 'ops', 'agent-pipeline', 'initiatives', 'delivery-os-mvp', 'work-packages', 'WP-003-process-meeting', 'work-package.md');
+    fs.writeFileSync(wp3Path, fs.readFileSync(wp3Path, 'utf8').replace(
+      '- Depends on: (none)',
+      '- Depends on: WP-001-foundation',
+    ));
+
+    let next = initiativeNext({
+      projectRoot: root,
+      initiativeId: 'delivery-os-mvp',
+    });
+
+    expect(next.next.id).toBe('WP-001-foundation');
+    expect(next.readiness.find((item) => item.workPackage.id === 'WP-003-process-meeting').blockers[0]).toContain('Dependency WP-001-foundation');
+
+    const wp1Path = path.join(root, 'ops', 'agent-pipeline', 'initiatives', 'delivery-os-mvp', 'work-packages', 'WP-001-foundation', 'work-package.md');
+    fs.writeFileSync(wp1Path, fs.readFileSync(wp1Path, 'utf8').replace('Status: pending', 'Status: completed'));
+
+    next = initiativeNext({
+      projectRoot: root,
+      initiativeId: 'delivery-os-mvp',
+    });
+
+    expect(next.next.id).toBe('WP-003-process-meeting');
+  });
+
+  it('blocks materialization when covered requirements have process-only acceptance', () => {
+    const root = makeProject();
+    createInitiative({
+      projectRoot: root,
+      initiativeId: 'delivery-os-mvp',
+      title: 'Delivery OS MVP',
+    });
+    addWorkPackage({
+      projectRoot: root,
+      initiativeId: 'delivery-os-mvp',
+      workPackageId: 'WP-001-foundation',
+      title: 'Foundation',
+    });
+    const wpPath = path.join(root, 'ops', 'agent-pipeline', 'initiatives', 'delivery-os-mvp', 'work-packages', 'WP-001-foundation', 'work-package.md');
+    fs.writeFileSync(wpPath, [
+      '# Work Package',
+      '',
+      'ID: WP-001-foundation',
+      'Initiative: delivery-os-mvp',
+      'Title: Foundation',
+      'Status: pending',
+      'Task:',
+      'Mode: standard_work_package',
+      '',
+      '## Goal',
+      '',
+      'Create foundation.',
+      '',
+      '## Requirements Coverage',
+      '',
+      '- REQ-002',
+      '',
+      '## Dependencies',
+      '',
+      '- Depends on: (none)',
+      '',
+      '## Slices',
+      '',
+      '- Slice 1: Build foundation.',
+      '',
+      '## Acceptance',
+      '',
+      '- Work-package task has completed Verify.',
+      '- Slice ledger is recorded in execution.md.',
+      '- Learning closeout is completed before task closeout.',
+      '',
+    ].join('\n'));
+
+    const next = initiativeNext({
+      projectRoot: root,
+      initiativeId: 'delivery-os-mvp',
+      materializeTask: true,
+    });
+
+    expect(next.next).toBeNull();
+    expect(next.materializedTask).toBeNull();
+    expect(next.readiness[0].blockers[0]).toContain('Acceptance is process-only');
+    expect(fs.existsSync(path.join(root, 'ops', 'agent-pipeline', 'tasks', 'TASK-001-foundation'))).toBe(false);
+  });
+
   it('indexes source docs and builds a requirements map', () => {
     const root = makeProject();
     const docsDir = path.join(root, 'docs', 'delivery-os');
@@ -593,6 +697,92 @@ describe('initiative framework', () => {
     });
     expect(synthesis.rewriteRequired).toBe(true);
   });
+
+  it('blocks planning when a non-closed schema foundation omits speaker and meeting fields', () => {
+    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',
+      '',
+      '- Migration 001b: person_aliases. Meeting fields: meeting_track, series_id, asr_quality, speaker_resolution_status, raw_speaker_labels.',
+    ].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',
+    });
+    const initiativeDir = path.join(root, 'ops', 'agent-pipeline', 'initiatives', 'delivery-os-mvp');
+    fs.writeFileSync(path.join(initiativeDir, 'requirements-map.md'), [
+      '# Requirements Map',
+      '',
+      '## Requirement Details',
+      '',
+      '### REQ-002',
+      '',
+      '- Status: `approved`',
+      '- Source: `docs/delivery-os/04-data-model.md:1206`',
+      '- Source hash: `sha`',
+      '- Phase: `phase-1`',
+      '- Quality: `complete`',
+      '- Quality issue: (none)',
+      '- Work package: WP-001',
+      '- Acceptance: Schema includes approved Phase 1 entities plus attribution/access foundations: created_by, app.current_user_id, owner_id, entity_history, enforcement-deferred.',
+      '- Decision: `approve`',
+      '- Notes: Human-approved attribution update.',
+      '- Requirement: Minimal Phase 1 Schema And Attribution Foundations.',
+      '',
+      '### REQ-003',
+      '',
+      '- Status: `approved`',
+      '- Source: `docs/delivery-os/06-roadmap.md:10`',
+      '- Source hash: `sha`',
+      '- Phase: `phase-1`',
+      '- Quality: `complete`',
+      '- Quality issue: (none)',
+      '- Work package: WP-003',
+      '- Acceptance: Meetings are classified with meeting_track.',
+      '- Decision: `approve`',
+      '- Notes: (empty)',
+      '- Requirement: Phase 1 classification uses meeting_track for client/internal/tracker/advisor_network/investor/grant_funding.',
+      '',
+      '### REQ-004',
+      '',
+      '- Status: `approved`',
+      '- Source: `docs/delivery-os/13-meeting-extraction-profiles.md:240`',
+      '- Source hash: `sha`',
+      '- Phase: `phase-1`',
+      '- Quality: `complete`',
+      '- Quality issue: (none)',
+      '- Work package: WP-001, WP-003',
+      '- Acceptance: Speaker resolution stores raw speaker labels/aliases and speaker_resolution_status.',
+      '- Decision: `approve`',
+      '- Notes: (empty)',
+      '- Requirement: Phase 1 supports speaker identity resolution and alias storage.',
+      '',
+    ].join('\n'));
+
+    const synthesis = initiativeRequirementsSynthesis({
+      projectRoot: root,
+      initiativeId: 'delivery-os-mvp',
+    });
+
+    const schemaGate = synthesis.gates.find((gate) => gate.id === 'schema-supports-derived-requirements');
+    expect(schemaGate).toMatchObject({
+      severity: 'critical',
+      blocking: true,
+    });
+    expect(schemaGate.issue).toContain('schema/foundation contract');
+    expect(schemaGate.issue).toContain('person_aliases');
+    expect(schemaGate.issue).toContain('meeting_track');
+    expect(schemaGate.action).toContain('meetings.raw_speaker_labels');
+  });
 });
 
 function makeProject() {

package/package.json

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