@besales/ops-framework 0.1.27 → 0.1.29

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.29
+
+- Added `precheck-remediation.md` for deterministic Check blocks so all missing plan gates are consolidated into one checklist before another external Check.
+- Included precheck remediation artifacts in Checker and Verifier LLM input packs.
+- Updated Checker/Verifier/Supervisor rules to avoid one-item precheck loops and route minor/tooling issues to notes or human decision when acceptance is covered.
+
+## 0.1.28
+
+- Added Verify reuse guard: a passing `verify.result.json` is reused when `plan.md` and `execution.md` hashes are unchanged, unless `--force` is passed.
+- Updated status after external Verify pass/fail/return verdicts so Supervisor routing does not keep asking for stale Verify reruns.
+- Routed passing Verify results to retrospective/learning closeout instead of repeated verifier loops.
+
 ## 0.1.27
 
 - Updated internal Verify closeout behavior so `status.md` moves to retrospective/learning closeout instead of continuing to ask for external Verify.

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

@@ -199,12 +199,13 @@ export function buildCheckerLlmInputPack({
 }) {
   const selectedMode = normalizeLlmContextMode(mode) || 'standard';
   const artifacts = selectedMode === 'strict'
-    ? readArtifacts(taskDir, ['brief.md', 'research.md', 'plan.md', 'status.md', 'feedback.md', 'execution-feedback.md'], 'full')
+    ? readArtifacts(taskDir, ['brief.md', 'research.md', 'plan.md', 'status.md', 'precheck-remediation.md', 'feedback.md', 'execution-feedback.md'], 'full')
     : {
         'brief.md': compactArtifact(taskDir, 'brief.md', selectedMode, ['goal', 'scope', 'success criteria']),
         'research.md': compactArtifact(taskDir, 'research.md', selectedMode, ['findings', 'evidence', 'repo', 'architecture', 'standards']),
         'plan.md': compactArtifact(taskDir, 'plan.md', selectedMode, CHECK_RELEVANT_SECTIONS),
         'status.md': compactStatus(readTaskFile(taskDir, 'status.md')),
+        'precheck-remediation.md': compactArtifact(taskDir, 'precheck-remediation.md', selectedMode, ['checklist', 'rerun rule', 'purpose']),
         'feedback.md': compactArtifact(taskDir, 'feedback.md', selectedMode, ['feedback event', 'classification', 'supervisor decision']),
       };
 
@@ -325,6 +326,7 @@ export function buildVerifierLlmInputPack({
           checkResult: readOptionalJson(taskDir, 'check.result.json'),
           mode: 'standard',
         }),
+        'precheck-remediation.md': compactArtifact(taskDir, 'precheck-remediation.md', 'standard', ['checklist', 'rerun rule', 'purpose']),
         'check-resolution.md': compactArtifact(taskDir, 'check-resolution.md', 'standard', ['structured resolution', 'root cause', 'resolution']),
         'human-gate-summary.md': truncateMiddle(readTaskFile(taskDir, 'human-gate-summary.md'), 3500),
         'execution.md': readTaskFile(taskDir, 'execution.md'),
@@ -346,6 +348,7 @@ export function buildVerifierLlmInputPack({
           checkResult: readOptionalJson(taskDir, 'check.result.json'),
           mode: selectedMode,
         }),
+        'precheck-remediation.md': compactArtifact(taskDir, 'precheck-remediation.md', selectedMode, ['checklist', 'rerun rule', 'purpose']),
         'check-resolution.md': truncateMiddle(readTaskFile(taskDir, 'check-resolution.md'), charLimitForMode(selectedMode, 1500, 3500)),
         'human-gate-summary.md': truncateMiddle(readTaskFile(taskDir, 'human-gate-summary.md'), charLimitForMode(selectedMode, 1200, 2500)),
         'execution.md': compactArtifact(taskDir, 'execution.md', selectedMode, VERIFY_EXECUTION_SECTIONS),

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

@@ -118,6 +118,42 @@ describe('llm input pack utilities', () => {
     expect(pack.meta.compactedArtifacts).toContain('plan.md');
   });
 
+  it('includes precheck remediation in checker packs when present', () => {
+    const taskDir = createTask();
+    write(taskDir, 'precheck-remediation.md', [
+      '# Precheck Remediation',
+      '',
+      '## Checklist',
+      '',
+      '- [ ] P-001: Optimization Strategy is missing.',
+      '',
+      '## Rerun Rule',
+      '',
+      '- Rerun Check only after every checklist item is addressed.',
+    ].join('\n'));
+
+    const pack = buildCheckerLlmInputPack({
+      taskDir,
+      taskId: 'TASK-999-token-pack',
+      checkerPromptSha: 'sha256:test',
+      cacheKey: { test: true },
+      checkContext: {
+        planSha: 'sha256:plan',
+        memorySha: 'sha256:memory',
+        riskProfile: 'high',
+        riskTriggers: ['source-sync-provider'],
+      },
+      checkEvidence: '# Evidence\n\nok',
+      checkerContextPack: '# Checker Context Pack\n\nok',
+      taskManifest: '{}',
+      projectMemory: [],
+      mode: 'standard',
+    });
+
+    expect(pack.input.taskArtifacts['precheck-remediation.md']).toContain('Optimization Strategy is missing.');
+    expect(pack.input.taskArtifacts['precheck-remediation.md']).toContain('Rerun Check only after every checklist item is addressed.');
+  });
+
   it('stabilizes checker task manifest by excluding volatile check telemetry', () => {
     const taskDir = createTask();
     const pack = buildCheckerLlmInputPack({
@@ -274,6 +310,28 @@ describe('llm input pack utilities', () => {
     expect(pack.input.taskArtifacts['check.md']).toContain('Human question should remain visible.');
   });
 
+  it('includes precheck remediation in verifier packs when present', () => {
+    const taskDir = createTask();
+    write(taskDir, 'precheck-remediation.md', [
+      '# Precheck Remediation',
+      '',
+      '## Checklist',
+      '',
+      '- [ ] P-001: Source Sync / Provider Gate is missing.',
+    ].join('\n'));
+
+    const pack = buildVerifierLlmInputPack({
+      taskDir,
+      taskId: 'TASK-999-token-pack',
+      planSha: 'sha256:plan',
+      executionSha: 'sha256:execution',
+      verifier: { provider: 'test', model: 'test', reasoningEffort: 'none', runId: 'run' },
+      mode: 'standard',
+    });
+
+    expect(pack.input.taskArtifacts['precheck-remediation.md']).toContain('Source Sync / Provider Gate is missing.');
+  });
+
   it('uses a conservative estimate for Cyrillic and JSON-heavy payloads', () => {
     const value = JSON.stringify({
       text: 'Проверка русскоязычного JSON payload с большим количеством кавычек и структурных символов.',

package/bin/run-check.mjs

@@ -462,6 +462,12 @@ function writeDeterministicPrecheckReturn({
     readyForHumanGate: false,
     createdAt: new Date().toISOString(),
   };
+  const remediation = buildPrecheckRemediation({
+    taskId,
+    checkContext,
+    issues,
+    startedAt,
+  });
   const markdown = [
     '# Check',
     '',
@@ -471,6 +477,10 @@ function writeDeterministicPrecheckReturn({
     '',
     'External checker was not invoked because machine-readable plan/context gates already found blocking issues.',
     '',
+    '## Consolidated remediation',
+    '',
+    'Before rerunning Check, close the full checklist in `precheck-remediation.md`. Do not fix one item and immediately rerun Check while other listed items remain open.',
+    '',
     '## structured findings',
     '',
     '| ID | Severity | Category | Claim | Expected correction |',
@@ -488,15 +498,16 @@ function writeDeterministicPrecheckReturn({
 
   writeTaskFile(taskDir, 'check.md', markdown);
   writeTaskFile(taskDir, 'check.result.json', JSON.stringify(result, null, 2));
+  writeTaskFile(taskDir, 'precheck-remediation.md', remediation.markdown);
   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.',
+    nextStep: 'Close every item in `precheck-remediation.md`, update plan/research/status once, then rerun Check.',
     humanApproval: 'no',
   });
   ensureFreshCheckContext(taskDir, taskId);
-  appendOrchestrationLog(taskDir, `deterministic Check preflight returned return_to_plan; findings=${findings.length}; external checker skipped`);
+  appendOrchestrationLog(taskDir, `deterministic Check preflight returned return_to_plan; findings=${findings.length}; remediation=${remediation.issueSetSha}; external checker skipped`);
 }
 
 function expectedCorrectionForPrecheckIssue(issue) {
@@ -509,6 +520,73 @@ function expectedCorrectionForPrecheckIssue(issue) {
   return 'Fix task-manifest/check-context consistency before external Check.';
 }
 
+function buildPrecheckRemediation({
+  taskId,
+  checkContext,
+  issues,
+  startedAt,
+}) {
+  const issueSetSha = sha256Json(issues.map((issue) => ({
+    category: issue.category,
+    message: issue.message,
+  })));
+  const grouped = groupIssuesByCategory(issues);
+  const lines = [
+    '# Precheck Remediation',
+    '',
+    `Task: \`${taskId}\``,
+    `Issue set: \`${issueSetSha}\``,
+    `Plan SHA: \`${checkContext.planSha}\``,
+    `Memory SHA: \`${checkContext.memorySha}\``,
+    `Created at: \`${new Date().toISOString()}\``,
+    `Precheck duration: \`${buildTiming(startedAt).durationMs}ms\``,
+    '',
+    '## Purpose',
+    '',
+    'This artifact consolidates deterministic Check blockers so the plan can be fixed in one focused pass before another external Check.',
+    '',
+    'Do not rerun external Check while any checklist item below is still open. Update `plan.md`, `research.md`, or `status.md` once, then rerun Check after the whole set is addressed.',
+    '',
+    '## Checklist',
+    '',
+  ];
+
+  let index = 1;
+  for (const [category, categoryIssues] of grouped.entries()) {
+    lines.push(`### ${category}`);
+    lines.push('');
+    for (const issue of categoryIssues) {
+      lines.push(`- [ ] P-${String(index).padStart(3, '0')}: ${issue.message}`);
+      lines.push(`  - Expected correction: ${expectedCorrectionForPrecheckIssue(issue)}`);
+      index += 1;
+    }
+    lines.push('');
+  }
+
+  lines.push('## Rerun Rule');
+  lines.push('');
+  lines.push('- Rerun Check only after every checklist item is addressed or explicitly rejected with evidence/human decision.');
+  lines.push('- If the same issue set appears again, consolidate the remaining fixes instead of starting another one-item loop.');
+  lines.push('- If a listed item is not applicable, record the reason in `plan.md` or `status.md` before rerunning Check.');
+  lines.push('');
+
+  return {
+    issueSetSha,
+    markdown: lines.join('\n'),
+  };
+}
+
+function groupIssuesByCategory(issues) {
+  const grouped = new Map();
+  for (const issue of issues) {
+    const category = issue.category || 'unknown';
+    const existing = grouped.get(category) || [];
+    existing.push(issue);
+    grouped.set(category, existing);
+  }
+  return grouped;
+}
+
 function escapeTableCell(value) {
   return String(value || '').replace(/\|/g, '\\|').replace(/\n/g, ' ').trim();
 }

package/bin/run-verify.mjs

@@ -46,6 +46,7 @@ async function runMain() {
   const taskDir = resolveTaskDir(taskArg);
   const taskId = path.basename(taskDir);
   const verifierConfig = resolveVerifierConfig(args);
+  const force = getFlag(args, 'force', false) === true;
   const runStartedAt = new Date();
   appendVerifyTimeline(taskDir, {
     event: 'verify_started',
@@ -85,6 +86,25 @@ async function runMain() {
     return;
   }
 
+  const reusableVerify = readReusableVerifyResult({ taskDir, planSha, executionSha });
+  if (reusableVerify && !force) {
+    updateStatusForVerifyResult(taskDir, reusableVerify, {
+      reused: true,
+      verifierMode: reusableVerify.verificationMode || verifierConfig.mode,
+    });
+    appendVerifyTimeline(taskDir, {
+      event: 'verify_reused',
+      verdict: reusableVerify.verdict,
+      verifierRunId: reusableVerify.verifierRunId || null,
+      timing: buildTiming(runStartedAt),
+    });
+    appendOrchestrationLog(taskDir, `verify result reused; verdict=${reusableVerify.verdict}; plan/execution unchanged; use --force to rerun`);
+    console.log(`Verifier result reused for ${taskId}: ${reusableVerify.verdict}`);
+    console.log('- reason: plan.md and execution.md hashes match existing passing verify.result.json');
+    console.log('- use --force to rerun Verify anyway');
+    return;
+  }
+
   if (verifierConfig.mode === 'internal_supervisor') {
     writeInternalSupervisorVerify({
       taskDir,
@@ -268,6 +288,10 @@ async function runMain() {
 
   writeTaskFile(taskDir, 'verify.md', verifyMarkdown);
   writeTaskFile(taskDir, 'verify.result.json', JSON.stringify(verifyResultJson, null, 2));
+  updateStatusForVerifyResult(taskDir, verifyResultJson, {
+    reused: false,
+    verifierMode: 'external_cli',
+  });
   if (finalPack) {
     recordLlmInputUsage({
       taskDir,
@@ -303,6 +327,85 @@ function buildTiming(startedAt, completedAt = new Date()) {
   };
 }
 
+function readReusableVerifyResult({ taskDir, planSha, executionSha }) {
+  const result = readOptionalJson(taskDir, 'verify.result.json');
+  if (!result || typeof result !== 'object' || Array.isArray(result)) {
+    return null;
+  }
+  if (!['pass', 'pass_with_notes'].includes(String(result.verdict || '').toLowerCase())) {
+    return null;
+  }
+  if (result.planSha !== planSha || result.executionSha !== executionSha) {
+    return null;
+  }
+  if (result.readyForRetrospective !== true) {
+    return null;
+  }
+  return result;
+}
+
+function updateStatusForVerifyResult(taskDir, result, { reused = false, verifierMode = null } = {}) {
+  const verdict = String(result?.verdict || 'unknown').toLowerCase();
+  const mode = verifierMode || result?.verificationMode || 'unknown';
+  const commonResult = [
+    `- \`verify.result.json\`: \`${verdict}\``,
+    `- Verification mode: \`${mode}\``,
+    `- Ready for retrospective: \`${Boolean(result?.readyForRetrospective)}\``,
+    reused ? '- Reused: `true` (plan/execution unchanged)' : null,
+  ].filter(Boolean).join('\n');
+
+  if (['pass', 'pass_with_notes'].includes(verdict)) {
+    updateStatus(taskDir, {
+      stage: 'Verify complete',
+      verifyVerdict: `\`${verdict}\``,
+      verifyResult: commonResult,
+      supervisorAction: reused
+        ? 'Existing passing Verify result reused because plan/execution hashes are unchanged.'
+        : 'Verify completed with sufficient evidence for this slice.',
+      expectedOutcome: 'Retrospective, learning closeout, then task closeout.',
+      humanApproval: 'no',
+      nextStep: 'Run learning closeout / retrospective. Do not rerun Verify unless plan/execution changes or explicit --force/human escalation applies.',
+    });
+    return;
+  }
+
+  if (verdict === 'return_to_execute') {
+    updateStatus(taskDir, {
+      stage: 'Execute',
+      verifyVerdict: '`return_to_execute`',
+      verifyResult: commonResult,
+      supervisorAction: 'Verify returned blocking execution findings.',
+      expectedOutcome: 'Address blocking Verify findings, update execution evidence, then rerun Verify.',
+      humanApproval: 'no',
+      nextStep: 'Return to Execute and fix the blocking Verify findings before another Verify run.',
+    });
+    return;
+  }
+
+  if (verdict === 'return_to_plan') {
+    updateStatus(taskDir, {
+      stage: 'Plan',
+      verifyVerdict: '`return_to_plan`',
+      verifyResult: commonResult,
+      supervisorAction: 'Verify found plan/scope mismatch.',
+      expectedOutcome: 'Revise plan/check artifacts before Execute continues.',
+      humanApproval: 'maybe',
+      nextStep: 'Return to Plan and resolve the Verify findings before Execute continues.',
+    });
+    return;
+  }
+
+  updateStatus(taskDir, {
+    stage: 'Verify',
+    verifyVerdict: `\`${verdict}\``,
+    verifyResult: commonResult,
+    supervisorAction: 'Verify did not produce a passing result.',
+    expectedOutcome: 'Resolve verifier failure or request human decision.',
+    humanApproval: 'maybe',
+    nextStep: 'Resolve Verify result before continuing.',
+  });
+}
+
 function appendVerifyTimeline(taskDir, event) {
   const timelinePath = path.join(taskDir, 'verify-timeline.json');
   let existing = [];
@@ -703,6 +806,10 @@ function writeVerifierFailure({
   };
   writeTaskFile(taskDir, 'verify.md', verifyMarkdown);
   writeTaskFile(taskDir, 'verify.result.json', JSON.stringify(result, null, 2));
+  updateStatusForVerifyResult(taskDir, result, {
+    reused: false,
+    verifierMode: 'external_cli',
+  });
   appendOrchestrationLog(taskDir, `external CLI verifier failed via ${verifierConfig.provider}; failureReason=${failureReason}; runId=${verifierRunId}`);
 }
 

package/package.json

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

package/prompts/checker.md

@@ -70,6 +70,8 @@ Project-specific context приходит только через task artifacts
 22. Если `checker-context-pack.md`, `task-manifest.json` или risk triggers показывают sync/import/provider/raw records/retries/pagination/rate limits/idempotency/replay/backfill/partial failure, план обязан содержать `## Source Sync / Provider Gate`: scope/provider window, idempotency with dedupe key and duplicate action, failure handling/retry boundaries and coverage/parity evidence. Для import/manual-upload/transcript/evidence-capture задач план также обязан содержать `## Import / Ingestion Contract`: real representative fixtures when available or explicit no-real-fixtures reason, raw metadata/speaker-label extraction needed downstream, and repeat-import policy. Размытое "duplicates detected or reported" без skip/link/update/reject/report-only semantics недостаточно.
 23. Если `task-manifest.json.loopDetector.requiresConsolidatedRemediation=true`, Checker должен блокировать повторный мелкий loop, пока plan/check-resolution не содержит consolidated remediation секцию, которая объединяет repeated reasons.
 24. Если `llmInputPolicy.mode` не `strict` и отсутствующий full artifact реально нужен для честной оценки, verdict должен быть `context_insufficient`. Не используй `context_insufficient`, если deterministic gate уже явно показывает `return_to_plan`.
+25. Если в task artifacts есть `precheck-remediation.md`, Checker должен проверить, что весь checklist был закрыт одним consolidated plan update. Не создавай новый мелкий blocker по одному пункту из старого checklist, если оставшиеся пункты тоже очевидно не закрыты: верни consolidated finding, ссылающийся на `precheck-remediation.md`.
+26. Minor process/evidence polish не должен блокировать Human Gate, если deterministic gates закрыты, acceptance criteria покрыты, scope/risk/security/data correctness не нарушены, а остаток можно безопасно записать как `non_blocking` или human question.
 
 ## Контракт выхода
 

package/prompts/supervisor.md

@@ -59,6 +59,8 @@ Supervisor является code-level orchestrator по контракту: rou
 25. `verify.result.json` должен сверять `plan.md` с фактическим `execution.md`, diff/files/tests и явным execution evidence. Self-reported executor checks без verifier verdict не являются достаточным Verify.
 26. `verify.result.json.verdict = pass | pass_with_notes` допустим при `verificationMode = internal_supervisor` для обычных `R0-R3` local engineering slices. Это cost-saving режим без независимого CLI/model verifier и он является default, если shared defaults или project agents override задают `verifier.mode = internal_supervisor`. `external_cli` обязателен только для R4/R5, production-readiness, destructive/security/financial/broad operational actions, production or real-user-data Prisma/data migrations/backfills, broad ambiguous refactors или explicit human request. Local scratch DB migrations, fixture imports and bounded local-only backfills can close with internal Verify when execution evidence covers the plan gates.
 27. Если external verifier/checker/browser tooling начинает тратить непропорционально много времени или блокируется окружением, Supervisor обязан остановить loop и вынести human decision: принять internal verify/evidence, запустить external escalation вручную или изменить scope.
+28. Если deterministic Check preflight создал `precheck-remediation.md`, Supervisor не должен запускать повторный Check после точечной правки одного пункта. Сначала Planner/Executor должен закрыть весь checklist или явно отметить not-applicable с evidence/human decision в `plan.md`/`status.md`, затем допускается один fresh Check.
+29. Перед повторным Check после deterministic precheck Supervisor обязан сверить, что `precheck-remediation.md` был использован как consolidated checklist: все listed gates отражены в plan/research/status, а не закрывались по одному через серию precheck loops.
 
 ## Hard Gate: Material Scope Expansion -> Brief Reset
 

package/prompts/verifier.md

@@ -44,6 +44,8 @@
 20. Если `plan.md` содержит `## Source Sync / Provider Gate`, verifier должен проверить `Source Sync / Provider Evidence`: scope/window, idempotency, retries/pagination/rate limits, raw-record handling, partial failure recovery and coverage/parity evidence.
 21. Если `task-manifest.json.loopDetector.requiresConsolidatedRemediation=true`, verifier не должен закрывать задачу, пока repeated return reasons не объединены в consolidated remediation и не покрыты execution evidence.
 22. Если `llmInputPolicy.mode` не `strict` и отсутствующий full artifact реально нужен для честной оценки, verdict должен быть `context_insufficient`. Не используй `context_insufficient`, если execution evidence уже явно отсутствует или противоречит plan.
+23. Если task содержит `precheck-remediation.md`, verifier должен проверить только применимые пункты, которые дошли до Execute. Не возвращай `return_to_execute` из-за старого precheck checklist, если план закрыл его до Human Gate и фактическая реализация покрывает acceptance.
+24. Environment/tooling failures внешнего verifier/browser smoke не должны превращаться в бесконечный `return_to_execute` loop. Если implementation evidence достаточно, но внешний инструмент заблокирован окружением, используй `pass_with_notes` или `human_arbitration_required` согласно риску.
 
 ## Контракт выхода