@bjoernrochel/sevro 0.1.0-rc.7 → 1.0.0

package/docs/typescript-quality.md

@@ -1,6 +1,7 @@
 # TypeScript quality
 
-`bun run check:typescript` is the local and CI acceptance command. It performs a
+`bun run check:typescript` is the complete local acceptance command. CI runs the
+same checks in parallel phases. The complete command performs a
 frozen dependency installation, checks the complete source inventory, verifies
 generated schemas, documentation contracts, formatting, type-aware lint and typing,
 checks the Codex guide evaluation in dry mode and runs documentation examples, exercises coverage
@@ -14,13 +15,44 @@ schemas, documentation contracts, formatting, lint and types without the full in
 or package installation. Install dependencies with `bun install --frozen-lockfile`
 first. Quality dependencies are development dependencies pinned in `bun.lock`.
 
+After frozen installation, `bun run check:typescript --phase <name>` runs one
+phase and checks the complete source inventory. Each phase reports its elapsed
+time, including when it fails. The complete command runs these same phases in
+order; `--fast` runs only `static` without installing dependencies.
+
+| Phase     | Checks                                                                                        |
+| --------- | --------------------------------------------------------------------------------------------- |
+| `static`  | Schema freshness, documentation contracts, formatting, type-aware lint and typing             |
+| `docs`    | All guide dry runs, tutorial examples and recipe checks                                       |
+| `tests`   | Coverage integrity controls, the complete instrumented Bun suite and both coverage thresholds |
+| `package` | Packed-package installation and installed CLI workflows                                       |
+
+Use the same prerequisites as the corresponding complete-gate checks. A single
+phase is partial evidence; full acceptance requires all four on the same candidate.
+CI assigns every test file to exactly one of four duration-balanced shards, then
+enforces both coverage thresholds on their combined counters over the complete
+production inventory. Local `--phase tests` and the complete command still run
+the suite in one process. See the [shard commands](../scripts/coverage/README.md#test-shards)
+for reproducing the CI split.
+
 ## Source dispositions
 
-[`typescript-sources.json`](../typescript-sources.json) explicitly lists every
-TypeScript and JavaScript source. The guard refuses new, missing or duplicated
-files and declarations outside the configured TypeScript project. Changing a
-source disposition requires review; adding a glob is not a substitute for the
-inventory. The coverage baseline includes the platform-reachable subset of
+The [inventory guard](../scripts/typescript-inventory.ts) derives every TypeScript
+and JavaScript source disposition from Git paths, following the
+[maintainer decision in #143](https://github.com/BjRo/sevro/issues/143#issuecomment-6382662399).
+It classifies `git ls-files --cached --others --exclude-standard -z` output using
+the checked path rules, so supported additions and staged renames or deletions
+need no manual manifest edit. Non-ignored untracked sources are included in local
+candidate checks; committed CI checkouts use their tracked paths. Declarations
+take precedence over directory roles, and only the validators in the shared
+[schema catalog](../scripts/schema-catalog.ts) receive the generated disposition.
+Unknown or ambiguous paths, missing tracked files, an incomplete generated set,
+and sources outside lint or typing are refused. An independent filesystem audit
+also refuses ignored authored sources rather than silently dropping them.
+Changing a disposition rule still requires review. Isolated coverage snapshots
+index their copied candidate independently, preserving additions and deletions
+without changing the source checkout's index.
+The coverage baseline includes the platform-reachable subset of
 `inventory.production`; `scripts/coverage/platform-scope.ts` names each excluded
 host-specific file. Every production file remains inventoried, typed and linted,
 and the opposite platform measures it. Current instrumentation supports authored
@@ -29,14 +61,14 @@ validators in `inventory.generated` are excluded from instrumentation and the
 coverage denominator. New `.tsx`, `.mts`, `.cts` or JavaScript
 production requires an explicit instrumentation and quality-policy change first.
 
-| Inventory      | Lint and typing                                                                                      | Test and coverage disposition                                                                                                                                                                        |
-| -------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `production`   | Type-aware strict lint and strict compiler                                                           | All platform-reachable authored executable `src` statements and branch outcomes, including unimported files in that scope                                                                            |
-| `generated`    | CommonJS syntax parsing, exact `schemas:check` freshness, and checked `.d.cts` boundary declarations | Real Bun schema tests; the five declared generated validators are outside the coverage denominator                                                                                                   |
-| `declarations` | Type-aware lint and compiler                                                                         | Declaration-only files have no executable counters                                                                                                                                                   |
-| `tooling`      | Same type-aware lint and strict compiler; `.mjs`/`.cjs` use `checkJs` and explicit JSDoc contracts   | Durable public gate probes, schema freshness, release and installed-package tests; outside the runner-production denominator                                                                         |
-| `tests`        | Same type-aware lint and strict compiler, including fixtures                                         | Real Bun filesystem/process/protocol tests; outside the production denominator                                                                                                                       |
-| `examples`     | Same type-aware lint and strict compiler                                                             | Packaged demonstration host adapters are synthetic consumer fixtures, exercised by installed-package validation; they implement no runner behavior and are outside the runner-production denominator |
+| Inventory      | Lint and typing                                                                                      | Test and coverage disposition                                                                                                                                                                                                |
+| -------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `production`   | Type-aware strict lint and strict compiler                                                           | All platform-reachable authored executable `src` statements and branch outcomes, including unimported files in that scope                                                                                                    |
+| `generated`    | CommonJS syntax parsing, exact `schemas:check` freshness, and checked `.d.cts` boundary declarations | Real Bun schema tests; the five declared generated validators are outside the coverage denominator                                                                                                                           |
+| `declarations` | Type-aware lint and compiler                                                                         | Declaration-only files have no executable counters                                                                                                                                                                           |
+| `tooling`      | Same type-aware lint and strict compiler; `.mjs`/`.cjs` use `checkJs` and explicit JSDoc contracts   | Durable public gate probes, schema freshness, release and installed-package tests; outside the runner-production denominator                                                                                                 |
+| `tests`        | Same type-aware lint and strict compiler, including fixtures                                         | Real Bun filesystem/process/protocol tests; outside the production denominator                                                                                                                                               |
+| `examples`     | Same type-aware lint and strict compiler                                                             | Packaged recipe adapters, extensions and evaluator checks are consumer examples, exercised by tutorial and installed-package validation; they implement no runner behavior and are outside the runner-production denominator |
 
 Generated AJV CommonJS is deliberately not rewritten to conform to authored-code
 rules. An earlier audit of the original four generated files using ESLint's
@@ -45,8 +77,8 @@ recommended JavaScript rules found 879 redeclarations, 281 useless assignments,
 generation freshness, typed public boundaries and runtime behavior remain checked.
 Generated compiler output is excluded from coverage because the coverage target
 measures authored runner behavior. This applies only to
-`src/generated/cli-result.cjs`, `extension.cjs`, `report.cjs`, `run-evidence.cjs` and `runtime.cjs`
-as explicitly declared in the inventory. This disposition does not apply to authored CommonJS, including
+the exact validator paths derived from the [schema catalog](../scripts/schema-catalog.ts),
+which also drives schema generation. This disposition does not apply to authored CommonJS, including
 the coverage capture hook.
 
 ## Types, functions and review
@@ -120,7 +152,7 @@ macOS `sandbox-exec`, Keychain and Apple metadata modules are excluded; on macOS
 `bubblewrap` module is excluded. Shared isolation and credential code is counted
 on both.
 
-Apple developer-tool discovery lives in `src/runtime-discovery-apple.ts`, which
+Apple developer-tool discovery lives in `src/runtime/discovery-apple.ts`, which
 the public loader imports only under its explicit Darwin guard. Linux excludes
 that exact native module; macOS measures it, and both platforms still typecheck
 and lint it. The provider lookup, bounded query and read-root safeguards remain
@@ -146,12 +178,24 @@ summary, process ledger, Bun test log, unmodified source snapshot, LCOV and HTML
 production files, branch exclusions, and exact projected counts.
 `coverage-raw.json` and the raw summary preserve all validated counters before
 platform projection.
+CI also retains `.quality/shards/<index>/` with each shard's source snapshot,
+process ledger, test log, raw and portable counters, and manifest. Process IDs
+remain scoped to their original shard. Aggregation verifies candidate contents,
+workflow run, platform, architecture, Bun version, instrumentation
+layout, and exact test assignments before combining counters with normalized
+source paths. Missing, repeated, incomplete, or mismatched shards fail the gate.
+Failed-job reruns can reuse successful shards from earlier attempts of the same
+workflow run; manifests retain each attempt, and rerun shards replace only their
+own artifacts. Another candidate or workflow run cannot supply missing evidence.
 `--coverage [Bun test arguments]` is a diagnostic measurement; it still enforces
 both thresholds and writes `.quality/coverage-targeted`, keeping it distinct from
 the full-suite evidence. Sparse runs are expected to fail the full denominator.
 
 The durable public probes are `--probe snapshot`, `--probe scope`, `--probe branch`,
 `--probe missing-reports`, `--probe integrity`, and `--probe source-map`.
+`tests/scripts/typescript-quality.test.ts` invokes each probe once during the suite;
+the phase entrypoint and shard merge do not rerun them. The commands remain
+available for targeted diagnostics.
 The scope probe records a zero-seeded baseline and merged real process report
 under `.quality/coverage-scope`; it verifies that ordinary generated CommonJS
 validation still runs. Branch and missing-report controls
@@ -167,21 +211,40 @@ Codex 0.160.1 and Claude Code 2.1.284 for deterministic native hook tests. Hoste
 CI targets `ubuntu-24.04` x64 with Bun 1.3.13 and Node 24.13.0. Its first
 successful hosted run is required before describing that environment as validated.
 GitHub documents the [Ubuntu runner labels](https://docs.github.com/en/actions/reference/runners/github-hosted-runners).
-Ubuntu installs `bubblewrap` and `socat` and runs the same native isolation cases;
-local macOS runs retain `sandbox-exec`. Windows remains unverified.
+Ubuntu installs `bubblewrap`, `ripgrep`, and `socat` and runs the same native isolation cases;
+local macOS runs retain `sandbox-exec`. The macOS quality and coverage gate is
+local-only; the hosted workflow does not run a macOS gate. Windows remains unverified.
+
+Ordinary changes and explicit workflow dispatches run the four canonical phases
+concurrently. The tests phase consists of four shard jobs followed by a combined
+coverage job. Each job installs locked dependencies; native host tools are
+installed for `docs` and the test shards, and UV and mise for `docs`. Each shard
+retains its evidence, and the combined `tests` job uploads `.quality` even when
+coverage fails. Shards do not cancel their siblings on failure. A new commit to
+the same pull request cancels its superseded workflow run; main pushes and manual
+runs have independent concurrency groups. The stable aggregate `TypeScript quality`
+status requires every phase and all four shards to succeed. A missing, cancelled,
+skipped or failed phase or shard cannot turn that status green.
 
-Ordinary changes and explicit workflow dispatches invoke the canonical gate,
-upload `.quality` even when coverage fails, and publish the stable aggregate
-`TypeScript quality` status. A cancelled or failed gate cannot turn that status
-green.
+CI caches Bun's package downloads by Bun version, OS, architecture and `bun.lock`;
+every job still performs frozen installation. The docs job and test shards also
+cache the installed Codex and Claude packages by OS, architecture and the setup
+script's content hash, which includes both pinned versions and their installation
+layout. There are no fallback keys for native tools. On a hit, setup copies the
+cached packages into a fresh temporary tool root and verifies both native versions
+before publishing their paths. The cache never contains credentials or replaces
+the isolation prerequisites or required checks.
 
 Release metadata changes follow [the release workflow](releases.md) and reuse a
 successful full gate from an ancestor on `main`, with identical code,
 dependencies, schemas, tests, and other quality inputs. The selector permits
 only version/distribution-tag changes and its exact release-file inventory.
-It verifies the original full-gate step, so a reused release run cannot serve
-as fresh test evidence. Release CI runs `check:typescript --fast`, records the
-tested source and CI run URL, and skips the test/coverage job. The aggregate
+It verifies each original phase job and its gate step, including every shard and
+the combined tests job for sharded runs, or a historical complete gate job and
+step. A partial matrix or reused release run cannot serve as fresh test evidence.
+Duplicate phase or shard jobs are ambiguous and refused. Release CI
+runs `check:typescript --fast`, records the tested source and CI run URL, and
+skips all four full-gate phase jobs. The aggregate
 status requires both verified prior evidence and successful static checks;
 missing, cancelled, failed, or ambiguous evidence cannot establish a pass.
 Reused results remain attributed to their original run rather than being

package/examples/recipes/candidate.ts

@@ -0,0 +1,26 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/** Trusted, deterministic participant for exercising the recipe's real graders. */
+const host = {
+  id: "recipes.deterministic",
+  model: "fixture-editor",
+  effort: "none",
+  async run({ workspace }: { workspace: string }) {
+    const task = await readFile(join(workspace, "README.md"), "utf8");
+    const failing = process.env.SEVRO_RECIPE_FAIL === "1";
+    if (task.includes("Fix add")) {
+      await writeFile(
+        join(workspace, "math.cjs"),
+        `exports.add = (a, b) => a ${failing ? "-" : "+"} b;\n`,
+      );
+    }
+    return {
+      finalMessage: failing
+        ? "Start with npm start on port 9000."
+        : "Run bun run dev on port 3000.",
+      complete: true,
+    };
+  },
+};
+export default host;

package/examples/recipes/cases/coding-change.json

@@ -0,0 +1,21 @@
+{
+  "id": "recipe-coding-change",
+  "prompt": "Fix add in math.cjs so it adds its two numeric arguments. Do not modify README.md. Explain how to start the application.",
+  "fixture": {
+    "files": {
+      "README.md": "Fix add in math.cjs. Start the application with bun run dev on port 3000.\n",
+      "math.cjs": "exports.add = (a, b) => a - b;\n"
+    }
+  },
+  "checks": [
+    {
+      "id": "addition",
+      "grader": "sevro.shell",
+      "configuration": {
+        "run": "{{evaluator-test}}",
+        "expectExact": "coding checks passed"
+      }
+    }
+  ],
+  "requiredEvidence": []
+}

package/examples/recipes/cases/host-tools.json

@@ -0,0 +1,21 @@
+{
+  "id": "recipe-host-tools",
+  "prompt": "Read app.env with rg, then explain the application's start command and port.",
+  "fixture": {
+    "files": {
+      "README.md": "Start with bun run dev on port 3000.\n",
+      "app.env": "port=3000\n"
+    }
+  },
+  "checks": [
+    {
+      "id": "rg-access",
+      "grader": "sevro.shell",
+      "configuration": {
+        "run": "rg '^port=3000$' app.env",
+        "expectExact": "port=3000"
+      }
+    }
+  ],
+  "requiredEvidence": []
+}

package/examples/recipes/cases/mise.json

@@ -0,0 +1,21 @@
+{
+  "id": "recipe-mise",
+  "prompt": "Use node from PATH to read app.json, then explain the application's start command and port. The operator has resolved mise's existing node@24.13.0 installation; do not download anything.",
+  "fixture": {
+    "files": {
+      "README.md": "Start with bun run dev on port 3000.\n",
+      "app.json": "{\"port\":3000}\n"
+    }
+  },
+  "checks": [
+    {
+      "id": "mise-node-access",
+      "grader": "sevro.shell",
+      "configuration": {
+        "run": "node -e 'if (process.version !== \"v24.13.0\") process.exit(1); const a = require(\"./app.json\"); if (a.port !== 3000) process.exit(1); console.log(a.port)'",
+        "expectExact": "3000"
+      }
+    }
+  ],
+  "requiredEvidence": []
+}

package/examples/recipes/cases/node.json

@@ -0,0 +1,21 @@
+{
+  "id": "recipe-node",
+  "prompt": "Read app.json with Node and explain the application's start command and port.",
+  "fixture": {
+    "files": {
+      "README.md": "Start with bun run dev on port 3000.\n",
+      "app.json": "{\"port\":3000}\n"
+    }
+  },
+  "checks": [
+    {
+      "id": "node-access",
+      "grader": "sevro.shell",
+      "configuration": {
+        "run": "node -e 'const a = require(\"./app.json\"); if (a.port !== 3000) process.exit(1); console.log(a.port)'",
+        "expectExact": "3000"
+      }
+    }
+  ],
+  "requiredEvidence": []
+}

package/examples/recipes/cases/python-uv.json

@@ -0,0 +1,21 @@
+{
+  "id": "recipe-python-uv",
+  "prompt": "Use uv run --offline --no-project --python \"$RECIPE_PYTHON\" python to read app.json, then explain the application's start command and port.",
+  "fixture": {
+    "files": {
+      "README.md": "Start with bun run dev on port 3000.\n",
+      "app.json": "{\"port\":3000}\n"
+    }
+  },
+  "checks": [
+    {
+      "id": "uv-python-access",
+      "grader": "sevro.shell",
+      "configuration": {
+        "run": "uv run --offline --no-project --python \"$RECIPE_PYTHON\" python -c 'import json; p=json.load(open(\"app.json\"))[\"port\"]; assert p == 3000; print(p)'",
+        "expectExact": "3000"
+      }
+    }
+  ],
+  "requiredEvidence": []
+}

package/examples/recipes/cases/semantic.json

@@ -0,0 +1,17 @@
+{
+  "id": "recipe-semantic",
+  "prompt": "Read README.md and explain how to start the application, including its port.",
+  "fixture": {
+    "files": { "README.md": "Start with bun run dev on port 3000.\n" }
+  },
+  "checks": [
+    {
+      "id": "startup-meaning",
+      "grader": "sevro.semantic",
+      "configuration": {
+        "proposition": "The response tells the reader to run bun run dev and says that the application listens on port 3000."
+      }
+    }
+  ],
+  "requiredEvidence": []
+}

package/examples/recipes/coding-change/check.ts

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+interface Addition {
+  add: (left: number, right: number) => number;
+}
+function isAddition(value: unknown): value is Addition {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "add" in value &&
+    typeof value.add === "function"
+  );
+}
+const candidate: unknown = await import(
+  pathToFileURL(join(process.cwd(), "math.cjs")).href
+);
+assert.ok(isAddition(candidate), "Candidate must export add");
+assert.equal(candidate.add(2, 3), 5);
+assert.equal(candidate.add(-2, 3), 1);
+assert.equal(candidate.add(0, 0), 0);
+console.log("coding checks passed");

package/examples/recipes/extension-artifacts.ts

@@ -0,0 +1,65 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export function artifact(relativePath: string, content: string) {
+  return {
+    id: `recipes.${createHash("sha256").update(relativePath).digest("hex").slice(0, 16)}`,
+    relativePath,
+    sha256: createHash("sha256").update(content).digest("hex"),
+    contentBase64: Buffer.from(content).toString("base64"),
+    gitExclude: true,
+  };
+}
+
+export async function repositoryArtifacts(host: string) {
+  const directory = host === "claude" ? ".claude" : ".agents";
+  const relative = `${directory}/skills/startup-guide/SKILL.md`;
+  const body = await readFile(
+    join(import.meta.dir, "repository-skill", relative),
+    "utf8",
+  );
+  return [artifact(relative, body)];
+}
+
+export function pluginArtifacts() {
+  const files = {
+    "marketplace/.claude-plugin/marketplace.json": JSON.stringify({
+      name: "recipes",
+      owner: { name: "Sevro examples" },
+      plugins: [
+        { name: "startup", source: "./plugin", description: "Startup recipe" },
+      ],
+    }),
+    "marketplace/plugin/.claude-plugin/plugin.json": JSON.stringify({
+      name: "startup",
+      version: "1.0.0",
+    }),
+    "marketplace/plugin/.codex-plugin/plugin.json": JSON.stringify({
+      name: "startup",
+      version: "1.0.0",
+      skills: "./skills/",
+    }),
+    "marketplace/plugin/skills/startup-guide/SKILL.md":
+      "---\nname: startup-guide\ndescription: Explain application startup.\n---\nRead README.md. Explain its command and port.\n",
+    "marketplace/plugin/hooks/hooks.json": JSON.stringify({
+      hooks: {
+        SessionStart: [
+          {
+            hooks: [
+              {
+                type: "command",
+                command: '/bin/sh "${CLAUDE_PLUGIN_ROOT}/hooks/start.sh"',
+              },
+            ],
+          },
+        ],
+      },
+    }),
+    "marketplace/plugin/hooks/start.sh":
+      "#!/bin/sh\nprintf 'hook ran\\n' > \"$PWD/hook-ran.txt\"\n",
+  };
+  return Object.entries(files).map(([path, content]) =>
+    artifact(path, content),
+  );
+}

package/examples/recipes/extension-methods.ts

@@ -0,0 +1,174 @@
+import {
+  artifact,
+  pluginArtifacts,
+  repositoryArtifacts,
+} from "./extension-artifacts";
+
+export function record(value: unknown): Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value))
+    throw new Error("Expected a JSON object");
+  return value as Record<string, unknown>;
+}
+
+export function describe(mode: string, host: string) {
+  const capabilities: Record<string, string[]> = {
+    lifecycle: [],
+    "repository-skill": [`sevro.${host}.repository-invocation`],
+    plugins:
+      host === "codex"
+        ? ["sevro.codex.plugin-marketplace", "sevro.codex.explicit-invocation"]
+        : ["sevro.claude.plugin-dirs", "sevro.claude.explicit-invocation"],
+  };
+  const requiredCapabilities = capabilities[mode];
+  if (!requiredCapabilities) throw new Error("Unknown extension recipe");
+  return {
+    extension: { id: "recipes.startup", version: "1.0.0" },
+    protocols: ["sevro.extension.v1"],
+    requiredCapabilities,
+    optionalCapabilities: [],
+    graders: ["recipes.startup"],
+    taskVerdictPolicies: [],
+  };
+}
+
+function requiredInvocation(mode: string, host: string): string[] {
+  if (mode !== "repository-skill") return [];
+  return [
+    host === "codex"
+      ? "sevro.codex.explicit-invocation"
+      : "sevro.claude.repository-invocation",
+  ];
+}
+
+export function resolveCase(mode: string, host: string, fail: boolean) {
+  const invocation = mode === "lifecycle" ? "" : "{{sevro.skill_invocation}} ";
+  const prompt = fail
+    ? "Deliberate negative control: return only wrong."
+    : "Read README.md. Explain the application's start command and port. Do not change files.";
+  const requiredEvidence = requiredInvocation(mode, host);
+  return {
+    cases: [
+      {
+        id: "recipe-extension",
+        prompt: invocation + prompt,
+        fixture: {
+          kind: "generated",
+          commits: [
+            {
+              message: "chore: initialize sample",
+              files: { "README.md": "Run bun run dev on port 3000.\n" },
+            },
+          ],
+        },
+        checks: [
+          {
+            id: "startup-command",
+            grader: "sevro.regex",
+            configuration: { pattern: "bun run dev" },
+          },
+          {
+            id: "prepared-input",
+            grader: "sevro.shell",
+            configuration: {
+              run: "test \"$(cat startup.txt)\" = 'prepared startup data'",
+            },
+          },
+          ...(mode === "plugins"
+            ? [
+                {
+                  id: "plugin-hook",
+                  grader: "sevro.shell",
+                  configuration: {
+                    run: "cat hook-ran.txt",
+                    expectExact: "hook ran",
+                  },
+                },
+              ]
+            : []),
+          {
+            id: "recipes.startup.answer",
+            grader: "recipes.startup",
+            configuration: {},
+          },
+        ],
+        requiredEvidence,
+        extensionData: { "recipes.startup": { mode, host } },
+      },
+    ],
+  };
+}
+
+export async function prepare(mode: string, host: string) {
+  const base = {
+    artifacts: [artifact("startup.txt", "prepared startup data\n")],
+    requestedInstrumentation: [],
+    extensionData: { "recipes.startup": { mode, host } },
+  };
+  switch (mode) {
+    case "repository-skill":
+      return {
+        ...base,
+        artifacts: [...base.artifacts, ...(await repositoryArtifacts(host))],
+        ...(host === "codex"
+          ? { codexRepositorySkillInvocation: { skillName: "startup-guide" } }
+          : {
+              claudeRepositorySkillInvocation: { skillName: "startup-guide" },
+            }),
+      };
+    case "plugins":
+      return {
+        ...base,
+        artifacts: [...base.artifacts, ...pluginArtifacts()],
+        ...(host === "codex"
+          ? {
+              codexMarketplace: {
+                artifactRoot: "marketplace",
+                marketplaceName: "recipes",
+                pluginNames: ["startup"],
+              },
+              codexSkillInvocation: {
+                pluginName: "startup",
+                skillName: "startup-guide",
+              },
+            }
+          : {
+              claudePluginDirs: { artifactRoots: ["marketplace/plugin"] },
+              claudeSkillInvocation: {
+                pluginName: "startup",
+                skillName: "startup-guide",
+              },
+            }),
+      };
+    default:
+      return base;
+  }
+}
+
+function answerStatus(observation: Record<string, unknown>) {
+  if (observation.completeness !== "complete") return "unavailable";
+  const text = record(observation.data).text;
+  return typeof text === "string" && /\b3000\b/.test(text)
+    ? "passed"
+    : "failed";
+}
+
+export function evaluate(params: Record<string, unknown>) {
+  if (!Array.isArray(params.observations))
+    throw new Error("Missing observations");
+  const observations: unknown[] = params.observations;
+  const observation = observations
+    .map(record)
+    .find((item) => item.id === "sevro.observation.final-message");
+  if (!observation) throw new Error("Missing final-message observation");
+  const status = answerStatus(observation);
+  return {
+    checks: [
+      {
+        id: "recipes.startup.answer",
+        status,
+        evidenceRefs: ["sevro.observation.final-message"],
+      },
+    ],
+    metrics: [],
+  };
+}

