@besales/ops-framework 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.1.8
+
+- Added `initiative-intake` for source-doc indexing, source SHA tracking and deterministic requirement candidates.
+- Added `initiative-requirements` to create `requirements-map.md` and `coverage.md` from intake candidates.
+- Added generated project scripts for initiative intake and requirements mapping.
+
+## 0.1.7
+
+- Added the first Initiative Framework layer above tasks for MVPs, large feature trains and multi-phase work.
+- Added `initiative-create`, `initiative-add-work-package`, `initiative-status` and `initiative-next`.
+- Added work-package task materialization so a work package remains a normal task while slices stay inside `plan.md` and `execution.md`.
+- Added `ops.initiativesDir` project config support and generated project scripts for initiative commands.
+
 ## 0.1.6
 
 - Added `ops-agent closeout <TASK>` as the Supervisor entrypoint before final task closure.

package/README.md

@@ -180,6 +180,12 @@ Do not commit that `file:` dependency to production projects. It is only for pac
 - `learning-report`
 - `learning-closeout`
 - `closeout`
+- `initiative-create`
+- `initiative-add-work-package`
+- `initiative-status`
+- `initiative-next`
+- `initiative-intake`
+- `initiative-requirements`
 - `test/self-test`
 
 ## Learning Loop
@@ -219,6 +225,41 @@ ops-agent closeout TASK-001-example
 
 Shared playbook candidates are intentionally manual-review only. Promote them through a separate reviewed framework task, not by auto-writing project-specific observations into the shared package.
 
+## Initiative Framework
+
+Initiatives are the program-level layer above tasks. Use them for MVPs, large feature trains and multi-phase functionality where a one-task-at-a-time flow would be too slow.
+
+```bash
+ops-agent initiative-create delivery-os-mvp --title "Delivery OS MVP" --mode fast_mvp
+ops-agent initiative-add-work-package delivery-os-mvp WP-001-foundation --title "Foundation"
+ops-agent initiative-intake delivery-os-mvp docs/delivery-os
+ops-agent initiative-requirements delivery-os-mvp
+ops-agent initiative-status delivery-os-mvp
+ops-agent initiative-next delivery-os-mvp --materialize-task
+```
+
+The hierarchy is:
+
+```text
+Initiative
+ -> Work-package task
+      -> Execution slices inside plan.md/execution.md
+```
+
+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.
+
+For source docs, use intake before work-package planning:
+
+```text
+Raw docs
+ -> initiative intake/source-index
+ -> requirements-map.md
+ -> work packages
+ -> tasks
+```
+
+`initiative-intake <initiative> <docs-dir>` indexes supported source documents, writes source SHA hashes and deterministic requirement candidates into `intake/`. `initiative-requirements <initiative>` turns those candidates into `REQ-*` rows in `requirements-map.md` and writes `coverage.md`. Human review is still required before treating candidates as approved or planned.
+
 ## Feedback Intake
 
 Feedback is stage-agnostic. Any user question, correction, review note or learning observation during an active task should be captured before it is acted on:

package/bin/initiative.mjs

