@awak-app/simy-cli 0.5.0 → 0.5.1

package/src/codex-plugins/simy/skills/agentic-delivery-loop/references/state-and-receipts.md

@@ -0,0 +1,142 @@
+# State and Receipt Contract
+
+Read this reference for multi-attempt, resumable, cross-repository, concurrent,
+merge, deployment, paid, or externally mutating work.
+
+## Delivery snapshot
+
+Persist one controller-owned snapshot with at least:
+
+- `run_id`, `state`, monotonic `revision`, and terminal disposition;
+- immutable explicit conditions and their stable digest;
+- repository, base SHA, head SHA, companion SHAs, merge SHA, image digests, and
+  deployed revision;
+- target environments, user journey, user/tenant fixture identities, and
+  required artifacts;
+- applicable gates and their current status;
+- attempt number, retry/time/cost budgets, and failure fingerprints;
+- append-only receipt IDs, evidence references, timestamps, and cleanup state.
+
+Use compare-and-set or an equivalent single-writer protocol. Replaying the same
+receipt must be a no-op. Reusing an idempotency key with different content is
+an integrity failure.
+
+## Typed receipts
+
+Use the smallest applicable receipts rather than free-form completion claims:
+
+- `CharterReceipt`
+- `FailureReproductionReceipt`
+- `ImplementationReceipt`
+- `LocalVerificationReceipt`
+- `IndependentReviewReceipt`
+- `PRCIReceipt`
+- `IntegrationVerificationReceipt`
+- `ContainerEnvironmentReceipt`
+- `ChromeUserJourneyReceipt`
+- `MergeReceipt`
+- `DeploymentIdentityReceipt`
+- `HealthReceipt`
+- `LiveEvidenceReceipt`
+- `CleanupReceipt`
+- `CompletionReceipt`
+- `FailureReceipt`
+
+Each receipt should contain:
+
+- schema version, Run ID, module, result ID, input digest, idempotency key, and
+  production time;
+- `success`, `retryable_error`, or `terminal_error`;
+- source revisions and environment identity;
+- executed action and observed result;
+- evidence references such as commands, exit codes, logs, screenshots, video,
+  network traces, DB rows, artifact hashes, CI/deploy URLs, and timestamps;
+- a typed error category and retryability when unsuccessful.
+
+## Monitor verdict and policy action
+
+The semantic monitor may emit:
+
+```text
+status:
+  on_track
+  insufficient_evidence
+  goal_drift
+  retryable_failure
+  needs_hil
+  blocked
+  completed
+
+recommended_action:
+  continue
+  retry_current
+  propose_replan
+  request_hil
+  abort
+  complete
+```
+
+The deterministic policy gate checks authorization, applicable state routes,
+revision identity, evidence completeness, idempotency, retry budget, repeated
+failure fingerprints, and external-effect ambiguity before accepting the
+recommendation.
+
+Do not expose hidden chain-of-thought. Publish only the typed verdict, concise
+reason, selected action, and evidence references.
+
+## Evidence invalidation
+
+Evidence is revision-bound:
+
+| Change | Invalidate |
+|---|---|
+| Charter or explicit success conditions | All affected downstream gates |
+| Head SHA or generated source changes | Local, CI, integration, container, and live evidence |
+| Base SHA or companion revision changes | Integration and later evidence |
+| Container image digest changes | Container user journey and later runtime evidence |
+| Merge SHA changes | Deployment identity and live evidence |
+| Deployed revision changes | Health and live evidence |
+| Browser profile, tenant, or fixture changes | Affected user-journey evidence |
+
+Do not discard historical receipts; mark them superseded for the current gate.
+
+## Failure handling
+
+Classify failures before retrying:
+
+- code defect;
+- stale or wrong revision;
+- environment/configuration drift;
+- weak or contaminated fixture;
+- external provider, authorization, rate limit, or timeout;
+- contract/schema drift;
+- persistence, concurrency, projection, cache, or replica race;
+- evidence collection failure.
+
+Retry only when the classification and policy permit it. Reconcile ambiguous
+external effects before retrying. Preserve passing work and repair the smallest
+affected surface. Repeated fingerprints require root-cause repair, replan, or
+human input rather than identical retries.
+
+## Completion predicate
+
+For the full delivery mode:
+
+```text
+done =
+  reproduction_verified
+  && locally_verified
+  && pr_ci_green
+  && integration_verified
+  && user_like_local_verified
+  && merged
+  && deployed_exact_revision
+  && health_verified
+  && live_verified
+  && cleanup_verified
+  && completion_receipt_created
+```
+
+Remove only genuinely non-applicable terms and record why. If merge or deploy
+is outside current authority, stop at the highest proven pre-authority state.
+

