vinv 0.0.2__py3-none-win_amd64.whl

bringup/__init__.py

@@ -0,0 +1,29 @@
+"""bringup — standalone, two-stage Stage 2 bring-up runbook renderer.
+
+Renders the runbooks a coding-agent harness executes off a repository's
+discovery handbook (``<repo>/.vinv/vinv.md``), in two stages:
+
+* ``render_list_prompt`` (Stage 2a) — the runbook that enumerates every
+  service and its modules into ``<repo>/.vinv/services.json``.
+* ``render_start_prompt`` (Stage 2b) — the runbook that installs and starts
+  one selected service, wrapping a Python service with ``tracelens run`` so
+  traces land in ``~/.tracelens/baselines/<session>/<service>/trace.jsonl``.
+
+Harness-only: no LLM calls are made in-process. The deterministic halves —
+service-inventory validation and the replay verification gate — live in
+``bringup.runner``.
+"""
+
+from bringup.runner import (
+    expect_vinv_handbook,
+    render_list_prompt,
+    render_start_prompt,
+    verify_replay,
+)
+
+__all__ = [
+    "expect_vinv_handbook",
+    "render_list_prompt",
+    "render_start_prompt",
+    "verify_replay",
+]

bringup/cli.py

@@ -0,0 +1,147 @@
+"""Click CLI for bringup: a two-stage Stage 2 bring-up driven by .vinv/vinv.md.
+
+Stage 2a — ``bringup list <repo>``  : render the runbook that enumerates every
+                                      service into ``<repo>/.vinv/services.json``.
+Stage 2b — ``bringup start <repo>`` : render the runbook that starts one selected
+                                      service (``--service``), instrumenting its
+                                      ``--module``(s) under tracelens.
+
+Harness-only: both commands print the fully rendered task prompt (zero LLM
+calls) for the caller's coding-agent harness to execute. The legacy in-process
+agent mode is gone; ``--print-prompt`` is accepted as a no-op for backwards
+compatibility.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+
+import click
+
+from bringup.runner import (
+    render_list_prompt,
+    render_start_prompt,
+)
+
+
+def _force_utf8_stdio() -> None:
+    """On Windows a piped stdout/stderr defaults to the ANSI codepage, and the
+    rendered prompts contain characters it cannot encode, so reconfigure the
+    streams in-process."""
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            if (stream.encoding or "").replace("-", "").lower() != "utf8":
+                stream.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+
+
+_force_utf8_stdio()
+
+
+def _configure_logging(verbose: bool) -> None:
+    logging.basicConfig(
+        level=logging.INFO if verbose else logging.WARNING,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        stream=sys.stderr,
+    )
+
+
+_GROUP_HELP = """\
+bringup — render the runbooks that enumerate and start a repository's services.
+
+\b
+  1. bringup list  <repo>
+       Print the runbook that writes a service inventory to
+       <repo>/.vinv/services.json. Installs nothing, starts nothing.
+  2. bringup start <repo> --service NAME [--module PKG ...]
+       Print the runbook that installs, starts and verifies ONE selected
+       service and records the verified start command(s).
+
+Both commands render the full task prompt (no LLM calls); pipe the output into
+your coding-agent harness (Claude Code, Cursor, Windsurf, ...) to execute it.
+Requires <repo>/.vinv/vinv.md to exist. Run `bringup list --help` or
+`bringup start --help` for per-command options.
+"""
+
+_LIST_HELP = """\
+Print the runbook that lists every service and its modules into
+REPO_PATH/.vinv/services.json.
+
+The runbook installs nothing and starts nothing; its output feeds
+`bringup start`. Requires REPO_PATH/.vinv/vinv.md to exist. Execute the
+printed runbook with your coding-agent harness.
+"""
+
+_START_HELP = """\
+Print the runbook that installs, starts and verifies ONE selected service,
+recording the verified start command(s) at
+REPO_PATH/.vinv/start_commands/<service>.json.
+
+Pass each package to instrument with a repeated --module flag. Requires
+REPO_PATH/.vinv/vinv.md to exist. Execute the printed runbook with your
+coding-agent harness.
+"""
+
+
+@click.group(help=_GROUP_HELP)
+def main() -> None:
+    pass
+
+
+@main.command("list", help=_LIST_HELP)
+@click.argument("repo_path", type=click.Path(exists=True, file_okay=False))
+@click.option("--print-prompt", is_flag=True, hidden=True,
+              help="Deprecated no-op: printing the rendered prompt is the only mode.")
+@click.option("--portable", is_flag=True,
+              help="Emit the tool-agnostic runbook variant (no Vinv-specific tool names) "
+                   "for a foreign coding agent.")
+@click.option("-v", "--verbose", is_flag=True, help="Enable INFO-level logging to stderr.")
+def list_cmd(repo_path: str, print_prompt: bool, portable: bool, verbose: bool) -> None:
+    _configure_logging(verbose)
+    click.echo(render_list_prompt(Path(repo_path), portable=portable))
+
+
+@main.command("start", help=_START_HELP)
+@click.argument("repo_path", type=click.Path(exists=True, file_okay=False))
+@click.option("--service", required=True,
+              help="Name of the service to bring up (from .vinv/services.json).")
+@click.option("--module", "modules", multiple=True,
+              help="Top-level Python package to instrument under tracelens (repeatable).")
+@click.option("--session-id", default="vinv-bringup",
+              help="Session id woven into tracelens output paths (default 'vinv-bringup').")
+@click.option("--start-hint", default=None,
+              help="How YOU start this service (e.g. 'make run-api'). The runbook verifies it, "
+                   "then records the tracelens-wrapped equivalent. Defaults to the hint recorded "
+                   "at .vinv/start_hints/<service>.json; a hint never lowers the verified bar.")
+@click.option("--print-prompt", is_flag=True, hidden=True,
+              help="Deprecated no-op: printing the rendered prompt is the only mode.")
+@click.option("--portable", is_flag=True,
+              help="Emit the tool-agnostic runbook variant (no Vinv-specific tool names) "
+                   "for a foreign coding agent.")
+@click.option("-v", "--verbose", is_flag=True, help="Enable INFO-level logging to stderr.")
+def start_cmd(
+    repo_path: str,
+    service: str,
+    modules: tuple[str, ...],
+    session_id: str,
+    start_hint: str | None,
+    print_prompt: bool,
+    portable: bool,
+    verbose: bool,
+) -> None:
+    _configure_logging(verbose)
+    click.echo(render_start_prompt(
+        Path(repo_path),
+        service=service,
+        modules=list(modules),
+        session_id=session_id,
+        portable=portable,
+        start_hint=start_hint,
+    ))
+
+
+if __name__ == "__main__":
+    main()

bringup/invocation_render.py

@@ -0,0 +1,191 @@
+"""Filling an invocation's command template — the Python half of the contract.
+
+A run-to-completion unit is driven many ways: a CLI has one invocation per
+subcommand, a library one per entry point. Each is recorded as a *template* plus
+the parameters that fill it, so the same record can serve a human filling a form
+and a headless pass taking the declared defaults.
+
+This module is duplicated VERBATIM in ``exerciser.invocation_render`` and
+mirrored in TypeScript by ``extension/src/bringup/invocations.ts``. Duplication
+rather than a shared import because ``bringup`` and ``exerciser`` deliberately do
+not depend on each other (the field contract is the file on disk, not the code
+that wrote it) — and the drift that invites is caught by
+``contracts/vectors/invocation_render.json``, which every one of the three suites
+reads. A change made on one side and not the others fails there instead of
+quietly producing a different command in each surface.
+
+The invariant worth stating plainly: rendering an invocation with all of its
+defaults must reproduce, byte for byte, the string bring-up actually ran. That is
+what keeps ``verified: true`` meaning something after parameters exist — see
+:func:`defaults_match_verified`.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+#: An ordinary argv token needs no quoting. Leaving these bare is what keeps the
+#: defaults render byte-identical to the verified string — quoting everything
+#: would be equally safe and would break the identity check on every record.
+_SAFE_TOKEN = re.compile(r"^[A-Za-z0-9_@%+=:,./-]+$")
+
+#: `C:\x` / `C:/x` → the `/c/x` spelling Git Bash reads. Keyed off the SHAPE of
+#: the value rather than the host platform, so the shared vectors give the same
+#: answer on every OS.
+_DRIVE = re.compile(r"^([A-Za-z]):[\\/](.*)$")
+
+#: An escape (`{{` / `}}`) or a placeholder, in one pass.
+_TOKEN = re.compile(r"\{\{|\}\}|\{([A-Za-z_][A-Za-z0-9_]*)\}")
+
+#: Values a `flag` parameter treats as "on". Anything else omits the flag.
+_TRUTHY = frozenset({"1", "true", "yes", "on"})
+
+
+class InvocationRenderError(ValueError):
+    """A template and its parameters disagree — never rendered past."""
+
+
+def shell_quote(value: str) -> str:
+    """Quote one value for the ``bash -lc`` the recorded command runs under."""
+    if _SAFE_TOKEN.match(value):
+        return value
+    return "'" + value.replace("'", "'\\''") + "'"
+
+
+def to_bash_path(value: str) -> str:
+    """Rewrite a Windows drive-letter path into the ``/c/…`` spelling.
+
+    Recorded commands are bash-spelled by contract: a ``C:\\…`` value arrives at
+    the program with its backslashes eaten as escapes, and a ``C:/…`` value has
+    its colon read as a PATH separator.
+    """
+    m = _DRIVE.match(value)
+    if m:
+        return "/" + m.group(1).lower() + "/" + m.group(2).replace("\\", "/")
+    return value.replace("\\", "/")
+
+
+def _substitute(param: dict[str, Any], raw: str) -> str:
+    """The text one parameter contributes, already quoted. ``""`` means omit."""
+    ptype = param.get("type")
+    value = to_bash_path(raw.strip()) if ptype == "path" else raw.strip()
+    name = str(param.get("name") or "")
+    render = param.get("render")
+
+    if ptype == "flag":
+        if value.lower() not in _TRUTHY:
+            return ""
+        return render.replace("{value}", "").strip() if isinstance(render, str) else f"--{name}"
+
+    if value == "":
+        if param.get("required"):
+            raise InvocationRenderError(f"'{name}' is required but empty")
+        return ""
+
+    choices = param.get("choices")
+    if ptype == "enum" and isinstance(choices, list) and choices:
+        if value not in choices:
+            raise InvocationRenderError(
+                f"'{name}' must be one of {', '.join(str(c) for c in choices)} (got '{value}')"
+            )
+    if ptype == "int" and not re.fullmatch(r"-?\d+", value):
+        raise InvocationRenderError(f"'{name}' must be a whole number (got '{value}')")
+    if ptype == "float" and not re.fullmatch(r"-?\d+(\.\d+)?", value):
+        raise InvocationRenderError(f"'{name}' must be a number (got '{value}')")
+
+    quoted = shell_quote(value)
+    return render.replace("{value}", quoted) if isinstance(render, str) else quoted
+
+
+def render_invocation(invocation: dict[str, Any], args: dict[str, str] | None = None) -> str:
+    """Fill ``invocation``'s template, falling back to each parameter's default.
+
+    Raises rather than guessing: an unknown placeholder, or a declared parameter
+    the template never uses, is a malformed record — rendering past it would
+    produce a command nobody verified.
+    """
+    args = args or {}
+    raw_params = invocation.get("params")
+    params: dict[str, dict[str, Any]] = {}
+    if isinstance(raw_params, list):
+        for p in raw_params:
+            if isinstance(p, dict) and isinstance(p.get("name"), str):
+                params[p["name"]] = p
+    command = invocation.get("command")
+    if not isinstance(command, str):
+        raise InvocationRenderError("invocation has no command string")
+    inv_id = invocation.get("id") or "?"
+
+    used: set[str] = set()
+    out: list[str] = []
+    last = 0
+    for m in _TOKEN.finditer(command):
+        out.append(command[last : m.start()])
+        last = m.end()
+        if m.group(0) in ("{{", "}}"):
+            out.append(m.group(0)[0])
+            continue
+        name = m.group(1)
+        param = params.get(name)
+        if param is None:
+            raise InvocationRenderError(
+                f"command uses {{{name}}} but no such parameter is declared on "
+                f"invocation '{inv_id}'"
+            )
+        used.add(name)
+        supplied = args.get(name)
+        if supplied is None:
+            supplied = param.get("default")
+        text = _substitute(param, str(supplied) if supplied is not None else "")
+        if text == "":
+            # An omitted parameter takes its own separating space with it, so the
+            # defaults render stays byte-identical to the verified string rather
+            # than leaving a tell-tale double space behind.
+            if out and out[-1].endswith(" "):
+                out[-1] = out[-1][:-1]
+            continue
+        out.append(text)
+    out.append(command[last:])
+
+    for name in params:
+        if name not in used:
+            raise InvocationRenderError(
+                f"invocation '{inv_id}' declares parameter '{name}' but its command "
+                f"has no {{{name}}}"
+            )
+    return "".join(out)
+
+
+def default_args(invocation: dict[str, Any]) -> dict[str, str]:
+    """Every parameter's default — what every headless consumer runs with."""
+    out: dict[str, str] = {}
+    raw = invocation.get("params")
+    if isinstance(raw, list):
+        for p in raw:
+            if isinstance(p, dict) and isinstance(p.get("name"), str):
+                default = p.get("default")
+                out[p["name"]] = "" if default is None else str(default)
+    return out
+
+
+def defaults_match_verified(invocation: dict[str, Any]) -> bool:
+    """Does rendering the defaults reproduce the string bring-up verified?
+
+    True when no ``verification.rendered_command`` was recorded: an older record
+    simply makes no claim, and refusing it would break every unit brought up
+    before parameters existed.
+    """
+    verification = invocation.get("verification")
+    recorded = verification.get("rendered_command") if isinstance(verification, dict) else None
+    if not isinstance(recorded, str) or not recorded:
+        return True
+    try:
+        return render_invocation(invocation, default_args(invocation)) == recorded
+    except InvocationRenderError:
+        return False
+
+
+def invocation_slug(value: str) -> str:
+    """Filesystem- and id-safe slug, mirroring ``serviceSlug`` on both sides."""
+    return re.sub(r"[^A-Za-z0-9_.-]", "_", value) or "invocation"