package/examples/recipes/extension.ts

@@ -0,0 +1,37 @@
+import {
+  describe,
+  evaluate,
+  prepare,
+  record,
+  resolveCase,
+} from "./extension-methods";
+
+const mode = process.argv[2] ?? "lifecycle";
+const host = process.argv[3] ?? "deterministic";
+const fail = process.argv[4] === "fail";
+const request = record(JSON.parse(await Bun.stdin.text()) as unknown);
+
+async function result() {
+  switch (request.method) {
+    case "describe":
+      return describe(mode, host);
+    case "resolve":
+      return resolveCase(mode, host, fail);
+    case "prepare":
+      return await prepare(mode, host);
+    case "evaluate":
+      return evaluate(record(request.params));
+    default:
+      throw new Error("Unsupported extension method");
+  }
+}
+
+// One request per process; stdout contains only the matching protocol response.
+process.stdout.write(
+  JSON.stringify({
+    protocol: request.protocol,
+    id: request.id,
+    method: request.method,
+    result: await result(),
+  }),
+);

package/examples/recipes/repository-skill/.agents/skills/startup-guide/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: startup-guide
+description: Explain how to start this sample application and identify its port.
+---
+
+Read README.md. Explain the exact start command and port from that file.
+Do not change files. Do not invent a different command or port.

package/examples/recipes/repository-skill/.claude/skills/startup-guide/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: startup-guide
+description: Explain how to start this sample application and identify its port.
+---
+
+Read README.md. Explain the exact start command and port from that file.
+Do not change files. Do not invent a different command or port.