package/src/codex-plugins/simy/skills/pr-review/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: pr-review
+description: Review the current or specified pull request for correctness, regressions, security, evidence gaps, and SIMY repository-policy violations. Use when the user asks SIMY to review a PR. Do not use for implementing fixes unless separately requested.
+---
+
+# SIMY pull request review
+
+Use the current Codex thread to resolve the intended behavior, then inspect the actual pull request and repository evidence.
+
+## Review contract
+
+- Resolve the PR from an explicit URL/number or the current branch. If it cannot be resolved unambiguously, ask for the smallest missing identifier.
+- Read applicable `AGENTS.md` instructions, the complete diff, changed-file context, tests, and current check state.
+- Focus on behaviorally meaningful findings: correctness, authorization and tenant boundaries, data loss, concurrency and retries, compatibility, security, and missing regression evidence.
+- Report findings first, ordered by severity, with precise file and line references. Explain impact and the smallest credible fix.
+- Distinguish verified defects from questions or residual risks. If there are no findings, say so and name the remaining verification gaps.
+- Do not edit code, post a review, approve, merge, deploy, or send external messages unless the user separately authorizes that action.
+- Never call a PR merged merely because auto-merge is enabled; verify its remote state and `mergedAt` when merge status matters.

package/src/codex-plugins/simy/skills/pr-review/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "SIMY PR Review"
+  short_description: "Review a pull request with SIMY evidence rules"
+  default_prompt: "Use $pr-review to review the current pull request."
+policy:
+  allow_implicit_invocation: true

package/src/codex-plugins/simy/skills/sqm-loop/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: sqm-loop
+description: Run the SIMY Software Quality Monitor against the repository and changes discussed in the current Codex thread. Use when the user asks SIMY to start SQM, quality-check the current work, or prepare a PR quality proof.
+---
+
+# SIMY SQM Loop
+
+Treat the current Codex thread, its attachments, and the active repository as the request context. Convert that context into explicit quality expectations, then verify the actual repository state; do not merely summarize the conversation.
+
+## Run the quality loop
+
+1. Identify the repository root and the user-visible behavior or incident discussed in the current thread.
+2. Preserve unrelated user changes and follow repository instructions.
+3. Run `simy sqm min-check` from the repository root.
+4. Run `simy sqm check --proof proof.json --signed-evidence proof.json.signed.json`.
+5. Read `proof.json` and require `outcome.status` to be `passed` before reporting success or proposing a pull request.
+6. Report the checked repository/revision, proof paths, outcome, blockers, and any evidence gap.
+
+If implementation is required before the check can pass, obtain or confirm the user's change authorization and make the smallest relevant repair. A request to run SQM alone does not authorize unrelated edits, a PR, merge, deployment, or external messages.
+
+Do not substitute an informal LLM review for SQM. If the CLI is unavailable, authentication is missing, or the proof is not passed, stop at the highest verified state and report the exact blocker.

package/src/codex-plugins/simy/skills/sqm-loop/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "SIMY SQM Loop"
+  short_description: "Run SQM from the current Codex thread"
+  default_prompt: "Use $sqm-loop to quality-check the work in this thread."
+policy:
+  allow_implicit_invocation: true

package/src/sqm/agent-skill.js

