Create a verification skill
Every serious project needs a scripted way to drive the real app and prove behavior: launch it, exercise a feature the way a user would, and capture evidence. This skill generates that as a project-local skill tailored to the repo. You write the generator's output for the next agent, not for a human: it will be read cold, mid-task, by an agent that has never seen the app.
Project-local verification skills live under the active harness's native skills directory. That harness-to-directory mapping is owned by the profiles (skills_dir in skills/setup-pstack/profiles/<host>.json or repository profiles/<host>.json, resolved canonically via scripts.setup_pstack.resolve_profiles_dir, and mirrored by DEFAULT_SKILLS_DIRS in scripts/portability_schema.py); read it there instead of keeping a copy here.
The scaffold probes the workspace markers in host-detection order and defaults to Grok when none exist. Set --host <harness> to override detection. Markers select a destination; they do not prove which host is running. Plugin doctor lives at <harness-skills-dir>/verify-pstack/. Do not ship application verification skills under shared skills/. Do not write global home directories. App names must use lowercase kebab-case, such as demo-app; pstack is reserved for the plugin doctor. Checking or listing an existing verify-pstack remains permitted.
Use scripts/scaffold_verification_skill.py --host codex --app demo-app --write for a draft in .codex/skills/verify-demo-app/. The helper supports six built-in scaffold destinations plus candidate harnesses such as Pi under .pi/skills. This distinguishes the six declared host census from Droid unproven native operations in verify_portable.py doctor --host all. The generator creates SKILL.md, features/README.md, features/core.md, and an executable driver script at scripts/driver.sh. It accepts an absent or empty target and refuses nonempty directories and symlink targets or ancestors before writing. A rerun preserves authored files by refusing to overwrite them. For an interrupted draft, inspect its files and deliberately choose a fresh target or recover the existing draft. An explicit --target-dir may have any scratch name; native skill directory names must match frontmatter.
Verification conforms to the three test tiers documented in docs/verification-test-tiers.md. Tier 1 covers offline contract checks. Tier 2 covers host-dependent smoke tests. Tier 3 covers observed live app conformance. Run scripts/scaffold_verification_skill.py --check --target-dir <skill-dir> for Tier 1 structural validation. A structural pass checks metadata, required sections including ## Helpers, and map references. It leaves runtime proof unassessed. The scaffold is a draft until you tailor its commands, ship the app driver, and complete the smoke below.
Why not a wiki
A wiki is for humans. Agents pay for every token they reread. Write a skill plus a feature map. Use one short file per feature, the same four H2s, and a README that is the sweep order. Keep the map next to the skill at features/. Do not grow it into a wiki. Do not put drive recipes in OpenSpec. openspec/specs is capability Gherkin, not a drive recipe.
1. Interview the repo, not the user
Answer these from the codebase and only ask the user what you cannot observe:
- Surface: what does a user actually touch? A web UI, a CLI/TUI, a desktop app, an API, a mobile app, a library? A repo can have several. Pick the primary one and note the rest.
- Run: how does the app start locally? Prefer the repo's own documented dev command (package scripts, Makefile, README quickstart). Note ports, env vars, seed data, auth.
- Drive: how can an agent interact with it programmatically? Existing harnesses first. Playwright/Cypress specs, expect scripts, PTY helpers, curl-able endpoints, a debug port. Only then pick a generic recipe: browser/CDP for web and Electron, a tmux/PTY harness for CLI/TUI, plain HTTP for services.
- Observe: what evidence can be captured? Screenshots, terminal transcripts, response bodies, logs, exit codes, DB state.
- Isolate: can two instances run side by side (ports, data dirs, profiles)? The generated skill must refuse to double-drive a shared instance. If isolation is possible, name the handle and require it on every command. If it is not, refuse a second concurrent drive rather than corrupt the user's session. A short-lived CLI isolates with
--run-id or a fresh PTY, and may share a checkout. Do not emit --checkout unless the interview found a long-lived desktop driven over CDP whose port and profile are derived from a git checkout.
If the checkout doesn't build or start as-is, fix that first (or report it precisely) before generating. A skill written against a broken base teaches wrong steps. When an irrelevant missing asset blocks startup (a static dir the API never serves, a sample config), the generated skill may create it, clearly marked as verification scaffolding, and remove it in cleanup.
2. Generate the skill
Write SKILL.md at the path above with YAML frontmatter:
name: verify-<app>
description that is Use-when triggers only. Name the app, the surface, and when to reach for the skill. Do not dump Launch/Doctor/Drive into the description.
disable-model-invocation: true
Keep the generated skill body under 24,000 bytes. Google Antigravity imposes a strict 24,000-byte body limit and truncates oversized skills. scripts/scaffold_verification_skill.py --check enforces this bound.
Without frontmatter the skill never registers. Then write these sections, each grounded in what the interview actually found (no placeholders left):
- Launch: the exact command that starts the app for verification, and how to tell it's ready (a log line, a prompt). Launch must reach a usable state from an empty data dir, including any migrations and seed data. Ready means usable, not just that a process answers. A database health check can pass while its init scripts are still running. Include teardown. For a short-lived CLI or TUI there is no server to keep alive. Launch means build the binary (or install deps) once, then start each drive in its own isolated PTY or tmux session. Encode the Isolate answer here. Refuse double-drive of a shared instance.
- Doctor: one read-only check that answers whether this instance is worth driving. Process up, right version/build, port owned by us, auth valid. An agent runs this first whenever anything looks off. Package descriptors (
pstack.package.json) must be valid JSON with a non-empty version string; verifiers fail closed with a named error on missing, corrupt, or unversioned descriptors rather than guessing fallback version literals.
- Drive: the harness recipe with real selectors/commands from this repo, not examples. Prefer stable handles (ARIA labels, data attributes, prompt strings, route paths) over coordinates and tab order.
- Proof bar: do not submit "look, it opens." Proof is the production user path plus an observable result a skeptical reviewer would accept. Exercise every reachable entry point, mode, gated variant, and the success, cancel, error, empty, and persistence paths the change can affect. Show the trigger and the stable end state in the same evidence. Verify side effects, not only the final screen. Run doctor first. A capture against a stale or wrong instance is not evidence. Reduce scenario verdicts with the strict failure-first lattice: FAIL > BLOCKED > UNTESTED > PASS. A failure beats a blocked run, and blocked beats untested. For a broad regression, walk
features/README.md top to bottom. When frozen evaluation or candidate scoring tables diverge due to scope changes, failure messages must name the exact remediation command (such as python3 scripts/eval_blinded_pstack.py --record-dsh) so fixes are discoverable from CI output alone.
- Evidence: what to capture for a proof and where it goes. Tag evidence with its exact evidence level:
observed_live for live user paths, offline for static or offline unit runs, or static for metadata validation. Exercise the real user path, not internal setters or test-only endpoints. Bound all driver command executions to 60 seconds with strict timeout handling. Capture the action and the resulting state, not just the final screen. Verify side effects (files written, rows inserted, messages sent) alongside what's visible. Mocks only where a production boundary already isolates the external system. When the safe path is a dry-run or test mode, verify what it actually skips by observing (files, network, git refs) rather than trusting its name. Some dry-runs still touch the network or open a browser.
- Cleanup: how to tear down instances the run created. Never kill by process name. Kill what you started. Cleanup removes instances and scratch state, never the evidence. Proof artifacts survive the teardown, in a location the skill names.
- Helpers: ship the driver at
scripts/driver.sh (or driver.py). Make it executable. Include the exact invocation in the skill body. The driver wraps Launch, Doctor, Drive, and Cleanup with 60 second timeout bounds and exit code checking. A helper the reader has to reverse-engineer is not a helper. The references/feature-map-example/ omits a driver on purpose (map-only sample). Generated skills do not copy that omission.
Architectural Discipline: SOLID, KISS, DRY, YAGNI
Verification skills and feature maps must follow strict design hygiene:
- Single Responsibility (SRP): Each feature file describes exactly one user-facing behavior. The driver handles only orchestration and process lifecycle (
launch, doctor, drive, cleanup).
- Open/Closed (OCP): Add new test journeys by adding new sibling markdown files to
features/ and updating the Full sweep order, without modifying the core harness or driver contract.
- Liskov Substitution (LSP): Verification drivers across all harnesses conform to the uniform command contract:
doctor, launch, drive, cleanup, and all. Any harness runner can invoke any driver interchangeably.
- Interface Segregation (ISP): Break monolithic verification into focused feature drives. Agents execute specific feature paths independently without running the entire suite.
- Dependency Inversion (DIP): Depend on user-visible abstractions and stable contracts (routes, CLI flags, ARIA roles, exit codes) rather than internal implementation details, internal variables, or fragile UI pixel coordinates.
- KISS & YAGNI: Prefer standard library tools and the simplest driver that works. Avoid speculative multi-process orchestration frameworks when a single isolated run or
--run-id suffices.
- DRY: Define verification recipes canonically once in their respective feature files. Reuse existing harness helpers rather than duplicating launch recipes.
Isolate the resources the driver touches
A driver that two concurrent runs can execute owns every port, path, marker, and child process it uses. Do not answer a collision by serialising the whole suite; isolate instead. In this repository the worked example is tests/fixtures/resource-isolation/. It holds a colliding and an isolated implementation of one two-worker shape in Python and Node, driven by tests/test_ci_resource_isolation.py. The colliding half is the negative control: it fails as soon as these rules are broken, so keep it failing.
- Owner. Name the run that owns each acquired resource. Two runs that could claim the same port or the same directory are already broken.
- Atomic allocation. Reserve by keeping whatever wins the race: bind port
0 and hold the socket, mktemp a fresh root. Never probe free-then-use; the gap between the check and the claim is the bug.
- Observed readiness. Start work only after the peer publishes a marker or accepts a connection, and bound that wait so a missing peer fails loudly instead of hanging. A sleep is not readiness, and a longer timeout is not a fix.
- Cross-process topology. Say which processes run at once and exactly where they meet (the fixture's rendezvous directory). Put the acquired port and root in the marker so the peer acts on the real values.
- Global state. Write only under your own private root, and restore anything you change, including environment, files, and shared names, on the failure path as well as the success path. In harness tests and package levers, isolate fixture state (such as
PSTACK_FIXTURE_HOME) from ambient user home configurations without disrupting system binary execution. Prune transient worktrees via git worktree prune.
- Cancellation. Cancel by signalling the child you started, never by process name, and only while it is still yours to stop.
- Quiescent teardown. Await the child's exit, close the listener, remove the private root, then assert the settled state: no listener, no leftover files, peers past the barrier.
kill, abort, or a bare close is not settled state.
- Platform. Port reuse, file locking, and termination signals differ between POSIX and Windows. Keep the driver's sequence portable, or declare the host it is proven on and treat the rest as untested.
3. Seed the feature map
Create features/README.md plus one file per user-facing feature you can identify (aim for the top 3-5 to start, from routes, commands, menus, or docs). Put the map at skill-root features/, next to SKILL.md. Do not nest it under references/features/ (that layout is the sample app). Do not write it under openspec/.
Follow the shape in references/feature-map-example/, with a README index and one file per feature. The README must include ## Full sweep. Walk features/README.md top to bottom for a broad regression. Driving one convenient feature is not a sweep. Add a journeys closer only when the app has cross-feature paths.
List sibling markdown filenames in sweep order, either as numbered backtick filenames under ## Full sweep or as links under ## Features with Full sweep prose directing that order. Each feature must appear once in that ordered list, with no missing or unlisted files. ./core.md and core.md name the same sibling. References must stay inside features/; directories and symlinks are not feature files. If both sections list files, they must cover the same files. Repeating a file across those two sections is allowed; repeating it within either section is a duplicate.
Each file answers, from the user's point of view, what the feature is, how to reach it, how to drive it with the harness, and what observable end state proves it works. Use exactly four H2s in this order: Sub-features, How to get to it (user POV), Driving it with <harness>, and Gotchas. Name a harness after Driving it with. If the seed data lacks a precondition that a journey needs, the journey reports a failure and the reason goes in that feature's Gotchas. Never weaken the journey to make it pass. The map is the repo's maintained verification source. A proof that drives one convenient entry point is incomplete when the map lists others.
Upstream-sync verification target (PStack 0.15.36)
Cross-port negative controls and authority
When translating a scenario from another agent harness (for example, the pinned pstack-claude Pi equivalence tests), preserve only the observable contract: host and version, actor/role, permission precondition, trigger, stable output/side effect, failure postcondition and cleanup owner. Capture the exact source revision and a pointer to the original test; classify policy forks explicitly. Rebind it to the active host's own profile/driver before calling it verified. Tool aliases, package manifests and reference-host tests are not sufficient for a target-host PASS. Reuse the host's existing verifier feature map and four-plane receipts; do not copy a second agent process manager or verification registry.
For a child or background workflow, include one deliberate counterexample for each newly adopted gate: denied spawn has no effect; child completion matches the spawned ID and actual exit; cancellation cannot count as PASS; wakeup stopped before delivery does not rearm; and worktree teardown preserves ignored, untracked, symlink-linked and committed data. Record a state transition and exact actor/child ID, not just a textual success line. Distinguish an interactive user question from an enforceable permission gate, especially in headless/nested sessions. If the installed runtime does not expose the behavior, mark that scenario BLOCKED/UNTESTED without weakening the gate. Map the contract to the current cross-port OpenSpec only when the proposed scenario actually applies to PStack.
When using this generator for PStack's upstream synchronization, map user-facing capabilities rather than filenames: skill discovery, host-specific routing, model-family judging, adversarial review, Orchestrate ownership, package projection and evidence/rollback. The feature map records which upstream source revision and applied port revision it covers. Capture one failing negative control per claimed safety gate (e.g. same-family judge, fabricated/replayed review finding, stale exact-head receipt, invalid package descriptor, missing required host capability). Never weaken a negative control just to obtain a green report. Keep verification receipts in an isolated run directory so cleanup cannot erase them.
A scaffold check or fixture-only pytest result is STATIC/OFFLINE, not proof of a working live host. A missing host's executable capability is BLOCKED or UNTESTED; source-only readings are SOURCE_REVIEWED. Give the operator the exact driver invocation and affected feature IDs. Do not create a second repository-wide status registry: use the existing scripts/verify_portable.py host census and the generated skill's own feature map.
4. Prove the generated skill before handing it over
Run its own instructions end to end once: launch, doctor, drive ONE mapped feature (one is enough for this smoke, and the map exists so later runs can cover the rest), capture evidence, clean up. That smoke is not a Full sweep. After cleanup, confirm the evidence still exists at the named location. A cleanup that eats the proof fails this step. Fix what fails, and run the generated cleanup after every failed iteration too, so broken attempts don't strand processes and ports. A generated skill that was never executed is a draft, not a deliverable. If you proved it in a stand-in for the real target (a container in place of a fresh VM, a local stack in place of a remote one), list every setup step the stand-in did that the target will not. Those steps stay unverified until a run on the real target covers them.
Use a fresh evidence directory for each run and each named step. Preserve earlier captures. Record the instance identity, source revision, feature, command, stdout, stderr, and exit code alongside the observed stable result and side effects. Keep doctor, trigger, result, and side-effect evidence tied to the same instance and feature. Static artifact names or a logging helper cannot prove an app drive. Report draft status, structural validation, and real runtime smoke evidence separately.
5. Offer the maintenance loop
Point the user at /maintain-verification-skill for keeping the map honest as the app changes. Suggest a cadence only if they ask.
1---2name: create-verification-skill3description: "Use when a project has no scripted way to prove UI, CLI, or service behavior, or for /create-verification-skill or \"make a control skill for this repo\"."4disable-model-invocation: true5metadata:6 source: https://skillmd.com/skills/tommy-ca/create-verification-skill7---89# Create a verification skill1011Every serious project needs a scripted way to drive the real app and prove behavior: launch it, exercise a feature the way a user would, and capture evidence. This skill generates that as a project-local skill tailored to the repo. You write the generator's output for the next agent, not for a human: it will be read cold, mid-task, by an agent that has never seen the app.1213Project-local verification skills live under the active harness's native skills directory. That harness-to-directory mapping is owned by the profiles (`skills_dir` in `skills/setup-pstack/profiles/<host>.json` or repository `profiles/<host>.json`, resolved canonically via `scripts.setup_pstack.resolve_profiles_dir`, and mirrored by `DEFAULT_SKILLS_DIRS` in `scripts/portability_schema.py`); read it there instead of keeping a copy here.1415The scaffold probes the workspace markers in host-detection order and defaults to Grok when none exist. Set `--host <harness>` to override detection. Markers select a destination; they do not prove which host is running. Plugin doctor lives at `<harness-skills-dir>/verify-pstack/`. Do not ship application verification skills under shared `skills/`. Do not write global home directories. App names must use lowercase kebab-case, such as `demo-app`; `pstack` is reserved for the plugin doctor. Checking or listing an existing `verify-pstack` remains permitted.1617Use `scripts/scaffold_verification_skill.py --host codex --app demo-app --write` for a draft in `.codex/skills/verify-demo-app/`. The helper supports six built-in scaffold destinations plus candidate harnesses such as Pi under `.pi/skills`. This distinguishes the six declared host census from Droid unproven native operations in `verify_portable.py doctor --host all`. The generator creates `SKILL.md`, `features/README.md`, `features/core.md`, and an executable driver script at `scripts/driver.sh`. It accepts an absent or empty target and refuses nonempty directories and symlink targets or ancestors before writing. A rerun preserves authored files by refusing to overwrite them. For an interrupted draft, inspect its files and deliberately choose a fresh target or recover the existing draft. An explicit `--target-dir` may have any scratch name; native skill directory names must match frontmatter.1819Verification conforms to the three test tiers documented in `docs/verification-test-tiers.md`. Tier 1 covers offline contract checks. Tier 2 covers host-dependent smoke tests. Tier 3 covers observed live app conformance. Run `scripts/scaffold_verification_skill.py --check --target-dir <skill-dir>` for Tier 1 structural validation. A structural pass checks metadata, required sections including `## Helpers`, and map references. It leaves runtime proof unassessed. The scaffold is a draft until you tailor its commands, ship the app driver, and complete the smoke below.2021## Why not a wiki2223A wiki is for humans. Agents pay for every token they reread. Write a skill plus a feature map. Use one short file per feature, the same four H2s, and a README that is the sweep order. Keep the map next to the skill at `features/`. Do not grow it into a wiki. Do not put drive recipes in OpenSpec. `openspec/specs` is capability Gherkin, not a drive recipe.2425## 1. Interview the repo, not the user2627Answer these from the codebase and only ask the user what you cannot observe:2829- **Surface:** what does a user actually touch? A web UI, a CLI/TUI, a desktop app, an API, a mobile app, a library? A repo can have several. Pick the primary one and note the rest.30- **Run:** how does the app start locally? Prefer the repo's own documented dev command (package scripts, Makefile, README quickstart). Note ports, env vars, seed data, auth.31- **Drive:** how can an agent interact with it programmatically? Existing harnesses first. Playwright/Cypress specs, expect scripts, PTY helpers, curl-able endpoints, a debug port. Only then pick a generic recipe: browser/CDP for web and Electron, a tmux/PTY harness for CLI/TUI, plain HTTP for services.32- **Observe:** what evidence can be captured? Screenshots, terminal transcripts, response bodies, logs, exit codes, DB state.33- **Isolate:** can two instances run side by side (ports, data dirs, profiles)? The generated skill must refuse to double-drive a shared instance. If isolation is possible, name the handle and require it on every command. If it is not, refuse a second concurrent drive rather than corrupt the user's session. A short-lived CLI isolates with `--run-id` or a fresh PTY, and may share a checkout. Do not emit `--checkout` unless the interview found a long-lived desktop driven over CDP whose port and profile are derived from a git checkout.3435If the checkout doesn't build or start as-is, fix that first (or report it precisely) before generating. A skill written against a broken base teaches wrong steps. When an irrelevant missing asset blocks startup (a static dir the API never serves, a sample config), the generated skill may create it, clearly marked as verification scaffolding, and remove it in cleanup.3637## 2. Generate the skill3839Write `SKILL.md` at the path above with YAML frontmatter:4041- `name: verify-<app>`42- `description` that is Use-when triggers only. Name the app, the surface, and when to reach for the skill. Do not dump Launch/Doctor/Drive into the description.43- `disable-model-invocation: true`4445Keep the generated skill body under 24,000 bytes. Google Antigravity imposes a strict 24,000-byte body limit and truncates oversized skills. `scripts/scaffold_verification_skill.py --check` enforces this bound.4647Without frontmatter the skill never registers. Then write these sections, each grounded in what the interview actually found (no placeholders left):4849- **Launch:** the exact command that starts the app for verification, and how to tell it's ready (a log line, a prompt). Launch must reach a usable state from an empty data dir, including any migrations and seed data. Ready means usable, not just that a process answers. A database health check can pass while its init scripts are still running. Include teardown. For a short-lived CLI or TUI there is no server to keep alive. Launch means build the binary (or install deps) once, then start each drive in its own isolated PTY or tmux session. Encode the Isolate answer here. Refuse double-drive of a shared instance.50- **Doctor:** one read-only check that answers whether this instance is worth driving. Process up, right version/build, port owned by us, auth valid. An agent runs this first whenever anything looks off. Package descriptors (`pstack.package.json`) must be valid JSON with a non-empty `version` string; verifiers fail closed with a named error on missing, corrupt, or unversioned descriptors rather than guessing fallback version literals.51- **Drive:** the harness recipe with real selectors/commands from this repo, not examples. Prefer stable handles (ARIA labels, data attributes, prompt strings, route paths) over coordinates and tab order.52- **Proof bar:** do not submit "look, it opens." Proof is the production user path plus an observable result a skeptical reviewer would accept. Exercise every reachable entry point, mode, gated variant, and the success, cancel, error, empty, and persistence paths the change can affect. Show the trigger and the stable end state in the same evidence. Verify side effects, not only the final screen. Run doctor first. A capture against a stale or wrong instance is not evidence. Reduce scenario verdicts with the strict failure-first lattice: FAIL > BLOCKED > UNTESTED > PASS. A failure beats a blocked run, and blocked beats untested. For a broad regression, walk `features/README.md` top to bottom. When frozen evaluation or candidate scoring tables diverge due to scope changes, failure messages must name the exact remediation command (such as `python3 scripts/eval_blinded_pstack.py --record-dsh`) so fixes are discoverable from CI output alone.53- **Evidence:** what to capture for a proof and where it goes. Tag evidence with its exact evidence level: `observed_live` for live user paths, `offline` for static or offline unit runs, or `static` for metadata validation. Exercise the real user path, not internal setters or test-only endpoints. Bound all driver command executions to 60 seconds with strict timeout handling. Capture the action and the resulting state, not just the final screen. Verify side effects (files written, rows inserted, messages sent) alongside what's visible. Mocks only where a production boundary already isolates the external system. When the safe path is a dry-run or test mode, verify what it actually skips by observing (files, network, git refs) rather than trusting its name. Some dry-runs still touch the network or open a browser.54- **Cleanup:** how to tear down instances the run created. Never kill by process name. Kill what you started. Cleanup removes instances and scratch state, never the evidence. Proof artifacts survive the teardown, in a location the skill names.55- **Helpers:** ship the driver at `scripts/driver.sh` (or `driver.py`). Make it executable. Include the exact invocation in the skill body. The driver wraps Launch, Doctor, Drive, and Cleanup with 60 second timeout bounds and exit code checking. A helper the reader has to reverse-engineer is not a helper. The `references/feature-map-example/` omits a driver on purpose (map-only sample). Generated skills do not copy that omission.5657## Architectural Discipline: SOLID, KISS, DRY, YAGNI5859Verification skills and feature maps must follow strict design hygiene:6061- **Single Responsibility (SRP):** Each feature file describes exactly one user-facing behavior. The driver handles only orchestration and process lifecycle (`launch`, `doctor`, `drive`, `cleanup`).62- **Open/Closed (OCP):** Add new test journeys by adding new sibling markdown files to `features/` and updating the Full sweep order, without modifying the core harness or driver contract.63- **Liskov Substitution (LSP):** Verification drivers across all harnesses conform to the uniform command contract: `doctor`, `launch`, `drive`, `cleanup`, and `all`. Any harness runner can invoke any driver interchangeably.64- **Interface Segregation (ISP):** Break monolithic verification into focused feature drives. Agents execute specific feature paths independently without running the entire suite.65- **Dependency Inversion (DIP):** Depend on user-visible abstractions and stable contracts (routes, CLI flags, ARIA roles, exit codes) rather than internal implementation details, internal variables, or fragile UI pixel coordinates.66- **KISS & YAGNI:** Prefer standard library tools and the simplest driver that works. Avoid speculative multi-process orchestration frameworks when a single isolated run or `--run-id` suffices.67- **DRY:** Define verification recipes canonically once in their respective feature files. Reuse existing harness helpers rather than duplicating launch recipes.6869## Isolate the resources the driver touches7071A driver that two concurrent runs can execute owns every port, path, marker, and child process it uses. Do not answer a collision by serialising the whole suite; isolate instead. In this repository the worked example is `tests/fixtures/resource-isolation/`. It holds a colliding and an isolated implementation of one two-worker shape in Python and Node, driven by `tests/test_ci_resource_isolation.py`. The colliding half is the negative control: it fails as soon as these rules are broken, so keep it failing.7273- **Owner.** Name the run that owns each acquired resource. Two runs that could claim the same port or the same directory are already broken.74- **Atomic allocation.** Reserve by keeping whatever wins the race: bind port `0` and hold the socket, `mktemp` a fresh root. Never probe free-then-use; the gap between the check and the claim is the bug.75- **Observed readiness.** Start work only after the peer publishes a marker or accepts a connection, and bound that wait so a missing peer fails loudly instead of hanging. A sleep is not readiness, and a longer timeout is not a fix.76- **Cross-process topology.** Say which processes run at once and exactly where they meet (the fixture's rendezvous directory). Put the acquired port and root in the marker so the peer acts on the real values.77- **Global state.** Write only under your own private root, and restore anything you change, including environment, files, and shared names, on the failure path as well as the success path. In harness tests and package levers, isolate fixture state (such as `PSTACK_FIXTURE_HOME`) from ambient user home configurations without disrupting system binary execution. Prune transient worktrees via `git worktree prune`.78- **Cancellation.** Cancel by signalling the child you started, never by process name, and only while it is still yours to stop.79- **Quiescent teardown.** Await the child's exit, close the listener, remove the private root, then assert the settled state: no listener, no leftover files, peers past the barrier. `kill`, `abort`, or a bare `close` is not settled state.80- **Platform.** Port reuse, file locking, and termination signals differ between POSIX and Windows. Keep the driver's sequence portable, or declare the host it is proven on and treat the rest as untested.8182## 3. Seed the feature map8384Create `features/README.md` plus one file per user-facing feature you can identify (aim for the top 3-5 to start, from routes, commands, menus, or docs). Put the map at skill-root `features/`, next to `SKILL.md`. Do not nest it under `references/features/` (that layout is the sample app). Do not write it under `openspec/`.8586Follow the shape in [`references/feature-map-example/`](references/feature-map-example/), with a README index and one file per feature. The README must include `## Full sweep`. Walk `features/README.md` top to bottom for a broad regression. Driving one convenient feature is not a sweep. Add a journeys closer only when the app has cross-feature paths.8788List sibling markdown filenames in sweep order, either as numbered backtick filenames under `## Full sweep` or as links under `## Features` with Full sweep prose directing that order. Each feature must appear once in that ordered list, with no missing or unlisted files. `./core.md` and `core.md` name the same sibling. References must stay inside `features/`; directories and symlinks are not feature files. If both sections list files, they must cover the same files. Repeating a file across those two sections is allowed; repeating it within either section is a duplicate.8990Each file answers, from the user's point of view, what the feature is, how to reach it, how to drive it with the harness, and what observable end state proves it works. Use exactly four H2s in this order: `Sub-features`, `How to get to it (user POV)`, `Driving it with <harness>`, and `Gotchas`. Name a harness after `Driving it with`. If the seed data lacks a precondition that a journey needs, the journey reports a failure and the reason goes in that feature's `Gotchas`. Never weaken the journey to make it pass. The map is the repo's maintained verification source. A proof that drives one convenient entry point is incomplete when the map lists others.9192## Upstream-sync verification target (PStack 0.15.36)9394## Cross-port negative controls and authority9596When translating a scenario from another agent harness (for example, the pinned pstack-claude Pi equivalence tests), preserve only the **observable contract**: host and version, actor/role, permission precondition, trigger, stable output/side effect, failure postcondition and cleanup owner. Capture the exact source revision and a pointer to the original test; classify policy forks explicitly. Rebind it to the active host's own profile/driver before calling it verified. Tool aliases, package manifests and reference-host tests are not sufficient for a target-host PASS. Reuse the host's existing verifier feature map and four-plane receipts; do not copy a second agent process manager or verification registry.9798For a child or background workflow, include one deliberate **counterexample** for each newly adopted gate: denied spawn has no effect; child completion matches the spawned ID and actual exit; cancellation cannot count as PASS; wakeup stopped before delivery does not rearm; and worktree teardown preserves ignored, untracked, symlink-linked and committed data. Record a state transition and exact actor/child ID, not just a textual success line. Distinguish an interactive user question from an enforceable permission gate, especially in headless/nested sessions. If the installed runtime does not expose the behavior, mark that scenario BLOCKED/UNTESTED without weakening the gate. Map the contract to [the current cross-port OpenSpec](../../openspec/specs/pstack-portability/spec.md) only when the proposed scenario actually applies to PStack.99100When using this generator for PStack's upstream synchronization, map user-facing capabilities rather than filenames: skill discovery, host-specific routing, model-family judging, adversarial review, Orchestrate ownership, package projection and evidence/rollback. The feature map records which upstream source revision and **applied** port revision it covers. Capture one failing negative control per claimed safety gate (e.g. same-family judge, fabricated/replayed review finding, stale exact-head receipt, invalid package descriptor, missing required host capability). Never weaken a negative control just to obtain a green report. Keep verification receipts in an isolated run directory so cleanup cannot erase them.101102A scaffold check or fixture-only pytest result is `STATIC`/`OFFLINE`, not proof of a working live host. A missing host's executable capability is `BLOCKED` or `UNTESTED`; source-only readings are `SOURCE_REVIEWED`. Give the operator the exact driver invocation and affected feature IDs. Do not create a second repository-wide status registry: use the existing `scripts/verify_portable.py` host census and the generated skill's own feature map.103104## 4. Prove the generated skill before handing it over105106Run its own instructions end to end once: launch, doctor, drive ONE mapped feature (one is enough for this smoke, and the map exists so later runs can cover the rest), capture evidence, clean up. That smoke is not a Full sweep. After cleanup, confirm the evidence still exists at the named location. A cleanup that eats the proof fails this step. Fix what fails, and run the generated cleanup after every failed iteration too, so broken attempts don't strand processes and ports. A generated skill that was never executed is a draft, not a deliverable. If you proved it in a stand-in for the real target (a container in place of a fresh VM, a local stack in place of a remote one), list every setup step the stand-in did that the target will not. Those steps stay unverified until a run on the real target covers them.107108Use a fresh evidence directory for each run and each named step. Preserve earlier captures. Record the instance identity, source revision, feature, command, stdout, stderr, and exit code alongside the observed stable result and side effects. Keep doctor, trigger, result, and side-effect evidence tied to the same instance and feature. Static artifact names or a logging helper cannot prove an app drive. Report draft status, structural validation, and real runtime smoke evidence separately.109110## 5. Offer the maintenance loop111112Point the user at `/maintain-verification-skill` for keeping the map honest as the app changes. Suggest a cadence only if they ask.