@@ -0,0 +1,823 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import {
+  getFlag,
+  parseCliArgs,
+  updateMarkdownSection,
+} from './lib/check-context-utils.mjs';
+import {
+  createTask,
+  summarizeChanges,
+} from './lib/bootstrap-utils.mjs';
+import { resolveProjectContext } from './lib/project-config.mjs';
+
+const INITIATIVE_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+const WORK_PACKAGE_ID_PATTERN = /^WP-\d{3}-[a-z0-9][a-z0-9-]*$/;
+const SUPPORTED_SOURCE_EXTENSIONS = new Set(['.md', '.markdown', '.txt', '.json', '.yaml', '.yml']);
+
+export function main() {
+  const command = process.argv[2];
+  const args = parseCliArgs(process.argv.slice(3));
+  try {
+    if (command === 'initiative-create') {
+      const result = createInitiative({
+        projectRoot: process.cwd(),
+        initiativeId: args.positional[0],
+        title: getFlag(args, 'title', null),
+        goal: getFlag(args, 'goal', null),
+        mode: getFlag(args, 'mode', 'fast_mvp'),
+        force: args.flags.has('force'),
+      });
+      printChangeSummary(`Initiative created: ${result.initiativeId}`, result.changes);
+      return;
+    }
+    if (command === 'initiative-add-work-package') {
+      const result = addWorkPackage({
+        projectRoot: process.cwd(),
+        initiativeId: args.positional[0],
+        workPackageId: args.positional[1],
+        title: getFlag(args, 'title', null),
+        goal: getFlag(args, 'goal', null),
+        mode: getFlag(args, 'mode', 'standard_work_package'),
+        force: args.flags.has('force'),
+      });
+      printChangeSummary(`Work package added: ${result.workPackageId}`, result.changes);
+      return;
+    }
+    if (command === 'initiative-status') {
+      const result = initiativeStatus({
+        projectRoot: process.cwd(),
+        initiativeId: args.positional[0],
+      });
+      printInitiativeStatus(result);
+      return;
+    }
+    if (command === 'initiative-next') {
+      const result = initiativeNext({
+        projectRoot: process.cwd(),
+        initiativeId: args.positional[0],
+        materializeTask: args.flags.has('materialize-task'),
+        taskId: getFlag(args, 'task-id', null),
+        force: args.flags.has('force'),
+      });
+      printInitiativeNext(result);
+      return;
+    }
+    if (command === 'initiative-intake') {
+      const result = initiativeIntake({
+        projectRoot: process.cwd(),
+        initiativeId: args.positional[0],
+        docsDir: args.positional[1],
+        force: args.flags.has('force'),
+      });
+      printChangeSummary(`Initiative intake written: ${result.initiativeId}`, result.changes);
+      console.log(`- sources: ${result.sources.length}`);
+      console.log(`- requirement candidates: ${result.candidates.length}`);
+      return;
+    }
+    if (command === 'initiative-requirements') {
+      const result = initiativeRequirements({
+        projectRoot: process.cwd(),
+        initiativeId: args.positional[0],
+        force: args.flags.has('force'),
+      });
+      printChangeSummary(`Initiative requirements map written: ${result.initiativeId}`, result.changes);
+      console.log(`- requirements: ${result.requirements.length}`);
+      return;
+    }
+    fail('Usage: ops-agent initiative-create|initiative-add-work-package|initiative-status|initiative-next|initiative-intake|initiative-requirements ...');
+  } catch (error) {
+    fail(error.message);
+  }
+}
+
+export function createInitiative({
+  projectRoot = process.cwd(),
+  initiativeId,
+  title,
+  goal,
+  mode = 'fast_mvp',
+  force = false,
+} = {}) {
+  assertInitiativeId(initiativeId);
+  const context = resolveProjectContext({ cwd: projectRoot });
+  const initiativeDir = path.join(context.initiativesRoot, initiativeId);
+  const workPackagesDir = path.join(initiativeDir, 'work-packages');
+  const changes = [];
+  ensureDirectory(context.initiativesRoot, changes);
+  ensureDirectory(initiativeDir, changes);
+  ensureDirectory(workPackagesDir, changes);
+  const displayTitle = title || humanizeSlug(initiativeId);
+  const displayGoal = goal || 'Define MVP/program outcome before planning work packages.';
+  writeFileIfAllowed(path.join(initiativeDir, 'initiative.yaml'), buildInitiativeYaml({
+    initiativeId,
+    title: displayTitle,
+    goal: displayGoal,
+    mode,
+  }), { force, changes });
+  writeFileIfAllowed(path.join(initiativeDir, 'initiative.md'), buildInitiativeMarkdown({
+    initiativeId,
+    title: displayTitle,
+    goal: displayGoal,
+    mode,
+  }), { force, changes });
+  writeFileIfAllowed(path.join(initiativeDir, 'status.md'), buildInitiativeStatus({
+    initiativeId,
+    title: displayTitle,
+  }), { force, changes });
+  writeFileIfAllowed(path.join(workPackagesDir, 'README.md'), buildWorkPackagesReadme(), { force, changes });
+  return {
+    initiativeId,
+    initiativeDir,
+    changes,
+  };
+}
+
+export function addWorkPackage({
+  projectRoot = process.cwd(),
+  initiativeId,
+  workPackageId,
+  title,
+  goal,
+  mode = 'standard_work_package',
+  force = false,
+} = {}) {
+  assertInitiativeId(initiativeId);
+  assertWorkPackageId(workPackageId);
+  const context = resolveProjectContext({ cwd: projectRoot });
+  const initiativeDir = path.join(context.initiativesRoot, initiativeId);
+  if (!fs.existsSync(initiativeDir)) {
+    throw new Error(`Initiative not found: ${initiativeId}. Run initiative-create first.`);
+  }
+  const workPackageDir = path.join(initiativeDir, 'work-packages', workPackageId);
+  const changes = [];
+  ensureDirectory(workPackageDir, changes);
+  writeFileIfAllowed(path.join(workPackageDir, 'work-package.md'), buildWorkPackageMarkdown({
+    initiativeId,
+    workPackageId,
+    title: title || humanizeSlug(workPackageId.replace(/^WP-\d{3}-/, '')),
+    goal: goal || 'Define work-package outcome before materializing a task.',
+    mode,
+  }), { force, changes });
+  return {
+    initiativeId,
+    workPackageId,
+    workPackageDir,
+    changes,
+  };
+}
+
+export function initiativeStatus({ projectRoot = process.cwd(), initiativeId } = {}) {
+  const initiative = readInitiative({ projectRoot, initiativeId });
+  const workPackages = listWorkPackages(initiative.initiativeDir);
+  return {
+    ...initiative,
+    workPackages,
+    counts: countBy(workPackages, (wp) => wp.status || 'pending'),
+  };
+}
+
+export function initiativeNext({
+  projectRoot = process.cwd(),
+  initiativeId,
+  materializeTask = false,
+  taskId = null,
+  force = false,
+} = {}) {
+  const status = initiativeStatus({ projectRoot, initiativeId });
+  const next = status.workPackages.find((wp) => ['pending', 'ready'].includes(wp.status));
+  if (!next) {
+    return {
+      initiativeId,
+      next: null,
+      materializedTask: null,
+    };
+  }
+  let materializedTask = null;
+  if (materializeTask) {
+    materializedTask = materializeWorkPackageTask({
+      projectRoot,
+      initiativeId,
+      workPackage: next,
+      taskId: taskId || taskIdForWorkPackage(next.id),
+      force,
+    });
+    updateWorkPackageStatus({
+      workPackagePath: next.path,
+      status: 'in_progress',
+      taskId: materializedTask.taskId,
+    });
+  }
+  return {
+    initiativeId,
+    next,
+    materializedTask,
+  };
+}
+
+export function initiativeIntake({
+  projectRoot = process.cwd(),
+  initiativeId,
+  docsDir,
+  force = false,
+} = {}) {
+  const initiative = readInitiative({ projectRoot, initiativeId });
+  if (!docsDir) {
+    throw new Error('Usage: ops-agent initiative-intake <initiative> <docs-dir>');
+  }
+  const absoluteDocsDir = path.resolve(projectRoot, docsDir);
+  if (!fs.existsSync(absoluteDocsDir) || !fs.statSync(absoluteDocsDir).isDirectory()) {
+    throw new Error(`Docs directory not found: ${docsDir}`);
+  }
+  const intakeDir = path.join(initiative.initiativeDir, 'intake');
+  const changes = [];
+  ensureDirectory(intakeDir, changes);
+  const sources = collectSourceDocuments({ projectRoot, docsDir: absoluteDocsDir });
+  const candidates = collectRequirementCandidates({ projectRoot, sources });
+  writeFileIfAllowed(path.join(intakeDir, 'source-index.json'), JSON.stringify({
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    docsDir: path.relative(projectRoot, absoluteDocsDir),
+    sources,
+  }, null, 2), { force: true, changes });
+  writeFileIfAllowed(path.join(intakeDir, 'sources.md'), renderSourcesMarkdown({ docsDir: absoluteDocsDir, projectRoot, sources }), { force, changes });
+  writeFileIfAllowed(path.join(intakeDir, 'extracted-requirements.md'), renderRequirementCandidatesMarkdown(candidates), { force: true, changes });
+  writeFileIfAllowed(path.join(intakeDir, 'open-questions.md'), buildOpenQuestionsMarkdown(), { force, changes });
+  writeFileIfAllowed(path.join(intakeDir, 'assumptions.md'), buildAssumptionsMarkdown(), { force, changes });
+  return {
+    initiativeId,
+    intakeDir,
+    sources,
+    candidates,
+    changes,
+  };
+}
+
+export function initiativeRequirements({
+  projectRoot = process.cwd(),
+  initiativeId,
+  force = false,
+} = {}) {
+  const initiative = readInitiative({ projectRoot, initiativeId });
+  const candidatesPath = path.join(initiative.initiativeDir, 'intake', 'extracted-requirements.md');
+  if (!fs.existsSync(candidatesPath)) {
+    throw new Error('Missing intake/extracted-requirements.md. Run initiative-intake first.');
+  }
+  const candidates = parseRequirementCandidates(fs.readFileSync(candidatesPath, 'utf8'));
+  const requirements = candidates.map((candidate, index) => ({
+    id: `REQ-${String(index + 1).padStart(3, '0')}`,
+    status: 'candidate',
+    title: summarizeRequirementTitle(candidate.text),
+    source: candidate.source,
+    sourceHash: candidate.sourceHash,
+    text: candidate.text,
+    workPackage: '',
+    acceptance: '',
+  }));
+  const changes = [];
+  writeFileIfAllowed(path.join(initiative.initiativeDir, 'requirements-map.md'), renderRequirementsMap(requirements), { force: true, changes });
+  writeFileIfAllowed(path.join(initiative.initiativeDir, 'coverage.md'), renderCoverage({ requirements }), { force, changes });
+  return {
+    initiativeId,
+    requirements,
+    changes,
+  };
+}
+
+function materializeWorkPackageTask({ projectRoot, initiativeId, workPackage, taskId, force }) {
+  const task = createTask({
+    projectRoot,
+    taskId,
+    title: workPackage.title,
+    owner: 'Supervisor',
+    force,
+  });
+  const briefPath = path.join(task.taskDir, 'brief.md');
+  const planPath = path.join(task.taskDir, 'plan.md');
+  const brief = fs.readFileSync(briefPath, 'utf8');
+  const plan = fs.readFileSync(planPath, 'utf8');
+  fs.writeFileSync(briefPath, updateMarkdownSection(brief, 'Initiative Context', [
+    `- Initiative: \`${initiativeId}\``,
+    `- Work package: \`${workPackage.id}\``,
+    `- Work package mode: \`${workPackage.mode}\``,
+    `- Goal: ${workPackage.goal}`,
+    '',
+    'This task is a work-package task. Do not create separate tasks for planned slices unless scope/risk escalation requires it.',
+  ].join('\n')));
+  fs.writeFileSync(planPath, updateMarkdownSection(plan, 'Execution Slices', renderExecutionSlices(workPackage)));
+  return task;
+}
+
+function collectSourceDocuments({ projectRoot, docsDir }) {
+  const files = [];
+  walkDocs(docsDir, files);
+  return files
+    .sort()
+    .map((filePath) => {
+      const content = fs.readFileSync(filePath, 'utf8');
+      return {
+        path: path.relative(projectRoot, filePath),
+        bytes: Buffer.byteLength(content),
+        sha256: sha256(content),
+        title: inferSourceTitle(content, filePath),
+      };
+    });
+}
+
+function walkDocs(directory, files) {
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    if (entry.name.startsWith('.') || entry.name === 'node_modules') {
+      continue;
+    }
+    const entryPath = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      walkDocs(entryPath, files);
+      continue;
+    }
+    if (entry.isFile() && SUPPORTED_SOURCE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
+      files.push(entryPath);
+    }
+  }
+}
+
+function collectRequirementCandidates({ projectRoot, sources }) {
+  const candidates = [];
+  const seen = new Set();
+  for (const source of sources) {
+    const sourcePath = path.join(projectRoot, source.path);
+    const lines = fs.readFileSync(sourcePath, 'utf8').split(/\r?\n/);
+    lines.forEach((line, index) => {
+      const normalized = normalizeRequirementCandidate(line);
+      if (!isRequirementCandidate(normalized)) {
+        return;
+      }
+      const key = sha256(`${source.path}:${normalized}`).slice(0, 16);
+      if (seen.has(key)) {
+        return;
+      }
+      seen.add(key);
+      candidates.push({
+        id: `RC-${String(candidates.length + 1).padStart(3, '0')}`,
+        source: `${source.path}:${index + 1}`,
+        sourceHash: source.sha256,
+        text: normalized,
+      });
+    });
+  }
+  return candidates;
+}
+
+function normalizeRequirementCandidate(line) {
+  return line
+    .replace(/^#{1,6}\s+/, '')
+    .replace(/^[-*]\s+/, '')
+    .replace(/^\d+[.)]\s+/, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function isRequirementCandidate(text) {
+  if (text.length < 20 || text.length > 500) {
+    return false;
+  }
+  return /(must|should|required|requirement|user can|user must|system must|needs to|нужно|должен|должна|должны|требован|пользователь может|пользователь должен|система должна|необходимо|важно)/i.test(text);
+}
+
+function renderSourcesMarkdown({ docsDir, projectRoot, sources }) {
+  return [
+    '# Initiative Sources',
+    '',
+    `Docs directory: \`${path.relative(projectRoot, docsDir)}\``,
+    '',
+    '| Source | Title | SHA-256 | Bytes |',
+    '| --- | --- | --- | --- |',
+    ...sources.map((source) => `| \`${source.path}\` | ${escapeTable(source.title)} | \`${source.sha256}\` | ${source.bytes} |`),
+    '',
+  ].join('\n');
+}
+
+function renderRequirementCandidatesMarkdown(candidates) {
+  return [
+    '# Extracted Requirement Candidates',
+    '',
+    'These are deterministic candidates from source docs. Human review is required before planning work packages.',
+    '',
+    ...candidates.map((candidate) => [
+      `## ${candidate.id}`,
+      '',
+      `- Source: \`${candidate.source}\``,
+      `- Source hash: \`${candidate.sourceHash}\``,
+      `- Candidate: ${candidate.text}`,
+      '',
+    ].join('\n')),
+  ].join('\n');
+}
+
+function parseRequirementCandidates(content) {
+  return content.split(/^##\s+/m).slice(1).map((section) => {
+    const [rawId, ...bodyLines] = section.split('\n');
+    const body = bodyLines.join('\n');
+    return {
+      id: rawId.trim(),
+      source: readMarkdownListField(body, 'Source'),
+      sourceHash: readMarkdownListField(body, 'Source hash'),
+      text: readMarkdownListField(body, 'Candidate'),
+    };
+  }).filter((candidate) => candidate.id && candidate.source && candidate.text);
+}
+
+function renderRequirementsMap(requirements) {
+  return [
+    '# Requirements Map',
+    '',
+    'Statuses: `candidate | approved | planned | implemented | rejected`.',
+    '',
+    '| ID | Status | Requirement | Source | Work package | Acceptance |',
+    '| --- | --- | --- | --- | --- | --- |',
+    ...requirements.map((req) => `| ${req.id} | ${req.status} | ${escapeTable(req.title)} | \`${req.source}\` | ${req.workPackage || ''} | ${req.acceptance || ''} |`),
+    '',
+    '## Requirement Details',
+    '',
+    ...requirements.map((req) => [
+      `### ${req.id}`,
+      '',
+      `- Status: \`${req.status}\``,
+      `- Source: \`${req.source}\``,
+      `- Source hash: \`${req.sourceHash}\``,
+      `- Work package: ${req.workPackage || '(unassigned)'}`,
+      `- Acceptance: ${req.acceptance || '(fill before implementation)'}`,
+      `- Requirement: ${req.text}`,
+      '',
+    ].join('\n')),
+  ].join('\n');
+}
+
+function renderCoverage({ requirements }) {
+  const counts = countBy(requirements, (req) => req.status || 'candidate');
+  return [
+    '# Initiative Coverage',
+    '',
+    `- Total requirements: ${requirements.length}`,
+    `- Candidate: ${counts.candidate || 0}`,
+    `- Approved: ${counts.approved || 0}`,
+    `- Planned: ${counts.planned || 0}`,
+    `- Implemented: ${counts.implemented || 0}`,
+    `- Rejected: ${counts.rejected || 0}`,
+    '',
+    '## Unassigned Requirements',
+    '',
+    ...requirements.filter((req) => !req.workPackage).map((req) => `- ${req.id}: ${req.title}`),
+    ...(requirements.some((req) => !req.workPackage) ? [] : ['- None.']),
+    '',
+  ].join('\n');
+}
+
+function buildOpenQuestionsMarkdown() {
+  return [
+    '# Open Questions',
+    '',
+    '- Add human decisions discovered during initiative intake.',
+    '',
+  ].join('\n');
+}
+
+function buildAssumptionsMarkdown() {
+  return [
+    '# Assumptions',
+    '',
+    '- Add assumptions that were required to interpret source docs.',
+    '',
+  ].join('\n');
+}
+
+function readInitiative({ projectRoot, initiativeId }) {
+  assertInitiativeId(initiativeId);
+  const context = resolveProjectContext({ cwd: projectRoot });
+  const initiativeDir = path.join(context.initiativesRoot, initiativeId);
+  if (!fs.existsSync(initiativeDir)) {
+    throw new Error(`Initiative not found: ${initiativeId}`);
+  }
+  const meta = readSimpleYaml(path.join(initiativeDir, 'initiative.yaml'));
+  return {
+    initiativeId,
+    initiativeDir,
+    title: meta.title || humanizeSlug(initiativeId),
+    mode: meta.mode || 'fast_mvp',
+    goal: meta.goal || '',
+  };
+}
+
+function listWorkPackages(initiativeDir) {
+  const root = path.join(initiativeDir, 'work-packages');
+  if (!fs.existsSync(root)) {
+    return [];
+  }
+  return fs.readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && WORK_PACKAGE_ID_PATTERN.test(entry.name))
+    .map((entry) => readWorkPackage(path.join(root, entry.name, 'work-package.md'), entry.name))
+    .sort((left, right) => left.id.localeCompare(right.id));
+}
+
+function readWorkPackage(filePath, fallbackId) {
+  const content = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+  return {
+    id: readInlineField(content, 'ID') || fallbackId,
+    title: readInlineField(content, 'Title') || humanizeSlug(fallbackId.replace(/^WP-\d{3}-/, '')),
+    status: readInlineField(content, 'Status') || 'pending',
+    task: readInlineField(content, 'Task') || '',
+    mode: readInlineField(content, 'Mode') || 'standard_work_package',
+    goal: readSection(content, 'Goal') || '',
+    slices: readBulletsFromSection(content, 'Slices'),
+    path: filePath,
+  };
+}
+
+function updateWorkPackageStatus({ workPackagePath, status, taskId }) {
+  const content = fs.readFileSync(workPackagePath, 'utf8');
+  let updated = content
+    .replace(/^Status:.*$/m, `Status: ${status}`)
+    .replace(/^Task:.*$/m, `Task: ${taskId}`);
+  if (updated === content) {
+    updated = `${content.trimEnd()}\n\nStatus: ${status}\nTask: ${taskId}\n`;
+  }
+  fs.writeFileSync(workPackagePath, updated.endsWith('\n') ? updated : `${updated}\n`);
+}
+
+function buildInitiativeYaml({ initiativeId, title, goal, mode }) {
+  return [
+    'schemaVersion: 1',
+    `id: ${initiativeId}`,
+    `title: ${title}`,
+    `mode: ${mode}`,
+    'humanAttention: milestone_and_escalations',
+    'riskPolicy: strict_on_high_risk_only',
+    `goal: ${goal}`,
+    '',
+  ].join('\n');
+}
+
+function buildInitiativeMarkdown({ initiativeId, title, goal, mode }) {
+  return [
+    `# ${title}`,
+    '',
+    `ID: ${initiativeId}`,
+    `Mode: ${mode}`,
+    'Human attention: milestone_and_escalations',
+    'Risk policy: strict_on_high_risk_only',
+    '',
+    '## Goal',
+    '',
+    goal,
+    '',
+    '## Phases',
+    '',
+    '- Phase 1: Foundation',
+    '- Phase 2: Core workflows',
+    '- Phase 3: UI/API integration',
+    '- Phase 4: QA, rollout and closeout',
+    '',
+    '## Work Package Policy',
+    '',
+    '- Work package is materialized as a normal task and remains the audit/logging unit.',
+    '- Slices live inside the work-package task plan/execution, not as separate task folders.',
+    '- Create a separate task only when a slice triggers scope, risk or architecture escalation.',
+    '',
+  ].join('\n');
+}
+
+function buildInitiativeStatus({ initiativeId, title }) {
+  return [
+    '# Initiative Status',
+    '',
+    `Initiative: ${initiativeId}`,
+    `Title: ${title}`,
+    'Current phase: planning',
+    'Current work package: none',
+    'Human approval needed: yes',
+    'Next step: Add work packages, then run initiative-next.',
+    '',
+  ].join('\n');
+}
+
+function buildWorkPackagesReadme() {
+  return [
+    '# Work Packages',
+    '',
+    'Each `WP-000-slug` is a planned work-package scope.',
+    '',
+    'Use `ops-agent initiative-next <initiative> --materialize-task` to turn the next pending work package into a normal task.',
+    '',
+  ].join('\n');
+}
+
+function buildWorkPackageMarkdown({ initiativeId, workPackageId, title, goal, mode }) {
+  return [
+    '# Work Package',
+    '',
+    `ID: ${workPackageId}`,
+    `Initiative: ${initiativeId}`,
+    `Title: ${title}`,
+    'Status: pending',
+    'Task:',
+    `Mode: ${mode}`,
+    '',
+    '## Goal',
+    '',
+    goal,
+    '',
+    '## Boundary',
+    '',
+    '- Included:',
+    '- Excluded:',
+    '- Escalate to separate task if:',
+    '',
+    '## Slices',
+    '',
+    '- Slice 1: Define the first implementation slice.',
+    '- Slice 2: Add the next implementation slice.',
+    '- Slice 3: Add micro-verify and evidence.',
+    '',
+    '## Acceptance',
+    '',
+    '- Work-package task has completed Verify.',
+    '- Slice ledger is recorded in execution.md.',
+    '- Learning closeout is completed before task closeout.',
+    '',
+  ].join('\n');
+}
+
+function renderExecutionSlices(workPackage) {
+  const slices = workPackage.slices.length
+    ? workPackage.slices
+    : ['Slice 1: Define implementation slice before Execute.'];
+  return [
+    `Work package: \`${workPackage.id}\``,
+    `Mode: \`${workPackage.mode}\``,
+    '',
+    '| Slice | Intent | Micro-verify | Escalation rule |',
+    '| --- | --- | --- | --- |',
+    ...slices.map((slice, index) => `| S-${String(index + 1).padStart(2, '0')} | ${escapeTable(slice)} | targeted test/typecheck/evidence | create separate task or return to Plan if scope/risk expands |`),
+    '',
+  ].join('\n');
+}
+
+function readSimpleYaml(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return {};
+  }
+  const result = {};
+  for (const line of fs.readFileSync(filePath, 'utf8').split(/\r?\n/)) {
+    const match = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+    if (match) {
+      result[match[1]] = match[2].trim();
+    }
+  }
+  return result;
+}
+
+function readInlineField(content, field) {
+  const match = new RegExp(`^${escapeRegExp(field)}:\\s*(.*)$`, 'm').exec(content);
+  return match ? match[1].trim() : '';
+}
+
+function readMarkdownListField(content, field) {
+  const match = new RegExp(`^- ${escapeRegExp(field)}:\\s*(.*)$`, 'm').exec(content);
+  return match ? match[1].replace(/^`|`$/g, '').trim() : '';
+}
+
+function readSection(content, heading) {
+  const match = new RegExp(`^##\\s+${escapeRegExp(heading)}\\s*\\n([\\s\\S]*?)(?=^##\\s+|\\s*$)`, 'm').exec(content);
+  return match ? match[1].trim() : '';
+}
+
+function readBulletsFromSection(content, heading) {
+  return readSection(content, heading)
+    .split(/\r?\n/)
+    .map((line) => line.replace(/^[-*]\s+/, '').trim())
+    .filter(Boolean);
+}
+
+function taskIdForWorkPackage(workPackageId) {
+  return workPackageId.replace(/^WP-/, 'TASK-');
+}
+
+function countBy(items, readKey) {
+  const counts = {};
+  for (const item of items) {
+    const key = readKey(item);
+    counts[key] = (counts[key] || 0) + 1;
+  }
+  return counts;
+}
+
+function ensureDirectory(directory, changes) {
+  if (fs.existsSync(directory)) {
+    changes.push({ path: directory, kind: 'directory', status: 'existing' });
+    return;
+  }
+  fs.mkdirSync(directory, { recursive: true });
+  changes.push({ path: directory, kind: 'directory', status: 'created' });
+}
+
+function writeFileIfAllowed(filePath, content, { force, changes }) {
+  const exists = fs.existsSync(filePath);
+  if (exists && !force) {
+    changes.push({ path: filePath, kind: 'file', status: 'existing' });
+    return;
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content.endsWith('\n') ? content : `${content}\n`);
+  changes.push({ path: filePath, kind: 'file', status: exists ? 'overwritten' : 'created' });
+}
+
+function printChangeSummary(title, changes) {
+  const summary = summarizeChanges(changes);
+  console.log(title);
+  console.log(`- created: ${summary.created}`);
+  console.log(`- existing: ${summary.existing}`);
+  console.log(`- overwritten: ${summary.overwritten}`);
+}
+
+function printInitiativeStatus(result) {
+  console.log(`Initiative status: ${result.initiativeId}`);
+  console.log(`- title: ${result.title}`);
+  console.log(`- mode: ${result.mode}`);
+  console.log(`- workPackages: ${result.workPackages.length}`);
+  for (const [status, count] of Object.entries(result.counts)) {
+    console.log(`- ${status}: ${count}`);
+  }
+  for (const wp of result.workPackages) {
+    console.log(`  - ${wp.id}: ${wp.status}${wp.task ? ` -> ${wp.task}` : ''}`);
+  }
+}
+
+function printInitiativeNext(result) {
+  console.log(`Initiative next: ${result.initiativeId}`);
+  if (!result.next) {
+    console.log('- no pending work packages');
+    return;
+  }
+  console.log(`- workPackage: ${result.next.id}`);
+  console.log(`- title: ${result.next.title}`);
+  console.log(`- mode: ${result.next.mode}`);
+  if (result.materializedTask) {
+    const summary = summarizeChanges(result.materializedTask.changes);
+    console.log(`- task: ${result.materializedTask.taskId}`);
+    console.log(`- taskDir: ${result.materializedTask.taskDir}`);
+    console.log(`- created: ${summary.created}`);
+    console.log(`- existing: ${summary.existing}`);
+  }
+}
+
+function assertInitiativeId(value) {
+  if (!INITIATIVE_ID_PATTERN.test(value || '')) {
+    throw new Error(`Initiative id must match ${INITIATIVE_ID_PATTERN}: ${value || '<missing>'}`);
+  }
+}
+
+function assertWorkPackageId(value) {
+  if (!WORK_PACKAGE_ID_PATTERN.test(value || '')) {
+    throw new Error(`Work package id must match ${WORK_PACKAGE_ID_PATTERN}: ${value || '<missing>'}`);
+  }
+}
+
+function humanizeSlug(slug) {
+  return slug
+    .replace(/^(TASK|WP)-\d{3}-/, '')
+    .split('-')
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
+function escapeTable(value) {
+  return String(value).replace(/\|/g, '\\|');
+}
+
+function inferSourceTitle(content, filePath) {
+  const heading = /^#\s+(.+)$/m.exec(content);
+  return heading ? heading[1].trim() : path.basename(filePath);
+}
+
+function summarizeRequirementTitle(text) {
+  return text.length > 120 ? `${text.slice(0, 117)}...` : text;
+}
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function fail(message) {
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+  main();
+}

package/bin/initiative.test.mjs

@@ -0,0 +1,133 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import {
+  addWorkPackage,
+  createInitiative,
+  initiativeIntake,
+  initiativeNext,
+  initiativeRequirements,
+  initiativeStatus,
+} from './initiative.mjs';
+
+describe('initiative framework', () => {
+  it('creates an initiative and summarizes work-package status', () => {
+    const root = makeProject();
+
+    createInitiative({
+      projectRoot: root,
+      initiativeId: 'delivery-os-mvp',
+      title: 'Delivery OS MVP',
+      goal: 'Build the first MVP train.',
+    });
+    addWorkPackage({
+      projectRoot: root,
+      initiativeId: 'delivery-os-mvp',
+      workPackageId: 'WP-001-foundation',
+      title: 'Foundation',
+      goal: 'Create the foundation.',
+    });
+
+    const status = initiativeStatus({ projectRoot: root, initiativeId: 'delivery-os-mvp' });
+
+    expect(status.mode).toBe('fast_mvp');
+    expect(status.workPackages).toHaveLength(1);
+    expect(status.workPackages[0]).toMatchObject({
+      id: 'WP-001-foundation',
+      status: 'pending',
+      title: 'Foundation',
+    });
+    expect(status.counts.pending).toBe(1);
+  });
+
+  it('materializes the next work package as a task with execution slices', () => {
+    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',
+      goal: 'Create the foundation.',
+    });
+
+    const result = initiativeNext({
+      projectRoot: root,
+      initiativeId: 'delivery-os-mvp',
+      materializeTask: true,
+    });
+
+    expect(result.materializedTask.taskId).toBe('TASK-001-foundation');
+    const taskDir = path.join(root, 'ops', 'agent-pipeline', 'tasks', 'TASK-001-foundation');
+    const brief = fs.readFileSync(path.join(taskDir, 'brief.md'), 'utf8');
+    const plan = fs.readFileSync(path.join(taskDir, 'plan.md'), 'utf8');
+    const workPackage = fs.readFileSync(path.join(root, 'ops', 'agent-pipeline', 'initiatives', 'delivery-os-mvp', 'work-packages', 'WP-001-foundation', 'work-package.md'), 'utf8');
+    expect(brief).toContain('## Initiative Context');
+    expect(brief).toContain('Work package: `WP-001-foundation`');
+    expect(plan).toContain('## Execution Slices');
+    expect(plan).toContain('S-01');
+    expect(workPackage).toContain('Status: in_progress');
+    expect(workPackage).toContain('Task: TASK-001-foundation');
+  });
+
+  it('indexes source docs and builds a requirements map', () => {
+    const root = makeProject();
+    const docsDir = path.join(root, 'docs', 'delivery-os');
+    fs.mkdirSync(docsDir, { recursive: true });
+    fs.writeFileSync(path.join(docsDir, 'mvp.md'), [
+      '# Delivery OS MVP',
+      '',
+      '- User must create delivery orders from the admin UI.',
+      '- Система должна показывать статус доставки оператору.',
+      '- Nice prose for background context only.',
+    ].join('\n'));
+    createInitiative({
+      projectRoot: root,
+      initiativeId: 'delivery-os-mvp',
+      title: 'Delivery OS MVP',
+    });
+
+    const intake = initiativeIntake({
+      projectRoot: root,
+      initiativeId: 'delivery-os-mvp',
+      docsDir: 'docs/delivery-os',
+    });
+    const requirements = initiativeRequirements({
+      projectRoot: root,
+      initiativeId: 'delivery-os-mvp',
+    });
+
+    expect(intake.sources).toHaveLength(1);
+    expect(intake.candidates).toHaveLength(2);
+    expect(requirements.requirements).toHaveLength(2);
+    const initiativeDir = path.join(root, 'ops', 'agent-pipeline', 'initiatives', 'delivery-os-mvp');
+    const sourceIndex = JSON.parse(fs.readFileSync(path.join(initiativeDir, 'intake', 'source-index.json'), 'utf8'));
+    const requirementsMap = fs.readFileSync(path.join(initiativeDir, 'requirements-map.md'), 'utf8');
+    expect(sourceIndex.sources[0].path).toBe('docs/delivery-os/mvp.md');
+    expect(requirementsMap).toContain('REQ-001');
+    expect(requirementsMap).toContain('User must create delivery orders');
+    expect(requirementsMap).toContain('REQ-002');
+  });
+});
+
+function makeProject() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ops-initiative-'));
+  fs.mkdirSync(path.join(root, 'ops'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'ops', 'project.ops.yaml'), [
+    'name: TestProject',
+    'ops:',
+    '  legacyPipelineDir: ops/agent-pipeline',
+    '  tasksDir: ops/agent-pipeline/tasks',
+    '  initiativesDir: ops/agent-pipeline/initiatives',
+    '  memoryDir: ops/agent-pipeline/memory',
+    '  cacheDir: ops/agent-pipeline/cache',
+    '  playbooksDir: ops/agent-pipeline/playbooks',
+    '',
+  ].join('\n'));
+  return root;
+}

