test(patterns): add validated HACK-P01 and HACK-P02 example fixtures

docs/agent-guidance.md

@@ -93,6 +93,17 @@ and domain owner; the disposition does not waive that owner's runtime gates.
 `tests/pattern-catalogue.test.ts` checks completeness, CLI_SPEC command
 resolution and the banned-recipe scan.
 
+A card's `example` field names a static example project under
+`examples/patterns/` (today HACK-P01 and HACK-P02). The field is contributor
+reference only and is not rendered, because the plugin ships without the
+repository's `examples/` tree. `tests/pattern-examples.test.ts` checks that each
+reference resolves and every fixture belongs to one card. It also validates
+each fixture's `hack.config.json` against the project schema and parser, the
+P01 Compose file against the `locked-v1` dependency cache contract, and the P02
+toolchain service against its card. Every `hack` command in a fixture README
+must resolve in CLI_SPEC and name a declared service and profile. These checks
+are static: they do not start containers or qualify the runtime gates.
+
 Skill candidates and where their patterns live now:
 
 | Candidate | Decision | Patterns live in | Promotion owner and missing contract |

examples/patterns/p01-dependency-bootstrap/.gitignore

@@ -0,0 +1 @@
+node_modules/

examples/patterns/p01-dependency-bootstrap/.hack/docker-compose.yml

@@ -0,0 +1,57 @@
+name: pattern-p01
+services:
+  # One-shot initializer for the immutable dependency payload (HACK-P01).
+  install:
+    image: oven/bun:1.4.2-alpine@sha256:d888c0ae6c86d7866ff10c5aafdd9077b36aee6455b33dd270fb93c0dd5cef6f
+    platform: linux/arm64
+    working_dir: /app
+    entrypoint: []
+    command: ["bun", "install", "--frozen-lockfile"]
+    labels:
+      hack.dependencies.cache-volume: dependencies
+      hack.dependencies.lockfiles: bun.lock
+      hack.dependencies.runtime-files: package.json,packages/greeting/package.json,packages/greeting/index.js
+      hack.dependencies.cache-protocol: locked-v1
+      hack.dependencies.cache-generation: "0"
+      hack.dependencies.cache-verify: '["bun", "-e", "require.resolve(\"greeting\")"]'
+    volumes:
+      - ..:/app
+      - dependencies:/app/node_modules
+
+  # Worktree-specific generation: always runs, owns its own output volume.
+  generate:
+    image: oven/bun:1.4.2-alpine@sha256:d888c0ae6c86d7866ff10c5aafdd9077b36aee6455b33dd270fb93c0dd5cef6f
+    platform: linux/arm64
+    working_dir: /app
+    command: ["bun", "scripts/generate.ts"]
+    depends_on:
+      install:
+        condition: service_completed_successfully
+    volumes:
+      - ..:/app
+      - dependencies:/app/node_modules:ro
+      - generated:/generated
+
+  app:
+    image: oven/bun:1.4.2-alpine@sha256:d888c0ae6c86d7866ff10c5aafdd9077b36aee6455b33dd270fb93c0dd5cef6f
+    platform: linux/arm64
+    working_dir: /app
+    command: ["bun", "src/server.ts"]
+    depends_on:
+      install:
+        condition: service_completed_successfully
+      generate:
+        condition: service_completed_successfully
+    volumes:
+      - ..:/app
+      - dependencies:/app/node_modules:ro
+      - generated:/generated:ro
+    healthcheck:
+      test: ["CMD", "bun", "-e", "const r = await fetch('http://127.0.0.1:3000/healthz'); process.exit(r.ok ? 0 : 1)"]
+      interval: 5s
+      timeout: 3s
+      retries: 12
+
+volumes:
+  dependencies: {}
+  generated: {}

examples/patterns/p01-dependency-bootstrap/.hack/hack.config.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://schemas.hack/hack.config.schema.json",
+  "name": "pattern-p01",
+  "dev_host": "pattern-p01.hack.local",
+  "logs": {
+    "follow_backend": "compose",
+    "snapshot_backend": "compose",
+    "clear_on_down": false
+  }
+}

