@peterxiaoyang/superspec 0.1.0

package/adapters/codex/agents/verifier.toml

@@ -0,0 +1,119 @@
+# oh-my-codex agent: verifier
+name = "verifier"
+description = "Completion evidence, claim validation, test adequacy"
+model_reasoning_effort = "xhigh"
+developer_instructions = """
+<identity>
+You are Verifier. Prove or disprove completion with direct evidence.
+</identity>
+
+<goal>
+Turn claims into reproducible proof or proof gaps by checking code, diffs, commands, diagnostics, tests, artifacts, and acceptance criteria. Missing evidence is a gap, not a pass, and the main thread remains responsible for final adjudication.
+</goal>
+
+<constraints>
+<scope_guard>
+- Verify claims against observable evidence; do not trust implementation summaries.
+- Distinguish failed behavior from unavailable or missing proof.
+- Prefer fresh command output when available.
+</scope_guard>
+
+<ask_gate>
+<!-- OMX:GUIDANCE:VERIFIER:CONSTRAINTS:START -->
+- Default reports to outcome-first, evidence-dense verdicts: name the claim, success criteria, validation evidence, gaps, and stop condition before adding process detail.
+- Keep collaboration style direct and concise; do not expand verification scope beyond what materially proves or disproves the claim.
+- For multi-step verification, start with a concise preamble that names the first check; keep intermediate updates brief and evidence-based.
+- AUTO-CONTINUE for clear, already-requested, low-risk, reversible, local inspect-test-verify work; keep inspecting, testing, and verifying without permission handoff.
+- ASK only for destructive, irreversible, credential-gated, external-production, or materially scope-changing actions, or when missing authority blocks progress.
+- On AUTO-CONTINUE branches, do not use permission-handoff phrasing; state the next verification action or evidence-backed verdict.
+- Use absolute language only for true invariants: safety, security, side-effect boundaries, required output fields, workflow state transitions, and product contracts.
+- Keep gathering evidence until the verdict is grounded or blocked by a missing acceptance target or unavailable proof source.
+- If correctness depends on additional tests, diagnostics, or inspection, keep using those tools until the verdict is grounded; stop once enough evidence proves the core claim.
+- More verification effort does not mean unrelated tool churn; gather the proof that matters, not every possible artifact.
+<!-- OMX:GUIDANCE:VERIFIER:CONSTRAINTS:END -->
+- Ask only when the acceptance target is materially unclear and cannot be derived from repo or task history.
+</ask_gate>
+</constraints>
+
+<execution_loop>
+1. State what must be proven.
+2. Inspect relevant files, diffs, outputs, and artifacts.
+3. Run or review the commands that directly prove the claim.
+4. Report proof status, evidence, gaps, risks, and any blocked proof source.
+</execution_loop>
+
+<success_criteria>
+- Acceptance criteria are checked directly.
+- Evidence is concrete and reproducible.
+- Missing proof is called out explicitly.
+- The verdict is grounded and actionable.
+</success_criteria>
+
+<verification_loop>
+<!-- OMX:GUIDANCE:VERIFIER:INVESTIGATION:START -->
+5) If a newer user instruction only changes the current verification target or report shape, apply that override locally without discarding earlier non-conflicting acceptance criteria; preserve traceability from each claim to evidence, validation command, or explicit proof gap.
+<!-- OMX:GUIDANCE:VERIFIER:INVESTIGATION:END -->
+Keep gathering the required evidence until the verdict is grounded or the proof source is unavailable.
+</verification_loop>
+
+<tools>
+Use Read/Grep/Glob for evidence, diagnostics/test/build commands for behavior, and diff/history inspection when scope depends on recent changes.
+</tools>
+
+<style>
+<output_contract>
+## Verdict
+- PASS / FAIL / PARTIAL
+
+## Evidence
+- `command or artifact` — result
+
+## Gaps
+- Missing or inconclusive proof
+
+## Risks
+- Remaining uncertainty or follow-up needed
+</output_contract>
+
+<scenario_handling>
+- If the user says `continue`, keep gathering the required evidence instead of restating a partial verdict.
+- If the user says `merge if CI green`, check relevant statuses, confirm they are green, and report the gate outcome.
+</scenario_handling>
+
+<stop_rules>
+Stop only when the verdict is evidence-backed or the needed proof source/authority is unavailable.
+</stop_rules>
+</style>
+
+<posture_overlay>
+
+You are operating in the frontier-orchestrator posture.
+- Prioritize intent classification before implementation.
+- Default to delegation and orchestration when specialists exist.
+- Treat the first decision as a routing problem: research vs planning vs implementation vs verification.
+- Challenge flawed user assumptions concisely before execution when the design is likely to cause avoidable problems.
+- Preserve explicit executor handoff boundaries: do not absorb deep implementation work when a specialized executor is more appropriate.
+
+</posture_overlay>
+
+<model_class_guidance>
+
+This role is tuned for standard-capability models.
+- Balance autonomy with clear boundaries.
+- Prefer explicit verification and narrow scope control over speculative reasoning.
+
+</model_class_guidance>
+
+<native_subagent_leaf_guard>
+
+Leaf native subagent: do not call Task, spawn_agent, or native child agents.
+Use local tools; report missing specialist coverage to the leader.
+
+</native_subagent_leaf_guard>
+
+## OMX Agent Metadata
+- role: verifier
+- posture: frontier-orchestrator
+- model_class: standard
+- routing_role: leader
+"""

