@peterxiaoyang/superspec 0.1.0

package/dist/src/util.js

@@ -0,0 +1,442 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { spawnSync } from "node:child_process";
+export const SCHEMA_VERSION = 1;
+export const GUARD_VERSION = "superspec-guard@1";
+export const CONFIG_FILENAME = "config.yaml";
+export const STATE_FILENAME = "superspec-state.json";
+export const STATE_LOCK_FILENAME = "superspec-state.lock";
+export const PROJECT_CONFIG_ALIASES = [
+    ".superspec.yaml",
+    ".superspec.yml",
+    "superspec.yaml",
+    "superspec.yml",
+    "superspec.json",
+    ".superspecrc",
+    ".superspec/config.json",
+];
+export const CHANGE_CONFIG_ALIASES = PROJECT_CONFIG_ALIASES;
+export const STATE_ALIASES = [
+    ".superspec/state.json",
+    ".superspec/state.lock",
+    ".superspec/superspec_state.json",
+    ".superspec/superspec-state.yaml",
+];
+export const REQUIRED_SIDECAR_DIRS = [
+    "artifacts",
+    "evidence/discovery",
+    "evidence/design",
+    "evidence/invariants",
+    "evidence/test-contract",
+    "evidence/tasks",
+    "evidence/red",
+    "evidence/green",
+    "evidence/reviews",
+    "evidence/verification",
+    "evidence/archive",
+    "handoffs",
+    "reports",
+    "raw",
+];
+export const BUILTIN_CONFIG = {
+    preset: "full",
+    commands: {},
+    roles: {},
+    rules: {},
+    trust: { v1_evidence: "audit-only" },
+    archive: {},
+};
+export const ALLOWED_CONFIG_KEYS = new Set(Object.keys(BUILTIN_CONFIG));
+export const EVIDENCE_STATUSES = new Set(["pass", "fail", "blocked", "superseded"]);
+// FIX-7 (audit C-3): kind whitelist assembled from every kind the guard recognizes plus the
+// conventional role-report kinds. A typo'd kind must fail loudly (evidence_unknown_kind)
+// instead of silently surfacing as "missing evidence" at some downstream gate.
+export const EVIDENCE_KINDS = new Set([
+    "review",
+    "subagent_report",
+    "workflow_review",
+    "source_guidance",
+    "main_adjudication",
+    "verification_review",
+    "final_test",
+    "test_run",
+    "alternative_verification",
+    "manual_verification",
+    "task_reopen",
+    "task_reopen_resolved",
+    "human_confirmation",
+    "superseded",
+    // Disclosure fixed-point loop (DISC Phase 1): user-visible review disclosure evidence.
+    "main_review_digest",
+    "user_review_decision",
+    "review_standing_authorization",
+]);
+// FIX-7 (audit C-3): gates where the guard consumes human_confirmation evidence.
+// A confirmation recorded against any other gate is unreachable and therefore a mistake.
+// FIX-8 (audit A-5) adds the previously anchor-less human pause points:
+// apply isolation choice, apply-phase scope expansion, and verify-failure disposition.
+export const HUMAN_CONFIRMATION_GATES = new Set([
+    "design_complete",
+    "invariants_reviewed",
+    "archive_ready",
+    "preset_upgrade",
+    "branch_handling",
+    "apply_isolation",
+    "scope_expansion",
+    "verify_failure_handling",
+]);
+export const NO_TDD_REASONS = new Set([
+    "documentation-only",
+    "configuration-only",
+    "test-only-refactor",
+    "mechanical-rename",
+    "generated-artifact-only",
+    "non-executable-spec-change",
+]);
+export const TDD_MODES = new Set(["new-behavior", "behavior-preserving-refactor", "hotfix"]);
+export const ROLE_EVIDENCE_FIELDS = ["agent_role", "agent_id", "prompt_ref", "output_ref", "source_anchors", "target_refs"];
+export const SELF_REVIEW_MARKERS = new Set(["main", "main-thread", "current-agent", "self", "lead", "leader", "orchestrator", "codex_exec"]);
+export const REVIEW_EVIDENCE_REQUIRED_FIELDS = ["base_ref", "head_ref", "reviewed_files"];
+export const VERIFY_EVIDENCE_REQUIRED_FIELDS = ["openspec_validate_ref", "task_matrix_ref", "invariant_matrix_ref", "scope_drift_ref", "test_evidence_refs"];
+export const REVIEW_GUIDANCE_ROLES = ["code-reviewer", "architect", "critic"];
+export const FINAL_VERIFICATION_ROLES = ["verifier", "critic"];
+export const SOURCE_GUIDANCE_REQUIRED_FIELDS = ["source_refs", "required_load_refs", "required_claim_ids"];
+export const MAIN_ADJUDICATION_REQUIRED_FIELDS = ["output_ref", "source_evidence_refs", "verification_evidence_refs", "loaded_refs", "claim_adjudications", "finding_adjudications"];
+export const MAIN_ADJUDICATION_DECISIONS = ["allow", "request_changes"];
+export const REQUEST_CHANGES_ROUTES = ["reopen_tasks", "change_update"];
+export const CLAIM_ADJUDICATION_DECISIONS = ["accept", "reject", "needs_fix"];
+export const FINDING_ADJUDICATION_DECISIONS = ["dismissed", "accepted_fixed", "accepted_deviation", "needs_fix"];
+export const FINAL_TEST_REQUIRED_FIELDS = ["test_command", "output_ref"];
+export const TASK_REOPEN_REQUIRED_FIELDS = [
+    "task_id",
+    "reopen_id",
+    "source_adjudication_evidence_id",
+    "source_guidance_evidence_id",
+    "violated_test_ids",
+    "violated_requirement_refs",
+    "invalidated_completion_evidence_ids",
+    "required_supersede_evidence_ids",
+    "completion_invalidity_class",
+    "scope_expansion",
+    "why_completion_invalid",
+    "required_fix",
+    "before_tasks_sha256",
+    "after_tasks_sha256",
+];
+export const TASK_REOPEN_RESOLVED_REQUIRED_FIELDS = [
+    "reopen_evidence_id",
+    "reopen_id",
+    "task_id",
+    "successor_completion_evidence_ids",
+    "after_tasks_sha256",
+];
+export const TASK_REOPEN_INVALIDITY_CLASSES = ["insufficient_completion_evidence"];
+export const FORBIDDEN_FIELDS = new Set([
+    "current",
+    "current_phase",
+    "current_stage",
+    "stage",
+    "stage_order",
+    "allowed_next",
+    "completed_phases",
+    "openspec_artifact_done",
+    "artifact_status",
+]);
+export const OPENSPEC_ARTIFACTS = new Set(["proposal", "specs", "design", "tasks"]);
+export const REQUIRED_OPENSPEC_CODEX_SKILLS = [
+    "openspec-explore",
+    "openspec-propose",
+    "openspec-apply-change",
+    "openspec-archive-change",
+];
+// D4 (audit G-2): SuperSpec's own workflow skills are part of the init health surface — a deleted
+// or renamed superspec-* skill must be visible at check-init, not discovered mid-workflow.
+export const REQUIRED_SUPERSPEC_WORKFLOW_SKILLS = [
+    "superspec-explore",
+    "superspec-propose",
+    "superspec-apply",
+    "superspec-review",
+    "superspec-archive",
+];
+export const REQUIRED_SUPERSPEC_AGENT_ROLES = [
+    "architect",
+    "critic",
+    "test-engineer",
+    "code-reviewer",
+    "verifier",
+];
+export const REQUIRED_OPENSPEC_CLI_SURFACES = [
+    ["instructions", "--help"],
+    ["archive", "--help"],
+    ["validate", "--help"],
+    ["status", "--help"],
+];
+export const ARTIFACT_ENTER_GATE = {
+    proposal: "explore_complete",
+    // DISC Phase 2: specs/design authoring cannot start before the proposal critic review
+    // has been run and its findings disclosed.
+    specs: "proposal_reviewed",
+    design: "proposal_reviewed",
+    tasks: "test_contract_drafted",
+};
+export const ROUTE_ORDER = {
+    init: 0,
+    explore: 1,
+    propose: 2,
+    apply: 3,
+    review: 4,
+    archive: 5,
+};
+export const ROUTE_ALIASES = {
+    start: "init",
+    proposal: "propose",
+    specs: "propose",
+    design: "propose",
+    tasks: "propose",
+    "test-contract": "propose",
+    "test-contract-drafted": "propose",
+    "test-contract-honored": "propose",
+    "business-invariants": "propose",
+    "invariants-reviewed": "propose",
+    "tasks-complete": "propose",
+    "apply-ready": "propose",
+    verify: "review",
+    verification: "review",
+    "archive-ready": "archive",
+    archived: "archive",
+    recompute: "init",
+};
+export const GATE_ALIASES = {
+    "propose.explore_linked": "explore_complete",
+    "propose.proposal_reviewed": "proposal_reviewed",
+    "propose.design_reviewed": "design_complete",
+    "propose.invariants_reviewed": "invariants_reviewed",
+    "propose.test_plan_drafted": "test_contract_drafted",
+    "propose.tasks_mapped": "tasks_complete",
+    "propose.apply_ready": "propose_complete",
+    apply_ready: "propose_complete",
+};
+export const GATE_ROUTE = {
+    explore_complete: "explore",
+    proposal_reviewed: "propose",
+    design_complete: "propose",
+    invariants_reviewed: "propose",
+    test_contract_drafted: "propose",
+    test_contract_honored: "propose",
+    tasks_complete: "propose",
+    propose_complete: "propose",
+    review_complete: "review",
+    verify_complete: "review",
+    archive_ready: "archive",
+};
+export class GuardError extends Error {
+}
+export const runtime = {};
+export function reason(code, message, refs = null) {
+    return { code, message, refs: refs ?? [] };
+}
+export function pinned_ref_key(item) {
+    return `${String(item.path)}\u0000${String(item.blob_sha)}`;
+}
+export function trustWarnings() {
+    return [
+        "v1 evidence is audit-only/self-reported unless explicitly backed by OpenSpec facts",
+        "v1 role evidence cannot mechanically prove a native subagent ran; it only checks schema, freshness, output refs, and non-direct authorship markers",
+    ];
+}
+export function allow(change, gate, opts = {}) {
+    return {
+        allowed: true,
+        decision: "allow",
+        change_id: change,
+        gate,
+        task_id: opts.task_id ?? null,
+        openspec_status_summary: opts.openspec_summary ?? {},
+        superspec_gate_summary: opts.gate_summary ?? {},
+        block_reasons: [],
+        next_allowed_actions: [],
+        trust_warnings: trustWarnings(),
+    };
+}
+export function block(change, gate, reasons, opts = {}) {
+    return {
+        allowed: false,
+        decision: "block",
+        change_id: change,
+        gate,
+        task_id: opts.task_id ?? null,
+        openspec_status_summary: opts.openspec_summary ?? {},
+        superspec_gate_summary: opts.gate_summary ?? {},
+        block_reasons: reasons,
+        next_allowed_actions: opts.next_actions ?? [],
+        trust_warnings: trustWarnings(),
+    };
+}
+export function printDecision(decision) {
+    process.stdout.write(`${JSON.stringify(decision, null, 2)}\n`);
+}
+export function runCommand(cmd, args, opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const invocation = platform === "win32" ? windowsCommandInvocation(cmd, args, opts.cwd) : { cmd, args };
+    const result = spawnSync(invocation.cmd, invocation.args, {
+        cwd: opts.cwd,
+        encoding: "utf8",
+        timeout: opts.timeout,
+    });
+    return {
+        status: result.status,
+        stdout: typeof result.stdout === "string" ? result.stdout : "",
+        stderr: typeof result.stderr === "string" ? result.stderr : "",
+        error: result.error,
+    };
+}
+export function sha256_text(text) {
+    return `sha256:${createHash("sha256").update(Buffer.from(text, "utf8")).digest("hex")}`;
+}
+export function sha256_file(filePath) {
+    if (!existsSync(filePath) || !statSync(filePath).isFile())
+        return null;
+    return `sha256:${createHash("sha256").update(readFileSync(filePath)).digest("hex")}`;
+}
+export function fingerprint_obj(obj) {
+    return sha256_text(stableJson(obj));
+}
+export function safe_within(base, candidate) {
+    if (isAbsolute(candidate) || candidate.split(/[\\/]+/).includes(".."))
+        return null;
+    const baseReal = realpathMaybe(base);
+    const resolved = resolve(base, candidate);
+    const candidateReal = resolveExistingPrefix(resolved);
+    const rel = relative(baseReal, candidateReal);
+    if (rel === "" || (!rel.startsWith("..") && !isAbsolute(rel)))
+        return candidateReal;
+    return null;
+}
+export function now() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+export function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function repr(value) {
+    if (typeof value === "string")
+        return `'${value}'`;
+    if (value === null)
+        return "None";
+    if (value === undefined)
+        return "None";
+    return JSON.stringify(value);
+}
+export function renderList(items) {
+    return `[${items.map((item) => (typeof item === "string" ? `'${item}'` : String(item))).join(", ")}]`;
+}
+function stableJson(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number")
+        return JSON.stringify(value);
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map((item) => stableJson(item)).join(", ")}]`;
+    if (isObject(value)) {
+        const parts = Object.keys(value).sort().map((key) => `${JSON.stringify(key)}: ${stableJson(value[key])}`);
+        return `{${parts.join(", ")}}`;
+    }
+    return JSON.stringify(value);
+}
+function realpathMaybe(filePath) {
+    try {
+        return realpathSync(filePath);
+    }
+    catch {
+        return resolve(filePath);
+    }
+}
+function resolveExistingPrefix(filePath) {
+    const abs = resolve(filePath);
+    if (existsSync(abs))
+        return realpathMaybe(abs);
+    const tail = [];
+    let cur = abs;
+    while (!existsSync(cur)) {
+        const parent = dirname(cur);
+        if (parent === cur)
+            return abs;
+        tail.unshift(cur.split(sep).at(-1) ?? "");
+        cur = parent;
+    }
+    return resolve(realpathMaybe(cur), ...tail);
+}
+export function walkFiles(root) {
+    const out = [];
+    if (!existsSync(root))
+        return out;
+    for (const name of readdirSync(root)) {
+        const item = join(root, name);
+        const stat = lstatSync(item);
+        if (stat.isSymbolicLink())
+            continue;
+        if (stat.isDirectory())
+            out.push(...walkFiles(item));
+        // Hardlinked files can alias content outside the change root; skip them like symlinks.
+        else if (stat.isFile() && stat.nlink <= 1)
+            out.push(item);
+    }
+    return out;
+}
+export function toPosix(pathValue) {
+    return pathValue.split(sep).join("/");
+}
+export function commandLookupInvocation(cmd, platform = process.platform) {
+    if (platform === "win32")
+        return { cmd: "where.exe", args: [cmd], shell: false };
+    return { cmd: "sh", args: ["-c", `command -v ${cmd}`], shell: false };
+}
+function resolveWindowsCommand(cmd, cwd) {
+    if (cmd.includes("\\") || cmd.includes("/") || extname(cmd))
+        return cmd;
+    const lookup = spawnSync("where.exe", [cmd], {
+        cwd,
+        encoding: "utf8",
+        timeout: 5_000,
+    });
+    if (lookup.status !== 0 || typeof lookup.stdout !== "string")
+        return cmd;
+    return lookup.stdout.split(/\r?\n/).map((line) => line.trim()).find(Boolean) ?? cmd;
+}
+export function windowsShellEscapeArg(arg) {
+    let escaped = String(arg);
+    escaped = escaped.replace(/(\\*)"/g, "$1$1\\\"");
+    escaped = escaped.replace(/(\\*)$/g, "$1$1");
+    escaped = `"${escaped}"`;
+    return escaped.replace(/([()[\]{}^=;!'+,`~&|<>%" *?])/g, "^$1");
+}
+export function windowsCmdShimInvocation(cmdPath, args, comspec = "cmd.exe") {
+    return {
+        cmd: comspec,
+        args: ["/d", "/s", "/c", [windowsShellEscapeArg(cmdPath), ...args.map(windowsShellEscapeArg)].join(" ")],
+    };
+}
+function windowsCommandInvocation(cmd, args, cwd) {
+    const resolved = resolveWindowsCommand(cmd, cwd);
+    if (/\.(?:cmd|bat)$/i.test(resolved))
+        return windowsCmdShimInvocation(resolved, args);
+    return { cmd: resolved, args };
+}
+export function commandExists(cmd, opts = {}) {
+    const lookup = commandLookupInvocation(cmd, opts.platform);
+    const proc = spawnSync(lookup.cmd, lookup.args, {
+        cwd: opts.cwd,
+        encoding: "utf8",
+        timeout: 5_000,
+        shell: lookup.shell,
+    });
+    return !proc.error && proc.status === 0;
+}
+export function deepEqual(a, b) {
+    return stableJson(a) === stableJson(b);
+}

