@fraylabs/possible 0.1.10 → 0.3.0

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@fraylabs/possible",
-  "version": "0.1.10",
-  "description": "Install the Possible Outcome Pack skill for Codex",
+  "version": "0.3.0",
+  "description": "Create, publish, discover, and reuse source-owned AI Outcomes",
   "keywords": [
     "codex",
     "ai-agents",
     "agent-skills",
-    "outcome-packs",
-    "developer-tools",
-    "verification"
+    "prompts",
+    "ai-outcomes",
+    "developer-tools"
   ],
   "homepage": "https://possible.sh",
   "repository": {
@@ -23,15 +23,10 @@
   "bin": {
     "possible": "src/index.mjs"
   },
-  "files": [
-    "assets/possible",
-    "src"
-  ],
+  "files": ["src"],
   "scripts": {
-    "build": "node scripts/verify-snapshot.mjs",
-    "test": "node --test test/*.test.mjs && node scripts/verify-snapshot.mjs",
-    "sync:skill": "node scripts/sync-skill.mjs",
-    "prepack": "node scripts/verify-snapshot.mjs --quiet"
+    "build": "node --check src/index.mjs && node --check src/directory.mjs",
+    "test": "node --test test/*.test.mjs"
   },
   "engines": {
     "node": ">=22"

package/src/bookmarks.mjs

@@ -0,0 +1,72 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+const SAFE_SLUG = /^[a-z0-9][a-z0-9-]*$/;
+const emptyBookmarks = () => ({ schemaVersion: 1, outcomes: [] });
+
+export const bookmarkFilePath = (environment = process.env) => join(
+  environment.POSSIBLE_HOME ? resolve(environment.POSSIBLE_HOME) : join(homedir(), ".possible"),
+  "bookmarks.json",
+);
+
+const validateBookmarks = (input, path) => {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) throw new Error(`Bookmarks at ${path} must be a JSON object`);
+  if (input.schemaVersion !== 1 || !Array.isArray(input.outcomes)) throw new Error(`Bookmarks at ${path} must contain schemaVersion 1 and an outcomes array`);
+  const slugs = new Set();
+  const outcomes = input.outcomes.map((bookmark, index) => {
+    if (bookmark === null || typeof bookmark !== "object" || Array.isArray(bookmark)) throw new Error(`Bookmark ${index + 1} must be an object`);
+    if (Object.keys(bookmark).some((key) => !["slug", "savedAt"].includes(key))) throw new Error(`Bookmark ${index + 1} contains an unsupported field`);
+    if (!SAFE_SLUG.test(bookmark.slug)) throw new Error(`Bookmark ${index + 1}.slug must be lowercase and hyphenated`);
+    if (slugs.has(bookmark.slug)) throw new Error(`Bookmarks at ${path} contain duplicate Outcome ${bookmark.slug}`);
+    if (typeof bookmark.savedAt !== "string" || Number.isNaN(Date.parse(bookmark.savedAt))) throw new Error(`Bookmark ${index + 1}.savedAt must be an ISO date or date-time`);
+    slugs.add(bookmark.slug);
+    return { slug: bookmark.slug, savedAt: bookmark.savedAt };
+  });
+  return { schemaVersion: 1, outcomes };
+};
+
+const readBookmarks = async (path) => {
+  const contents = await readFile(path, "utf8").catch((error) => error?.code === "ENOENT" ? undefined : Promise.reject(error));
+  if (contents === undefined) return emptyBookmarks();
+  try {
+    return validateBookmarks(JSON.parse(contents), path);
+  } catch (error) {
+    if (error instanceof SyntaxError) throw new Error(`Bookmarks at ${path} contain invalid JSON and were left unchanged`);
+    throw error;
+  }
+};
+
+const writeBookmarks = async (path, bookmarks) => {
+  await mkdir(dirname(path), { recursive: true });
+  const temporaryPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+  await writeFile(temporaryPath, `${JSON.stringify(bookmarks, null, 2)}\n`, { flag: "wx" });
+  await rename(temporaryPath, path);
+};
+
+export async function runBookmarkCommand(args, options = {}) {
+  const [command, slug, ...rest] = args;
+  if (rest.length > 0) throw new Error("Bookmark commands accept only one Outcome slug");
+  const path = bookmarkFilePath(options.environment);
+  const bookmarks = await readBookmarks(path);
+
+  if (command === "list") {
+    if (slug !== undefined) throw new Error("Usage: possible bookmark list");
+    return bookmarks.outcomes.length ? bookmarks.outcomes.map(({ slug: value }) => value).join("\n") : "No bookmarked Outcomes.";
+  }
+  if ((command === "add" || command === "remove") && (!slug || !SAFE_SLUG.test(slug))) throw new Error(`Usage: possible bookmark ${command} <outcome-slug>`);
+  if (command === "add") {
+    if (bookmarks.outcomes.some(({ slug: value }) => value === slug)) return `${slug} is already bookmarked.`;
+    bookmarks.outcomes.push({ slug, savedAt: new Date().toISOString() });
+    bookmarks.outcomes.sort((left, right) => left.slug.localeCompare(right.slug));
+    await writeBookmarks(path, bookmarks);
+    return `Bookmarked ${slug}.`;
+  }
+  if (command === "remove") {
+    if (!bookmarks.outcomes.some(({ slug: value }) => value === slug)) throw new Error(`No bookmarked Outcome matches ${slug}`);
+    bookmarks.outcomes = bookmarks.outcomes.filter(({ slug: value }) => value !== slug);
+    await writeBookmarks(path, bookmarks);
+    return `Removed bookmark ${slug}.`;
+  }
+  throw new Error(`Unknown bookmark command: ${command ?? ""}`);
+}

package/src/directory.mjs

@@ -0,0 +1,37 @@
+const DEFAULT_ENDPOINT = "https://abutwsaahahtbtlopczi.supabase.co/functions/v1/outcome-directory";
+
+const directoryEndpoint = () => process.env.POSSIBLE_DIRECTORY_ENDPOINT?.trim() || DEFAULT_ENDPOINT;
+
+async function requestDirectory(parameters, fetchImplementation = fetch) {
+  const url = new URL(directoryEndpoint());
+  for (const [name, value] of Object.entries(parameters)) url.searchParams.set(name, value);
+  const response = await fetchImplementation(url, { headers: { accept: "application/json" } });
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok) throw new Error(body.error || `Possible directory returned HTTP ${response.status}`);
+  return body;
+}
+
+export async function searchOutcomes(query, options = {}) {
+  const normalized = String(query ?? "").trim();
+  if (!normalized) throw new Error("Search requires an ordinary-language query");
+  const body = await requestDirectory({ q: normalized, limit: "5" }, options.fetchImplementation);
+  return Array.isArray(body.outcomes) ? body.outcomes : [];
+}
+
+export async function fetchOutcome(id, options = {}) {
+  const normalized = String(id ?? "").trim();
+  if (!normalized) throw new Error("Fetch requires an Outcome ID from search results");
+  const body = await requestDirectory({ id: normalized }, options.fetchImplementation);
+  if (!body.outcome || typeof body.outcome.prompt !== "string") throw new Error("Possible returned an invalid Outcome");
+  return body.outcome;
+}
+
+export function formatSearchResults(outcomes) {
+  if (!outcomes.length) return "No matching Outcomes found.\n";
+  return `${outcomes.map((outcome, index) => [
+    `${index + 1}. ${outcome.title}`,
+    `   ${outcome.summary}`,
+    `   ID: ${outcome.id}`,
+    `   Source: ${outcome.source_locator}`,
+  ].join("\n")).join("\n\n")}\n`;
+}