package/bin/lib/bootstrap-utils.mjs

@@ -121,6 +121,12 @@ export function buildOpsScripts(packageSpec) {
     'agent:learning-report': run('learning-report'),
     'agent:learning-closeout': run('learning-closeout'),
     'agent:closeout': run('closeout'),
+    'agent:initiative-create': run('initiative-create'),
+    'agent:initiative-add-work-package': run('initiative-add-work-package'),
+    'agent:initiative-status': run('initiative-status'),
+    'agent:initiative-next': run('initiative-next'),
+    'agent:initiative-intake': run('initiative-intake'),
+    'agent:initiative-requirements': run('initiative-requirements'),
     'agent:test': run('test/self-test'),
   };
 }
@@ -290,6 +296,7 @@ function buildProjectConfig({ projectName, opsRoot }) {
     'ops:',
     `  legacyPipelineDir: ${opsRoot}/agent-pipeline`,
     `  tasksDir: ${opsRoot}/agent-pipeline/tasks`,
+    `  initiativesDir: ${opsRoot}/agent-pipeline/initiatives`,
     `  memoryDir: ${opsRoot}/agent-pipeline/memory`,
     `  cacheDir: ${opsRoot}/agent-pipeline/cache`,
     `  playbooksDir: ${opsRoot}/agent-pipeline/playbooks`,

package/bin/lib/bootstrap-utils.test.mjs

@@ -140,6 +140,10 @@ describe('buildOpsScripts', () => {
     expect(scripts['agent:quality-gates']).toBe('ops-agent quality-gates');
     expect(scripts['agent:learning-closeout']).toBe('ops-agent learning-closeout');
     expect(scripts['agent:closeout']).toBe('ops-agent closeout');
+    expect(scripts['agent:initiative-create']).toBe('ops-agent initiative-create');
+    expect(scripts['agent:initiative-next']).toBe('ops-agent initiative-next');
+    expect(scripts['agent:initiative-intake']).toBe('ops-agent initiative-intake');
+    expect(scripts['agent:initiative-requirements']).toBe('ops-agent initiative-requirements');
     expect(scripts['agent:test']).toBe('ops-agent test/self-test');
   });
 });

