@llm4ts/shell 2.11.0 → 2.13.0

package/flows/epic-stories.js

@@ -29,7 +29,7 @@ import { landEpic } from "@llm4ts/flow/Landing";
 import { implementStoriesFlow } from "@llm4ts/flow/Stories";
 import { makeStoryPlanStore, validateStoryPlan } from "@llm4ts/flow/StoryPlan";
 import * as Console from "effect/Console";
-import { awaitServer, chooseEpic, epicsDir, listEpics, renderEpicList, combineTotals, epicIdFor, flagsFromEnvironment, gateCommands, gatesIn, generateStoryPlan, httpProbe, judgeStory, localCoderServer, parseEpicArgs, reasonerFromEnvironment, serverHealthUrl, setupIn, storyCoderFromEnvironment, verifyBlockedOn, worktreeRootFor, worktreeSetupCommand } from "./lib/epic-stories.js";
+import { awaitServer, chooseEpic, epicsDir, listEpics, renderEpicList, combineTotals, epicIdFor, flagsFromEnvironment, appDirFor, appScripts, gateCommands, gatesIn, inAppDir, generateStoryPlan, httpProbe, judgeStory, localCoderServer, parseEpicArgs, reasonerFromEnvironment, serverHealthUrl, setupAgentEnabled, setupIn, storyCoderFromEnvironment, verifyBlockedOn, worktreeRootFor, worktreeSetupCommand } from "./lib/epic-stories.js";
 /** `LLM4TS_CODER_MODEL` / `LLM4TS_REASONING_MODEL`: pi takes `provider/model` (e.g. `openai-codex/gpt-5.5`). */
 const withOptionalModel = (config, model) => {
     const trimmed = model?.trim();
@@ -95,6 +95,17 @@ const program = Effect.gen(function* () {
         if (flags.planOnly) {
             return;
         }
+        // Setup and gates run where the application is, in every checkout.
+        const appDir = yield* appDirFor(input.workDir, process.env);
+        if (appDir !== ".") {
+            yield* events.publish(Info.make({ message: `app dir: ${appDir} (setup and gates run there; LLM4TS_APP_DIR)` }));
+        }
+        const commands = gateCommands(process.env, yield* appScripts(files, join(input.workDir, appDir)));
+        yield* events.publish(Info.make({
+            message: commands.length === 0
+                ? "gates: none (the app defines none of typecheck, lint, test, build; set LLM4TS_GATES)"
+                : `gates: ${commands.map((command) => command.join(" ")).join(" · ")}`
+        }));
         if (flags.land !== undefined) {
             const landed = yield* landEpic(context, {
                 plan,
@@ -102,7 +113,7 @@ const program = Effect.gen(function* () {
                 stateDir,
                 target: flags.land,
                 keepWorktrees: flags.keepWorktrees,
-                gates: gatesIn(nodeProcessExecutor, events, gateCommands(process.env)),
+                gates: inAppDir(appDir, gatesIn(nodeProcessExecutor, events, commands)),
                 system: ["House rules of the target repository (CONTRIBUTING.md):", guidance].join("\n")
             });
             yield* events.publish(Info.make({
@@ -126,7 +137,12 @@ const program = Effect.gen(function* () {
                 message: "this runner cannot rebind seats to a worktree (no contextFor)"
             });
         }
-        const gates = gatesIn(nodeProcessExecutor, events, gateCommands(process.env));
+        const appDirNote = appDir === "."
+            ? []
+            : [
+                `The application lives in ${appDir}/ — its package.json, sources and tests; the gates run there.`
+            ];
+        const gates = inAppDir(appDir, gatesIn(nodeProcessExecutor, events, commands));
         const setupCommand = worktreeSetupCommand(process.env);
         const healthUrl = serverHealthUrl(localServer, process.env);
         const report = yield* implementStoriesFlow({ ...context, reasoning: reasoningMeter.service }, {
@@ -151,7 +167,10 @@ const program = Effect.gen(function* () {
             }),
             ...(setupCommand === undefined
                 ? {}
-                : { setup: setupIn(nodeProcessExecutor, events, setupCommand) }),
+                : {
+                    setup: inAppDir(appDir, setupIn(nodeProcessExecutor, events, setupCommand)),
+                    setupAgent: setupAgentEnabled(process.env)
+                }),
             gates,
             // With a roster, the judge and the verifier are leased per story,
             // away from the executor coding it (ADR 0019).
@@ -166,7 +185,8 @@ const program = Effect.gen(function* () {
                 "House rules of the target repository (CONTRIBUTING.md):",
                 guidance,
                 "",
-                `Imitate the exemplar feature before inventing anything. Story id: ${story.id}.`
+                `Imitate the exemplar feature before inventing anything. Story id: ${story.id}.`,
+                ...appDirNote
             ].join("\n")),
             concurrency,
             failFast: flags.failFast

package/flows/lib/epic-stories.js

@@ -2,9 +2,10 @@
 // story-plan generator prompt and schema, the story judge, the gate runner,
 // and seat selection. The executor itself is `@llm4ts/flow/Stories`.
 import { readdir } from "node:fs/promises";
-import { join } from "node:path";
+import { isAbsolute, join, normalize } from "node:path";
 import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
 import { Dimension, Sample } from "@llm4ts/core/eval/Eval";
 import { judge } from "@llm4ts/core/eval/Judge";
 import { TokenUsage } from "@llm4ts/core/Models";
@@ -34,9 +35,13 @@ export const epicUsage = [
     "Seats: LLM4TS_REASONER (claude|gemini|…, default claude) splits, reviews, judges;",
     "       LLM4TS_CODER (default pi) implements; LLM4TS_REASONING_MODEL / LLM4TS_CODER_MODEL",
     "       pick their models (pi: provider/model); LLM4TS_CODER_FLAGS / LLM4TS_REASONING_FLAGS",
-    "       add CLI flags (key=value;key=value). LLM4TS_GATES overrides the gate commands;",
+    "       add CLI flags (key=value;key=value). LLM4TS_GATES overrides the gate commands",
+    "       (default: those of pnpm typecheck|lint|test|build the app's package.json defines);",
     "       LLM4TS_WORKTREE_SETUP (default: pnpm install --offline) prepares each worktree;",
     "       LLM4TS_WORKTREE_ROOT (default: <repo>.worktrees beside the repository) holds them;",
+    "       LLM4TS_APP_DIR (e.g. frontend) runs setup and gates in that subfolder; unset, a",
+    "       repository without a root package.json uses its one subfolder that has one;",
+    "       LLM4TS_SETUP_AGENT=1 gives the coder one turn to fix a failed setup, then reruns it;",
     "       LLM4TS_CODER_HEALTH_URL is polled after the coder's serving engine goes down."
 ].join("\n");
 /** The flow's own flags, taken out before the shared `--repo`/prompt parsing sees the rest. */
@@ -544,6 +549,45 @@ export const judgeStory = (reasoning, story, diff, budget, plan) => judge(reason
     response: cap(diff, budget).text
 }))
     .pipe(Effect.mapError(FlowLlmError.from), Effect.map((scored) => subBar(scored, story)));
+// ---- App directory ----------------------------------------------------------------
+/** Folders never taken for the application: dependencies, build output, llm4ts state. */
+const ignoredAppDirs = new Set(["node_modules", "dist", "build", "out", "coverage"]);
+const hasPackageJson = (dir) => Effect.tryPromise(() => readdir(dir)).pipe(Effect.map((names) => names.includes("package.json")), Effect.catch(() => Effect.succeed(false)));
+/**
+ * Where setup and gates run, relative to a checkout: `LLM4TS_APP_DIR` when set
+ * (`.` for the root); otherwise the root when it has a `package.json`, else
+ * its ONE first-level subfolder that has one (a Next.js app in `frontend/`).
+ * Several candidates, or none, keep the root — the setup error then names it.
+ * The value is relative so it applies to every worktree and the epic checkout.
+ */
+export const appDirFor = (workDir, environment) => Effect.gen(function* () {
+    const configured = environment.LLM4TS_APP_DIR?.trim();
+    if (configured !== undefined && configured.length > 0) {
+        const normalized = normalize(configured);
+        const relative = normalized.replace(/[\\/]+$/, "");
+        if (isAbsolute(normalized) || relative === ".." || /^\.\.[\\/]/.test(relative)) {
+            return yield* ScriptUsage.make({
+                message: `LLM4TS_APP_DIR must be a folder inside the repository, got '${configured}'`
+            });
+        }
+        return relative.length === 0 ? "." : relative;
+    }
+    if (yield* hasPackageJson(workDir)) {
+        return ".";
+    }
+    const entries = yield* Effect.tryPromise(() => readdir(workDir, { withFileTypes: true })).pipe(Effect.catch(() => Effect.succeed([])));
+    const candidates = [];
+    for (const entry of entries) {
+        if (entry.isDirectory() && !entry.name.startsWith(".") && !ignoredAppDirs.has(entry.name)) {
+            if (yield* hasPackageJson(join(workDir, entry.name))) {
+                candidates.push(entry.name);
+            }
+        }
+    }
+    return candidates.length === 1 ? (candidates[0] ?? ".") : ".";
+});
+/** Runs a per-checkout step in the app directory of whichever checkout it is given. */
+export const inAppDir = (appDir, step) => (workDir) => step(appDir === "." ? workDir : join(workDir, appDir));
 // ---- Worktree setup --------------------------------------------------------------
 export const defaultWorktreeSetup = ["pnpm", "install", "--offline"];
 /**
@@ -562,13 +606,19 @@ export const worktreeSetupCommand = (environment) => {
         .filter((part) => part.length > 0);
     return parts.length === 0 ? undefined : parts;
 };
+/**
+ * `LLM4TS_SETUP_AGENT=1` (or `true`/`on`): a failed setup gets one coder turn
+ * to make the worktree ready, then runs again as the check. Off by default.
+ */
+export const setupAgentEnabled = (environment) => /^(1|true|on|yes)$/i.test(environment.LLM4TS_SETUP_AGENT?.trim() ?? "");
+const output = (result) => result.issues.map((issue) => issue.description).join("\n");
 /** Runs the setup command in a worktree; a non-zero exit fails the story with the output. */
 export const setupIn = (process, events, command) => (workDir) => Effect.flatMap(lintCommand(process, events, command, workDir), (result) => result.isClean
     ? Effect.void
     : FlowAborted.make({
-        message: `worktree setup failed (${command.join(" ")}):\n${result.issues
-            .map((issue) => issue.description)
-            .join("\n")}`
+        message: `worktree setup failed (${command.join(" ")}):\n${output(result)}${/ERR_PNPM_NO_PKG_MANIFEST|ENOENT.*package\.json/.test(output(result))
+            ? "\n(the application is not at this folder: set LLM4TS_APP_DIR to its subfolder)"
+            : ""}`
     }));
 // ---- Gates ---------------------------------------------------------------------
 export const defaultGateCommands = [
@@ -577,11 +627,29 @@ export const defaultGateCommands = [
     ["pnpm", "test"],
     ["pnpm", "build"]
 ];
-/** `LLM4TS_GATES="pnpm typecheck;pnpm test"` overrides the four defaults. */
-export const gateCommands = (environment) => {
+/** The part of an application's package.json the gates care about. */
+const PackageScripts = Schema.fromJsonString(Schema.Struct({
+    scripts: Schema.optional(Schema.Record(Schema.String, Schema.String))
+}));
+/**
+ * The script names in `<appRoot>/package.json`; undefined when it is missing
+ * or unreadable, which keeps every default gate (the failure then says why).
+ */
+export const appScripts = (files, appRoot) => files.read(join(appRoot, "package.json")).pipe(Effect.flatMap((text) => text === undefined
+    ? Effect.succeed(undefined)
+    : Effect.map(Schema.decodeUnknownEffect(PackageScripts)(text), (manifest) => new Set(Object.keys(manifest.scripts ?? {})))), Effect.catch(() => Effect.succeed(undefined)));
+/**
+ * `LLM4TS_GATES="pnpm typecheck;pnpm test"` overrides the four defaults.
+ * Without it, a default gate runs only when the application defines that
+ * script: a Next.js app has `lint` and `build` but seldom `typecheck`, and
+ * `pnpm typecheck` there fails with "Command not found", not a red gate.
+ */
+export const gateCommands = (environment, scripts) => {
     const raw = environment.LLM4TS_GATES?.trim();
     if (raw === undefined || raw.length === 0) {
-        return defaultGateCommands;
+        return scripts === undefined
+            ? defaultGateCommands
+            : defaultGateCommands.filter((command) => scripts.has(command[1] ?? ""));
     }
     return raw
         .split(";")

package/kits/soap-ace/README.md

@@ -0,0 +1,313 @@
+# Kit: soap-ace
+
+SOAP services to REST APIs on IBM ACE 12: discover the WSDL, sample and analyse real responses, design the REST contract, and plan the ACE build as an epic.
+
+In bank integration work most new REST APIs are exposed through IBM ACE on
+top of an existing SOAP service. This kit turns a WSDL (a file or URL, with
+auth when needed) into evidence first, then into a design, and only then into
+an ACE implementation plan. The spec of record is
+[`specs/pending/soap-ace-kit.md`](../../specs/pending/soap-ace-kit.md).
+
+Direction: SOAP is the source and ACE the **target**. The
+`mainframe-java/ace-integration` pack goes the other way (ACE as legacy
+source) and shares nothing with this kit.
+
+## Status
+
+| Piece                                              | State    |
+| -------------------------------------------------- | -------- |
+| Strict XML reader (`flows/lib/soap/Xml.ts`)        | done     |
+| WSDL 1.1/2.0 + XSD catalog (`Wsdl.ts`, `Xsd.ts`)   | done     |
+| `demo-bank-soap` fixture                           | WSDL/XSD |
+| `soap-discover` flow and operation classification  | pending  |
+| Masking, auth profile, transport, sample authoring | pending  |
+| Analysis, REST design, OpenAPI projection          | pending  |
+| `ace12-rest` pack, scaffold, `soap-epic`           | pending  |
+
+## soap-discover
+
+```bash
+llm4ts run soap-discover --repo ~/work/conti-api ./wsdl/DemoBank.wsdl
+```
+
+Writes under `<repo>/.llm4ts/soap/<service>/`:
+
+| File            | What it is                                                               |
+| --------------- | ------------------------------------------------------------------------ |
+| `catalog.json`  | the typed catalog every later step reads                                 |
+| `catalog.md`    | human summary: endpoints, operations and their fields, open questions    |
+| `operations.md` | proposed `read`/`mutating` classes; review, then set `Status: confirmed` |
+
+`operations.md` is the approval file: until its status is `confirmed` every
+operation counts as unclassified, so nothing can be called and the design
+cannot pick REST verbs. An existing file is never overwritten; rerunning
+reports operations it does not mention and entries no longer in the WSDL.
+Classes are proposed by a name heuristic (Italian and English verbs) and, when
+`LLM4TS_JUDGMENT_PROVIDER` names a judgment seat, by a typed judgment
+(ADR 0017); without one, discovery makes no model call at all.
+`LLM4TS_SOAP_SERVICE` overrides the service directory name; for a WSDL URL it
+also selects the auth profile whose `fetch` side authenticates every document
+request.
+
+## Discovery guarantees
+
+- The catalog is produced by code, never by a model. Every operation, type,
+  and field it lists is read from the WSDL and the schemas it imports.
+- Constructs the reader does not model (`xs:any`, substitution groups,
+  model-group refs, complex restrictions, list/union types, dangling
+  references) are listed as **open questions** with their document and line.
+- Only document/literal SOAP bindings (bare and wrapped, SOAP 1.1 and 1.2)
+  become operations. A WSDL whose every binding is RPC or encoded is refused
+  with an error naming the bindings; a WSDL that also offers a
+  document/literal binding keeps it and lists the others as open questions.
+- `<!DOCTYPE` is refused outright: no external entities, no entity expansion.
+  Schemas in ISO-8859-1 and windows-1252 are decoded by their declaration.
+
+## soap-sample
+
+Runs after `soap-discover` in the same repository; the task text is a
+command.
+
+```bash
+llm4ts run soap-sample --repo . "import ./DemoBank-soapui-project.xml"   # requests + mock responses, masked
+llm4ts run soap-sample --repo . "init cercaMovimenti fine-mese"          # commented skeleton to edit
+llm4ts run soap-sample --repo . "propose cercaMovimenti"                 # scenario set from the reasoning seat
+llm4ts run soap-sample --repo . "call cercaMovimenti"                    # every request of the operation
+llm4ts run soap-sample --repo . -- --allow-mutating revocaBonifico "call revocaBonifico/gia-eseguito"
+llm4ts run soap-sample --repo . list
+```
+
+A request is a YAML projection of the XSD, one file per scenario under
+`samples/<operation>/<name>.request.yaml`:
+
+```yaml
+# cercaMovimenti: fine mese
+operation: cercaMovimenti
+purpose: "fine mese"
+body:
+  iban: IT12L0542811101309953525271 # IbanType, string, pattern …, length 27 [1]
+  dataDa: 2026-01-15 # date [1]
+  dataA: 2026-01-15 # date [1]
+  paginazione: # PaginazioneRichiesta [1]
+    numeroPagina: 1 # int [1]
+    dimensionePagina: 1 # int, 1..100 [1]
+```
+
+Required fields come filled with values that satisfy the schema: identifiers
+already seen in earlier (masked) samples first, then checksummed example
+IBANs and codici fiscali, enumeration values, and strings built from the XSD
+patterns. Optional fields and choice alternatives are commented out. Every
+value is a string, sent exactly as written; `~` sends `xsi:nil`. A raw
+`<name>.request.xml` (the body element or a whole envelope, with an optional
+`<!-- purpose: … -->`) is accepted as a second form and validated the same way.
+
+`call` never sends a request that does not validate; it lists what to fix.
+It records `<name>.exchange.json` beside the request: the masked request
+and response envelopes without security headers, safe HTTP headers, status,
+latency, any SOAP fault, and every place the response breaks its schema
+(values outside an enumeration, undeclared elements), which are findings for
+the design rather than errors. `--keep-raw` also writes the unmasked response
+to the gitignored `raw/`, never shown to a model.
+
+`propose` asks the reasoning seat (`LLM4TS_REASONER`, default `claude`) for
+three to six scenarios (happy path, empty result, pagination boundary, a
+business error, a schema edge) and writes each as a request file, listing
+at its top whatever does not validate. `import` reads the requests saved in a
+SoapUI or ReadyAPI project (interface calls and test steps) and its mock
+responses; stored credentials are counted and ignored, and everything is
+masked before it is written. `LLM4TS_SOAP_STUB=<dir>` answers calls from
+`<dir>/<operation>.xml` instead of the network, for rehearsals; the fixture's
+`responses/` directory is one.
+
+## soap-design
+
+```bash
+llm4ts run soap-design --repo . "analyse"     # evidence per operation (no model)
+llm4ts run soap-design --repo . mapping       # the 1:1 XSD ↔ JSON mapping (no model)
+llm4ts run soap-design --repo . design        # the reasoning seat drafts design/api-design.md
+llm4ts run soap-design --repo . check         # deterministic review; rerun after every edit
+llm4ts run soap-design --repo . revise        # redraft against the check's findings
+llm4ts run soap-design --repo . openapi       # design/openapi.yaml from an approved design
+```
+
+### analyse
+
+Reads the recorded exchanges (calls and SoapUI mocks) and writes
+`analysis/<operation>.md` with a typed `analysis/<operation>.json` beside it.
+No model is involved; the report is the evidence the REST design must cite:
+
+- **observations**: values outside a declared enumeration, undeclared code
+  lists, required fields that are always empty, optional ones always present,
+  `xsi:nil` usage, business errors carried inside successful responses,
+  faults, and how many declared fields were never observed;
+- **business outcome codes** (`esito.codice` and similar) with their
+  descriptions and the samples that produced them;
+- **SOAP faults** by code, detail element, and reason;
+- **pagination**: page-number, offset, or cursor style, from the request and
+  response field names, plus what the samples showed (last-page flags, most
+  items per response);
+- **response fields**: presence, emptiness and nil counts, and the masked
+  values seen (most frequent first);
+- **schema findings**: every place a response broke its WSDL;
+- fields **never observed**, optional **request fields no sample used**,
+  and **latency** across real calls.
+
+### mapping, design, check, openapi
+
+`mapping` writes `design/mapping.json` and `mapping.md`: every request and
+response field with the JSON path and type a literal facade would use
+(decimals stay strings). It is the traceability base: the only paths a
+design may cite.
+
+`design` asks the reasoning seat (`LLM4TS_REASONER`, default `claude`) for a
+resource-oriented design, giving it the style guide as hard rules, the
+confirmed classes, the mapping, the named XSD types, and the analysis
+evidence. The draft is written to `design/api-design.md` under
+`Status: proposed`, with the check's findings above the design of record, a
+` ```json apidesign ` block:
+
+- **endpoints** name their SOAP `sources`, parameters cite request paths,
+  responses name a model and the response path it comes from (`list`/`paged`
+  for collections), **errors** list the outcome codes and fault elements they
+  map, and **evidence** cites the analysis;
+- **models** bind to an XSD element or named type (`sourceType`); each
+  property cites a path within it (`saldo.valore`) or a `derivation`, and an
+  `enumMap` translates SOAP values to REST values;
+- **excluded** lists operations deliberately not exposed, with reasons.
+
+`check` is the deterministic reviewer, run on every draft and after every
+edit. Errors: an operation neither exposed nor excluded, `GET` over a
+mutating operation, a source path that is not in the XSD, a model rendered
+from a type it is not bound to, an `enumMap` missing a declared value or a
+value the samples showed (`SOSPESO`), and style violations (paths, names,
+`esito` in payloads, problem codes). Warnings: REST promising a field the
+XSD leaves optional, business errors or faults seen in samples but not
+mapped, unused models. `revise` hands the findings back to the seat.
+
+The file is the approval: edit the JSON block, rerun `check`, and set
+`Status: approved`. `design` never overwrites it. `openapi` refuses a design
+that is not approved or still has errors, then projects `design/openapi.yaml`
+(OpenAPI 3.1): component schemas per model, `{ items, page }` wrappers for
+collections, RFC 9457 problems per error status with their codes
+(`x-problem-codes`), a `Location` header on creations, a default `502`, and
+`x-soap-*` extensions tracing every operation, parameter, and property to the
+SOAP service. Nobody edits it; the ACE pack implements it. The fixture's
+[`design/api-design.md`](fixtures/demo-bank-soap/design/api-design.md) is a
+reviewed example.
+
+## soap-epic
+
+```bash
+llm4ts run soap-epic --repo . doctor                                # ACE 12 usable here?
+llm4ts run soap-epic --repo . -- --target ~/work/demo-bank-ace plan # seed + story plan
+```
+
+`plan` takes an approved design with no check errors and prepares the ACE
+repository (`--target`, a git repository):
+
+- **regenerated every run**: `contracts/` (the design, `openapi.yaml` 3.1,
+  `openapi-ace.yaml` 3.0.3 because ACE 12 imports OpenAPI 3.0, the 1:1
+  mapping, the WSDL and XSDs re-encoded as UTF-8), `test-data/` (the masked
+  exchanges the backend stubs are built from), `docs/analysis/`, and
+  `docs/patterns/` (the ESQL pattern cards);
+- **created once, then the team's**: the
+  [`ace12-rest-api`](scaffolds/ace12-rest-api) scaffold: README,
+  `CONTRIBUTING.md` (house rules every coder reads), and
+  `scripts/ace-gates.sh build | test` (`ibmint package`; `ibmint deploy` to a
+  scratch work directory and `IntegrationServer --test-project`, after
+  sourcing `mqsiprofile`), plus a container variant.
+
+It then derives the story plan, not generates it: `api-skeleton` (REST API
+project descriptors and main flow), `policies` (dev/test/uat endpoints and
+security), `shared-lib` (WSDL, backend call, error mapping), `backend-stub`
+(test project and stubs), one `resource-<name>` story per resource owning its
+broker schema folder and tests, and `contract-check`. The plan is saved where
+the engine's `epic-stories` flow looks for it
+(`.llm4ts/epics/<epic-id>/plan.md`, same epic id), so that flow executes it
+unchanged: parallel stories in worktrees (concurrency 2), the ACE gates,
+the judge, the board, branches only. An existing plan is kept; editing it is
+the re-plan. `plan` prints the exact `epic-stories` command.
+
+The [`ace12-rest`](packs/ace12-rest/pack.md) pack names the same gates and
+the judge's rubric (contract, mapping, errors); its prompt and reviewer
+sidecars carry the same rules as `CONTRIBUTING.md`.
+
+## Auth profile
+
+`.llm4ts/soap/<service>/auth.json` is gitignored (discovery writes the
+directory's `.gitignore`) and holds **references only**: `env:NAME` or
+`file:path`. A literal where a secret belongs is refused when the profile is
+read, and errors name the reference, never its value.
+
+```json
+{
+  "environment": "uat",
+  "endpoint": "https://esb-uat.bank.internal/soap/DemoBank",
+  "fetch": { "auth": { "scheme": "basic", "user": "svc-wsdl", "password": "env:WSDL_PASSWORD" } },
+  "call": {
+    "auth": { "scheme": "bearer", "token": "env:SOAP_TOKEN" },
+    "tls": {
+      "pfx": "file:/secure/client.p12",
+      "passphrase": "env:P12_PASS",
+      "ca": "file:/secure/ca.pem"
+    }
+  },
+  "wsSecurity": { "user": "env:WS_USER", "password": "env:WS_PASSWORD", "passwordType": "digest" },
+  "mutating": { "uat": "deny" }
+}
+```
+
+- `environment` must be `dev`, `test`, or `uat`; nothing else is accepted.
+- `fetch` and `call` are configured separately: `auth` is `none`, `basic`, or
+  `bearer`; `tls` is `cert`+`key` (PEM) or `pfx`+`passphrase`, plus an
+  optional `ca`.
+- `wsSecurity` adds a WS-Security `UsernameToken` (`text` or `digest`) to
+  calls.
+- Operations confirmed as `mutating` in `operations.md` follow the
+  environment's policy: `confirm` (default in dev) asks, `flag` (default in
+  test and uat) needs `--allow-mutating <operation>`, `deny` refuses.
+  Unclassified operations are never called.
+
+Persisted exchanges drop `wsse:Security` headers and credential-bearing HTTP
+headers (`authorization`, cookies, anything named like a token or secret).
+
+## Masking
+
+Every SOAP sample is masked before it is written anywhere or shown to a
+model; there is no switch. Personal data is found two ways:
+
+- **by field**: element and attribute names (Italian and English words:
+  `iban`, `codiceFiscale`, `partitaIva`, `numeroCarta`, `intestatario`,
+  `indirizzo`, `dataNascita`, `codiceOtp`, ...) and the XSD type a field is
+  declared with (`IbanType`, `CodiceFiscaleType`);
+- **by value**, anywhere in text: IBANs (mod-97), codici fiscali (check
+  letter), PANs (Luhn, issuer range), partite IVA after `IT`, emails, and
+  `+39` phone numbers.
+
+Replacements are keyed HMAC pseudonyms that keep the format and stay valid:
+an Italian IBAN keeps its ABI/CAB and gets a correct CIN and check digits, a
+codice fiscale keeps the holder's sex and a valid check letter, a PAN keeps
+its BIN and Luhn digit, a partita IVA its office code. One key per service
+maps the same input to the same pseudonym everywhere, so relationships
+between request and response survive. Free-text fields (`causale`,
+`descrizione`) are only scanned for identifiers; a name written inside them
+needs a `mask` override in `masking.json` (`{ "fields": { "causale": "mask" } }`),
+which also accepts `keep` for a field wrongly caught by a name rule. Every
+replacement is reported by path, kind, and reason.
+
+## Layout
+
+```text
+soap-ace/
+  README.md
+  flows/soap-discover.ts        catalog + open questions + proposed operation classes
+  flows/soap-sample.ts          request files, calls, SoapUI import, scenario proposals
+  flows/soap-design.ts          analysis, 1:1 mapping, design draft and check, OpenAPI projection
+  flows/soap-epic.ts            ACE repository seed and the story plan epic-stories runs
+  packs/ace12-rest/             gates, judge rubric, prompts, and api-style.md (the REST style guide)
+  scaffolds/ace12-rest-api/     README, CONTRIBUTING.md, gate scripts for the ACE repository
+  patterns/                     ESQL pattern cards (esito, faults, amounts and enums, paging, nil)
+  flows/lib/soap/               the SOAP library (XML, WSDL/XSD, auth, transport, masking, samples)
+  fixtures/demo-bank-soap/      synthetic service (WSDL/XSD, responses, SoapUI project, reference design) and the RUNBOOK
+  test/
+```

package/kits/soap-ace/fixtures/demo-bank-soap/RUNBOOK.md

@@ -0,0 +1,102 @@
+# Runbook: from a WSDL to ACE 12 branches
+
+A developer laptop with Node 22+, llm4ts, a Claude (or other) CLI for the
+reasoning seat, and IBM ACE 12 installed. Rehearse it first on the
+synthetic fixture (every command below works against it with the stub), then
+on a real service in dev, test, or uat, never production.
+
+## 0. Two repositories
+
+```bash
+mkdir -p ~/work/conti-analysis ~/work/conti-ace
+git -C ~/work/conti-analysis init && git -C ~/work/conti-ace init
+cd ~/work/conti-analysis
+```
+
+The analysis repository holds `.llm4ts/soap/<service>/`: catalog, samples,
+analysis, design. The ACE repository receives the contracts and the code.
+
+## 1. Discover
+
+```bash
+llm4ts run soap-discover --repo . ./wsdl/ContiService.wsdl        # or an https URL
+```
+
+Read `catalog.md`, especially the open questions. Review
+`operations.md`: every `class:` is `read` or `mutating`; set
+`Status: confirmed`. For a URL behind auth, write `auth.json` first (below)
+and set `LLM4TS_SOAP_SERVICE`.
+
+## 2. Credentials and environment
+
+`.llm4ts/soap/<service>/auth.json` (gitignored), references only:
+
+```json
+{
+  "environment": "test",
+  "endpoint": "https://esb-test.bank.internal/soap/Conti",
+  "call": {
+    "auth": { "scheme": "basic", "user": "svc-conti", "password": "env:CONTI_PASSWORD" },
+    "tls": { "pfx": "file:/secure/client.p12", "passphrase": "env:P12_PASS" }
+  },
+  "wsSecurity": { "user": "env:WS_USER", "password": "env:WS_PASSWORD", "passwordType": "digest" }
+}
+```
+
+## 3. Samples
+
+```bash
+llm4ts run soap-sample --repo . "import ./ContiService-soapui-project.xml"   # if the team has one
+llm4ts run soap-sample --repo . "propose cercaMovimenti"                      # scenario drafts
+llm4ts run soap-sample --repo . "init dettaglioConto"                        # or write one by hand
+llm4ts run soap-sample --repo . "call all"
+llm4ts run soap-sample --repo . -- --allow-mutating revocaBonifico "call revocaBonifico/gia-eseguito"
+llm4ts run soap-sample --repo . list
+```
+
+Replace seeded identifiers with ones the test environment knows before
+calling. Rehearsal without a backend: `LLM4TS_SOAP_STUB=<dir of <operation>.xml>`.
+
+## 4. Analyse and design
+
+```bash
+llm4ts run soap-design --repo . analyse      # read analysis/*.md: this is the evidence
+llm4ts run soap-design --repo . design       # draft design/api-design.md
+llm4ts run soap-design --repo . check        # edit the JSON block, re-check, repeat
+llm4ts run soap-design --repo . revise       # optional: let the seat fix what check found
+```
+
+Set `Status: approved` when the check reports no errors and the warnings are
+understood; then `llm4ts run soap-design --repo . openapi`.
+
+## 5. Plan the ACE build
+
+```bash
+llm4ts run soap-epic --repo . doctor
+llm4ts run soap-epic --repo . -- --target ~/work/conti-ace plan
+git -C ~/work/conti-ace add -A && git -C ~/work/conti-ace commit -m "Seed from soap-ace"
+```
+
+Review `.llm4ts/epics/<epic-id>/plan.md` in the ACE repository (edit it to
+re-plan), then run the command `plan` printed:
+
+```bash
+LLM4TS_GATES="bash scripts/ace-gates.sh build;bash scripts/ace-gates.sh test" LLM4TS_WORKTREE_SETUP= \
+  llm4ts run epic-stories --repo ~/work/conti-ace -- --concurrency 2 "<the epic sentence>"
+```
+
+Each story lands on its own branch and merges into `epic/<epic-id>` after its
+gates and judge pass; nothing reaches `main` without a human. The board and
+report live under `.llm4ts/epics/<epic-id>/`. Azure DevOps mirroring is the
+optional board of ADR 0011.
+
+## When something is off
+
+- `ace-gates.sh` cannot find `mqsiprofile`: set `MQSI_PROFILE` or `ACE_HOME`;
+  on a machine without ACE use `scripts/ace-gates-container.sh` with
+  `ACE_IMAGE`.
+- Your ACE fix pack spells a command differently: override the whole gate
+  with `LLM4TS_GATES`.
+- The service changed: rerun discover, sample, analyse, and `check`; the
+  design check points at every citation that broke. `soap-epic plan`
+  regenerates contracts and keeps the team's files.