examples/patterns/p01-dependency-bootstrap/README.md

@@ -0,0 +1,64 @@
+# HACK-P01 example: one-shot dependency and generated-artifact bootstrap
+
+Minimal project for catalogue card HACK-P01 (tracked in HACK-1145). It shows the
+part of the pattern Hack supports today. The card's disposition is **partial**;
+see "What this example does not prove" below.
+
+## Layout
+
+- `install` is a one-shot initializer. It opts into the
+  `hack.dependencies.cache-protocol: locked-v1` label, uses a digest-pinned
+  installer image with an explicit platform, keeps the default (empty)
+  environment, and writes only the `dependencies` volume.
+- `generate` is the worktree-specific generation step. It always runs, owns its
+  own `generated` volume, and publishes its output by rename.
+- `app` starts only after both one-shot services exit successfully. It mounts
+  `dependencies` and `generated` read-only and has its own health check.
+
+Installation, generation and application readiness are separate steps. The
+verifier label (`require.resolve("greeting")`) checks the real dependency the
+application imports, not just a populated directory.
+
+Set `platform` to the platform of your Docker daemon before you run it.
+
+## Commands
+
+Start the project and wait for the detached startup result:
+
+```sh
+hack up --json
+```
+
+Inspect service state, including the one-shot exits:
+
+```sh
+hack ps --json
+```
+
+Read the initializer's bounded log:
+
+```sh
+hack logs --no-follow --tail 100 install
+```
+
+Stop the project. Ordinary `hack down` keeps the dependency volume:
+
+```sh
+hack down
+```
+
+If an initializer attempt fails or is interrupted, find the cause, then increment
+`hack.dependencies.cache-generation` in `.hack/docker-compose.yml` and run
+`hack up --json` again. Do not delete protocol markers to force reuse.
+
+## What this example does not prove
+
+- Atomic publication of worktree-specific generated artifacts across concurrent
+  writers.
+- Installers that need credentials or environment values. `locked-v1` refuses
+  explicit `environment` and `env_file` on the initializer.
+- Two-worktree or interrupted-writer qualification. Those runtime gates belong to
+  WU07/WU11.
+
+The static checks in `tests/pattern-examples.test.ts` validate this config and
+its commands. They do not start containers.

examples/patterns/p01-dependency-bootstrap/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "pattern-p01",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "greeting": "file:./packages/greeting"
+  }
+}

examples/patterns/p01-dependency-bootstrap/packages/greeting/index.js

@@ -0,0 +1,4 @@
+/** Stand-in for an installed dependency that the application imports. */
+export function greet(name) {
+  return `hello, ${name}`;
+}

examples/patterns/p01-dependency-bootstrap/packages/greeting/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "greeting",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "index.js"
+}

examples/patterns/p01-dependency-bootstrap/scripts/generate.ts

@@ -0,0 +1,13 @@
+/**
+ * Worktree-specific generation step. It runs only after the shared dependency
+ * initializer succeeds and writes only to this instance's `generated` volume.
+ */
+import { rename, writeFile } from "node:fs/promises";
+
+const target = "/generated/build-info.json";
+const pending = `${target}.pending`;
+const payload = `${JSON.stringify({ generatedAt: new Date().toISOString() })}\n`;
+
+// Publish by rename so readers see a complete old or complete new file.
+await writeFile(pending, payload);
+await rename(pending, target);

examples/patterns/p01-dependency-bootstrap/src/server.ts

@@ -0,0 +1,20 @@
+import { readFile } from "node:fs/promises";
+import { greet } from "greeting";
+
+const buildInfo = JSON.parse(
+  await readFile("/generated/build-info.json", "utf8")
+) as { readonly generatedAt: string };
+
+Bun.serve({
+  port: 3000,
+  fetch(request) {
+    const { pathname } = new URL(request.url);
+    if (pathname === "/healthz") {
+      return new Response("ok");
+    }
+    return Response.json({
+      message: greet("pattern-p01"),
+      generatedAt: buildInfo.generatedAt,
+    });
+  },
+});