package/dist/superspec.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+export * from "./src/init_cli.ts";
+export * from "./src/cli.ts";
+export declare function main_superspec(argv?: string[]): Promise<number>;

package/dist/superspec.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+export * from "./src/init_cli.js";
+export * from "./src/cli.js";
+import { main } from "./src/cli.js";
+import { main_init_async } from "./src/init_cli.js";
+function realpathMaybe(filePath) {
+    try {
+        return realpathSync(filePath);
+    }
+    catch {
+        return resolve(filePath);
+    }
+}
+function help() {
+    return [
+        "usage: superspec <command> [options]",
+        "",
+        "commands:",
+        "  init        install SuperSpec Codex surfaces (asks project/user; default project)",
+        "  update      update manifest-managed SuperSpec surfaces",
+        "  uninstall   remove manifest-managed SuperSpec surfaces",
+        "  guard       run the SuperSpec guard command surface",
+        "",
+        "examples:",
+        "  superspec init --scope project",
+        "  superspec init --scope user",
+        "  superspec guard check-init --change <change>",
+        "",
+    ].join("\n");
+}
+export async function main_superspec(argv = process.argv.slice(2)) {
+    const [command, ...rest] = argv;
+    if (command === undefined || command === "-h" || command === "--help") {
+        process.stdout.write(help());
+        return 0;
+    }
+    if (command === "init")
+        return main_init_async(rest);
+    if (command === "update")
+        return main_init_async([...rest, "--update"]);
+    if (command === "uninstall")
+        return main_init_async([...rest, "--uninstall"]);
+    if (command === "guard")
+        return main(rest);
+    // Convenience fallback: `superspec check-init ...` behaves like `superspec guard check-init ...`.
+    if (command.startsWith("check-") || command === "status" || command === "recompute" || command === "init") {
+        return main(argv);
+    }
+    process.stderr.write(`superspec: unknown command ${JSON.stringify(command)}\n\n${help()}`);
+    return 2;
+}
+const currentFile = realpathMaybe(process.argv[1] ?? "");
+if (currentFile === realpathMaybe(new URL(import.meta.url).pathname)) {
+    process.exitCode = await main_superspec();
+}