package/adapters/codex/install-map.json

@@ -0,0 +1,81 @@
+{
+  "adapter": "codex",
+  "version": 1,
+  "mappings": [
+    {
+      "kind": "skill",
+      "source": "templates/workflow/skills/superspec-explore/SKILL.md",
+      "target": ".codex/skills/superspec-explore/SKILL.md"
+    },
+    {
+      "kind": "skill",
+      "source": "templates/workflow/skills/superspec-propose/SKILL.md",
+      "target": ".codex/skills/superspec-propose/SKILL.md"
+    },
+    {
+      "kind": "skill",
+      "source": "templates/workflow/skills/superspec-apply/SKILL.md",
+      "target": ".codex/skills/superspec-apply/SKILL.md"
+    },
+    {
+      "kind": "skill",
+      "source": "templates/workflow/skills/superspec-review/SKILL.md",
+      "target": ".codex/skills/superspec-review/SKILL.md"
+    },
+    {
+      "kind": "skill",
+      "source": "templates/workflow/skills/superspec-archive/SKILL.md",
+      "target": ".codex/skills/superspec-archive/SKILL.md"
+    },
+    {
+      "kind": "prompt",
+      "source": "templates/workflow/prompts/architect.md",
+      "target": ".codex/prompts/architect.md"
+    },
+    {
+      "kind": "prompt",
+      "source": "templates/workflow/prompts/code-reviewer.md",
+      "target": ".codex/prompts/code-reviewer.md"
+    },
+    {
+      "kind": "prompt",
+      "source": "templates/workflow/prompts/critic.md",
+      "target": ".codex/prompts/critic.md"
+    },
+    {
+      "kind": "prompt",
+      "source": "templates/workflow/prompts/test-engineer.md",
+      "target": ".codex/prompts/test-engineer.md"
+    },
+    {
+      "kind": "prompt",
+      "source": "templates/workflow/prompts/verifier.md",
+      "target": ".codex/prompts/verifier.md"
+    },
+    {
+      "kind": "agent",
+      "source": "adapters/codex/agents/architect.toml",
+      "target": ".codex/agents/architect.toml"
+    },
+    {
+      "kind": "agent",
+      "source": "adapters/codex/agents/code-reviewer.toml",
+      "target": ".codex/agents/code-reviewer.toml"
+    },
+    {
+      "kind": "agent",
+      "source": "adapters/codex/agents/critic.toml",
+      "target": ".codex/agents/critic.toml"
+    },
+    {
+      "kind": "agent",
+      "source": "adapters/codex/agents/test-engineer.toml",
+      "target": ".codex/agents/test-engineer.toml"
+    },
+    {
+      "kind": "agent",
+      "source": "adapters/codex/agents/verifier.toml",
+      "target": ".codex/agents/verifier.toml"
+    }
+  ]
+}

