@besales/ops-framework 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+- Created the first local shared Ops Framework package boundary.
+- Added `ops-agent` command dispatch for the current agent command surface.
+- Added project config resolution through `ops/project.ops.yaml`.
+- Kept task, memory, cache and project-specific provider overrides outside shared defaults.
+- Added `ops-agent init` and `ops-agent new-task` for project bootstrap and task scaffolding.
+- Added bootstrap tests for idempotent project setup, portable generated config and fixture lifecycle smoke.

package/README.md

@@ -0,0 +1,328 @@
+# Ops Framework
+
+Reusable human-in-the-loop delivery framework for planning, checking, executing and verifying software tasks across separate project repositories.
+
+The package owns the process engine and reusable assets. Each project owns its task history, memory, cache, project playbook overlays and local provider overrides.
+
+## What Lives In The Package
+
+- `bin/`: CLI commands and shared implementation utilities.
+- `prompts/`: reusable agent prompts for supervisor, researcher, planner, checker, executor and verifier.
+- `templates/`: task artifact templates.
+- `playbooks/`: shared reusable procedures for UI acceptance, complexity, rollout, provider/source-sync and checker context.
+- `config/default-agents.json`: portable defaults with environment placeholders, not local machine paths.
+
+## What Stays In Each Project
+
+- `ops/project.ops.yaml`: project binding file.
+- `ops/agent-pipeline/tasks/`: task artifacts and history.
+- `ops/agent-pipeline/memory/`: project memory.
+- `ops/agent-pipeline/playbooks/`: project playbook overlays with project-specific routes, commands, services, environments and provider quirks.
+- `ops/agent-pipeline/cache/`: project-local generated cache.
+- `ops/agent-pipeline/config/agents.json`: optional project/user provider override.
+- Project-specific deferred work, SQL, runtime notes and learning candidates.
+
+Do not put project memory, task history, secrets, project-specific paths, project service names, routes, provider names or local absolute provider paths into this shared package unless they are explicitly marked as generic examples.
+
+## Layer Model
+
+Ops Framework has three layers:
+
+- Shared framework core: CLI, lifecycle, prompts, templates, config defaults and generic gates.
+- Shared playbooks: reusable procedures that apply across projects.
+- Project overlays: project memory, project playbooks, tasks, cache, local providers and runtime commands.
+
+When a task has relevant risk triggers, checker/verifier context can include both layers:
+
+```text
+Shared Playbook: UI Acceptance
+Project Overlay: UI Acceptance
+```
+
+Shared playbooks stay portable. Project overlays add concrete routes, commands, services, environments and known project quirks.
+
+## Project Config
+
+The recommended setup is:
+
+```bash
+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.
+
+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"
+  }
+}
+```
+
+Use `--framework-version 0.1.0` to pin a specific version, or `--framework-package @scope/name` for a different registry package name.
+
+The generated `ops/project.ops.yaml` shape is:
+
+```yaml
+name: ExampleProject
+ops:
+  legacyPipelineDir: ops/agent-pipeline
+  tasksDir: ops/agent-pipeline/tasks
+  memoryDir: ops/agent-pipeline/memory
+  playbooksDir: ops/agent-pipeline/playbooks
+  cacheDir: ops/agent-pipeline/cache
+agents:
+  configFile: ops/agent-pipeline/config/agents.json
+risk:
+  uiRoots:
+    - apps/web
+  backendRoots:
+    - apps/api
+  workerRoots:
+    - apps/workers
+```
+
+`ops-agent` walks upward from the current working directory until it finds `ops/project.ops.yaml`.
+
+It then resolves:
+
+- project artifacts from the configured project paths;
+- framework prompts/templates/config from this package;
+- shared playbooks from the package and project playbook overlays from `ops.playbooksDir`;
+- project provider overrides from `agents.configFile`, if present.
+
+Risk roots are project-owned. They decide when generic triggers such as UI, user-visible API, worker, production or performance gates apply. Do not hardcode one project's app layout into shared playbooks or shared risk classification.
+
+Fresh bootstrap projects start with commented placeholder root examples. Until a project fills them, `build-check-context` and `preflight` warn that path-based UI/API/worker detection is disabled or limited.
+
+If no project config exists, the resolver falls back to a legacy `ops/agent-pipeline` layout when it can find one.
+
+## Optimization Gate
+
+Optimization is built into the normal Plan -> Check -> Execute -> Verify flow, but it is bounded by risk tier so delivery stays fast:
+
+- `O0`: no dedicated optimization section.
+- `O1`: normal implementation checklist.
+- `O2`: one focused review for touched UI/API/read-model hot paths.
+- `O3`: one focused review plus one representative measurement for workers, materializers, source-sync/provider or production-runtime hot paths.
+
+For O2/O3 work, `plan.md` must include `## Optimization Strategy` with tier, hot paths, expected data size, chosen efficient approach, avoided anti-patterns and a stop rule. `execution.md` must then include `## Optimization Review Evidence` before Verify can pass.
+
+The framework blocks obvious inefficiency early, but speculative or broad optimization ideas should be deferred instead of expanding the task.
+
+## CLI
+
+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
+```
+
+When installed as a package, the intended command is:
+
+```bash
+ops-agent init --project-name ExampleProject
+ops-agent new-task TASK-001-example --title "Example task"
+ops-agent manifest TASK-001-example
+```
+
+For local package development in another project, use a `file:` dependency:
+
+```json
+{
+  "devDependencies": {
+    "@besales/ops-framework": "file:../shared-platform/packages/ops-framework"
+  }
+}
+```
+
+Do not commit that `file:` dependency to production projects. It is only for package development because production builders usually do not have a sibling `../shared-platform` checkout.
+
+## Supported Commands
+
+- `init`
+- `new-task`
+- `manifest`
+- `preflight`
+- `transition`
+- `build-check-context`
+- `validate-check-artifacts`
+- `estimate-llm-input`
+- `quality-gates`
+- `run-check`
+- `run-verify`
+- `hash-task-artifacts`
+- `build-execution-ledger`
+- `task-metrics`
+- `run-plan-check-loop`
+- `supervisor-turn`
+- `intake-feedback`
+- `intake-execution-feedback`
+- `guard-task`
+- `memory-candidates`
+- `learning-index`
+- `learning-review`
+- `update-memory`
+- `learning-audit`
+- `learning-report`
+- `test/self-test`
+
+## Learning Loop
+
+Learning is controlled and human-approved:
+
+```text
+retrospective/feedback/check/verify artifacts
+ -> memory/playbook candidates
+ -> learning index
+ -> human promote/defer/reject
+ -> update memory/playbooks
+```
+
+Use:
+
+```bash
+ops-agent memory-candidates
+ops-agent learning-index
+ops-agent learning-review
+ops-agent learning-audit
+ops-agent update-memory --apply-approved
+ops-agent learning-report
+```
+
+`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.
+
+`learning-review` writes `ops/agent-pipeline/memory/learning-review.md`, a human approval pack with each pending candidate and the allowed decisions: `promote`, `defer`, `reject` or `rewrite`.
+
+`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.
+
+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
+
+Feedback is stage-agnostic. Any user question, correction, review note or learning observation during an active task should be captured before it is acted on:
+
+```bash
+ops-agent intake-feedback TASK-001-example "Feedback text"
+```
+
+This appends a classified event to `feedback.md`, updates `status.md`, appends `orchestration-log.md` and makes the event available to checker/verifier context and learning candidates.
+
+Use `learning_capture` for process/memory/playbook observations that should feed retrospective without invalidating the current implementation scope.
+
+For active task conversations, prefer the turn router:
+
+```bash
+ops-agent supervisor-turn TASK-001-example "User message"
+```
+
+It records the message, appends a `supervisor_turn` log event and prints the mandatory response contract:
+
+```text
+TASK: ...
+STAGE: ...
+SUPERVISOR: active
+FEEDBACK INTAKE: recorded (...)
+ALLOWED NOW: ...
+NOT ALLOWED NOW: ...
+Следующий шаг: ...
+```
+
+## Provider Config
+
+Shared defaults use environment placeholders:
+
+- `CODEX_CLI_COMMAND`
+- `CLAUDE_CLI_COMMAND`
+- `CLOUD_CLI_COMMAND`
+- `CHECKER_CLI_COMMAND`
+
+Project-local overrides may point to real local binaries in the project or user environment. Keep those overrides out of shared defaults.
+
+## Verification Model
+
+The normal lifecycle is:
+
+```text
+Brief -> Research -> Plan -> Check -> Human Gate -> Execute -> Verify
+```
+
+`Check` reviews the plan before implementation. `Verify` reviews the result after execution evidence exists.
+
+Internal supervisor verify is acceptable for ordinary local engineering slices. External CLI verify should be used for production readiness, destructive or security-sensitive work, material data migrations/backfills, broad ambiguous refactors or explicit human request.
+
+## Release
+
+`@besales/ops-framework` is published as a public scoped npm package through GitHub Actions trusted publishing.
+
+The release workflow is `.github/workflows/publish-ops-framework.yml`.
+
+Required npm trusted publisher configuration:
+
+- Package: `@besales/ops-framework`
+- Provider: GitHub Actions
+- Organization / user: `be-sales`
+- Repository: `shared-platform`
+- Workflow filename: `publish-ops-framework.yml`
+- Environment: leave empty
+- Allowed action: `npm publish`
+
+The workflow uses GitHub OIDC (`id-token: write`) and does not require an `NPM_TOKEN` secret.
+
+For first-time package creation, npm requires the package to exist before a trusted publisher can be attached. Bootstrap the first version with a short-lived manual publish path, configure the trusted publisher, then use the workflow for all future versions.
+
+Manual workflow release:
+
+```bash
+gh workflow run publish-ops-framework.yml --repo be-sales/shared-platform -f version=0.1.0
+```
+
+Tag workflow release:
+
+```bash
+git tag ops-framework-v0.1.0
+git push origin ops-framework-v0.1.0
+```
+
+## Validation
+
+Run package tests:
+
+```bash
+yarn workspace @besales/ops-framework test
+```
+
+Run package lint:
+
+```bash
+node bin/self-lint.mjs
+```
+
+Auto-fix supported whitespace issues:
+
+```bash
+node bin/self-lint.mjs --fix
+```
+
+The lint script checks:
+
+- no `.DS_Store` files;
+- no open-work markers in package files;
+- no local home-directory or application-bundle absolute paths in shared files;
+- no known project-specific paths or project names in shared files;
+- no trailing whitespace;
+- text files end with a newline.
+
+## Pilot Status
+
+This package was first extracted from a project-local Ops Framework. Pilot task history, memory and provider paths remain project-owned and are connected through that project's `ops/project.ops.yaml`.

package/bin/build-check-context.mjs

@@ -0,0 +1,67 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  buildCheckerContextPack,
+  buildCheckContext,
+  buildEvidenceMarkdown,
+  computeTaskContextInputs,
+  riskRootWarnings,
+  resolveTaskDir,
+} from './lib/check-context-utils.mjs';
+
+function main() {
+  const taskArg = process.argv[2];
+  if (!taskArg) {
+    fail('Usage: node ops/agent-pipeline/bin/build-check-context.mjs <TASK-id-or-task-path>');
+  }
+
+  try {
+    const taskDir = resolveTaskDir(taskArg);
+    const taskId = path.basename(taskDir);
+    const inputs = computeTaskContextInputs(taskDir);
+    const checkContext = buildCheckContext({
+      taskId,
+      inputs,
+    });
+    const evidence = buildEvidenceMarkdown({
+      taskId,
+      risk: inputs.risk,
+      qualityGates: inputs.qualityGates,
+      referencedFiles: inputs.referencedFiles,
+      structuralLines: inputs.structuralLines,
+      planFingerprint: inputs.planFingerprint,
+      memorySha: inputs.memorySha,
+      taskArtifacts: inputs.taskArtifacts,
+    });
+    const checkerContextPack = buildCheckerContextPack({
+      taskId,
+      risk: inputs.risk,
+      qualityGates: inputs.qualityGates,
+      referencedFiles: inputs.referencedFiles,
+      structuralLines: inputs.structuralLines,
+      taskArtifacts: inputs.taskArtifacts,
+    });
+
+    fs.writeFileSync(path.join(taskDir, 'check-context.json'), `${JSON.stringify(checkContext, null, 2)}\n`);
+    fs.writeFileSync(path.join(taskDir, 'check-evidence.md'), evidence);
+    fs.writeFileSync(path.join(taskDir, checkContext.checkerContextPackFile), checkerContextPack);
+
+    console.log(`Built check context for ${taskId}`);
+    console.log(`- riskProfile: ${inputs.risk.riskProfile}`);
+    console.log(`- riskTriggers: ${inputs.risk.riskTriggers.join(', ') || 'none'}`);
+    for (const warning of riskRootWarnings()) {
+      console.log(`- warning: ${warning}`);
+    }
+    console.log(`- referencedFiles: ${inputs.referencedFiles.length}`);
+    console.log(`- checkerContextPack: ${checkContext.checkerContextPackFile}`);
+  } catch (error) {
+    fail(error.message);
+  }
+}
+
+function fail(message) {
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+main();

package/bin/build-execution-ledger.mjs

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  normalizeMarkdownBody,
+  parseCliArgs,
+  readTaskFile,
+  repoRoot,
+  resolveTaskDir,
+  sha256,
+  writeTaskFile,
+} from './lib/check-context-utils.mjs';
+import { buildExecutionLedger } from './lib/execution-ledger-utils.mjs';
+
+function main() {
+  const args = parseCliArgs(process.argv.slice(2));
+  const taskArg = args.positional[0];
+  if (!taskArg) {
+    fail('Usage: node ops/agent-pipeline/bin/build-execution-ledger.mjs <TASK-id-or-task-path>');
+  }
+
+  try {
+    const taskDir = resolveTaskDir(taskArg);
+    const taskId = path.basename(taskDir);
+    const ledger = buildExecutionLedger({
+      taskId,
+      taskDir,
+      repoRoot,
+      planSha: hashTaskMarkdown(taskDir, 'plan.md'),
+      executionSha: hashTaskMarkdown(taskDir, 'execution.md'),
+    });
+
+    writeTaskFile(taskDir, 'execution-ledger.json', JSON.stringify(ledger, null, 2));
+    console.log(`Built execution ledger for ${taskId}`);
+    console.log(`- changedFiles: ${ledger.git.changedFiles.length}`);
+    console.log(`- unrelatedDirtyFiles: ${ledger.git.unrelatedDirtyFiles.length}`);
+  } catch (error) {
+    fail(error.message);
+  }
+}
+
+function hashTaskMarkdown(taskDir, fileName) {
+  const content = readTaskFile(taskDir, fileName);
+  if (!content) {
+    throw new Error(`Task artifact is missing or empty: ${fileName}`);
+  }
+  return sha256(normalizeMarkdownBody(content));
+}
+
+function fail(message) {
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+main();

package/bin/estimate-llm-input.mjs

@@ -0,0 +1,160 @@
+import path from 'node:path';
+import {
+  buildCheckerContextPack,
+  buildCheckContext,
+  buildEvidenceMarkdown,
+  computePromptSha,
+  computeTaskContextInputs,
+  getFlag,
+  normalizeMarkdownBody,
+  parseCliArgs,
+  readMemorySnapshot,
+  readPrompt,
+  readTaskFile,
+  resolveTaskDir,
+  sha256,
+} from './lib/check-context-utils.mjs';
+import {
+  buildCheckerLlmInputPack,
+  buildVerifierLlmInputPack,
+  estimatePayload,
+  resolveLlmContextMode,
+  summarizePackForConsole,
+} from './lib/llm-input-pack-utils.mjs';
+
+function main() {
+  const args = parseCliArgs(process.argv.slice(2));
+  const taskArg = args.positional[0];
+  if (!taskArg) {
+    fail('Usage: node ops/agent-pipeline/bin/estimate-llm-input.mjs <TASK-id-or-task-path> --stage check|verify [--mode fast|standard|strict] [--json]');
+  }
+
+  try {
+    const taskDir = resolveTaskDir(taskArg);
+    const taskId = path.basename(taskDir);
+    const stage = String(getFlag(args, 'stage') || args.positional[1] || 'check').toLowerCase();
+    const pack = stage === 'verify'
+      ? buildVerifyEstimatePack({ taskDir, taskId, args })
+      : buildCheckEstimatePack({ taskDir, taskId, args });
+    const promptName = stage === 'verify' ? 'verifier.md' : 'checker.md';
+    const fullPromptEstimate = estimatePayload([
+      readPrompt(promptName),
+      '',
+      JSON.stringify(pack.input, null, 2),
+    ].join('\n'));
+    const result = {
+      taskId,
+      stage,
+      mode: pack.meta.mode,
+      capTokens: pack.meta.capTokens,
+      packBytes: pack.meta.bytes,
+      packEstimatedTokens: pack.meta.estimatedTokens,
+      fullPromptBytes: fullPromptEstimate.bytes,
+      fullPromptEstimatedTokens: fullPromptEstimate.estimatedTokens,
+      overCap: pack.meta.overCap,
+      compactedArtifacts: pack.meta.compactedArtifacts,
+    };
+
+    if (args.flags.has('json')) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`LLM input estimate for ${taskId} (${stage})`);
+      for (const line of summarizePackForConsole(pack)) {
+        console.log(line);
+      }
+      console.log(`- fullPromptEstimatedTokens: ${result.fullPromptEstimatedTokens}`);
+      console.log(`- overCap: ${result.overCap ? 'yes' : 'no'}`);
+    }
+    process.exit(result.overCap ? 1 : 0);
+  } catch (error) {
+    fail(error.message);
+  }
+}
+
+function buildCheckEstimatePack({ taskDir, taskId, args }) {
+  const inputs = computeTaskContextInputs(taskDir);
+  const checkContext = buildCheckContext({ taskId, inputs });
+  const checkerContextPack = buildCheckerContextPack({
+    taskId,
+    risk: inputs.risk,
+    qualityGates: inputs.qualityGates,
+    referencedFiles: inputs.referencedFiles,
+    structuralLines: inputs.structuralLines,
+    taskArtifacts: inputs.taskArtifacts,
+  });
+  const checkEvidence = buildEvidenceMarkdown({
+    taskId,
+    risk: inputs.risk,
+    qualityGates: inputs.qualityGates,
+    referencedFiles: inputs.referencedFiles,
+    structuralLines: inputs.structuralLines,
+    planFingerprint: inputs.planFingerprint,
+    memorySha: inputs.memorySha,
+    taskArtifacts: inputs.taskArtifacts,
+  });
+  const memorySnapshot = readMemorySnapshot(checkContext.memoryFiles);
+  const mode = resolveLlmContextMode({
+    requestedMode: getFlag(args, 'mode') || getFlag(args, 'context-mode'),
+    riskTriggers: checkContext.riskTriggers,
+  });
+  return buildCheckerLlmInputPack({
+    taskDir,
+    taskId,
+    checkerPromptSha: computePromptSha('checker.md'),
+    cacheKey: { taskId, estimate: true, contextMode: mode },
+    checkContext,
+    checkEvidence,
+    checkerContextPack,
+    taskManifest: readTaskFile(taskDir, 'task-manifest.json'),
+    projectMemory: memorySnapshot.map((item) => ({
+      path: item.path,
+      sha: item.sha,
+      content: item.content,
+    })),
+    mode,
+  });
+}
+
+function buildVerifyEstimatePack({ taskDir, taskId, args }) {
+  const manifest = readOptionalJson(taskDir, 'task-manifest.json');
+  const mode = resolveLlmContextMode({
+    requestedMode: getFlag(args, 'mode') || getFlag(args, 'context-mode'),
+    riskTriggers: manifest?.context?.riskTriggers || [],
+  });
+  return buildVerifierLlmInputPack({
+    taskDir,
+    taskId,
+    planSha: hashTaskMarkdown(taskDir, 'plan.md'),
+    executionSha: hashTaskMarkdown(taskDir, 'execution.md'),
+    verifier: {
+      provider: 'estimate',
+      model: 'estimate',
+      reasoningEffort: 'none',
+      runId: 'estimate',
+    },
+    mode,
+  });
+}
+
+function hashTaskMarkdown(taskDir, fileName) {
+  return sha256(normalizeMarkdownBody(readTaskFile(taskDir, fileName)));
+}
+
+function readOptionalJson(taskDir, fileName) {
+  const raw = readTaskFile(taskDir, fileName);
+  if (!raw) {
+    return null;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function fail(message) {
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+main();