examples/patterns/p02-portable-toolchain/.gitignore

@@ -0,0 +1 @@
+node_modules/

examples/patterns/p02-portable-toolchain/.hack/docker-compose.yml

@@ -0,0 +1,21 @@
+name: pattern-p02
+services:
+  # One-shot toolchain behind an opt-in profile (HACK-P02). There is no
+  # long-running application service in this project.
+  toolchain:
+    image: oven/bun:1.4.2-alpine@sha256:d888c0ae6c86d7866ff10c5aafdd9077b36aee6455b33dd270fb93c0dd5cef6f
+    profiles: [toolchain]
+    init: true
+    working_dir: /app
+    cpus: 2
+    mem_limit: 2g
+    environment:
+      BUN_INSTALL_CACHE_DIR: /cache/bun
+    volumes:
+      - ..:/app
+      - toolchain_dependencies:/app/node_modules
+      - toolchain_bun_cache:/cache/bun
+
+volumes:
+  toolchain_dependencies: {}
+  toolchain_bun_cache: {}

examples/patterns/p02-portable-toolchain/.hack/hack.config.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://schemas.hack/hack.config.schema.json",
+  "name": "pattern-p02",
+  "dev_host": "pattern-p02.hack.local"
+}

examples/patterns/p02-portable-toolchain/README.md

@@ -0,0 +1,48 @@
+# HACK-P02 example: portable toolchain without an always-on application
+
+Minimal project for catalogue card HACK-P02 (tracked in HACK-1146). It shows the
+part of the pattern Hack supports today. The card's disposition is **partial**;
+see "What this example does not prove" below.
+
+## Layout
+
+The project has no long-running application. `.hack/docker-compose.yml` declares
+one one-shot `toolchain` service behind the opt-in `toolchain` profile:
+
+- a digest-pinned tool image, so every machine runs the same Bun version;
+- explicit resource bounds (`cpus`, `mem_limit`);
+- separate named volumes for installed dependencies and the Bun download cache;
+- no Docker socket, user home, SSH agent or credential directory mounts, and no
+  `env_file`. Keep project secrets out of the image build context as well.
+
+## Commands
+
+Install dependencies into the toolchain's own volume:
+
+```sh
+hack run --profile toolchain toolchain -- bun install --frozen-lockfile
+```
+
+Run the checks:
+
+```sh
+hack run --profile toolchain toolchain -- bun test
+```
+
+The command's own exit status is the result. Check it directly; do not pipe the
+output through a filter that can hide a failed check.
+
+The service is one-shot, so there is nothing to keep running. `hack down` keeps
+the named cache volumes.
+
+## What this example does not prove
+
+- Cache reuse across worktrees with bounded eviction.
+- A source receipt for linked worktrees, whose `.git` entry is a pointer file
+  rather than a directory.
+- Owned cache accounting. Those runtime gates belong to WU11.
+
+A test-only source identity override must never reach release evidence.
+
+The static checks in `tests/pattern-examples.test.ts` validate this config and
+its commands. They do not start containers.

examples/patterns/p02-portable-toolchain/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "pattern-p02",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "check": "bun test"
+  }
+}

examples/patterns/p02-portable-toolchain/src/sum.test.ts

@@ -0,0 +1,7 @@
+import { expect, test } from "bun:test";
+import { sum } from "./sum.ts";
+
+test("sum adds every value", () => {
+  expect(sum([1, 2, 3])).toBe(6);
+  expect(sum([])).toBe(0);
+});

examples/patterns/p02-portable-toolchain/src/sum.ts

@@ -0,0 +1,4 @@
+/** Tiny library code so the toolchain service has something to check. */
+export function sum(values: readonly number[]): number {
+  return values.reduce((total, value) => total + value, 0);
+}