@awak-app/simy-cli 0.5.10 → 0.5.12

package/src/orchestrator/instruction.js

@@ -1,3 +1,4 @@
+import { minimumCharter } from "../codex-plugins/simy/skills/agentic-delivery-loop/scripts/check-minimum-completion.mjs";
 import { bullets, looksLikeUiTask, section } from "./shared.js";
 import { problemSolvingResultContract } from "./problem-solving.js";
 import { acceptanceCriterionRows } from "./completion-contract.js";
@@ -36,6 +37,12 @@ export function buildCodingInstruction(
       "completion_contract",
       [
         `User-visible outcome: ${charter.completion_contract?.user_outcome || charter.thread_state.user_goal}`,
+        `Beneficiary: ${charter.completion_contract?.experience?.beneficiary || "not recorded"}`,
+        `Situation: ${charter.completion_contract?.experience?.situation || "not recorded"}`,
+        `Experience goal: ${charter.completion_contract?.experience?.goal || "not recorded"}`,
+        `Usable outcome: ${charter.completion_contract?.experience?.usable_outcome || "not recorded"}`,
+        `Recovery experience: ${charter.completion_contract?.experience?.recovery || "not recorded"}`,
+        `Forbidden experiences:\n${bullets(charter.completion_contract?.experience?.forbidden_experiences || [])}`,
         `Minimum scope:\n${bullets(charter.completion_contract?.minimum_scope || charter.acceptance_criteria)}`,
         `Non-goals:\n${bullets(charter.completion_contract?.non_goals || charter.thread_state.non_goals)}`,
         `Proof required:\n${bullets(charter.completion_contract?.proof_required || [])}`,
@@ -50,6 +57,17 @@ export function buildCodingInstruction(
         ),
       ),
     ),
+    section("minimum_completion_evidence", [
+      "All delivery levels require this floor. Before implementation reconcile every original requirement and frozen experience with the stable criterion-ID list; report omissions instead of silently dropping them.",
+      "Save a matrix.json under the local evidence root (ui_evidence_root or repository .artifacts). Return delivery_evidence_path in SIMY_RESULT_JSON. A passed flag or tests_run string is not proof.",
+      "Use check-minimum-completion.mjs from the installed Delivery Loop skill. Its reference minimum-completion.md defines the matrix and structured observation format.",
+      "For each stable criterion ID include real implementation_refs and required user/system evidence. Exercise the actual operation and result, then inspect postcondition and integration independently. For saving, reload/return in a new session and verify stored values and ownership. Document-only work uses the real command/consumer and artifact integrity, not imaginary API/DB checks.",
+      "First evidence artifact per layer must be JSON: {criterion_id, context_sha256, checks}. User checks: operation (expected=true, actual=observed boolean) and result; system checks: postcondition and integration. Each check includes subject, expected and actual. Derive expected values from the original requirement, not from the candidate output. Include screenshots/logs as additional evidence.",
+      "Freeze and bind observations to the current committed revision and charter before verification. Do not rehash old observations to make changed code pass. Use pending/failed for unavailable or mismatching evidence.",
+      `Controller input JSON: ${JSON.stringify({ id: charter.id, requirement: charter.requirement, repository: charter.repository, acceptance_criteria: charter.acceptance_criteria, completion_contract: charter.completion_contract, thread_state: { original_request: charter.thread_state.original_request } })}`,
+      `Controller-owned acceptance specification: ${JSON.stringify(minimumCharter(charter))}`,
+      `Context: run_id=${charter.id}, stage=locally_verified, environment=local, fixture_id=${charter.id}; input_sha256 is contextDigest(spec.source); source_revisions maps ${charter.repository} to current full HEAD.`,
+    ].join("\n")),
     section("expected_tests", bullets(charter.expected_tests)),
     section("must_not", bullets(charter.must_not)),
   ];