package/src/index.mjs

@@ -1,35 +1,105 @@
 #!/usr/bin/env node
 
 import process from "node:process";
-import { installPossibleSkill } from "./init.mjs";
+import { runBookmarkCommand } from "./bookmarks.mjs";
+import { fetchOutcome, formatSearchResults, searchOutcomes } from "./directory.mjs";
+import { addOutcomeSource, createOutcome, publishOutcomeSource, useOutcome, validateOutcomes } from "./outcome-commands.mjs";
 
 const HELP = `Possible CLI
 
 Usage:
-  possible init
+  possible create <slug>
+  possible validate [directory]
+  possible publish [owner/repository | https://publisher.example]
+  possible search <ordinary-language query>
+  possible fetch <outcome-id>
+  possible add <owner/repository | https://publisher.example>
+  possible use <source>@<slug>
+  possible bookmark <command>
 
 Commands:
-  init  Install the Possible skill into the current project
+  create    Create outcome.json, outcome.md, prompt.md, and media/ for one Outcome
+  validate  Validate every Outcome folder below a directory
+  publish   Validate and submit one public publisher source; no account required
+  search    Find relevant Outcomes in the live public directory
+  fetch     Print one directory Outcome's exact prompt
+  add       Discover a public source and save it to .possible/sources.json
+  use       Print one exact execution prompt to standard output
+  bookmark  add | list | remove locally saved Outcome slugs
 `;
 
 const args = process.argv.slice(2);
