@besales/ops-framework 0.1.17 → 0.1.18

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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.

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,
   };
 }
 
@@ -1327,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}-/, '')),
@@ -1334,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
@@ -1438,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.',
@@ -1446,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.',
@@ -1562,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');

package/package.json

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