@@ -130,10 +148,10 @@ export function buildCodingInstruction(
       "result_contract",
       [
         "Finish with exactly one line beginning SIMY_RESULT_JSON: followed by one JSON object.",
-        "Required keys: outcome_kind, summary, branch_name, commit_sha, commit_message_headline, pr_url, pr_number, pr_title, pr_base_branch, tests_run, tests_passed, ui_evidence_path, unrelated_changes_detected, secret_scan_passed, changed_files, residual_risks, problem_solving, uncertainty_verification, criterion_evidence, visual_review.",
+        "Required keys: outcome_kind, summary, branch_name, commit_sha, commit_message_headline, pr_url, pr_number, pr_title, pr_base_branch, tests_run, tests_passed, ui_evidence_path, unrelated_changes_detected, secret_scan_passed, changed_files, residual_risks, problem_solving, uncertainty_verification, criterion_evidence, visual_review, delivery_evidence_path.",
         problemSolvingResultContract(),
         "uncertainty_verification must contain top_uncertainty, first_verification, evidence_checked, observed_result, resolved, and fallback. Only set resolved=true when concrete observed evidence resolves it.",
-        "criterion_evidence must contain one entry for every AC-N with criterion_id, passed, verification_method, evidence_refs, and observed_result. Only set passed=true when the evidence directly proves that criterion.",
+        "criterion_evidence must contain one entry for every stable criterion ID with criterion_id, passed, verification_method, evidence_refs, and observed_result. Only set passed=true when the evidence directly proves that criterion.",
         "For UI or browser-extension work, visual_review must contain inspected=true, the local screenshot or video paths in artifacts, and concrete acceptance_observations from viewing the actual content. Capturing a file without viewing it does not count.",
         "Use null for unavailable scalar values and [] for unavailable arrays. Do not claim evidence that was not observed.",
       ].join("\n"),

package/src/orchestrator/loop.js

@@ -1,3 +1,4 @@
+import { minimumCharter } from "../codex-plugins/simy/skills/agentic-delivery-loop/scripts/check-minimum-completion.mjs";
 import { auditAttempt, evaluatePrReadiness } from "./audit.js";
 import {
   buildIndependentAudit,
@@ -9,7 +10,7 @@ import { buildAttempt, mergeTokenUsage } from "./result.js";
 import { evaluateRetryCircuit } from "./retry.js";
 import { appendEvent, publish } from "./shared.js";
 
-export async function runCodingLoop({
+async function runCodingLoopOwned({
   snapshot,
   executeAttempt,
   executeIndependentAudit,
@@ -21,6 +22,19 @@ export async function runCodingLoop({
   shouldStop = () => false,
   consumeHumanGuidance = () => "",
 }) {
+  if (!resume && snapshot.attempts.length > 0) {
+    return recheckPrReadinessOwned({ snapshot, collectEvidence, checkSqm, onUpdate });
+  }
+  snapshot.implementation_gate_passed = false;
+  snapshot.done_gate_passed = false;
+  try { minimumCharter(snapshot.charter); } catch {
+    snapshot.final_audit = humanGate("Completion charter requires refresh before verification.", [{
+      code: "MINIMUM_CHARTER_REQUIRED", severity: "blocker", target: "completion_contract",
+      explanation: "Missing or unsupported completion charter. Preserve history, re-charter and collect current minimum evidence.", repairability: "manual",
+    }]);
+    await publish(snapshot, "waiting_human", onUpdate);
+    return snapshot;
+  }
   if (!resume || snapshot.attempts.length === 0) {
     appendEvent(snapshot, "risk_classifying", "PR risk classification completed.", {
       risk: snapshot.charter.risk,
@@ -197,6 +211,7 @@ export async function runCodingLoop({
     await publish(snapshot, "independent_auditing", onUpdate);
     if (shouldStop()) return stopCodingLoop(snapshot, onUpdate);
     const auditInstruction = buildIndependentAuditInstruction(snapshot.charter, attempt);
+    const reviewedMatrix = attempt.observed_evidence?.minimum_completion?.matrix_sha256;
     const auditExecution = await safeExecution(() =>
       executeIndependentAudit({
         attemptNumber,
@@ -215,6 +230,8 @@ export async function runCodingLoop({
     attempt.token_usage = mergeTokenUsage(attempt.token_usage, auditExecution.tokenUsage);
     attempt.budget = refreshBudgetState(snapshot);
 
+    attempt.independent_audit.minimum_matrix_sha256 = reviewedMatrix;
+
     // Re-collect after the read-only auditor to catch any mutated HEAD or working tree.
     attempt.observed_evidence = await safeEvidence(collectEvidence, attempt);
     attempt.sqm = await safeSqm(checkSqm, attempt, attempt.sqm);
@@ -276,9 +293,11 @@ async function stopCodingLoop(snapshot, onUpdate) {
   return snapshot;
 }
 
-export async function recheckPrReadiness({ snapshot, collectEvidence, checkSqm = null, onUpdate }) {
+async function recheckPrReadinessOwned({ snapshot, collectEvidence, checkSqm = null, onUpdate }) {
   const attempt = snapshot.attempts.at(-1);
-  if (!attempt || !attempt.audit?.passed || !attempt.independent_audit?.passed) return snapshot;
+  snapshot.implementation_gate_passed = false;
+  snapshot.done_gate_passed = false;
+  if (!attempt) return snapshot;
   appendEvent(snapshot, "checking_pr", "Refreshing GitHub review and CI evidence.", {
     attempt_number: attempt.attempt_number,
   });
@@ -296,7 +315,7 @@ export async function recheckPrReadiness({ snapshot, collectEvidence, checkSqm =
   snapshot.final_audit = aggregateAudit(
     attempt,
     attempt.pr_readiness.ready,
-    attempt.independent_audit.findings || [],
+    attempt.independent_audit?.findings || [],
   );
   appendEvent(snapshot, attempt.pr_readiness.state, attempt.pr_readiness.summary, {
     pr_url: attempt.pr_url,
@@ -583,3 +602,14 @@ function humanGate(summary, findings) {
     release_gate: null,
   };
 }
+
+const activeControllers = new Set();
+async function withController(options, action) {
+  const owner = options.snapshot?.id;
+  if (typeof owner !== "string" || !owner) throw new Error("Delivery snapshot ID required");
+  if (activeControllers.has(owner)) throw new Error("Delivery controller is already active for this snapshot");
+  activeControllers.add(owner);
+  try { return await action(options); } finally { activeControllers.delete(owner); }
+}
+export const runCodingLoop = options => withController(options, runCodingLoopOwned);
+export const recheckPrReadiness = options => withController(options, recheckPrReadinessOwned);

package/src/orchestrator/minimum-completion.js

@@ -0,0 +1,108 @@
+import path from "node:path";
+import { lstat, realpath } from "node:fs/promises";
+import {
+  minimumCharter,
+  minimumContext,
+  checkMinimumCompletion,
+  loadMinimumJson,
+} from "../codex-plugins/simy/skills/agentic-delivery-loop/scripts/check-minimum-completion.mjs";
+import {
+  contextDigest,
+  sha256,
+} from "../codex-plugins/simy/skills/agentic-delivery-loop/scripts/check-acceptance.mjs";
+
+export function minimumCharterDigest(charter) {
+  return sha256(Buffer.from(JSON.stringify(minimumCharter(charter))));
+}
+
+export async function collectMinimumCompletion({
+  charter,
+  attempt,
+  repositoryPath,
+  local,
+}) {
+  try {
+    if (!local.available || !local.working_tree_clean)
+      throw new Error("Clean current checkout required");
+    const root = await realpath(
+      charter.ui_evidence_root || path.join(repositoryPath, ".artifacts"),
+    );
+    const requested = attempt.raw_output?.delivery_evidence_path;
+    if (typeof requested !== "string") throw new Error("Matrix path missing");
+    const file = path.resolve(root, requested);
+    const relative = path.relative(root, file);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative))
+      throw new Error("Outside evidence root");
+    let current = root;
+    for (const segment of relative.split(path.sep)) {
+      current = path.join(current, segment);
+      if ((await lstat(current)).isSymbolicLink())
+        throw new Error("Symlink evidence path");
+    }
+    const matrix = await loadMinimumJson(file);
+    const report = await checkMinimumCompletion({
+      charter,
+      matrix,
+      context: minimumContext(charter, local.head_sha),
+      evidenceRoot: path.dirname(file),
+    });
+    if (report.status !== "evidence_complete") return report;
+    // Check mapping paths without reading source contents or following links outside the checkout.
+    const repo = await realpath(repositoryPath);
+    for (const row of matrix.results) {
+      for (const ref of row.implementation_refs || []) {
+        if (typeof ref !== "string") continue;
+        const target = await realpath(path.resolve(repo, ref));
+        const rel = path.relative(repo, target);
+        if (
+          rel.startsWith("..") ||
+          path.isAbsolute(rel) ||
+          !(await lstat(target)).isFile()
+        )
+          throw new Error("Invalid implementation mapping");
+      }
+    }
+    if (contextDigest(await loadMinimumJson(file)) !== report.matrix_sha256)
+      throw new Error("Matrix changed during verification");
+    return { ...report, evidence_path: file };
+  } catch {
+    return {
+      status: "evidence_incomplete",
+      errors: [
+        "Minimum completion evidence missing, invalid or stale; verify the actual operation, result, postcondition and integration for every stable criterion ID.",
+      ],
+    };
+  }
+}
+
+export function minimumCompletionCheck(charter, attempt) {
+  const report = attempt.observed_evidence?.minimum_completion;
+  const head = attempt.observed_evidence?.local?.head_sha;
+  let passed = false;
+  try {
+    passed =
+      report?.minimum_completion_version === 1 &&
+      report.status === "evidence_complete" &&
+      report.errors?.length === 0 &&
+      report.charter_sha256 === minimumCharterDigest(charter) &&
+      report.context_sha256 === contextDigest(minimumContext(charter, head)) &&
+      /^[a-f0-9]{64}$/.test(report.matrix_sha256) &&
+      report.head_sha === head &&
+      attempt.observed_evidence.local.working_tree_clean === true;
+  } catch {
+    /* Unsupported/missing charters never waive this gate. */
+  }
+  return {
+    id: "minimum_completion",
+    label: "Every requested outcome has current operation and system evidence",
+    passed: Boolean(passed),
+    detail: passed
+      ? "Current minimum evidence verified; independent coverage/oracle review and remaining gates still apply."
+      : (
+          report?.errors || [
+            "Minimum completion evidence has not been verified.",
+          ]
+        ).join("; "),
+    evidence_refs: report?.evidence_path ? [report.evidence_path] : [],
+  };
+}

package/src/orchestrator/result.js

@@ -1,3 +1,6 @@
+import { minimumCharterDigest } from "./minimum-completion.js";
+import { minimumContext } from "../codex-plugins/simy/skills/agentic-delivery-loop/scripts/check-minimum-completion.mjs";
+import { contextDigest } from "../codex-plugins/simy/skills/agentic-delivery-loop/scripts/check-acceptance.mjs";
 import { cleanString, stringArray } from "./shared.js";
 import { normalizeProblemSolving } from "./problem-solving.js";
 import {
@@ -15,6 +18,8 @@ export function buildAttempt({ attemptNumber, charter, instruction, promptInterv
   const completed = execution.exitCode === 0 && !execution.error;
   const now = new Date().toISOString();
   return {
+    minimum_charter_sha256: safeDigest(() => minimumCharterDigest(charter)),
+    minimum_context_sha256: safeDigest(() => contextDigest(minimumContext(charter, cleanString(result.commit_sha)))),
     attempt_number: attemptNumber,
     backend: charter.backend,
     base_branch: charter.base_branch,
@@ -112,3 +117,5 @@ function buildArtifactPreviews(result) {
 function isUsageRecord(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
+
+function safeDigest(compute) { try { return compute(); } catch { return null; } }