@besales/ops-framework 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 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.
+- Closeout now validates Verify and Retrospective readiness, automatically runs learning closeout, pauses for unresolved learning decisions and can apply approved learning with `--apply-approved`.
+- Added generated project script support for `agent:closeout`.
+
 ## 0.1.5
 
 - Added `ops-agent learning-closeout <TASK>` as the default post-retrospective learning checkpoint.

package/README.md

@@ -179,6 +179,11 @@ Do not commit that `file:` dependency to production projects. It is only for pac
 - `learning-audit`
 - `learning-report`
 - `learning-closeout`
+- `closeout`
+- `initiative-create`
+- `initiative-add-work-package`
+- `initiative-status`
+- `initiative-next`
 - `test/self-test`
 
 ## Learning Loop
@@ -203,6 +208,7 @@ ops-agent learning-audit
 ops-agent update-memory --apply-approved
 ops-agent learning-report
 ops-agent learning-closeout TASK-001-example
+ops-agent closeout TASK-001-example
 ```
 
 `memory-candidates` creates structured learning cards with source, reason hash, learning layer, confidence, problem, lesson, repeat risk, proposed wording and suggested target. `learning-index` turns those cards into human-reviewable decisions. `update-memory` only writes approved entries when `--apply-approved` is passed.
@@ -213,8 +219,31 @@ ops-agent learning-closeout TASK-001-example
 
 `learning-closeout <TASK>` is the default closeout checkpoint after retrospective. It collects candidates from that task, refreshes `learning-index.json`, writes `learning-review.md`, writes `learning-report.md`, creates `learning-closeout.md` inside the task and updates `status.md` so human approval is visible. The review must show every learning candidate individually with summary, target, source artifact, reason, proposed change, scope, confidence, promotion risk and the current decision.
 
+`closeout <TASK>` is the Supervisor entrypoint before any final closure. It validates `verify.result.json` and `retrospective.md`, automatically runs `learning-closeout <TASK>`, pauses when learning decisions are still `pending` or `rewrite`, and after `--apply-approved` applies approved learning, refreshes the report and runs the final guard unless `--skip-guard` is passed.
+
 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-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.
+
 ## 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/closeout.mjs

@@ -0,0 +1,224 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import {
+  appendOrchestrationLog,
+  parseCliArgs,
+  projectContext,
+  readJsonFile,
+  readTaskFile,
+  repoRoot,
+  resolveTaskDir,
+  updateStatus,
+} from './lib/check-context-utils.mjs';
+import {
+  INDEX_FILE,
+  REPORT_FILE,
+  updateMemory,
+  writeLearningCloseout,
+  writeLearningReport,
+} from './learning-loop.mjs';
+
+export function main() {
+  const args = parseCliArgs(process.argv.slice(2));
+  const taskArg = args.positional[0] || args.flags.get('task');
+  if (!taskArg) {
+    fail('Usage: ops-agent closeout <TASK-id-or-task-path> [--apply-approved] [--skip-guard]');
+  }
+
+  try {
+    const result = closeoutTask({
+      taskArg,
+      applyApproved: args.flags.has('apply-approved'),
+      runGuard: !args.flags.has('skip-guard'),
+    });
+    printCloseoutResult(result);
+    if (!result.ok) {
+      process.exit(1);
+    }
+  } catch (error) {
+    fail(error.message);
+  }
+}
+
+export function closeoutTask({ taskArg, applyApproved = false, runGuard = true } = {}) {
+  const taskDir = resolveTaskDir(taskArg);
+  const taskId = path.basename(taskDir);
+  const prerequisiteIssues = validateCloseoutPrerequisites(taskDir);
+  if (prerequisiteIssues.length) {
+    updateStatus(taskDir, {
+      stage: 'Closeout Blocked',
+      supervisorAction: 'Closeout orchestration blocked by missing prerequisites.',
+      nextStep: prerequisiteIssues.join(' '),
+      humanApproval: 'no',
+    });
+    appendOrchestrationLog(taskDir, `closeout blocked; issues=${prerequisiteIssues.length}`);
+    return {
+      ok: false,
+      taskId,
+      status: 'blocked_prerequisites',
+      issues: prerequisiteIssues,
+    };
+  }
+
+  writeLearningCloseout({ taskArg });
+  const beforeApply = readLearningDecisionSummary();
+  if (applyApproved) {
+    updateMemory({ applyApproved: true });
+    writeLearningReport();
+  }
+  const afterApply = readLearningDecisionSummary();
+  const unresolved = afterApply.pending + afterApply.rewrite;
+
+  if (unresolved > 0) {
+    updateStatus(taskDir, {
+      stage: 'Retrospective / Learning Review',
+      supervisorAction: 'Closeout paused for human learning decisions.',
+      nextStep: `Review ${relativeProjectPath(path.join(projectContext.memoryRoot, 'learning-review.md'))}; set pending/rewrite entries in ${relativeProjectPath(path.join(projectContext.memoryRoot, INDEX_FILE))} to promote, defer or reject; rerun agent:closeout --apply-approved.`,
+      humanApproval: 'yes',
+    });
+    appendOrchestrationLog(taskDir, `closeout paused for learning decisions; pending=${afterApply.pending}; rewrite=${afterApply.rewrite}`);
+    return {
+      ok: false,
+      taskId,
+      status: 'learning_review_required',
+      beforeApply,
+      afterApply,
+      issues: [`Learning decisions unresolved: pending=${afterApply.pending}, rewrite=${afterApply.rewrite}.`],
+    };
+  }
+
+  updateStatus(taskDir, {
+    stage: 'Closeout Audit',
+    supervisorAction: 'Closeout orchestration completed learning loop; ready for final guard.',
+    nextStep: 'Review learning-report.md and guard-task result before marking the task Closed, Accepted or Ready To Pause.',
+    humanApproval: 'yes',
+  });
+  appendOrchestrationLog(taskDir, `closeout learning loop resolved; promoted=${afterApply.promote}; deferred=${afterApply.defer}; rejected=${afterApply.reject}`);
+
+  const guard = runGuard ? runGuardTask(taskArg) : { ok: true, skipped: true, output: 'guard skipped by --skip-guard' };
+  if (!guard.ok) {
+    return {
+      ok: false,
+      taskId,
+      status: 'guard_failed',
+      beforeApply,
+      afterApply,
+      guard,
+      issues: ['Closeout guard failed. Fix listed issues before final closure.'],
+    };
+  }
+
+  return {
+    ok: true,
+    taskId,
+    status: 'ready_for_human_closeout',
+    beforeApply,
+    afterApply,
+    guard,
+    issues: [],
+  };
+}
+
+export function validateCloseoutPrerequisites(taskDir) {
+  const issues = [];
+  const verifyPath = path.join(taskDir, 'verify.result.json');
+  if (!fs.existsSync(verifyPath)) {
+    issues.push('verify.result.json is missing; run Verify before closeout.');
+  } else {
+    try {
+      const verify = readJsonFile(verifyPath);
+      if (!['pass', 'pass_with_notes'].includes(verify.verdict)) {
+        issues.push(`verify.result.json verdict=${verify.verdict}; closeout requires pass or pass_with_notes.`);
+      }
+    } catch (error) {
+      issues.push(`verify.result.json is invalid JSON: ${error.message}`);
+    }
+  }
+
+  const retrospective = readTaskFile(taskDir, 'retrospective.md');
+  if (!retrospective.trim()) {
+    issues.push('retrospective.md is missing or empty; fill Retrospective before closeout.');
+  }
+  if (/\[fill in\]|`not_started`|Retrospective has not started/i.test(retrospective)) {
+    issues.push('retrospective.md still contains placeholders or not_started markers; complete Retrospective before closeout.');
+  }
+  return issues;
+}
+
+function readLearningDecisionSummary() {
+  const indexPath = path.join(projectContext.memoryRoot, INDEX_FILE);
+  if (!fs.existsSync(indexPath)) {
+    return {
+      total: 0,
+      pending: 0,
+      promote: 0,
+      defer: 0,
+      reject: 0,
+      rewrite: 0,
+    };
+  }
+  const index = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+  const summary = {
+    total: 0,
+    pending: 0,
+    promote: 0,
+    defer: 0,
+    reject: 0,
+    rewrite: 0,
+  };
+  for (const entry of index.entries || []) {
+    const decision = entry.decision || 'pending';
+    summary.total += 1;
+    summary[decision] = (summary[decision] || 0) + 1;
+  }
+  return summary;
+}
+
+function runGuardTask(taskArg) {
+  const result = spawnSync(process.execPath, [path.join(path.dirname(fileURLToPath(import.meta.url)), 'guard-task.mjs'), taskArg], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+  });
+  return {
+    ok: result.status === 0,
+    status: result.status,
+    output: `${result.stdout || ''}${result.stderr || ''}`.trim(),
+  };
+}
+
+function printCloseoutResult(result) {
+  console.log(`Closeout ${result.status} for ${result.taskId}`);
+  for (const issue of result.issues || []) {
+    console.log(`- ${issue}`);
+  }
+  if (result.afterApply) {
+    console.log(`- learning total: ${result.afterApply.total}`);
+    console.log(`- learning pending: ${result.afterApply.pending}`);
+    console.log(`- learning rewrite: ${result.afterApply.rewrite}`);
+    console.log(`- learning promoted: ${result.afterApply.promote}`);
+    console.log(`- learning deferred: ${result.afterApply.defer}`);
+    console.log(`- learning rejected: ${result.afterApply.reject}`);
+    console.log(`- learning report: ${relativeProjectPath(path.join(projectContext.memoryRoot, REPORT_FILE))}`);
+  }
+  if (result.guard) {
+    console.log(`- guard: ${result.guard.ok ? 'ok' : 'failed'}`);
+    if (result.guard.output) {
+      console.log(result.guard.output);
+    }
+  }
+}
+
+function relativeProjectPath(filePath) {
+  return path.relative(projectContext.projectRoot, filePath) || path.basename(filePath);
+}
+
+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/closeout.test.mjs

@@ -0,0 +1,46 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { validateCloseoutPrerequisites } from './closeout.mjs';
+
+describe('closeout', () => {
+  it('blocks closeout when verify result is missing and retrospective still has placeholders', () => {
+    const taskDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ops-closeout-blocked-'));
+    fs.writeFileSync(path.join(taskDir, 'retrospective.md'), [
+      '# Retrospective',
+      '',
+      '## Статус',
+      '',
+      '`not_started`',
+      '',
+      '- `ops-agent closeout <TASK>` запущен как основной closeout entrypoint: `[fill in]`',
+    ].join('\n'));
+
+    const issues = validateCloseoutPrerequisites(taskDir);
+
+    expect(issues).toContain('verify.result.json is missing; run Verify before closeout.');
+    expect(issues).toContain('retrospective.md still contains placeholders or not_started markers; complete Retrospective before closeout.');
+  });
+
+  it('allows closeout prerequisites when verify passed and retrospective is complete', () => {
+    const taskDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ops-closeout-ready-'));
+    fs.writeFileSync(path.join(taskDir, 'verify.result.json'), JSON.stringify({
+      schemaVersion: 1,
+      verdict: 'pass_with_notes',
+    }, null, 2));
+    fs.writeFileSync(path.join(taskDir, 'retrospective.md'), [
+      '# Retrospective',
+      '',
+      '## Статус',
+      '',
+      '`completed`',
+      '',
+      '## Переиспользуемые выводы',
+      '',
+      '- Feedback capture worked and learning review was shown.',
+    ].join('\n'));
+
+    expect(validateCloseoutPrerequisites(taskDir)).toEqual([]);
+  });
+});

package/bin/initiative.mjs

@@ -0,0 +1,530 @@
+import fs from 'node:fs';
+import path from 'node:path';
+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-]*$/;
+
+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;
+    }
+    fail('Usage: ops-agent initiative-create|initiative-add-work-package|initiative-status|initiative-next ...');
+  } 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,
+  };
+}
+
+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 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 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 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,92 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import {
+  addWorkPackage,
+  createInitiative,
+  initiativeNext,
+  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');
+  });
+});
+
+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

@@ -120,6 +120,11 @@ export function buildOpsScripts(packageSpec) {
     'agent:learning-audit': run('learning-audit'),
     '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:test': run('test/self-test'),
   };
 }
@@ -289,6 +294,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

@@ -139,6 +139,9 @@ describe('buildOpsScripts', () => {
     expect(scripts.ops).toBe('ops-agent');
     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: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

@@ -33,6 +33,11 @@ const COMMANDS = new Map([
   ['learning-audit', 'learning-loop.mjs'],
   ['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'],
   ['test/self-test', null],
 ]);
 
@@ -57,7 +62,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.5",
+  "version": "0.1.7",
   "type": "module",
   "bin": {
     "ops-agent": "bin/ops-agent.mjs"

package/prompts/supervisor.md

@@ -193,7 +193,7 @@ Allowed ref types:
    - `human_arbitration_required` -> route to `Human Arbitration`;
    - `verifier_failed` -> остаться в `Verify` до remediation или провайдера/контекста.
 4. `Retrospective`: `retrospective.md` заполнен и содержит итоговый статус/verdict.
-5. `Learning Loop Audit`: Supervisor запускает `learning-closeout <TASK>` или эквивалентную последовательность `memory-candidates`, `learning-index`, `learning-review`, human decisions, `update-memory --apply-approved` для promoted entries and `learning-report`; human должен видеть каждый learning отдельно: summary, target, source artifact, reason, proposed change, scope, confidence, risk, current decision и куда approved entries записаны.
+5. `Learning Loop Audit`: Supervisor запускает `closeout <TASK>` как основной вход в закрытие. Эта команда валидирует Verify/Retrospective, автоматически запускает `learning-closeout <TASK>`, останавливает закрытие при pending/rewrite learning decisions, а после human decisions запускается повторно с `--apply-approved`. Human должен видеть каждый learning отдельно: summary, target, source artifact, reason, proposed change, scope, confidence, risk, current decision и куда approved entries записаны.
 6. `Closeout Audit`: Supervisor проверяет `status.md`, `verify.md`, `verify.result.json`, `retrospective.md`, `orchestration-log.md`, `learning-report.md`, deferred/follow-up фиксацию и `git diff --check`.
 7. `Human Closeout Gate`: только после audit можно предлагать закрытие/паузу/task switch.
 

package/templates/retrospective.md

@@ -16,6 +16,7 @@
 
 ## Learning Loop Audit
 
+- `ops-agent closeout <TASK>` запущен как основной closeout entrypoint: `[fill in]`
 - `ops-agent learning-closeout <TASK>` выполнен после заполнения retrospective: `[fill in]`
 - `ops-agent memory-candidates` выполнен после заполнения retrospective/check/verify feedback: `[fill in]`
 - `ops-agent learning-index` создал human-reviewable decisions: `[fill in]`