@besales/ops-framework 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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.
+- Expanded `learning-review.md` into per-learning approval cards with summary, target, source, reason, proposed change, scope, confidence, risk and decision.
+- Preserved existing pending learning index entries when refreshing task-specific learning candidates.
+- Added closeout guard coverage for `learning-closeout.md`, `learning-index.json`, `learning-review.md` and `learning-report.md`.
+- Added generated project script support for `agent:learning-closeout`.
+
 ## 0.1.4
 
 - Switched generated project scripts from repeated `yarn dlx` execution to installed `ops-agent` package scripts.

package/README.md

@@ -178,6 +178,8 @@ Do not commit that `file:` dependency to production projects. It is only for pac
 - `update-memory`
 - `learning-audit`
 - `learning-report`
+- `learning-closeout`
+- `closeout`
 - `test/self-test`
 
 ## Learning Loop
@@ -201,6 +203,8 @@ ops-agent learning-review
 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.
@@ -209,6 +213,10 @@ ops-agent learning-report
 
 `learning-report` writes `ops/agent-pipeline/memory/learning-report.md`. Show the review pack before approval and the report during closeout so the human can see what the framework learned, what is still pending, and which approved entries were written to project memory or project playbooks.
 
+`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/guard-task.mjs

@@ -33,6 +33,7 @@ function main() {
     validateHumanGateSummary(taskDir, errors);
     validateFeedback(taskDir, errors);
     validateExecutionEvidence(taskDir, errors);
+    validateLearningCloseout(taskDir, errors);
     validateStatusSync(taskDir, errors);
 
     if (errors.length > 0) {
@@ -49,6 +50,30 @@ function main() {
   }
 }
 
+function validateLearningCloseout(taskDir, errors) {
+  const stage = readStatusStage(taskDir);
+  const stagesRequiringLearningCloseout = new Set([
+    'Closeout Audit',
+    'Human Closeout Gate',
+    'Closed',
+    'Accepted',
+    'Ready To Pause',
+  ]);
+  if (!stagesRequiringLearningCloseout.has(stage)) {
+    return;
+  }
+  const taskLearningCloseoutPath = path.join(taskDir, 'learning-closeout.md');
+  if (!fs.existsSync(taskLearningCloseoutPath)) {
+    errors.push('learning-closeout.md is missing before closeout. Run ops-agent learning-closeout <TASK> and show learning-review.md to human.');
+  }
+  for (const fileName of ['learning-index.json', 'learning-review.md', 'learning-report.md']) {
+    const filePath = path.join(projectContext.memoryRoot, fileName);
+    if (!fs.existsSync(filePath)) {
+      errors.push(`${fileName} is missing before closeout. Run ops-agent learning-closeout <TASK>.`);
+    }
+  }
+}
+
 function validateHumanGateSummary(taskDir, errors) {
   const stage = readStatusStage(taskDir);
   if (stage !== 'Human Gate') {

package/bin/learning-loop.mjs

@@ -3,9 +3,12 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
+  appendOrchestrationLog,
   getFlag,
   parseCliArgs,
   projectContext,
+  resolveTaskDir,
+  updateStatus,
 } from './lib/check-context-utils.mjs';
 
 export const CANDIDATES_FILE = 'learning-candidates.md';
@@ -13,6 +16,7 @@ export const INDEX_FILE = 'learning-index.json';
 export const APPROVED_FILE = 'approved-learning.md';
 export const REPORT_FILE = 'learning-report.md';
 export const REVIEW_FILE = 'learning-review.md';
+export const CLOSEOUT_FILE = 'learning-closeout.md';
 const PROJECT_PLAYBOOK_TARGET_PREFIX = 'project-playbook/';
 const MEMORY_TARGET_PREFIX = 'memory/';
 
@@ -44,15 +48,22 @@ export function main() {
       writeLearningReport();
       return;
     }
-    fail('Usage: ops-agent memory-candidates|learning-index|learning-review|update-memory|learning-audit|learning-report');
+    if (command === 'learning-closeout') {
+      writeLearningCloseout({
+        taskArg: args.positional[0] || getFlag(args, 'task'),
+        limit: Number(getFlag(args, 'limit', 20)),
+      });
+      return;
+    }
+    fail('Usage: ops-agent memory-candidates|learning-index|learning-review|update-memory|learning-audit|learning-report|learning-closeout');
   } catch (error) {
     fail(error.message);
   }
 }
 
-export function writeMemoryCandidates({ limit }) {
+export function writeMemoryCandidates({ limit, taskDir = null } = {}) {
   ensureMemoryRoot();
-  const candidates = collectLearningCandidates({ limit });
+  const candidates = collectLearningCandidates({ limit, taskDir });
   const content = [
     '# Learning Candidates',
     '',
@@ -81,32 +92,21 @@ export function writeMemoryCandidates({ limit }) {
   fs.writeFileSync(path.join(projectContext.memoryRoot, CANDIDATES_FILE), content.endsWith('\n') ? content : `${content}\n`);
   console.log(`Learning candidates written: ${path.join(projectContext.memoryRoot, CANDIDATES_FILE)}`);
   console.log(`- candidates: ${candidates.length}`);
+  return candidates;
 }
 
-export function writeLearningIndex() {
+export function writeLearningIndex({ preserveExisting = true } = {}) {
   ensureMemoryRoot();
   const candidatesPath = path.join(projectContext.memoryRoot, CANDIDATES_FILE);
   if (!fs.existsSync(candidatesPath)) {
     throw new Error(`Missing ${CANDIDATES_FILE}. Run ops-agent memory-candidates first.`);
   }
-  const entries = parseLearningCandidatesMarkdown(fs.readFileSync(candidatesPath, 'utf8'))
-    .map((candidate) => ({
-      id: candidate.id,
-      source: candidate.source,
-      sourceArtifact: candidate.sourceArtifact,
-      reasonHash: candidate.reasonHash,
-      kind: candidate.kind,
-      learningLayer: candidate.learningLayer,
-      confidence: candidate.confidence,
-      problem: candidate.problem,
-      lesson: candidate.lesson,
-      repeatRisk: candidate.repeatRisk,
-      candidate: candidate.text,
-      proposedWording: candidate.proposedWording,
-      decision: 'pending',
-      target: candidate.suggestedTarget,
-      notes: '',
-    }));
+  const existingEntries = preserveExisting ? readExistingLearningEntries() : [];
+  const entries = mergeLearningIndexEntries({
+    candidateEntries: parseLearningCandidatesMarkdown(fs.readFileSync(candidatesPath, 'utf8'))
+      .map((candidate) => buildLearningIndexEntry(candidate, existingEntries)),
+    existingEntries,
+  });
   const index = {
     schemaVersion: 1,
     generatedAt: new Date().toISOString(),
@@ -116,6 +116,7 @@ export function writeLearningIndex() {
   fs.writeFileSync(path.join(projectContext.memoryRoot, INDEX_FILE), `${JSON.stringify(index, null, 2)}\n`);
   console.log(`Learning index written: ${path.join(projectContext.memoryRoot, INDEX_FILE)}`);
   console.log(`- entries: ${entries.length}`);
+  return index;
 }
 
 export function writeLearningReview({ memoryRoot = projectContext.memoryRoot, projectRoot = projectContext.projectRoot } = {}) {
@@ -173,6 +174,45 @@ export function writeLearningReview({ memoryRoot = projectContext.memoryRoot, pr
   fs.writeFileSync(path.join(memoryRoot, REVIEW_FILE), content.endsWith('\n') ? content : `${content}\n`);
   console.log(`Learning review written: ${path.join(memoryRoot, REVIEW_FILE)}`);
   console.log(`- pending: ${pending.length}`);
+  return {
+    entries,
+    pending,
+    reviewPath: path.join(memoryRoot, REVIEW_FILE),
+  };
+}
+
+export function writeLearningCloseout({ taskArg, limit = 20 } = {}) {
+  if (!taskArg) {
+    throw new Error('Usage: ops-agent learning-closeout <TASK-id-or-task-path> [--limit 20]');
+  }
+  const taskDir = resolveTaskDir(taskArg);
+  const taskId = path.basename(taskDir);
+  const candidates = writeMemoryCandidates({ limit, taskDir });
+  const index = writeLearningIndex({ preserveExisting: true });
+  const review = writeLearningReview();
+  writeLearningReport();
+  const closeoutPath = writeLearningCloseoutSummary({
+    taskDir,
+    taskId,
+    candidates,
+    entries: index.entries || [],
+    reviewPath: review.reviewPath,
+  });
+  updateStatus(taskDir, {
+    stage: 'Retrospective / Learning Review',
+    supervisorAction: 'Generated learning closeout candidates, review pack and report.',
+    nextStep: 'Show learning-review.md to human; set each learning-index.json decision to promote, defer, reject or rewrite; then run update-memory --apply-approved and learning-report.',
+    humanApproval: 'yes',
+  });
+  appendOrchestrationLog(taskDir, `learning closeout generated; candidates=${candidates.length}; review=${relativeProjectPath(review.reviewPath)}; summary=${path.basename(closeoutPath)}`);
+  console.log(`Learning closeout ready for ${taskId}`);
+  console.log(`- candidates: ${candidates.length}`);
+  console.log(`- review: ${relativeProjectPath(review.reviewPath)}`);
+  console.log(`- report: ${relativeProjectPath(path.join(projectContext.memoryRoot, REPORT_FILE))}`);
+  console.log(`- task summary: ${relativeProjectPath(closeoutPath)}`);
+  for (const line of renderConsoleLearningCards(index.entries || [])) {
+    console.log(line);
+  }
 }
 
 export function updateMemory({ applyApproved }) {
@@ -279,20 +319,26 @@ export function writeLearningReport({ memoryRoot = projectContext.memoryRoot, pr
   console.log(`Learning report written: ${path.join(memoryRoot, REPORT_FILE)}`);
 }
 
-export function collectLearningCandidates({ limit, tasksRoot = projectContext.tasksRoot } = {}) {
+export function collectLearningCandidates({ limit, tasksRoot = projectContext.tasksRoot, taskDir = null } = {}) {
   const candidates = [];
   const seen = new Set();
-  if (!fs.existsSync(tasksRoot)) {
+  const taskDirs = taskDir
+    ? [taskDir]
+    : fs.existsSync(tasksRoot)
+      ? fs.readdirSync(tasksRoot)
+        .filter((name) => name.startsWith('TASK-'))
+        .sort()
+        .reverse()
+        .map((name) => path.join(tasksRoot, name))
+      : [];
+  if (!taskDirs.length) {
     return candidates;
   }
-  const taskDirs = fs.readdirSync(tasksRoot)
-    .filter((name) => name.startsWith('TASK-'))
-    .sort()
-    .reverse();
-  for (const taskName of taskDirs) {
+  for (const taskPath of taskDirs) {
+    const taskName = path.basename(taskPath);
     for (const fileName of ['retrospective.md', 'feedback.md', 'execution-feedback.md', 'verify.md', 'check.md']) {
       const sourceArtifact = `${taskName}/${fileName}`;
-      const filePath = path.join(tasksRoot, taskName, fileName);
+      const filePath = path.join(taskPath, fileName);
       if (!fs.existsSync(filePath)) {
         continue;
       }
@@ -510,6 +556,78 @@ function suggestLearningTarget(text) {
   return `${MEMORY_TARGET_PREFIX}${APPROVED_FILE}`;
 }
 
+function buildLearningIndexEntry(candidate, existingEntries) {
+  const previous = existingEntries.find((entry) => entry.reasonHash === candidate.reasonHash)
+    || existingEntries.find((entry) => entry.id === candidate.id);
+  return {
+    id: previous?.id || candidate.id,
+    source: candidate.source,
+    sourceArtifact: candidate.sourceArtifact,
+    reasonHash: candidate.reasonHash,
+    kind: candidate.kind,
+    learningLayer: candidate.learningLayer,
+    summary: candidate.lesson,
+    confidence: candidate.confidence,
+    problem: candidate.problem,
+    lesson: candidate.lesson,
+    repeatRisk: candidate.repeatRisk,
+    scope: scopeForTarget(previous?.target || candidate.suggestedTarget),
+    risk: riskForCandidate(candidate),
+    candidate: candidate.text,
+    proposedChange: previous?.proposedChange || candidate.proposedWording,
+    proposedWording: previous?.proposedWording || candidate.proposedWording,
+    decision: previous?.decision || 'pending',
+    target: previous?.target || candidate.suggestedTarget,
+    notes: previous?.notes || '',
+  };
+}
+
+function mergeLearningIndexEntries({ candidateEntries, existingEntries }) {
+  const seen = new Set(candidateEntries.map((entry) => entry.reasonHash || entry.id));
+  const preserved = existingEntries.filter((entry) => {
+    const key = entry.reasonHash || entry.id;
+    if (!key || seen.has(key)) {
+      return false;
+    }
+    seen.add(key);
+    return true;
+  });
+  return [...candidateEntries, ...preserved];
+}
+
+function readExistingLearningEntries() {
+  const indexPath = path.join(projectContext.memoryRoot, INDEX_FILE);
+  if (!fs.existsSync(indexPath)) {
+    return [];
+  }
+  try {
+    const index = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+    return Array.isArray(index.entries) ? index.entries : [];
+  } catch {
+    return [];
+  }
+}
+
+function scopeForTarget(target) {
+  if (target?.startsWith('shared-playbook/')) {
+    return 'cross-project candidate; manual shared-framework review required before promotion.';
+  }
+  if (target?.startsWith(PROJECT_PLAYBOOK_TARGET_PREFIX)) {
+    return 'current project playbook overlay; project-specific procedures, routes, commands or runtime quirks.';
+  }
+  return 'current project memory; durable architecture, product or process knowledge.';
+}
+
+function riskForCandidate(candidate) {
+  if (candidate.suggestedTarget?.startsWith('shared-playbook/')) {
+    return 'High if promoted without validation: a task-specific observation could become cross-project guidance.';
+  }
+  if (candidate.confidence === 'low') {
+    return 'Medium: wording may be too vague or one-off; prefer defer/rewrite unless confirmed.';
+  }
+  return 'Low if reviewed: promotion is human-approved and source-linked.';
+}
+
 function readMarkdownField(body, fieldName) {
   const pattern = new RegExp(`^- ${escapeRegExp(fieldName)}: (.*)$`, 'm');
   const match = pattern.exec(body);
@@ -622,24 +740,66 @@ function renderReviewEntries(entries) {
     return ['- None.'];
   }
   return entries.flatMap((entry) => [
-    `### ${entry.id}`,
+    `### ${entry.id}: ${entry.summary || entry.lesson || entry.candidate || 'Learning candidate'}`,
     '',
