@besales/ops-framework 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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,7 @@ Do not commit that `file:` dependency to production projects. It is only for pac
 - `learning-audit`
 - `learning-report`
 - `learning-closeout`
+- `closeout`
 - `test/self-test`
 
 ## Learning Loop
@@ -203,6 +204,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,6 +215,8 @@ 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.
 
 ## Feedback Intake

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/lib/bootstrap-utils.mjs

@@ -120,6 +120,7 @@ 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:test': run('test/self-test'),
   };
 }

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

@@ -139,6 +139,7 @@ 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:test']).toBe('ops-agent test/self-test');
   });
 });

package/bin/ops-agent.mjs

@@ -33,6 +33,7 @@ const COMMANDS = new Map([
   ['learning-audit', 'learning-loop.mjs'],
   ['learning-report', 'learning-loop.mjs'],
   ['learning-closeout', 'learning-loop.mjs'],
+  ['closeout', 'closeout.mjs'],
   ['test/self-test', null],
 ]);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@besales/ops-framework",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "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]`