@awak-app/simy-cli 0.1.0

package/src/orchestrator/audit.js

@@ -0,0 +1,317 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  bullets,
+  evidenceKind,
+  hasAllowedPrefix,
+  stringArray,
+} from "./shared.js";
+
+export async function auditAttempt(charter, attempt) {
+  const checks = [];
+  const addCheck = (id, label, passed, detail, severity = "blocker", repairability = "auto") => {
+    checks.push({ id, label, passed, severity, detail, repairability, evidence_refs: [] });
+  };
+  const local = attempt.observed_evidence?.local || {};
+
+  addCheck(
+    "executor_succeeded",
+    "Local executor completed",
+    attempt.status === "completed",
+    attempt.status === "completed" ? "Executor exited successfully." : attempt.summary,
+  );
+  addCheck(
+    "pr_url_present",
+    "PR URL recorded",
+    Boolean(attempt.pr_url),
+    attempt.pr_url || "Missing PR URL.",
+  );
+  addCheck(
+    "branch_recorded",
+    "Feature branch recorded",
+    Boolean(attempt.branch_name),
+    attempt.branch_name || "Missing feature branch.",
+  );
+  addCheck(
+    "commit_recorded",
+    "Commit SHA recorded",
+    Boolean(attempt.commit_sha),
+    attempt.commit_sha || "Missing commit SHA.",
+  );
+  addCheck(
+    "reported_base_branch_locked",
+    "Executor reported the required base branch",
+    attempt.pr_base_branch === charter.base_branch,
+    `Expected ${charter.base_branch}; observed ${attempt.pr_base_branch || "missing"}.`,
+  );
+  addCheck(
+    "local_git_evidence_available",
+    "Local Git evidence is available",
+    local.available === true,
+    local.errors?.join("; ") || "Local Git evidence collected.",
+    "blocker",
+    "manual",
+  );
+  addCheck(
+    "commit_matches_local_head",
+    "Reported commit matches local HEAD",
+    Boolean(local.head_sha && attempt.commit_sha && local.head_sha === attempt.commit_sha),
+    `Reported ${attempt.commit_sha || "missing"}; local ${local.head_sha || "missing"}.`,
+  );
+  addCheck(
+    "branch_matches_local_checkout",
+    "Reported branch matches the local checkout",
+    Boolean(local.branch_name && attempt.branch_name && local.branch_name === attempt.branch_name),
+    `Reported ${attempt.branch_name || "missing"}; local ${local.branch_name || "missing"}.`,
+  );
+  addCheck(
+    "working_tree_clean",
+    "Working tree is clean after implementation",
+    local.working_tree_clean === true,
+    local.status_lines?.join(", ") || "Working tree clean.",
+  );
+  const missingExpectedTests = charter.expected_tests.filter(
+    (command) => !attempt.tests_run.includes(command),
+  );
+  addCheck(
+    "tests_recorded_and_passing",
+    "Expected tests are recorded as passing",
+    attempt.tests_run.length > 0 &&
+      attempt.tests_passed === true &&
+      missingExpectedTests.length === 0,
+    missingExpectedTests.length > 0
+      ? `Missing expected tests: ${missingExpectedTests.join(", ")}`
+      : attempt.tests_run.join(", ") || "No passing test command recorded.",
+  );
+  addCheck(
+    "commit_headline_prefix",
+    "Observed commit headline uses an allowed prefix",
+    hasAllowedPrefix(local.commit_headline),
+    local.commit_headline || "Local commit headline missing.",
+  );
+  const changedFiles = stringArray(local.changed_files);
+  const reportedFiles = stringArray(attempt.raw_output.changed_files);
+  addCheck(
+    "changed_files_match_git",
+    "Reported changed files match the local diff",
+    local.available === true && sameStrings(changedFiles, reportedFiles),
+    `Reported: ${reportedFiles.join(", ") || "none"}; local: ${changedFiles.join(", ") || "none"}.`,
+  );
+  const unintendedArtifacts = changedFiles.filter((file) =>
+    /(^|\/)(\.evidence|evidence|screenshots?|videos?)(\/|$)|\.(png|jpe?g|webp|gif|mp4|mov|webm)$/i.test(
+      file,
+    ),
+  );
+  addCheck(
+    "no_unintended_artifacts",
+    "No local evidence artifacts committed",
+    unintendedArtifacts.length === 0,
+    unintendedArtifacts.length > 0
+      ? `Unexpected artifacts: ${unintendedArtifacts.join(", ")}`
+      : "No committed local evidence artifacts reported.",
+  );
+
+  const evidenceRequired = charter.expected_evidence.includes("ui_evidence_path");
+  const evidenceArtifact = await inspectEvidence(charter, attempt.ui_evidence_path);
+  if (evidenceRequired || attempt.ui_evidence_path) {
+    addCheck(
+      "evidence_exists_local_only",
+      "Local evidence exists under the required root",
+      Boolean(
+        evidenceArtifact?.exists &&
+          evidenceArtifact.under_required_root &&
+          evidenceArtifact.size_bytes > 0,
+      ),
+      evidenceArtifact?.summary || "Local evidence path missing.",
+    );
+  }
+
+  const findings = checks
+    .filter((check) => !check.passed)
+    .map((check) => ({
+      code: check.id.toUpperCase(),
+      title: check.label,
+      severity: check.severity,
+      target: check.id,
+      explanation: check.detail,
+      repairability:
+        check.id === "executor_succeeded" && attempt.raw_output.blocked
+          ? "manual"
+          : check.repairability,
+      auto_fix_hint:
+        check.id === "executor_succeeded" && attempt.raw_output.blocked
+          ? null
+          : `Repair ${check.label.toLowerCase()} and report fresh evidence.`,
+    }));
+  const passed = findings.length === 0;
+  const requiresHuman = findings.some((finding) => finding.repairability === "manual");
+  const implementationGate = {
+    passed,
+    summary: passed
+      ? "Implementation evidence passed local verification."
+      : "Implementation evidence failed local verification.",
+    checks,
+  };
+
+  return {
+    passed,
+    summary: passed
+      ? "Implementation is ready for independent audit."
+      : "Implementation did not satisfy local evidence gates.",
+    evaluations: [
+      {
+        kind: "intent_fit",
+        passed,
+        score:
+          checks.length === 0 ? 1 : checks.filter((check) => check.passed).length / checks.length,
+        summary: passed
+          ? "Structured evidence matches the charter."
+          : "Structured evidence is incomplete.",
+        findings,
+        evidence_refs: [attempt.pr_url, attempt.commit_sha, attempt.ui_evidence_path].filter(
+          Boolean,
+        ),
+        reviewer_id: "simy_cli_deterministic_auditor.v1",
+      },
+    ],
+    findings,
+    auto_repairable: !passed && !requiresHuman,
+    requires_human: requiresHuman,
+    reinstruction: passed
+      ? null
+      : `Preserve the original requirement and repair these findings:\n${bullets(
+          findings.map(
+            (finding) => `${finding.code}: ${finding.auto_fix_hint || finding.explanation}`,
+          ),
+        )}`,
+    evidence_artifacts: evidenceArtifact ? [evidenceArtifact] : [],
+    implementation_gate: implementationGate,
+    release_gate: null,
+    work_log_signals: [],
+    work_log_interventions: [],
+  };
+}
+
+export function evaluatePrReadiness(charter, attempt) {
+  const github = attempt.observed_evidence?.github || {};
+  const local = attempt.observed_evidence?.local || {};
+  const independentAudit = attempt.independent_audit;
+  const checks = [
+    readinessCheck("implementation_gate", attempt.audit?.passed === true, "Implementation gate must pass."),
+    readinessCheck(
+      "independent_ai_audit",
+      independentAudit?.passed === true,
+      independentAudit?.summary || "Independent AI audit has not passed.",
+    ),
+    readinessCheck(
+      "github_evidence",
+      github.available === true,
+      github.error || "GitHub PR evidence is unavailable.",
+    ),
+    readinessCheck(
+      "pr_url_matches",
+      Boolean(github.url && attempt.pr_url && github.url === attempt.pr_url),
+      `Reported ${attempt.pr_url || "missing"}; GitHub reports ${github.url || "missing"}.`,
+    ),
+    readinessCheck("pr_not_draft", github.available && github.is_draft === false, "PR is still draft."),
+    readinessCheck(
+      "pr_title_prefix",
+      hasAllowedPrefix(github.title),
+      github.title || "GitHub PR title is missing.",
+    ),
+    readinessCheck(
+      "pr_repository_matches",
+      normalizeRepository(github.repository) === normalizeRepository(charter.repository),
+      `Expected ${charter.repository}; GitHub reports ${github.repository || "missing"}.`,
+    ),
+    readinessCheck(
+      "head_sha_matches",
+      Boolean(github.head_sha && local.head_sha && github.head_sha === local.head_sha),
+      `GitHub head ${github.head_sha || "missing"}; local head ${local.head_sha || "missing"}.`,
+    ),
+    readinessCheck(
+      "head_branch_matches",
+      Boolean(github.head_branch && local.branch_name && github.head_branch === local.branch_name),
+      `GitHub branch ${github.head_branch || "missing"}; local branch ${local.branch_name || "missing"}.`,
+    ),
+    readinessCheck(
+      "base_branch_matches",
+      github.base_branch === charter.base_branch,
+      `Expected ${charter.base_branch}; GitHub reports ${github.base_branch || "missing"}.`,
+    ),
+    readinessCheck(
+      "pr_mergeable",
+      github.mergeable === "MERGEABLE" && github.merge_state_status === "CLEAN",
+      `Mergeable ${github.mergeable || "unknown"}; state ${github.merge_state_status || "unknown"}.`,
+    ),
+    readinessCheck("status_checks_present", github.checks_present === true, "No PR status checks found."),
+    readinessCheck("status_checks_passing", github.checks_passing === true, "PR checks are pending or failing."),
+    readinessCheck(
+      "required_checks_present",
+      github.required_checks_present === true,
+      `Missing required checks: ${charter.required_checks.join(", ") || "none configured"}.`,
+    ),
+    readinessCheck(
+      "human_peer_approval",
+      !charter.require_human_approval || github.human_approved === true,
+      "Human peer approval is still required.",
+    ),
+  ];
+  const ready = checks.every((check) => check.passed);
+  return {
+    ready,
+    state: ready ? "merge_ready" : "pr_ready_for_review",
+    summary: ready
+      ? "PR has independently verified evidence, passing checks, and required approval."
+      : "Implementation is complete, but the PR is not merge-ready.",
+    checks,
+    pending_reasons: checks.filter((check) => !check.passed).map((check) => check.detail),
+  };
+}
+
+function readinessCheck(id, passed, detail) {
+  return { id, passed: Boolean(passed), detail };
+}
+
+function sameStrings(left, right) {
+  const a = [...new Set(left)].sort();
+  const b = [...new Set(right)].sort();
+  return a.length === b.length && a.every((value, index) => value === b[index]);
+}
+
+function normalizeRepository(value) {
+  return String(value || "")
+    .trim()
+    .replace(/^https?:\/\/github\.com\//, "")
+    .replace(/\.git$/, "")
+    .toLowerCase();
+}
+
+async function inspectEvidence(charter, evidencePath) {
+  if (!evidencePath) return null;
+  const resolved = path.resolve(evidencePath);
+  const root = charter.ui_evidence_root ? path.resolve(charter.ui_evidence_root) : null;
+  let fileStat = null;
+  try {
+    fileStat = await stat(resolved);
+  } catch {
+    // Missing evidence is represented in the returned artifact.
+  }
+  const underRoot = Boolean(
+    root && (resolved === root || resolved.startsWith(`${root}${path.sep}`)),
+  );
+  return {
+    path: resolved,
+    kind: fileStat?.isDirectory() ? "directory" : evidenceKind(resolved),
+    exists: Boolean(fileStat),
+    under_required_root: underRoot,
+    size_bytes: fileStat?.size ?? 0,
+    file_count: fileStat?.isFile() ? 1 : 0,
+    git_tracked: false,
+    summary:
+      fileStat && underRoot && fileStat.size > 0
+        ? "Evidence exists under the required local root."
+        : "Evidence is missing, empty, or outside the required local root.",
+  };
+}

package/src/orchestrator/contract.js

@@ -0,0 +1,125 @@
+import { randomUUID } from "node:crypto";
+
+import {
+  clampAttempts,
+  cleanString,
+  event,
+  looksLikeUiTask,
+  stringArray,
+} from "./shared.js";
+import { classifyRisk } from "./risk.js";
+
+export function createCodingLoopSnapshot({ runId, request, metadata = {} }) {
+  const now = new Date().toISOString();
+  const baseBranch = cleanString(request.base_branch) || "dev";
+  const expectedEvidence = stringArray(request.expected_evidence);
+  if (looksLikeUiTask(request.requirement) && !expectedEvidence.includes("ui_evidence_path")) {
+    expectedEvidence.push("ui_evidence_path");
+  }
+  const acceptanceCriteria = stringArray(request.acceptance_criteria);
+  const mustNot = stringArray(request.must_not);
+  const risk = classifyRisk(request);
+  const designSummary = cleanString(request.design_summary);
+  const designApprovedBy = cleanString(request.design_review_approved_by);
+  const designEvidenceUrl = cleanString(request.design_review_url);
+
+  return {
+    id: runId,
+    state: "queued",
+    metadata: { ...metadata, execution_location: "local_cli" },
+    charter: {
+      id: `${runId}_charter`,
+      requirement: cleanString(request.requirement),
+      repository: cleanString(request.repository),
+      backend: request.backend === "claude" ? "claude" : "codex",
+      audit_backend:
+        request.audit_backend === "claude" || request.audit_backend === "codex"
+          ? request.audit_backend
+          : request.backend === "claude"
+            ? "claude"
+            : "codex",
+      base_branch: baseBranch,
+      max_attempts: clampAttempts(request.max_attempts),
+      ui_evidence_root: cleanString(request.ui_evidence_root),
+      acceptance_criteria:
+        acceptanceCriteria.length > 0
+          ? acceptanceCriteria
+          : [
+              "The requested change is implemented without unrelated scope.",
+              "Relevant tests pass and are recorded.",
+              `A pull request targets ${baseBranch}.`,
+            ],
+      acceptance_criteria_source: acceptanceCriteria.length > 0 ? "explicit" : "default",
+      expected_tests: stringArray(request.expected_tests),
+      expected_evidence: expectedEvidence,
+      required_checks: stringArray(request.required_checks),
+      require_human_approval:
+        risk.requires_design_review || request.require_human_approval !== false,
+      must_not:
+        mustNot.length > 0
+          ? mustNot
+          : [
+              "commit local evidence artifacts",
+              `target a branch other than ${baseBranch}`,
+              "include unrelated changes",
+            ],
+      proposal_id: cleanString(request.proposal_id) || null,
+      risk,
+      design_review: {
+        required: risk.requires_design_review,
+        summary: designSummary || null,
+        approved_by: designApprovedBy || null,
+        evidence_url: designEvidenceUrl || null,
+        status: risk.requires_design_review
+          ? designSummary && designApprovedBy && designEvidenceUrl
+            ? "approved"
+            : "missing"
+          : "not_required",
+      },
+      thread_state: {
+        original_request: cleanString(request.requirement),
+        user_goal: cleanString(request.requirement),
+        non_goals: ["Unrelated refactors", "Server-side execution of repository code"],
+        expected_finish_line: `A verified pull request targeting ${baseBranch}.`,
+        artifacts_required: ["pr_url", "commit_sha", "tests_run", ...expectedEvidence],
+        failure_count: 0,
+        assumptions: [],
+      },
+      prompt_policy_report: buildPromptPolicyReport(request, risk),
+      created_at: now,
+    },
+    attempts: [],
+    events: [
+      event("queued", "Coding loop queued for local orchestration.", {
+        execution_location: "local_cli",
+      }),
+    ],
+    final_audit: null,
+    implementation_gate_passed: false,
+    done_gate_passed: false,
+    created_at: now,
+    updated_at: now,
+  };
+}
+
+export function newRunId() {
+  return `coding_loop_${randomUUID()}`;
+}
+
+function buildPromptPolicyReport(request, risk) {
+  const ui = looksLikeUiTask(request.requirement);
+  const matched = [
+    "coding.purpose_lock",
+    "coding.release_management",
+    "coding.completion_self_audit",
+    ...(ui ? ["coding.browser_verification"] : []),
+  ];
+  return {
+    registry_id: "simy_cli_coding_prompt_policy.v1",
+    matched_policy_ids: matched,
+    matched_triggers: matched.map((id) => id.slice("coding.".length)),
+    risk_level: risk.level,
+    risk_tags: risk.tags,
+    reasons: matched.map((id) => `${id}: selected by local coding policy`),
+  };
+}

package/src/orchestrator/evidence.js

@@ -0,0 +1,184 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+import { cleanString, stringArray } from "./shared.js";
+
+const execFileAsync = promisify(execFile);
+const SUCCESS_CONCLUSIONS = new Set(["SUCCESS", "NEUTRAL", "SKIPPED"]);
+const FAILURE_CONCLUSIONS = new Set([
+  "ACTION_REQUIRED",
+  "CANCELLED",
+  "FAILURE",
+  "STALE",
+  "TIMED_OUT",
+]);
+
+export async function collectPrEvidence({
+  charter,
+  attempt,
+  repositoryPath,
+  runCommand = execFileAsync,
+}) {
+  const local = await collectLocalGitEvidence({
+    baseBranch: charter.base_branch,
+    repositoryPath,
+    runCommand,
+  });
+  const github = await collectGitHubEvidence({ charter, attempt, repositoryPath, runCommand });
+  return {
+    collected_at: new Date().toISOString(),
+    local,
+    github,
+  };
+}
+
+async function collectLocalGitEvidence({ baseBranch, repositoryPath, runCommand }) {
+  const [head, branch, headline, status, changed] = await Promise.all([
+    command(runCommand, "git", ["rev-parse", "HEAD"], repositoryPath),
+    command(runCommand, "git", ["branch", "--show-current"], repositoryPath),
+    command(runCommand, "git", ["log", "-1", "--pretty=%s"], repositoryPath),
+    command(runCommand, "git", ["status", "--porcelain"], repositoryPath),
+    changedFiles(runCommand, baseBranch, repositoryPath),
+  ]);
+  const statusLines = lines(status.stdout);
+  return {
+    available: head.ok && branch.ok && headline.ok && status.ok && changed.ok,
+    head_sha: cleanString(head.stdout) || null,
+    branch_name: cleanString(branch.stdout) || null,
+    commit_headline: cleanString(headline.stdout) || null,
+    working_tree_clean: status.ok && statusLines.length === 0,
+    status_lines: statusLines,
+    changed_files: lines(changed.stdout),
+    errors: [head, branch, headline, status, changed]
+      .filter((item) => !item.ok)
+      .map((item) => item.error),
+  };
+}
+
+async function changedFiles(runCommand, baseBranch, repositoryPath) {
+  const refs = [`origin/${baseBranch}`, baseBranch];
+  for (const ref of refs) {
+    const result = await command(
+      runCommand,
+      "git",
+      ["diff", "--name-only", "--diff-filter=ACMR", `${ref}...HEAD`],
+      repositoryPath,
+    );
+    if (result.ok) return result;
+  }
+  return { ok: false, stdout: "", error: `Could not diff against ${baseBranch}.` };
+}
+
+async function collectGitHubEvidence({ charter, attempt, repositoryPath, runCommand }) {
+  const target = attempt.pr_url || (attempt.pr_number ? String(attempt.pr_number) : "");
+  if (!target) return unavailable("PR URL or number was not reported.");
+  const fields = [
+    "url",
+    "number",
+    "title",
+    "isDraft",
+    "mergeable",
+    "mergeStateStatus",
+    "reviewDecision",
+    "headRefName",
+    "headRefOid",
+    "headRepository",
+    "headRepositoryOwner",
+    "baseRefName",
+    "reviews",
+    "statusCheckRollup",
+  ].join(",");
+  const result = await command(
+    runCommand,
+    "gh",
+    ["pr", "view", target, "--json", fields],
+    repositoryPath,
+  );
+  if (!result.ok) return unavailable(result.error);
+
+  let payload;
+  try {
+    payload = JSON.parse(result.stdout);
+  } catch {
+    return unavailable("GitHub PR evidence was not valid JSON.");
+  }
+  const checks = normalizeChecks(payload.statusCheckRollup);
+  const requiredChecks = stringArray(charter.required_checks);
+  const checkNames = new Set(checks.map((item) => item.name));
+  const approvals = Array.isArray(payload.reviews)
+    ? payload.reviews
+        .filter((item) => cleanString(item?.state).toUpperCase() === "APPROVED")
+        .map((item) => cleanString(item?.author?.login))
+        .filter(Boolean)
+    : [];
+  return {
+    available: true,
+    url: cleanString(payload.url) || null,
+    number: Number.isInteger(payload.number) ? payload.number : null,
+    title: cleanString(payload.title) || null,
+    is_draft: payload.isDraft === true,
+    mergeable: cleanString(payload.mergeable) || null,
+    merge_state_status: cleanString(payload.mergeStateStatus) || null,
+    review_decision: cleanString(payload.reviewDecision) || null,
+    approvals,
+    human_approved: cleanString(payload.reviewDecision) === "APPROVED" || approvals.length > 0,
+    head_branch: cleanString(payload.headRefName) || null,
+    head_sha: cleanString(payload.headRefOid) || null,
+    repository:
+      cleanString(payload.headRepositoryOwner?.login) && cleanString(payload.headRepository?.name)
+        ? `${cleanString(payload.headRepositoryOwner.login)}/${cleanString(payload.headRepository.name)}`
+        : null,
+    base_branch: cleanString(payload.baseRefName) || null,
+    checks,
+    checks_present: checks.length > 0,
+    checks_passing:
+      checks.length > 0 && checks.every((item) => item.state === "success"),
+    required_checks_present: requiredChecks.every((name) => checkNames.has(name)),
+    error: null,
+  };
+}
+
+function normalizeChecks(value) {
+  if (!Array.isArray(value)) return [];
+  return value.map((item) => {
+    const name = cleanString(item?.name || item?.context || item?.workflowName) || "unknown";
+    const status = cleanString(item?.status || item?.state).toUpperCase();
+    const conclusion = cleanString(item?.conclusion || item?.state).toUpperCase();
+    let state = "pending";
+    if (SUCCESS_CONCLUSIONS.has(conclusion)) state = "success";
+    if (FAILURE_CONCLUSIONS.has(conclusion)) state = "failure";
+    if (status === "COMPLETED" && !conclusion) state = "failure";
+    return { name, status: status || null, conclusion: conclusion || null, state };
+  });
+}
+
+async function command(runCommand, file, args, cwd) {
+  try {
+    const result = await runCommand(file, args, { cwd, maxBuffer: 1024 * 1024 });
+    return { ok: true, stdout: cleanString(result?.stdout), error: null };
+  } catch (error) {
+    return {
+      ok: false,
+      stdout: cleanString(error?.stdout),
+      error: cleanString(error?.stderr || error?.message) || `${file} failed.`,
+    };
+  }
+}
+
+function lines(value) {
+  return String(value || "")
+    .split(/\r?\n/)
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function unavailable(error) {
+  return {
+    available: false,
+    checks: [],
+    checks_present: false,
+    checks_passing: false,
+    required_checks_present: false,
+    error,
+  };
+}