-    `- Source: \`${entry.sourceArtifact || entry.source}\``,
-    `- Current decision: \`${entry.decision || 'pending'}\``,
+    `- Summary: ${entry.summary || entry.lesson || 'Not specified.'}`,
     `- Suggested target: \`${entry.target || 'memory/approved-learning.md'}\``,
-    `- Kind: \`${entry.kind || 'unknown'}\``,
-    `- Learning layer: \`${entry.learningLayer || learningLayerForKind(entry.kind)}\``,
+    `- Source artifact: \`${entry.sourceArtifact || entry.source}\``,
+    `- Reason hash: \`${entry.reasonHash || 'missing'}\``,
+    `- Reason: ${entry.problem || 'Not specified.'}`,
+    `- Proposed change: ${entry.proposedChange || entry.proposedWording || entry.candidate}`,
+    `- Scope: ${entry.scope || scopeForTarget(entry.target)}`,
     `- Confidence: \`${entry.confidence || 'unknown'}\``,
-    `- Repeat risk: ${entry.repeatRisk || 'Not specified.'}`,
-    `- Problem: ${entry.problem || 'Not specified.'}`,
-    `- Lesson: ${entry.lesson || 'Not specified.'}`,
-    `- Proposed wording: ${entry.proposedWording || entry.candidate}`,
+    `- Risk if promoted: ${entry.risk || 'Not specified.'}`,
+    `- Repeat risk if ignored: ${entry.repeatRisk || 'Not specified.'}`,
+    `- Current decision: \`${entry.decision || 'pending'}\``,
+    `- Human notes: ${entry.notes || '(empty)'}`,
     '',
     'Decision to set in `learning-index.json`: `promote | defer | reject | rewrite`',
     '',
   ]);
 }
 