package/bin/lib/project-config.mjs

@@ -134,6 +134,7 @@ function buildConfiguredContext({ projectRoot, configPath, config }) {
     frameworkRoot,
     pipelineRoot: legacyPipelineRoot,
     tasksRoot: resolveProjectPath(projectRoot, ops.tasksDir || 'ops/agent-pipeline/tasks'),
+    initiativesRoot: resolveProjectPath(projectRoot, ops.initiativesDir || 'ops/agent-pipeline/initiatives'),
     memoryRoot: resolveProjectPath(projectRoot, ops.memoryDir || 'ops/agent-pipeline/memory'),
     cacheRoot: resolveProjectPath(projectRoot, ops.cacheDir || 'ops/agent-pipeline/cache'),
     promptsRoot: path.join(frameworkRoot, 'prompts'),
@@ -163,6 +164,7 @@ function buildLegacyContext({ cwd }) {
     frameworkRoot,
     pipelineRoot: legacyPipelineRoot,
     tasksRoot: path.join(legacyPipelineRoot, 'tasks'),
+    initiativesRoot: path.join(legacyPipelineRoot, 'initiatives'),
     memoryRoot: path.join(legacyPipelineRoot, 'memory'),
     cacheRoot: path.join(legacyPipelineRoot, 'cache'),
     promptsRoot: path.join(frameworkRoot, 'prompts'),

package/bin/ops-agent.mjs

@@ -34,6 +34,12 @@ const COMMANDS = new Map([
   ['learning-report', 'learning-loop.mjs'],
   ['learning-closeout', 'learning-loop.mjs'],
   ['closeout', 'closeout.mjs'],
+  ['initiative-create', 'initiative.mjs'],
+  ['initiative-add-work-package', 'initiative.mjs'],
+  ['initiative-status', 'initiative.mjs'],
+  ['initiative-next', 'initiative.mjs'],
+  ['initiative-intake', 'initiative.mjs'],
+  ['initiative-requirements', 'initiative.mjs'],
   ['test/self-test', null],
 ]);
 
@@ -58,7 +64,7 @@ function main() {
   }
 
   const script = path.join(binRoot, COMMANDS.get(command));
-  const scriptArgs = COMMANDS.get(command) === 'learning-loop.mjs' ? [command, ...args] : args;
+  const scriptArgs = ['learning-loop.mjs', 'initiative.mjs'].includes(COMMANDS.get(command)) ? [command, ...args] : args;
   const result = spawnSync(process.execPath, [script, ...scriptArgs], {
     cwd: process.cwd(),
     env: process.env,

package/package.json

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