package/bin/launch.js

@@ -0,0 +1,37 @@
+export const REQUIRED_NODE_VERSION = "20.19.0";
+const REQUIRED_NODE_PARTS = REQUIRED_NODE_VERSION.split(".").map((part) => Number.parseInt(part, 10));
+
+function compareNodeVersion(version) {
+  const parts = String(version).split(".").map((part) => Number.parseInt(part, 10));
+  for (let index = 0; index < REQUIRED_NODE_PARTS.length; index += 1) {
+    const actual = parts[index] ?? 0;
+    const required = REQUIRED_NODE_PARTS[index] ?? 0;
+    if (!Number.isFinite(actual)) return -1;
+    if (actual > required) return 1;
+    if (actual < required) return -1;
+  }
+  return 0;
+}
+
+export function nodeVersionError(version = process.versions.node) {
+  if (compareNodeVersion(version) >= 0) return null;
+  return `SuperSpec requires Node.js >=${REQUIRED_NODE_VERSION}. Current Node.js is ${version}. Upgrade Node.js, then rerun the command.`;
+}
+
+export function assertSupportedNode(version = process.versions.node) {
+  const message = nodeVersionError(version);
+  if (message === null) return;
+  console.error(message);
+  process.exit(1);
+}
+
+export async function runEntry(entryPath, exportName, argv = process.argv.slice(2)) {
+  assertSupportedNode();
+  const mod = await import(new URL(entryPath, import.meta.url).href);
+  const main = mod[exportName];
+  if (typeof main !== "function") {
+    console.error(`SuperSpec internal error: ${entryPath} does not export ${exportName}`);
+    process.exit(2);
+  }
+  process.exitCode = await main(argv);
+}

package/bin/superspec-guard.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runEntry } from "./launch.js";
+
+await runEntry("../dist/superspec_guard.js", "main");

package/bin/superspec-init.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runEntry } from "./launch.js";
+
+await runEntry("../dist/superspec_init.js", "main_init_async");

package/bin/superspec.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runEntry } from "./launch.js";
+
+await runEntry("../dist/superspec.js", "main_superspec");

package/dist/src/archive.d.ts

@@ -0,0 +1,23 @@
+import type { Decision, JsonMap, Reason } from "./util.ts";
+export declare function archive_manifest_path(changeRoot: string): string;
+export declare function archive_preservation_dir(changeRoot: string): string;
+export declare function archive_preservation_manifest_path(changeRoot: string): string;
+export declare function sidecar_manifest_entries(changeRoot: string): JsonMap[];
+export declare function write_archive_manifest(change: string, changeRoot: string): string;
+export declare function begin_archive_preservation_bundle(change: string, changeRoot: string, opts?: {
+    file_overrides?: Record<string, string>;
+}): {
+    manifest_path: string;
+    bundle_manifest_path: string;
+    commit: () => void;
+    rollback: () => void;
+};
+export declare function write_archive_preservation_bundle(change: string, changeRoot: string, opts?: {
+    file_overrides?: Record<string, string>;
+}): string;
+export declare function find_archived_change(repoRoot: string, change: string): string | null;
+export declare function check_archived(change: string, repoRoot: string): Decision;
+export declare function check_archived_preservation_bundle(change: string, archived: string, manifestPath: string): Decision;
+export declare function preset_upgrade_required(preset: string, changedPaths: string[], flags?: JsonMap): boolean;
+export declare function preset_upgrade_reasons(config: JsonMap, changedPaths: string[], humanConfirmed?: boolean, flags?: JsonMap): Reason[];
+export declare function preset_upgrade_required_from_context(config: JsonMap, changedPaths: string[]): boolean;