-
 if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
   process.stdout.write(HELP);
   process.exitCode = args.length === 0 ? 1 : 0;
-} else if (args.length !== 1 || args[0] !== "init") {
-  process.stderr.write(`Unknown command: ${args.join(" ")}\n\n${HELP}`);
-  process.exitCode = 1;
-} else {
+} else if (args[0] === "bookmark") {
+  try {
+    const result = await runBookmarkCommand(args.slice(1));
+    if (result) process.stdout.write(`${result}\n`);
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+} else if (args[0] === "search" && args.length >= 2) {
+  try {
+    const outcomes = await searchOutcomes(args.slice(1).join(" "));
+    process.stdout.write(formatSearchResults(outcomes));
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+} else if (args[0] === "fetch" && args.length === 2) {
+  try {
+    const outcome = await fetchOutcome(args[1]);
+    process.stdout.write(`${outcome.prompt}\n`);
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+} else if (args[0] === "create" && args.length === 2) {
+  try {
+    const folder = await createOutcome(args[1]);
+    process.stdout.write(`Created ${folder}\n`);
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+} else if (args[0] === "validate" && args.length <= 2) {
   try {
-    const result = await installPossibleSkill();
-    process.stdout.write(
-      `${result.changed ? "Possible installed" : "Possible is already installed"} at ${result.installPath}\n\n` +
-        "Open Codex in this project and type:\n\n" +
-        "  $possible\n",
-    );
+    const result = await validateOutcomes(args[1] ?? process.cwd());
+    process.stdout.write(`Validated ${result.count} Outcome${result.count === 1 ? "" : "s"}.\n`);
   } catch (error) {
     process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
     process.exitCode = 1;
   }
+} else if (args[0] === "add" && args.length === 2) {
+  try {
+    const result = await addOutcomeSource(args[1]);
+    process.stdout.write(`Added ${result.discovery.locator}: ${result.discovery.outcomes.length} Outcome${result.discovery.outcomes.length === 1 ? "" : "s"}.\nSaved ${result.sourcesPath}\n`);
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+} else if (args[0] === "use" && args.length === 2) {
+  try {
+    const result = await useOutcome(args[1]);
+    process.stdout.write(`${result.outcome.prompt}\n`);
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+} else if (args[0] === "publish" && args.length <= 2) {
+  try {
+    const result = await publishOutcomeSource(args[1]);
+    const publicUrl = result.result.url ?? result.result.href;
+    const outcomes = Array.isArray(result.result.outcomes) ? result.result.outcomes : [];
+    const locator = result.result.source?.locator ?? result.source;
+    process.stdout.write(`Published ${outcomes.length} Outcome${outcomes.length === 1 ? "" : "s"} from ${locator}.${publicUrl ? `\n${publicUrl}` : ""}\n`);
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+} else {
+  process.stderr.write(`Unknown command: ${args.join(" ")}\n\n${HELP}`);
+  process.exitCode = 1;
 }

package/src/outcome-commands.mjs

@@ -0,0 +1,134 @@
+import { execFile } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { discoverLocalOutcomes } from "./outcome-format.mjs";
+import { discoverOutcomeSource } from "./sources.mjs";
+
+const execFileAsync = promisify(execFile);
+const SAFE_SLUG = /^[a-z0-9][a-z0-9-]*$/;
+const DEFAULT_PUBLISH_ENDPOINT = "https://abutwsaahahtbtlopczi.supabase.co/functions/v1/register-outcome-source";
+
+export async function createOutcome(slug, { directory = process.cwd() } = {}) {
+  if (!SAFE_SLUG.test(slug ?? "")) throw new Error("Outcome slug must be lowercase and hyphenated");
+  const root = resolve(directory);
+  const indexPath = join(root, "outcomes.json");
+  let publisherIndex = {
+    schemaVersion: 1,
+    publisher: { name: "Replace with publisher name", url: "https://example.com" },
+    outcomes: [],
+  };
+  try {
+    publisherIndex = JSON.parse(await readFile(indexPath, "utf8"));
+    if (publisherIndex.schemaVersion !== 1 || !Array.isArray(publisherIndex.outcomes)) throw new Error("outcomes.json must be a publisher index with schemaVersion 1");
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  const folder = join(root, "outcomes", slug);
+  await mkdir(join(folder, "media"), { recursive: true });
+  const manifestPath = join(folder, "outcome.json");
+  const manifest = {
+    schemaVersion: 3,
+    slug,
+    files: { about: "outcome.md", prompt: "prompt.md" },
+    authoredAt: null,
+    author: { name: "Replace with publisher name", url: "https://example.com" },
+    models: [{ provider: "Replace with provider", model: "Replace with model", role: "execution" }],
+    requirements: [],
+  };
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, { flag: "wx" });
+  await writeFile(join(folder, "outcome.md"), `# Replace with Outcome name\n\nDescribe the concrete result in one clear opening paragraph.\n`, { flag: "wx" });
+  await writeFile(join(folder, "prompt.md"), "Replace this line with the exact reusable execution prompt.\n", { flag: "wx" });
+  const entry = { slug, url: `./outcomes/${slug}/outcome.json` };
+  publisherIndex.outcomes = [...publisherIndex.outcomes.filter((outcome) => outcome?.slug !== slug), entry]
+    .sort((left, right) => String(left.slug).localeCompare(String(right.slug)));
+  await writeFile(indexPath, `${JSON.stringify(publisherIndex, null, 2)}\n`);
+  return folder;
+}
+
+export async function validateOutcomes(directory = process.cwd()) {
+  const root = resolve(directory);
+  const outcomes = await discoverLocalOutcomes(root);
+  const indexPath = join(root, "outcomes.json");
+  let publisherIndex;
+  try { publisherIndex = JSON.parse(await readFile(indexPath, "utf8")); }
+  catch (error) {
+    if (error?.code === "ENOENT") throw new Error("outcomes.json is required at the publisher repository root");
+    throw error;
+  }
+  if (publisherIndex?.schemaVersion !== 1 || !Array.isArray(publisherIndex.outcomes) || publisherIndex.outcomes.length === 0) throw new Error("outcomes.json must be a non-empty publisher index with schemaVersion 1");
+  if (!publisherIndex.publisher || typeof publisherIndex.publisher.name !== "string" || !publisherIndex.publisher.name.trim()) throw new Error("outcomes.json requires publisher.name");
+  try {
+    if (new URL(publisherIndex.publisher.url).protocol !== "https:") throw new Error();
+  } catch { throw new Error("outcomes.json requires an HTTPS publisher.url"); }
+  const indexed = new Map();
+  for (const [position, entry] of publisherIndex.outcomes.entries()) {
+    if (!entry || typeof entry.slug !== "string" || !SAFE_SLUG.test(entry.slug)) throw new Error(`outcomes.json outcomes[${position}].slug is invalid`);
+    const expectedUrl = `./outcomes/${entry.slug}/outcome.json`;
+    if (entry.url !== expectedUrl) throw new Error(`outcomes.json outcomes[${position}].url must be ${expectedUrl}`);
+    if (indexed.has(entry.slug)) throw new Error(`outcomes.json contains duplicate slug ${entry.slug}`);
+    indexed.set(entry.slug, entry);
+  }
+  const discovered = new Set(outcomes.map(({ slug }) => slug));
+  for (const slug of indexed.keys()) if (!discovered.has(slug)) throw new Error(`outcomes.json references missing Outcome ${slug}`);
+  for (const slug of discovered) if (!indexed.has(slug)) throw new Error(`outcomes.json does not list Outcome ${slug}`);
+  return { count: outcomes.length, outcomes };
+}
+
+async function gitOutput(directory, args) {
+  const result = await execFileAsync("git", args, { cwd: directory, encoding: "utf8" });
+  return result.stdout.trim();
+}
+
+export async function inferGitHubSource(directory = process.cwd()) {
+  const root = await gitOutput(directory, ["rev-parse", "--show-toplevel"]);
+  const dirty = await gitOutput(root, ["status", "--porcelain"]);
+  if (dirty) throw new Error("Commit the Outcome files before publishing so Possible can snapshot an exact public revision");
+  const remote = await gitOutput(root, ["remote", "get-url", "origin"]);
+  const match = remote.match(/github\.com[/:]([^/]+)\/([^/]+?)(?:\.git)?$/);
+  if (!match) throw new Error("The repository origin must be a public GitHub repository");
+  return `${match[1]}/${match[2]}`;
+}
+
+export async function addOutcomeSource(source, { directory = process.cwd(), fetchOptions } = {}) {
+  const discovery = await discoverOutcomeSource(source, fetchOptions);
+  const possibleDirectory = join(directory, ".possible");
+  const sourcesPath = join(possibleDirectory, "sources.json");
+  await mkdir(possibleDirectory, { recursive: true });
+  let current = { schemaVersion: 1, sources: [] };
+  try { current = JSON.parse(await readFile(sourcesPath, "utf8")); } catch (error) { if (error?.code !== "ENOENT") throw error; }
+  const nextSource = { type: discovery.type, locator: discovery.locator, installUrl: discovery.installUrl, revision: discovery.revision };
+  const sources = [...(Array.isArray(current.sources) ? current.sources : []).filter((entry) => !(entry.type === nextSource.type && entry.locator === nextSource.locator)), nextSource]
+    .sort((left, right) => left.locator.localeCompare(right.locator));
+  await writeFile(sourcesPath, `${JSON.stringify({ schemaVersion: 1, sources }, null, 2)}\n`);
+  return { discovery, sourcesPath };
+}
+
+function splitUseReference(reference) {
+  const separator = reference.lastIndexOf("@");
+  if (separator <= 0 || separator === reference.length - 1) throw new Error("Use an Outcome as <source>@<slug>");
+  return { source: reference.slice(0, separator), slug: reference.slice(separator + 1) };
+}
+
+export async function useOutcome(reference, { fetchOptions } = {}) {
+  const { source, slug } = splitUseReference(reference);
+  const discovery = await discoverOutcomeSource(source, fetchOptions);
+  const outcome = discovery.outcomes.find((entry) => entry.slug === slug);
+  if (!outcome) throw new Error(`${source} does not publish an Outcome named ${slug}`);
+  return { discovery, outcome };
+}
+
+export async function publishOutcomeSource(source, { directory = process.cwd(), endpoint = process.env.POSSIBLE_PUBLISH_URL ?? DEFAULT_PUBLISH_ENDPOINT } = {}) {
+  const resolvedSource = source || await inferGitHubSource(directory);
+  if (!source) await validateOutcomes(directory);
+  const response = await fetch(endpoint, {
+    method: "POST",
+    headers: { "content-type": "application/json", accept: "application/json" },
+    body: JSON.stringify({ source: resolvedSource }),
+  });
+  const body = await response.text();
+  if (!response.ok) throw new Error(`Possible publishing returned HTTP ${response.status}${body ? `: ${body}` : ""}`);
+  let result = {};
+  try { result = body ? JSON.parse(body) : {}; } catch { result = { message: body }; }
+  return { source: resolvedSource, result };
+}

package/src/outcome-format.mjs

@@ -0,0 +1,201 @@
+import { readFile, readdir } from "node:fs/promises";
+import { basename, join, relative, resolve } from "node:path";
+
+const SAFE_SLUG = /^[a-z0-9][a-z0-9-]*$/;
+const EXACT_REVISION = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const PRODUCT_ID = /^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/;
+const GITHUB_REPOSITORY = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const SAFE_REPOSITORY_PATH = /^(?:\.|[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*)$/;
+const MODEL_ROLES = new Set(["authorship", "execution", "review"]);
+const FILE_TYPES = new Set(["image", "video", "audio", "cad", "document", "data", "source", "archive", "other"]);
+const MANIFEST_KEYS = new Set(["schemaVersion", "slug", "files", "authoredAt", "author", "models", "requirements", "products", "skills", "inputs", "artifacts", "preview"]);
+
+const asObject = (value, context) => {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`${context} must be a JSON object`);
+  return value;
+};
+
+const string = (value, context) => {
+  if (typeof value !== "string" || value.trim().length === 0) throw new Error(`${context} must be a non-empty string`);
+  return value;
+};
+
+const exactKeys = (value, allowed, context) => {
+  for (const key of Object.keys(value)) if (!allowed.has(key)) throw new Error(`${context}.${key} is unsupported`);
+};
+
+const httpsUrl = (value, context) => {
+  const candidate = string(value, context);
+  let parsed;
+  try { parsed = new URL(candidate); } catch { throw new Error(`${context} must be an HTTPS URL`); }
+  if (parsed.protocol !== "https:") throw new Error(`${context} must be an HTTPS URL`);
+  return candidate;
+};
+
+const safeRelativePath = (value, context) => {
+  const candidate = string(value, context);
+  if (candidate.includes("\\") || candidate.startsWith("/") || candidate.split("/").some((part) => part === "" || part === "." || part === "..")) {
+    throw new Error(`${context} must be a safe repository-relative path`);
+  }
+  return candidate;
+};
+
+const validateFiles = (value, context) => {
+  if (value === undefined) return;
+  if (!Array.isArray(value) || value.length === 0) throw new Error(`${context} must be omitted or a non-empty array`);
+  const seen = new Set();
+  value.forEach((entry, index) => {
+    const file = asObject(entry, `${context}[${index}]`);
+    exactKeys(file, new Set(["type", "src", "label", "format"]), `${context}[${index}]`);
+    if (!FILE_TYPES.has(file.type)) throw new Error(`${context}[${index}].type is unsupported`);
+    const source = file.src?.startsWith("https://") ? httpsUrl(file.src, `${context}[${index}].src`) : safeRelativePath(file.src, `${context}[${index}].src`);
+    string(file.label, `${context}[${index}].label`);
+    if (file.format !== undefined) string(file.format, `${context}[${index}].format`);
+    if (seen.has(source)) throw new Error(`${context} contains duplicate source ${source}`);
+    seen.add(source);
+  });
+};
+
+export function validateOutcomeManifest(value, context = "outcome.json") {
+  const manifest = asObject(value, context);
+  exactKeys(manifest, MANIFEST_KEYS, context);
+  if (manifest.schemaVersion !== 3) throw new Error(`${context}.schemaVersion must be 3`);
+  if (!SAFE_SLUG.test(string(manifest.slug, `${context}.slug`))) throw new Error(`${context}.slug must be lowercase and hyphenated`);
+
+  const files = asObject(manifest.files, `${context}.files`);
+  exactKeys(files, new Set(["about", "prompt"]), `${context}.files`);
+  if (files.about !== "outcome.md" || files.prompt !== "prompt.md") throw new Error(`${context}.files must reference outcome.md and prompt.md`);
+
+  if (manifest.authoredAt !== null) {
+    const authoredAt = string(manifest.authoredAt, `${context}.authoredAt`);
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?(?:Z|[+-]\d{2}:\d{2})$/.test(authoredAt) || Number.isNaN(Date.parse(authoredAt))) {
+      throw new Error(`${context}.authoredAt must be null or an ISO 8601 timestamp with a timezone`);
+    }
+  }
+
+  const author = asObject(manifest.author, `${context}.author`);
+  exactKeys(author, new Set(["name", "url"]), `${context}.author`);
+  string(author.name, `${context}.author.name`);
+  httpsUrl(author.url, `${context}.author.url`);
+
+  if (!Array.isArray(manifest.models) || manifest.models.length === 0) throw new Error(`${context}.models must be a non-empty array`);
+  manifest.models.forEach((entry, index) => {
+    const model = asObject(entry, `${context}.models[${index}]`);
+    exactKeys(model, new Set(["provider", "model", "agent", "role"]), `${context}.models[${index}]`);
+    string(model.provider, `${context}.models[${index}].provider`);
+    string(model.model, `${context}.models[${index}].model`);
+    if (model.agent !== undefined) string(model.agent, `${context}.models[${index}].agent`);
+    if (!MODEL_ROLES.has(model.role)) throw new Error(`${context}.models[${index}].role is unsupported`);
+  });
+
+  if (!Array.isArray(manifest.requirements)) throw new Error(`${context}.requirements must be an array`);
+  const requirements = manifest.requirements.map((entry, index) => string(entry, `${context}.requirements[${index}]`));
+  if (new Set(requirements).size !== requirements.length) throw new Error(`${context}.requirements contains duplicates`);
+
+  if (manifest.products !== undefined) {
+    if (!Array.isArray(manifest.products) || manifest.products.length === 0) throw new Error(`${context}.products must be omitted or a non-empty array`);
+    for (const [index, product] of manifest.products.entries()) if (!PRODUCT_ID.test(string(product, `${context}.products[${index}]`))) throw new Error(`${context}.products[${index}] is invalid`);
+    if (new Set(manifest.products).size !== manifest.products.length) throw new Error(`${context}.products contains duplicates`);
+  }
+
+  if (manifest.skills !== undefined) {
+    if (!Array.isArray(manifest.skills) || manifest.skills.length === 0) throw new Error(`${context}.skills must be omitted or a non-empty array`);
+    for (const [index, entry] of manifest.skills.entries()) {
+      const skill = asObject(entry, `${context}.skills[${index}]`);
+      exactKeys(skill, new Set(["repository", "lastReviewedCommit", "directory"]), `${context}.skills[${index}]`);
+      if (!GITHUB_REPOSITORY.test(string(skill.repository, `${context}.skills[${index}].repository`))) throw new Error(`${context}.skills[${index}].repository is invalid`);
+      if (!EXACT_REVISION.test(string(skill.lastReviewedCommit, `${context}.skills[${index}].lastReviewedCommit`))) throw new Error(`${context}.skills[${index}].lastReviewedCommit must be an exact commit`);
+      const directory = string(skill.directory, `${context}.skills[${index}].directory`);
+      if (!SAFE_REPOSITORY_PATH.test(directory) || (directory !== "." && directory.split("/").some((part) => part === "." || part === ".."))) throw new Error(`${context}.skills[${index}].directory is invalid`);
+    }
+  }
+
+  validateFiles(manifest.inputs, `${context}.inputs`);
+  validateFiles(manifest.artifacts, `${context}.artifacts`);
+  if (manifest.preview !== undefined) asObject(manifest.preview, `${context}.preview`);
+  return manifest;
+}
+
+const plainInlineMarkdown = (value) => value
+  .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1")
+  .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
+  .replace(/[*_~`]/g, "")
+  .replace(/\s+/g, " ")
+  .trim();
+
+export function parseOutcomeMarkdown(value, context = "outcome.md") {
+  const markdown = string(value, context).trim();
+  const lines = markdown.split(/\r?\n/);
+  const titleLine = lines[0] ?? "";
+  if (!titleLine.startsWith("# ") || titleLine.slice(2).trim().length === 0) throw new Error(`${context} must begin with one # title`);
+  if (lines.slice(1).some((line) => line.startsWith("# "))) throw new Error(`${context} must contain exactly one # title`);
+  let index = 1;
+  while (index < lines.length && lines[index]?.trim() === "") index += 1;
+  const summaryLines = [];
+  while (index < lines.length && lines[index]?.trim() !== "" && !lines[index]?.startsWith("## ")) {
+    summaryLines.push(lines[index]);
+    index += 1;
+  }
+  const summaryMarkdown = summaryLines.join("\n").trim();
+  if (!summaryMarkdown) throw new Error(`${context} must contain an opening summary after its title`);
+
+  const originalHeading = lines.findIndex((line) => line.trim().toLowerCase() === "## original request");
+  let originalPrompt;
+  if (originalHeading >= 0) {
+    const quoted = [];
+    for (const line of lines.slice(originalHeading + 1)) {
+      if (line.startsWith("## ")) break;
+      if (line.startsWith("> ")) quoted.push(line.slice(2));
+      else if (line === ">") quoted.push("");
+    }
+    const joined = quoted.join("\n").trim();
+    if (joined) originalPrompt = joined;
+  }
+  return {
+    title: plainInlineMarkdown(titleLine.slice(2)),
+    summary: plainInlineMarkdown(summaryMarkdown),
+    summaryMarkdown,
+    markdown,
+    ...(originalPrompt ? { originalPrompt } : {}),
+  };
+}
+
+export async function readOutcomeFolder(folder) {
+  const [manifestText, aboutText, promptText] = await Promise.all([
+    readFile(join(folder, "outcome.json"), "utf8"),
+    readFile(join(folder, "outcome.md"), "utf8"),
+    readFile(join(folder, "prompt.md"), "utf8"),
+  ]);
+  const manifest = validateOutcomeManifest(JSON.parse(manifestText), `${relative(process.cwd(), join(folder, "outcome.json")) || "outcome.json"}`);
+  if (basename(folder) !== manifest.slug) throw new Error(`${manifest.slug}: folder name must match outcome.json slug`);
+  const about = parseOutcomeMarkdown(aboutText, `${manifest.slug}/outcome.md`);
+  const executionPrompt = string(promptText, `${manifest.slug}/prompt.md`).trim();
+  return { slug: manifest.slug, folder, manifest, about, executionPrompt };
+}
+
+export async function discoverLocalOutcomes(repositoryRoot) {
+  const found = [];
+  async function walk(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    if (entries.some((entry) => entry.isFile() && entry.name === "outcome.json")) {
+      found.push(await readOutcomeFolder(directory));
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.isSymbolicLink() || entry.name === ".git" || entry.name === "node_modules") continue;
+      await walk(join(directory, entry.name));
+    }
+  }
+  await walk(resolve(repositoryRoot));
+  if (found.length === 0) throw new Error(`No Outcome folders found under ${repositoryRoot}`);
+  const identities = new Set();
+  for (const outcome of found) {
+    if (identities.has(outcome.slug)) throw new Error(`Duplicate Outcome slug: ${outcome.slug}`);
+    identities.add(outcome.slug);
+  }
+  return found.sort((left, right) => left.about.title.localeCompare(right.about.title));
+}
+
+export function relativeOutcomePath(repositoryRoot, folder) {
+  return relative(resolve(repositoryRoot), resolve(folder)).split("\\").join("/");
+}