@@ -0,0 +1,373 @@
+import { createHash } from "node:crypto";
+import { cp, lstat, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const SQM_AGENT_SKILL_ID = "simy-sqm-pr-check";
+export const SQM_AGENT_SKILL_VERSION = "2.0.0";
+export const SIMY_CODEX_PLUGIN_ID = "simy";
+export const SIMY_CODEX_PLUGIN_VERSION = "0.1.0";
+
+const BUNDLED_CODEX_PLUGIN_ROOT = fileURLToPath(
+  new URL(`../codex-plugins/${SIMY_CODEX_PLUGIN_ID}/`, import.meta.url),
+);
+const MANAGED_PLUGIN_AUTHOR = "Specialist Doctors Inc.";
+const MANAGED_MARKETPLACE_SOURCE = `./plugins/${SIMY_CODEX_PLUGIN_ID}`;
+
+const SKILL_CONTENT = `---
+name: ${SQM_AGENT_SKILL_ID}
+description: Run SIMY Software Quality Monitor checks before creating or proposing a pull request. Use whenever preparing, opening, or updating a PR.
+---
+
+# SIMY SQM PR check
+
+Before creating or proposing a pull request:
+
+1. Run \`simy sqm min-check\` from the repository root.
+2. Run \`simy sqm check --proof proof.json --signed-evidence proof.json.signed.json\`.
+3. Read \`proof.json\` and require \`outcome.status\` to be \`passed\`.
+4. If either command fails, SQM is unavailable, or the proof is not passed, stop. Report the exact blocker and do not create the PR.
+5. Include the proof path and SQM outcome in the PR body when the check passes.
+
+Do not replace SQM with an LLM review, and do not claim the check passed without reading the generated proof.
+`;
+
+const HOOK_SCRIPT = `#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+
+let raw = "";
+for await (const chunk of process.stdin) raw += chunk;
+let payload = {};
+try { payload = raw ? JSON.parse(raw) : {}; } catch { process.exit(0); }
+const command = String(payload?.tool_input?.command || payload?.tool_input?.cmd || "");
+if (!/(^|[;&|]\\s*)gh\\s+pr\\s+create(?:\\s|$)/.test(command)) process.exit(0);
+
+for (const args of [["sqm", "min-check"], ["sqm", "check"]]) {
+  const result = spawnSync("simy", args, { cwd: process.cwd(), stdio: "inherit" });
+  if (result.error || result.status !== 0) {
+    console.error(result.error ? \`SIMY SQM PR gate failed: \${result.error.message}\` : \`SIMY SQM PR gate blocked the PR (exit \${result.status}).\`);
+    process.exit(2);
+  }
+}
+`;
+
+const TARGETS = {
+  codex: [".agents", "skills", SQM_AGENT_SKILL_ID, "SKILL.md"],
+  claude: [".claude", "skills", SQM_AGENT_SKILL_ID, "SKILL.md"],
+};
+
+export function sqmAgentSkillDigest() {
+  return digestText(SKILL_CONTENT);
+}
+
+export async function inspectSqmAgentSkill({ home = homedir() } = {}) {
+  const digest = sqmAgentSkillDigest();
+  const codexPlugin = await inspectCodexPlugin({ home });
+  const hookPath = managedHookPath(home);
+  const installedHookDigest = await fileDigest(hookPath);
+  const hookMatches = installedHookDigest === digestText(HOOK_SCRIPT);
+  const platforms = {};
+  for (const [platform, segments] of Object.entries(TARGETS)) {
+    const target = path.join(home, ...segments);
+    const installedDigest = await fileDigest(target);
+    const skillMatches = installedDigest === digest;
+    const hookConfigured = await hasManagedHook(platform, home, hookPath);
+    const platformExtraMatches = platform !== "codex" || codexPlugin.installed;
+    platforms[platform] = {
+      path: target,
+      hook_path: platformHookConfigPath(platform, home),
+      installed: skillMatches && hookMatches && hookConfigured && platformExtraMatches,
+      state:
+        installedDigest === null ||
+        !hookConfigured ||
+        installedHookDigest === null ||
+        (platform === "codex" && codexPlugin.state === "missing")
+          ? "missing"
+          : skillMatches && hookMatches && platformExtraMatches
+            ? "installed"
+            : "outdated",
+      ...(platform === "codex" ? { plugin: codexPlugin } : {}),
+    };
+  }
+  return {
+    skill_id: SQM_AGENT_SKILL_ID,
+    version: SQM_AGENT_SKILL_VERSION,
+    digest: `sha256:${digest}`,
+    enforcement: "pre_tool_use",
+    codex_plugin: codexPlugin,
+    installed: Object.values(platforms).every((entry) => entry.installed),
+    platforms,
+  };
+}
+
+export async function installSqmAgentSkill({ home = homedir(), platforms = Object.keys(TARGETS) } = {}) {
+  const requested = [...new Set(platforms)];
+  if (!requested.length || requested.some((platform) => !Object.hasOwn(TARGETS, platform))) {
+    throw new Error("platforms must contain codex and/or claude");
+  }
+  const hookPath = managedHookPath(home);
+  if (requested.includes("codex")) await installCodexPlugin({ home });
+  await atomicText(hookPath, HOOK_SCRIPT, 0o700);
+  for (const platform of requested) {
+    await atomicText(path.join(home, ...TARGETS[platform]), SKILL_CONTENT, 0o600);
+    await installManagedHook(platform, home, hookPath);
+  }
+  return inspectSqmAgentSkill({ home });
+}
+
+export async function inspectCodexPlugin({ home = homedir() } = {}) {
+  const expectedDigest = await directoryDigest(BUNDLED_CODEX_PLUGIN_ROOT);
+  const target = codexPluginPath(home);
+  const installedDigest = await directoryDigest(target, { missing: null });
+  const marketplacePath = codexMarketplacePath(home);
+  const marketplace = await readJsonFile(marketplacePath, { missing: null, invalid: null });
+  const entry = Array.isArray(marketplace?.plugins)
+    ? marketplace.plugins.find((candidate) => candidate?.name === SIMY_CODEX_PLUGIN_ID)
+    : null;
+  const marketplaceMatches = isManagedMarketplaceEntry(entry);
+  const filesMatch = installedDigest === expectedDigest;
+  return {
+    plugin_id: SIMY_CODEX_PLUGIN_ID,
+    version: SIMY_CODEX_PLUGIN_VERSION,
+    path: target,
+    marketplace_path: marketplacePath,
+    digest: `sha256:${expectedDigest}`,
+    installed: filesMatch && marketplaceMatches,
+    state:
+      installedDigest === null || !entry
+        ? "missing"
+        : filesMatch && marketplaceMatches
+          ? "installed"
+          : "outdated",
+  };
+}
+
+async function installCodexPlugin({ home }) {
+  const target = codexPluginPath(home);
+  const marketplacePath = codexMarketplacePath(home);
+  const marketplace = await readJsonFile(marketplacePath, { missing: {}, invalid: "throw" });
+  if (!marketplace || typeof marketplace !== "object" || Array.isArray(marketplace)) {
+    throw new Error(`${marketplacePath} must contain a JSON object before SIMY can install its Codex plugin.`);
+  }
+  const plugins = Array.isArray(marketplace.plugins) ? marketplace.plugins : [];
+  const collision = plugins.find((entry) => entry?.name === SIMY_CODEX_PLUGIN_ID);
+  if (collision && !isManagedMarketplaceEntry(collision)) {
+    throw new Error(`Codex marketplace already contains an unmanaged ${SIMY_CODEX_PLUGIN_ID} plugin entry.`);
+  }
+  await assertManagedPluginTarget(target);
+
+  const staged = path.join(path.dirname(target), `.${SIMY_CODEX_PLUGIN_ID}.${process.pid}.tmp`);
+  const backup = path.join(path.dirname(target), `.${SIMY_CODEX_PLUGIN_ID}.${process.pid}.bak`);
+  await mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+  await rm(staged, { recursive: true, force: true });
+  await rm(backup, { recursive: true, force: true });
+  await cp(BUNDLED_CODEX_PLUGIN_ROOT, staged, { recursive: true, errorOnExist: true });
+  let backedUp = false;
+  try {
+    if (await pathExists(target)) {
+      await rename(target, backup);
+      backedUp = true;
+    }
+    await rename(staged, target);
+    if (backedUp) await rm(backup, { recursive: true, force: true });
+  } catch (error) {
+    await rm(staged, { recursive: true, force: true });
+    if (backedUp && !(await pathExists(target))) await rename(backup, target);
+    throw error;
+  }
+
+  const nextMarketplace = {
+    ...marketplace,
+    name: typeof marketplace.name === "string" && marketplace.name.trim()
+      ? marketplace.name
+      : "personal",
+    interface: {
+      displayName: "Personal",
+      ...(marketplace.interface && typeof marketplace.interface === "object"
+        ? marketplace.interface
+        : {}),
+    },
+    plugins: [
+      ...plugins.filter((entry) => entry?.name !== SIMY_CODEX_PLUGIN_ID),
+      managedMarketplaceEntry(),
+    ],
+  };
+  await atomicText(marketplacePath, `${JSON.stringify(nextMarketplace, null, 2)}\n`, 0o600);
+}
+
+function managedMarketplaceEntry() {
+  return {
+    name: SIMY_CODEX_PLUGIN_ID,
+    source: { source: "local", path: MANAGED_MARKETPLACE_SOURCE },
+    policy: { installation: "INSTALLED_BY_DEFAULT", authentication: "ON_INSTALL" },
+    category: "Developer Tools",
+  };
+}
+
+function isManagedMarketplaceEntry(entry) {
+  return entry?.name === SIMY_CODEX_PLUGIN_ID &&
+    entry?.source?.source === "local" &&
+    entry?.source?.path === MANAGED_MARKETPLACE_SOURCE &&
+    entry?.policy?.installation === "INSTALLED_BY_DEFAULT" &&
+    entry?.policy?.authentication === "ON_INSTALL";
+}
+
+async function assertManagedPluginTarget(target) {
+  if (!(await pathExists(target))) return;
+  const manifest = await readJsonFile(path.join(target, ".codex-plugin", "plugin.json"), {
+    missing: null,
+    invalid: null,
+  });
+  if (manifest?.name !== SIMY_CODEX_PLUGIN_ID || manifest?.author?.name !== MANAGED_PLUGIN_AUTHOR) {
+    throw new Error(`${target} already exists and is not a SIMY-managed Codex plugin.`);
+  }
+}
+
+function codexPluginPath(home) {
+  return path.join(home, "plugins", SIMY_CODEX_PLUGIN_ID);
+}
+
+function codexMarketplacePath(home) {
+  return path.join(home, ".agents", "plugins", "marketplace.json");
+}
+
+function managedHookPath(home) {
+  return path.join(home, ".simy", "integrations", "sqm-agent", "pre-pr-hook.mjs");
+}
+
+function platformHookConfigPath(platform, home) {
+  return platform === "codex"
+    ? path.join(home, ".codex", "hooks.json")
+    : path.join(home, ".claude", "settings.json");
+}
+
+function managedHookGroup(hookPath) {
+  return {
+    matcher: "Bash",
+    hooks: [
+      {
+        type: "command",
+        command: `node ${JSON.stringify(hookPath)}`,
+        statusMessage: "Running SIMY SQM PR gate",
+      },
+    ],
+  };
+}
+
+async function installManagedHook(platform, home, hookPath) {
+  const target = platformHookConfigPath(platform, home);
+  let config = {};
+  try {
+    config = JSON.parse(await readFile(target, "utf8"));
+  } catch (error) {
+    if (error?.code !== "ENOENT") {
+      throw new Error(`${target} must contain valid JSON before SIMY can merge the SQM hook.`);
+    }
+  }
+  const hooks = config && typeof config === "object" && !Array.isArray(config)
+    ? { ...(config.hooks || {}) }
+    : {};
+  const existing = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
+  hooks.PreToolUse = [
+    ...existing.filter((group) => !groupContainsManagedHook(group)),
+    managedHookGroup(hookPath),
+  ];
+  await atomicText(target, `${JSON.stringify({ ...config, hooks }, null, 2)}\n`, 0o600);
+}
+
+async function hasManagedHook(platform, home, hookPath) {
+  try {
+    const config = JSON.parse(await readFile(platformHookConfigPath(platform, home), "utf8"));
+    return Array.isArray(config?.hooks?.PreToolUse) &&
+      config.hooks.PreToolUse.some((group) => groupContainsManagedHook(group, hookPath));
+  } catch (error) {
+    if (error?.code === "ENOENT" || error instanceof SyntaxError) return false;
+    throw error;
+  }
+}
+
+function groupContainsManagedHook(group, expectedPath = null) {
+  if (!Array.isArray(group?.hooks)) return false;
+  return group.hooks.some((hook) => {
+    const command = typeof hook?.command === "string" ? hook.command : "";
+    return expectedPath
+      ? command === `node ${JSON.stringify(expectedPath)}`
+      : command.includes("/.simy/integrations/sqm-agent/pre-pr-hook.mjs") ||
+          command.includes("\\.simy\\integrations\\sqm-agent\\pre-pr-hook.mjs");
+  });
+}
+
+async function fileDigest(target) {
+  try {
+    return digestText(await readFile(target, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+async function directoryDigest(root, { missing = "throw" } = {}) {
+  let rootStat;
+  try {
+    rootStat = await lstat(root);
+  } catch (error) {
+    if (error?.code === "ENOENT" && missing !== "throw") return missing;
+    throw error;
+  }
+  if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+    throw new Error(`${root} must be a real directory.`);
+  }
+  const hash = createHash("sha256");
+  const visit = async (directory, prefix = "") => {
+    const entries = await readdir(directory, { withFileTypes: true });
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+      const target = path.join(directory, entry.name);
+      if (entry.isSymbolicLink()) throw new Error(`${target} must not be a symbolic link.`);
+      if (entry.isDirectory()) {
+        await visit(target, relative);
+        continue;
+      }
+      if (!entry.isFile()) throw new Error(`${target} must be a regular file.`);
+      hash.update(relative).update("\0").update(await readFile(target)).update("\0");
+    }
+  };
+  await visit(root);
+  return hash.digest("hex");
+}
+
+async function readJsonFile(target, { missing, invalid }) {
+  try {
+    return JSON.parse(await readFile(target, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return missing;
+    if (error instanceof SyntaxError) {
+      if (invalid !== "throw") return invalid;
+      throw new Error(`${target} must contain valid JSON before SIMY can update it.`);
+    }
+    throw error;
+  }
+}
+
+async function pathExists(target) {
+  try {
+    await lstat(target);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function digestText(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+async function atomicText(target, content, mode) {
+  await mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+  const temporary = `${target}.${process.pid}.tmp`;
+  await writeFile(temporary, content, { encoding: "utf8", mode });
+  await rename(temporary, target);
+}