+function renderConsoleLearningCards(entries) {
+  const pending = entries.filter((entry) => !entry.decision || entry.decision === 'pending');
+  if (!pending.length) {
+    return ['- pending learning cards: none'];
+  }
+  return [
+    '- pending learning cards:',
+    ...pending.map((entry) => `  - ${entry.id}: ${entry.summary || entry.lesson || entry.candidate} -> ${entry.target || 'memory/approved-learning.md'}`),
+  ];
+}
+
+function writeLearningCloseoutSummary({ taskDir, taskId, candidates, entries, reviewPath }) {
+  const pending = entries.filter((entry) => !entry.decision || entry.decision === 'pending');
+  const content = [
+    '# Learning Closeout',
+    '',
+    `Task: \`${taskId}\``,
+    `Generated at: \`${new Date().toISOString()}\``,
+    '',
+    '## Human Action Required',
+    '',
+    `Review \`${relativeProjectPath(reviewPath)}\` and set every pending entry in \`${relativeProjectPath(path.join(projectContext.memoryRoot, INDEX_FILE))}\` to \`promote\`, \`defer\`, \`reject\` or \`rewrite\`.`,
+    '',
+    '## Summary',
+    '',
+    `- Candidates collected from this task: ${candidates.length}`,
+    `- Pending learning decisions: ${pending.length}`,
+    `- Learning review: \`${relativeProjectPath(reviewPath)}\``,
+    `- Learning report: \`${relativeProjectPath(path.join(projectContext.memoryRoot, REPORT_FILE))}\``,
+    '',
+    '## Pending Cards',
+    '',
+    ...renderReviewEntries(pending),
+    '',
+  ].join('\n');
+  const closeoutPath = path.join(taskDir, CLOSEOUT_FILE);
+  fs.writeFileSync(closeoutPath, content.endsWith('\n') ? content : `${content}\n`);
+  return closeoutPath;
+}
+
 function relativeProjectPath(filePath, projectRoot = projectContext.projectRoot) {
   return path.relative(projectRoot, filePath) || path.basename(filePath);
 }