bringup/prompts/list_instruction.txt

@@ -0,0 +1,290 @@
+## Vinv Stage 2a — Python service inventory (read-only, terminal)
+
+You are **TerminalExecutor** on an **Vinv bring-up enumeration** task. You are **NOT** starting or
+installing anything in this stage — you are producing a machine-readable inventory of the **Python
+services** in this repo. A later `bringup start <service>` invocation consumes your output to bring
+services up one at a time.
+
+### What counts as a "service" (read carefully)
+
+- **A service is a Python distribution/component we instrument** — the unit a later
+  `bringup start --service <name>` brings up while tracelens AST-rewrites its import package(s).
+  Most repos ship one per packaging manifest (`pyproject.toml` / `setup.py`); the framework scan
+  below lists the candidates it found and, for each, the **import package(s)** that belong in
+  `modules`. Distribution names may contain `-`; import packages never do.
+- **"Service" is broader than HTTP.** Include every long-running Python process the repo defines:
+  web apps (`python_web`), background/queue workers (`python_worker`), **stdio JSON-RPC servers**
+  (`python_stdio` — MCP servers and the like, spoken to over stdin/stdout, no port), and
+  beat/cron-style schedulers (`python_scheduler`). A port scan finds none of the last three —
+  find them from the handbook's enumeration, the manifest-scan list below, and the entry code.
+- **"Service" is also broader than long-running.** Tracelens instruments a *process*, not a
+  server: `tracelens run -t pkg -- <any command>` records a run that starts, works and exits
+  just as faithfully as one that stays up. So the inventory also covers the two units of work
+  that never listen on anything:
+  - `python_cli` — a console script or `__main__` the repo declares, invoked with argv and run
+    to completion (`acme-tool report --since 7d`);
+  - `python_library` — an importable package with **no entrypoint of its own**, whose functions
+    are called by the exerciser's function driver.
+
+  These are not consolation prizes for repos without a server. In a toolchain, a SDK or a
+  framework (LangChain and its kin) they are the *only* units of work there are, and an
+  inventory that omits them traces nothing at all.
+- **EXCLUDE stateful infrastructure** (Postgres, MySQL, Redis, ClickHouse, Kafka, Mongo, etc.,
+  i.e. the handbook's `### Run in Docker` table). We do **not** instrument or bring those up here;
+  the start stage starts them as a dependency when needed. They must **not** appear in your output.
+- **EXCLUDE non-Python processes** (Node/Vite/Next frontends). Only Python services count.
+- **NEVER FABRICATE A `command`.** This is the rule the library case used to be a special case of,
+  and it is the only one that still bites: a command grounded in nothing wastes an entire
+  downstream bring-up attempt before anyone notices it cannot work. A Python package with **no
+  runnable process of its own** — no `[project.scripts]` / `[tool.poetry.scripts]` console script,
+  no `__main__.py`, no handbook `### Run on host` row naming it — is a library, and inventing an
+  entrypoint for it is the classic way to break this rule. Three legitimate outcomes:
+  1. **Its code runs inside another service's process** (the app imports it): list it as a service
+     entry whose `command`, `working_directory` and `port` are **the host app's own** (the shared-
+     command case below) — the entries then differ only in which package tracelens instruments.
+  2. **Nothing in the repo runs it, but its functions can be called**: list it as
+     `kind: "python_library"` and **omit `command` entirely**. The harness synthesizes the
+     exerciser function driver — you are not being asked to guess one, and writing one anyway is
+     the fabrication this rule forbids. This is the normal outcome for a library.
+  3. **It should not be driven at all** (a vendored copy, a dev-only shim, generated code): leave
+     it out of `services`.
+
+  Outcome 2 is what makes a library-only repo tractable. Reserve outcome 3 for packages nothing
+  should ever call — not for "I could not find its entrypoint", which is what `python_library`
+  exists to express.
+
+### Candidate services (framework scan — strong prior; the handbook decides)
+
+{_pkgs_note}
+
+### Source of truth
+
+1. **Read** the handbook at **`{vinv_md}`** first. It was produced in Stage 1 (discovery) and lists
+   runbooks, dependencies, ports, components, and a
+   `## Bring-up recipe (host vs container)` section. Use the
+   `### Run on host (instrumented by tracelens)` rows to find the **start command, working directory
+   and port** for the Python app(s). Ignore the `### Run in Docker` table for the inventory itself.
+2. Treat the handbook as authoritative and the scan as a strong prior. Where the handbook is thin,
+   you may `cat` `pyproject.toml`, `compose.yaml`, the package's own `__main__.py` / entrypoint,
+   etc. to fill gaps — but do **not** install dependencies or start any process.
+
+### What to capture for each Python service
+
+- **`name`** — the service name: use the candidate name from the scan verbatim; for a service you
+  add from the handbook, use its distribution name (its `pyproject.toml` `[project].name` or
+  `[tool.poetry].name`, whichever table the manifest uses).
+- **`kind`** — one of:
+  - `python_web` — serves HTTP (FastAPI/uvicorn, Flask, Django, a stdlib `http.server`, …);
+  - `python_worker` — background worker/consumer (celery/dramatiq/rq worker, queue consumer), no
+    HTTP port;
+  - `python_stdio` — a stdio JSON-RPC server (an MCP server or similar): long-running, port-less,
+    reads requests from stdin and writes JSON responses to stdout;
+  - `python_scheduler` — a beat/cron-style scheduler process (celery beat, apscheduler runner);
+  - `python_cli` — a console script / `__main__` that runs to completion and exits (a Click or
+    argparse CLI, a batch job, a report generator, a migration runner);
+  - `python_library` — an importable package with no entrypoint of its own, driven by the
+    exerciser calling its functions.
+- **`transport`** — optional: `"http"` for `python_web`, `"stdio"` for `python_stdio`, else omit
+  or `null`. `python_cli` and `python_library` are never spoken to over a transport — omit it.
+- **VERIFY each candidate is actually startable by READING ITS ENTRY CODE before you emit it.**
+  Open the module the command names (the console script's target function, the `__main__.py`, the
+  uvicorn app path) and confirm it really constructs a server / worker / stdio loop — or that it
+  returns. This read is also how you classify `kind`: a console script whose target calls
+  `uvicorn.run(...)` is `python_web`; one that builds a `FastMCP(...)` app or opens an `mcp` stdio
+  transport is `python_stdio`; a celery `worker_main`/`Worker` is `python_worker`; a beat/scheduler
+  loop is `python_scheduler`. **A console script whose target computes something, prints it and
+  returns is `python_cli`** — that is a unit of work, not a failed server, and it belongs in the
+  file. A candidate whose entry code you could not locate does not go in the file.
+
+  **The discriminator is whether the entrypoint blocks, never whether it declares a console
+  script.** A repo can declare a dozen `[project.scripts]` where one parks on `serve_forever` and
+  eleven return — that is one `python_web` and eleven `python_cli`, not one service and eleven
+  omissions. Read the target function and see which it does.
+- **`command`** — the native start command that runs this service (NEVER `docker compose up`), taken
+  from what the repo **actually declares**: the handbook's `### Run on host` row, a
+  `[project.scripts]` / `[tool.poetry.scripts]` console script (e.g. `acme-payment-serve`), a
+  verified `python -m <module>` target, or the server command the project documents
+  (uvicorn/gunicorn/`manage.py runserver`/`flask run`/a worker entrypoint — whatever THIS project
+  uses, in `python -m <server> …` form where supported). **Verify before you emit:** only write
+  `python -m <module>` if that package really has a `__main__.py` (check it — `ls
+  <pkg-dir>/__main__.py`); a command you could not ground in the handbook, a manifest script, or an
+  existing entrypoint file is a fabrication and will burn a whole bring-up attempt downstream.
+  **`python -m <module>:<attr>` is INVALID** — `-m` takes a module; the `module:attr` form is an
+  app-factory reference that only uvicorn/gunicorn understand. If several services are served by the
+  **same** app process it is fine for them to share the same `command` — they differ only in which
+  package tracelens instruments at start.
+  For `python_cli` the same grounding rule applies to the *whole* invocation: the subcommand and
+  its argv must come from something the repo declares — the CLI's own `--help`/`@click.command`
+  definitions, a README example, a CI workflow step, a Makefile target, a test that shells out.
+  For `python_library`, **omit `command`** and let the harness synthesize the driver.
+- **`invocations`** — optional, and only for `python_cli` / `python_library`: the representative
+  ways this unit is driven, one entry per way. Each is a **complete runnable command**, not an
+  argv fragment: `{{"id": "report", "command": "acme-tool report --since 7d",
+  "purpose": "weekly report", "expect_exit": 0}}`. `expect_exit` defaults to `0` — set it only
+  where the documented behavior is a non-zero exit (a linter that reports findings, a check
+  command). Omit the field entirely and `command` becomes the single invocation, which is the
+  right answer for a CLI with one real mode. Prefer two or three invocations that exercise
+  genuinely different code paths over ten variations of the same flag; each one is a separate
+  traced run.
+  - **`id`** — a short, stable slug naming this way of driving the unit (`report`, `check`,
+    `migrate`). It is the **unit identity everywhere downstream**: findings, coverage and history
+    all key on `<service>#<id>`. Give every invocation one. Without it the id is derived from the
+    subcommand, which is usually right and occasionally surprising; with it, nothing moves when
+    you reorder or re-word the list.
+- **`params`** — optional, per invocation: the arguments a human should be able to change at run
+  time, so the editor can offer a form instead of a frozen command line. Write the command as a
+  **template** with `{{name}}` placeholders and declare one entry per placeholder:
+
+  ```json
+  {{"id": "report",
+    "command": "acme-tool report --since {{since}} --format {{format}}",
+    "params": [
+      {{"name": "since", "type": "string", "default": "7d", "help": "lookback window"}},
+      {{"name": "format", "type": "enum", "default": "json", "choices": ["json", "csv"]}}
+    ]}}
+  ```
+
+  - `type` is one of `string` (default), `int`, `float`, `enum`, `path`, `flag`. A `flag` renders
+    as `--<name>` when on and disappears when off; a `path` value is rewritten to the `/c/…`
+    spelling bash reads; an `enum` needs a `choices` list.
+  - **`default` is not a suggestion — it is what runs.** Every headless consumer (the exercise
+    pass, the replay gate, the Run button's one-click path) fills every parameter with its
+    default, so rendering the template with the defaults must produce **exactly the command you
+    verified**. If it does not, the file is rejected.
+  - **Ground the defaults and the choices in what the repo declares**, the same rule as `command`:
+    the CLI's own `--help` / `@click.option` / `argparse` definitions, a README example, a CI step.
+    Never invent a value to fill a slot — a fabricated default is worse than no parameter, because
+    it renders into a command that then claims to be verified.
+  - **Only parameterize what is genuinely worth changing.** A slot per flag is noise; the useful
+    ones are the inputs a person actually retypes (a path, a date range, an output format).
+  - `examples` (optional, a list) is how you offer extra values for the exercise pass to try. It
+    runs the declared defaults plus one variant per enumerated value, and **nothing else** — it
+    will never invent argv of its own, because `--force` and `--delete` are flags too.
+- **`working_directory`** — absolute path the command runs from (default the candidate's own path
+  from the scan, else `{root}`).
+- **`port`** — the HTTP port it listens on (**required** for `python_web`); `null` for every other
+  kind (`python_stdio` in particular MUST have `port: null` — it has no socket, and `python_cli` /
+  `python_library` MUST have `port: null` — they never listen at all).
+- **Readiness for non-HTTP kinds** — a `python_stdio` service cannot be probed on a port. Its
+  readiness check (used by Stage 2b and the replay gate) is a **JSON-RPC initialize round-trip**:
+  spawn the command, write one `{{"jsonrpc":"2.0","id":1,"method":"initialize",...}}` line to its
+  stdin, expect a JSON line back on stdout. Stage 2b records this as
+  `"probe": {{"type": "stdio-jsonrpc"}}` in the start_commands file (`"process"` for
+  workers/schedulers that just have to stay alive, `"port"` for web, `"exit"` for the
+  run-to-completion kinds). You don't run the probe in this read-only stage — but classify `kind`
+  correctly so Stage 2b knows which oracle to use.
+- **Readiness for the run-to-completion kinds** — there is nothing to probe, because the process
+  **exiting is the successful outcome**. Stage 2b runs the tracelens-wrapped invocation to
+  completion and accepts it when the exit code matches and the trace is non-empty. Getting `kind`
+  wrong in this direction is expensive in both directions: a CLI filed as `python_web` hangs
+  Stage 2b until its deadline waiting for a port that never opens, and a server filed as
+  `python_cli` fails the moment it does not exit.
+- **`modules`** — the top-level **import package(s)** tracelens instruments for this service
+  (`--target-package`). Use the import package(s) from the scan — each must be a valid Python
+  identifier. A directory or distribution name containing `-` is NEVER a module name. Add another
+  package only if this service's process genuinely also runs that package's code and you want it
+  traced too.
+
+### How to write the file
+
+You have a `save_file(content, file_path)` tool wired into this run. **Use it.** Compose the full
+JSON document as a single string in your reasoning, then call:
+
+```
+save_file(content=<full json>, file_path="{services_json}")
+```
+
+The JSON must have exactly this shape (one entry per Python service, no infra, no frontends):
+
+```json
+{{
+  "services": [
+    {{
+      "name": "acme-payment",
+      "kind": "python_web",
+      "transport": "http",
+      "command": "python -m uvicorn acme_payment.main:app --host 0.0.0.0 --port 8000",
+      "working_directory": "{root}",
+      "port": 8000,
+      "modules": ["acme_payment"]
+    }},
+    {{
+      "name": "toolshed",
+      "kind": "python_worker",
+      "command": "python -m toolshed",
+      "working_directory": "{root}",
+      "port": null,
+      "modules": ["toolshed"]
+    }},
+    {{
+      "name": "acme-mcp",
+      "kind": "python_stdio",
+      "transport": "stdio",
+      "command": "python -m acme_mcp.server",
+      "working_directory": "{root}",
+      "port": null,
+      "modules": ["acme_mcp"]
+    }},
+    {{
+      "name": "acme-tool",
+      "kind": "python_cli",
+      "command": "acme-tool report --since 7d",
+      "working_directory": "{root}",
+      "port": null,
+      "modules": ["acme_tool"],
+      "invocations": [
+        {{"id": "report", "command": "acme-tool report --since {{since}}",
+          "purpose": "the reporting path",
+          "params": [{{"name": "since", "default": "7d", "help": "lookback window"}}]}},
+        {{"id": "check", "command": "acme-tool check ./sample",
+          "purpose": "the validation path", "expect_exit": 1}}
+      ]
+    }},
+    {{
+      "name": "acme-sdk",
+      "kind": "python_library",
+      "working_directory": "{root}",
+      "port": null,
+      "modules": ["acme_sdk"]
+    }}
+  ]
+}}
+```
+
+(The names above are illustrative of the **shape** — note how the service `name` may carry a dash
+while `modules` carries the underscore import package, how the stdio server carries
+`transport: "stdio"` with `port: null`, how the CLI's `invocations` are each a full command with
+its own stable `id`, how the first carries a `{{since}}` slot a human can change while the second
+documents a legitimate non-zero exit, and how the library entry carries **no `command` at all**.
+Use the actual names for this repo.) Emit
+**valid JSON only** (no trailing commas, no comments in the actual file). Do **not** wrap it in
+Markdown fences inside the file. After `save_file` returns `status: success`, run
+`cat '{services_json}'` once via `send_terminal_command` to confirm it landed and parses, then end
+the trajectory.
+
+### Execution discipline
+
+- Use **terminal tools** only for **reading** (`cat`, `ls`, `grep`); set `block: true` on any command
+  whose output you need.
+- Do **NOT** run installs, builds, `docker compose up`, `uvicorn`, `npm run dev`, or any process
+  start in this stage. Enumeration is read-only.
+- Do **not** call `close_terminal`.
+
+### Finish — what "done" actually means
+
+You are done only when **`{services_json}` exists on disk** with a valid `services` array covering
+every service in the handbook. That means: you called
+`save_file(content=<full json>, file_path="{services_json}")`, it returned `status: success`, and
+`cat` confirmed it on disk. Reading and thinking are not a substitute for writing the file.
+
+After you finish, the harness validates the file deterministically — every `modules` entry must be
+an importable Python identifier, `kind` must be one of `python_web` / `python_worker` /
+`python_stdio` / `python_scheduler` / `python_cli` / `python_library`, `python_web` entries must
+carry an integer `port`, `python_stdio` / `python_cli` / `python_library` entries must carry
+`port: null`, `transport` (when present) must be `"http"` or `"stdio"` and match the kind,
+`invocations` (when present) may only appear on `python_cli` / `python_library` and each entry
+must carry a full `command` and a unique `id`, every `params` entry must name a `{{placeholder}}`
+the command actually contains (and vice versa) and render with its defaults, every entry except
+`python_library` must carry a `command`, and commands must be runnable (no `-m module:attr`, no
+docker) — and re-opens this task with the exact violations if it fails. Get it right the first
+time.