@besales/ops-framework 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 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:

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'),
@@ -139,10 +139,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,9 @@ 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: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/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.4",
   "type": "module",
   "bin": {
     "ops-agent": "bin/ops-agent.mjs"