package/dist/superspec_guard.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+export * from "./src/core.ts";
+export * from "./src/cli.ts";
+export * from "./src/cli_args.ts";

package/dist/superspec_guard.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+export * from "./src/core.js";
+export * from "./src/cli.js";
+export * from "./src/cli_args.js";
+import { main } from "./src/cli.js";
+function realpathMaybe(filePath) {
+    try {
+        return realpathSync(filePath);
+    }
+    catch {
+        return resolve(filePath);
+    }
+}
+const currentFile = realpathMaybe(process.argv[1] ?? "");
+if (currentFile === realpathMaybe(new URL(import.meta.url).pathname)) {
+    process.exitCode = main();
+}

package/dist/superspec_init.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export * from "./src/init_cli.ts";

package/dist/superspec_init.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+export * from "./src/init_cli.js";
+import { main_init_async } from "./src/init_cli.js";
+function realpathMaybe(filePath) {
+    try {
+        return realpathSync(filePath);
+    }
+    catch {
+        return resolve(filePath);
+    }
+}
+const currentFile = realpathMaybe(process.argv[1] ?? "");
+if (currentFile === realpathMaybe(new URL(import.meta.url).pathname)) {
+    process.exitCode = await main_init_async();
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@peterxiaoyang/superspec",
+  "version": "0.1.0",
+  "description": "SuperSpec workflow package: guard runtime, generic workflow templates, and Codex adapter payload.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PeterYaoYang/SuperSpec.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PeterYaoYang/SuperSpec/issues"
+  },
+  "homepage": "https://github.com/PeterYaoYang/SuperSpec#readme",
+  "private": false,
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "bin": {
+    "superspec": "bin/superspec.js",
+    "superspec-guard": "bin/superspec-guard.js",
+    "superspec-init": "bin/superspec-init.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/superspec.d.ts",
+      "default": "./dist/superspec.js"
+    },
+    "./superspec_guard": {
+      "types": "./dist/superspec_guard.d.ts",
+      "default": "./dist/superspec_guard.js"
+    },
+    "./superspec_init": {
+      "types": "./dist/superspec_init.d.ts",
+      "default": "./dist/superspec_init.js"
+    },
+    "./templates/*": "./templates/*",
+    "./adapters/*": "./adapters/*",
+    "./schemas/*": "./schemas/*"
+  },
+  "files": [
+    "README.md",
+    "bin",
+    "dist",
+    "templates",
+    "adapters",
+    "schemas"
+  ],
+  "scripts": {
+    "build": "node build.js",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test tests/test_install_engine.test.ts tests/test_real_openspec_smoke.test.ts tests/test_superspec_guard.test.ts tests/test_superspec_skills.test.ts",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run build",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.0",
+    "typescript": "^6.0.3"
+  }
+}