@besales/ops-framework 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 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.
+- Added deterministic Check preflight to skip external checker calls when manifest/context quality gates already block Human Gate.
+- Changed Check context policy to standard-first with strict escalation only when needed.
+- Added Check timing telemetry in `task-manifest.json`.
+
 ## 0.1.0
 
 - Created the first local shared Ops Framework package boundary.

package/README.md

@@ -49,16 +49,19 @@ The recommended setup is:
 corepack yarn dlx @besales/ops-framework@latest init --project-name ExampleProject --install-scripts
 ```
 
-This creates the project-owned `ops/**` structure, including `ops/project.ops.yaml`, task roots, cache, memory files and project-local agent config. With `--install-scripts`, it also writes package-manager scripts that call the pinned framework package through `corepack yarn dlx`; it does not add the framework as a dependency, so production installs do not need access to a local framework checkout.
+This creates the project-owned `ops/**` structure, including `ops/project.ops.yaml`, task roots, cache, memory files and project-local agent config. With `--install-scripts`, it also writes package-manager scripts that call the installed `ops-agent` bin and pins the framework package in `devDependencies`.
 
 The generated scripts look like:
 
 ```json
 {
   "scripts": {
-    "ops": "corepack yarn dlx @besales/ops-framework@0.1.0",
-    "agent:run-check": "corepack yarn dlx @besales/ops-framework@0.1.0 run-check",
-    "agent:run-verify": "corepack yarn dlx @besales/ops-framework@0.1.0 run-verify"
+    "ops": "ops-agent",
+    "agent:run-check": "ops-agent run-check",
+    "agent:run-verify": "ops-agent run-verify"
+  },
+  "devDependencies": {
+    "@besales/ops-framework": "0.1.0"
   }
 }
 ```
@@ -119,13 +122,13 @@ The framework blocks obvious inefficiency early, but speculative or broad optimi
 From a project root, run commands through the package entry point:
 
 ```bash
-corepack yarn dlx @besales/ops-framework@0.1.0 init --project-name ExampleProject --install-scripts
-corepack yarn dlx @besales/ops-framework@0.1.0 new-task TASK-001-example --title "Example task"
-corepack yarn dlx @besales/ops-framework@0.1.0 manifest TASK-001-example
-corepack yarn dlx @besales/ops-framework@0.1.0 preflight TASK-001-example --target execute
-corepack yarn dlx @besales/ops-framework@0.1.0 build-check-context TASK-001-example
-corepack yarn dlx @besales/ops-framework@0.1.0 run-check TASK-001-example
-corepack yarn dlx @besales/ops-framework@0.1.0 run-verify TASK-001-example
+ops-agent init --project-name ExampleProject --install-scripts
+ops-agent new-task TASK-001-example --title "Example task"
+ops-agent manifest TASK-001-example
+ops-agent preflight TASK-001-example --target execute
+ops-agent build-check-context TASK-001-example
+ops-agent run-check TASK-001-example
+ops-agent run-verify TASK-001-example
 ```
 
 When installed as a package, the intended command is:
@@ -175,6 +178,7 @@ Do not commit that `file:` dependency to production projects. It is only for pac
 - `update-memory`
 - `learning-audit`
 - `learning-report`
+- `learning-closeout`
 - `test/self-test`
 
 ## Learning Loop
@@ -198,6 +202,7 @@ 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
 ```
 
 `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.
@@ -206,6 +211,8 @@ 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.
+
 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/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

@@ -93,9 +93,9 @@ export function buildFrameworkPackageSpec({ frameworkPackage = null, frameworkVe
 }
 
 export function buildOpsScripts(packageSpec) {
-  const run = (command) => `corepack yarn dlx ${packageSpec} ${command}`;
+  const run = (command) => `ops-agent ${command}`;
   return {
-    ops: `corepack yarn dlx ${packageSpec}`,
+    ops: 'ops-agent',
     'agent:build-check-context': run('build-check-context'),
     'agent:validate-check-artifacts': run('validate-check-artifacts'),
     'agent:manifest': run('manifest'),
@@ -119,6 +119,7 @@ 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:test': run('test/self-test'),
   };
 }
@@ -139,10 +140,30 @@ function upsertPackageScripts({ packageJsonPath, packageSpec, changes }) {
     ...(packageJson.scripts || {}),
     ...buildOpsScripts(packageSpec),
   };
+  const dependency = buildFrameworkPackageDependency(packageSpec);
+  packageJson.devDependencies = {
+    ...(packageJson.devDependencies || {}),
+    [dependency.name]: dependency.version,
+  };
   fs.writeFileSync(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`);
   changes.push({ path: packageJsonPath, kind: 'file', status: 'overwritten' });
 }
 
+function buildFrameworkPackageDependency(packageSpec) {
+  const spec = String(packageSpec || '@besales/ops-framework').trim();
+  const atIndex = spec.startsWith('@') ? spec.indexOf('@', 1) : spec.indexOf('@');
+  if (atIndex > 0) {
+    return {
+      name: spec.slice(0, atIndex),
+      version: spec.slice(atIndex + 1) || 'latest',
+    };
+  }
+  return {
+    name: spec,
+    version: 'latest',
+  };
+}
+
 export function createTask({
   projectRoot = process.cwd(),
   taskId,

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

@@ -56,7 +56,7 @@ describe('bootstrap utilities', () => {
     expect(() => assertPortableGeneratedConfig({ projectConfigContent, agentsConfigContent })).not.toThrow();
   });
 
-  it('can install dlx-based package scripts without adding package dependencies', () => {
+  it('can install local ops-agent scripts with a pinned package dependency', () => {
     const root = makeTempProject();
     fs.writeFileSync(path.join(root, 'package.json'), `${JSON.stringify({
       name: 'fixture-project',
@@ -79,10 +79,10 @@ describe('bootstrap utilities', () => {
 
     const packageJson = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
     expect(packageJson.scripts.test).toBe('echo ok');
-    expect(packageJson.scripts.ops).toBe('corepack yarn dlx @besales/ops-framework@0.1.0');
-    expect(packageJson.scripts['agent:run-verify']).toBe('corepack yarn dlx @besales/ops-framework@0.1.0 run-verify');
+    expect(packageJson.scripts.ops).toBe('ops-agent');
+    expect(packageJson.scripts['agent:run-verify']).toBe('ops-agent run-verify');
     expect(packageJson.dependencies.leftpad).toBe('1.0.0');
-    expect(packageJson.devDependencies?.['@besales/ops-framework']).toBeUndefined();
+    expect(packageJson.devDependencies?.['@besales/ops-framework']).toBe('0.1.0');
   });
 
   it('creates a minimal task artifact set', () => {
@@ -136,9 +136,10 @@ describe('buildOpsScripts', () => {
   it('generates the standard project script surface', () => {
     const scripts = buildOpsScripts('@besales/ops-framework@0.1.0');
 
-    expect(scripts.ops).toBe('corepack yarn dlx @besales/ops-framework@0.1.0');
-    expect(scripts['agent:quality-gates']).toBe('corepack yarn dlx @besales/ops-framework@0.1.0 quality-gates');
-    expect(scripts['agent:test']).toBe('corepack yarn dlx @besales/ops-framework@0.1.0 test/self-test');
+    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:test']).toBe('ops-agent test/self-test');
   });
 });
 

package/bin/lib/llm-input-pack-utils.mjs

@@ -23,13 +23,6 @@ const MEMORY_MAX_CHARS = {
   strict: Infinity,
 };
 
-const STRICT_TRIGGER_PATTERNS = [
-  'auth-security',
-  'prisma-schema',
-  'production-runtime',
-  'source-sync-provider',
-];
-
 const CHECK_RELEVANT_SECTIONS = [
   'цель',
   'goal',
@@ -157,9 +150,7 @@ export function resolveLlmContextMode({ requestedMode, riskTriggers = [] } = {})
   if (requested) {
     return requested;
   }
-  return riskTriggers.some((trigger) => STRICT_TRIGGER_PATTERNS.includes(trigger))
-    ? 'strict'
-    : 'standard';
+  return 'standard';
 }
 
 export function normalizeLlmContextMode(value) {

package/bin/lib/llm-input-pack-utils.test.mjs

@@ -202,9 +202,9 @@ describe('llm input pack utilities', () => {
     expect(pack.estimatedTokens).toBeGreaterThan(Math.ceil(value.length / 2.3));
   });
 
-  it('defaults high-risk production/source-sync tasks to strict context', () => {
-    expect(resolveLlmContextMode({ riskTriggers: ['production-runtime'] })).toBe('strict');
-    expect(resolveLlmContextMode({ riskTriggers: ['source-sync-provider'] })).toBe('strict');
+  it('defaults to standard context and escalates only after context_insufficient', () => {
+    expect(resolveLlmContextMode({ riskTriggers: ['production-runtime'] })).toBe('standard');
+    expect(resolveLlmContextMode({ riskTriggers: ['source-sync-provider'] })).toBe('standard');
     expect(resolveLlmContextMode({ riskTriggers: ['panel-ui'] })).toBe('standard');
     expect(resolveLlmContextMode({ requestedMode: 'fast', riskTriggers: ['production-runtime'] })).toBe('fast');
   });

package/bin/lib/task-manifest-utils.mjs

@@ -234,7 +234,15 @@ export function writeTaskManifest(taskDir, manifest) {
   fs.writeFileSync(path.join(taskDir, TASK_MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`);
 }
 
-export function recordLlmInputUsage({ taskDir, stage, packMeta, attempts = [], rerunCount = 0, now = new Date().toISOString() }) {
+export function recordLlmInputUsage({
+  taskDir,
+  stage,
+  packMeta,
+  attempts = [],
+  rerunCount = 0,
+  now = new Date().toISOString(),
+  timing = null,
+}) {
   const existing = readExistingManifest(taskDir);
   if (!existing) {
     return null;
@@ -263,6 +271,7 @@ export function recordLlmInputUsage({ taskDir, stage, packMeta, attempts = [], r
         rerunCount,
         attempts: normalizedAttempts,
         cumulativeEstimatedTokens: normalizedAttempts.reduce((sum, attempt) => sum + (attempt.estimatedTokens || 0), 0),
+        timing: timing || undefined,
         updatedAt: now,
       },
     },

package/bin/ops-agent.mjs

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

package/bin/run-check.mjs

@@ -24,6 +24,7 @@ import {
   resolveConfigValue,
   resolveTaskDir,
   sha256Json,
+  updateStatus,
   writeTaskFile,
 } from './lib/check-context-utils.mjs';
 import {
@@ -38,7 +39,12 @@ import {
   resolveLlmContextMode,
   summarizePackForConsole,
 } from './lib/llm-input-pack-utils.mjs';
-import { recordLlmInputUsage } from './lib/task-manifest-utils.mjs';
+import {
+  buildTaskManifest,
+  recordLlmInputUsage,
+  validateManifest,
+  writeTaskManifest,
+} from './lib/task-manifest-utils.mjs';
 
 function main() {
   runMain().catch((error) => {
@@ -59,8 +65,25 @@ async function runMain() {
   const dryRun = getFlag(args, 'dry-run', false) === true;
   const noCache = getFlag(args, 'no-cache', false) === true;
   const checkerConfig = resolveCheckerConfig(args);
+  const runStartedAt = new Date();
 
-  const checkContext = ensureFreshCheckContext(taskDir, taskId);
+  let checkContext = ensureFreshCheckContext(taskDir, taskId);
+  const deterministicPrecheck = syncManifestAndStatusBeforeCheck({ taskDir, taskId, checkContext });
+  checkContext = deterministicPrecheck.checkContext;
+  if (!deterministicPrecheck.ok) {
+    writeDeterministicPrecheckReturn({
+      taskDir,
+      taskId,
+      checkContext,
+      checkerConfig,
+      issues: deterministicPrecheck.issues,
+      startedAt: runStartedAt,
+    });
+    runValidator(taskArg);
+    console.log(`Checker preflight blocked ${taskId}: return_to_plan`);
+    console.log(`- deterministicIssues: ${deterministicPrecheck.issues.length}`);
+    return;
+  }
   const initialContextMode = resolveLlmContextMode({
     requestedMode: getFlag(args, 'context-mode') || getFlag(args, 'llm-context-mode'),
     riskTriggers: checkContext.riskTriggers,
@@ -152,6 +175,7 @@ async function runMain() {
         packMeta: promptPayload.pack.meta,
         attempts: llmInputAttempts,
         rerunCount,
+        timing: buildTiming(runStartedAt),
       });
       runValidator(taskArg);
       console.log(`Checker blocked for ${taskId}: strict context pack over cap`);
@@ -166,6 +190,7 @@ async function runMain() {
         packMeta: promptPayload.pack.meta,
         attempts: llmInputAttempts,
         rerunCount,
+        timing: buildTiming(runStartedAt),
       });
       console.log(`Checker cache hit for ${taskId}: ${cacheKeySha}`);
       return;
@@ -197,6 +222,7 @@ async function runMain() {
         packMeta: promptPayload.pack.meta,
         attempts: llmInputAttempts,
         rerunCount,
+        timing: buildTiming(runStartedAt),
       });
       runValidator(taskArg);
       throw new Error(`Checker provider failed with ${failureReason}: ${error.message}`);
@@ -229,6 +255,7 @@ async function runMain() {
     packMeta: promptPayload.pack.meta,
     attempts: llmInputAttempts,
     rerunCount,
+    timing: buildTiming(runStartedAt),
   });
   runValidator(taskArg);
   console.log(`Checker run completed for ${taskId}: ${providerOutput.checkResultJson?.verdict}`);
@@ -247,6 +274,142 @@ function buildAttemptRecord(packMeta, outcome) {
   };
 }
 
+function buildTiming(startedAt, completedAt = new Date()) {
+  return {
+    startedAt: startedAt.toISOString(),
+    completedAt: completedAt.toISOString(),
+    durationMs: Math.max(0, completedAt.getTime() - startedAt.getTime()),
+  };
+}
+
+function syncManifestAndStatusBeforeCheck({ taskDir, taskId, checkContext }) {
+  updateStatus(taskDir, {
+    planSha: `\`${checkContext.planSha}\``,
+    memorySha: `\`${checkContext.memorySha}\``,
+    checkResult: '- `check.result.json`: pending_current_check',
+    supervisorAction: 'Synchronized manifest/status before Check.',
+    nextStep: 'Run Check or fix deterministic plan quality gates before Human Gate.',
+  });
+
+  const syncedCheckContext = ensureFreshCheckContext(taskDir, taskId);
+  const manifest = buildTaskManifest({ taskDir });
+  writeTaskManifest(taskDir, manifest);
+
+  const issues = validateManifest(manifest).map((message) => ({
+    category: 'manifest_validation',
+    message,
+  }));
+  if (!manifest.context.checkContextCurrent) {
+    issues.push({
+      category: 'stale_check_context',
+      message: 'check-context.json/checker-context-pack.md is stale after synchronization.',
+    });
+  }
+  for (const signal of manifest.qualitySignals || []) {
+    issues.push({
+      category: 'plan_quality_gate',
+      message: signal,
+    });
+  }
+
+  return {
+    ok: issues.length === 0,
+    manifest,
+    issues,
+    checkContext: syncedCheckContext,
+  };
+}
+
+function writeDeterministicPrecheckReturn({
+  taskDir,
+  taskId,
+  checkContext,
+  checkerConfig,
+  issues,
+  startedAt,
+}) {
+  const findings = issues.map((issue, index) => ({
+    id: `F-${String(index + 1).padStart(3, '0')}`,
+    severity: 'blocking',
+    claimCategory: issue.category === 'plan_quality_gate' ? 'risk_unaddressed' : 'missing_evidence',
+    claim: issue.message,
+    evidenceRefs: [
+      {
+        type: 'file',
+        ref: issue.category === 'plan_quality_gate' ? 'plan.md' : 'task-manifest.json',
+      },
+    ],
+    affectedPlanSections: ['Plan/Check'],
+    expectedCorrection: expectedCorrectionForPrecheckIssue(issue),
+  }));
+  const result = {
+    taskId,
+    stage: 'Check',
+    checkerProvider: 'deterministic-precheck',
+    checkerModel: 'none',
+    planSha: checkContext.planSha,
+    memorySha: checkContext.memorySha,
+    riskProfile: checkContext.riskProfile,
+    verdict: 'return_to_plan',
+    failureReason: null,
+    blockingFindings: findings.length,
+    nonBlockingFindings: 0,
+    humanQuestions: 0,
+    findings,
+    readyForHumanGate: false,
+    createdAt: new Date().toISOString(),
+  };
+  const markdown = [
+    '# Check',
+    '',
+    '## итоговая оценка',
+    '',
+    '`return_to_plan` from deterministic pre-check.',
+    '',
+    'External checker was not invoked because machine-readable plan/context gates already found blocking issues.',
+    '',
+    '## structured findings',
+    '',
+    '| ID | Severity | Category | Claim | Expected correction |',
+    '| --- | --- | --- | --- | --- |',
+    ...findings.map((finding) => `| ${finding.id} | ${finding.severity} | ${finding.claimCategory} | ${escapeTableCell(finding.claim)} | ${escapeTableCell(finding.expectedCorrection)} |`),
+    '',
+    '## рекомендация supervisor',
+    '',
+    '`return_to_plan`',
+    '',
+    '## Timing',
+    '',
+    `- Duration: ${buildTiming(startedAt).durationMs}ms`,
+  ].join('\n');
+
+  writeTaskFile(taskDir, 'check.md', markdown);
+  writeTaskFile(taskDir, 'check.result.json', JSON.stringify(result, null, 2));
+  updateStatus(taskDir, {
+    checkVerdict: '`return_to_plan`',
+    checkResult: '- `check.result.json`: current',
+    supervisorAction: 'Deterministic Check preflight blocked external checker invocation.',
+    nextStep: 'Fix deterministic Check findings, then rerun Check.',
+    humanApproval: 'no',
+  });
+  ensureFreshCheckContext(taskDir, taskId);
+  appendOrchestrationLog(taskDir, `deterministic Check preflight returned return_to_plan; findings=${findings.length}; external checker skipped`);
+}
+
+function expectedCorrectionForPrecheckIssue(issue) {
+  if (issue.category === 'plan_quality_gate') {
+    return 'Update plan.md so deterministic quality gates are complete before external Check.';
+  }
+  if (issue.category === 'stale_check_context') {
+    return 'Regenerate check context and task manifest before rerunning Check.';
+  }
+  return 'Fix task-manifest/check-context consistency before external Check.';
+}
+
+function escapeTableCell(value) {
+  return String(value || '').replace(/\|/g, '\\|').replace(/\n/g, ' ').trim();
+}
+
 function buildCheckerCacheKey({
   taskId,
   checkContext,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@besales/ops-framework",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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 запускает `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 записаны.
 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,11 @@
 
 ## Learning Loop Audit
 
+- `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]`