package/bin/learning-loop.test.mjs

@@ -170,6 +170,29 @@ describe('learning loop', () => {
     const review = fs.readFileSync(path.join(memoryRoot, 'learning-review.md'), 'utf8');
     expect(review).toContain('## Human Approval Contract');
     expect(review).toContain('Decision to set in `learning-index.json`: `promote | defer | reject | rewrite`');
+    expect(review).toContain('### LC-001: Capture feedback at every stage.');
+    expect(review).toContain('- Summary: Capture feedback at every stage.');
+    expect(review).toContain('- Source artifact: `TASK-001/feedback.md`');
+    expect(review).toContain('- Reason hash: `missing`');
+    expect(review).toContain('- Proposed change: Project memory note: capture feedback at every stage.');
+    expect(review).toContain('- Scope: current project memory; durable architecture, product or process knowledge.');
+    expect(review).toContain('- Risk if promoted: Not specified.');
     expect(review).toContain('Project memory note: capture feedback at every stage.');
   });
+
+  it('collects closeout candidates from one task when taskDir is provided', () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ops-learning-task-filter-'));
+    const taskA = path.join(root, 'TASK-001-current');
+    const taskB = path.join(root, 'TASK-002-other');
+    fs.mkdirSync(taskA, { recursive: true });
+    fs.mkdirSync(taskB, { recursive: true });
+    fs.writeFileSync(path.join(taskA, 'retrospective.md'), '- UI acceptance playbook should include current route.\n');
+    fs.writeFileSync(path.join(taskB, 'retrospective.md'), '- UI acceptance playbook should include other route.\n');
+
+    const candidates = collectLearningCandidates({ taskDir: taskA, tasksRoot: root, limit: 10 });
+
+    expect(candidates).toHaveLength(1);
+    expect(candidates[0].sourceArtifact).toBe('TASK-001-current/retrospective.md');
+    expect(candidates[0].text).toContain('current route');
+  });
 });

package/bin/lib/bootstrap-utils.mjs

@@ -119,6 +119,8 @@ export function buildOpsScripts(packageSpec) {
     'agent:update-memory': run('update-memory'),
     '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

@@ -138,6 +138,8 @@ 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

@@ -32,6 +32,8 @@ const COMMANDS = new Map([
   ['update-memory', 'learning-loop.mjs'],
   ['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.4",
+  "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 запускает/проверяет `memory-candidates`, `learning-index`, `learning-review`, human decisions, `update-memory --apply-approved` для promoted entries and `learning-report`; human должен видеть, какие lessons предложены, какие отклонены/отложены and куда 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,9 +16,12 @@
 
 ## 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]`
 - `ops-agent learning-review` создал human approval pack и был показан human: `[fill in]`
+- Каждый learning показан human отдельной карточкой с summary/target/source/reason/proposed change/scope/confidence/risk/decision: `[fill in]`
 - `learning-index.json` reviewed human/supervisor: `[fill in]`
 - Promoted to project memory: `[fill in]`
 - Promoted to project playbooks: `[fill in]`