@llm4ts/shell 0.5.0 → 0.6.0

package/flows/modernize-extract.ts

@@ -19,8 +19,9 @@
 // `- [ ] Approved` marker in `docs/modernization/README.md`.
 //
 // Pack: LLM4TS_PACK=<dir> (default packs/cobol-springboot, resolved against the
-// launch dir). LLM4TS_WAVE=<name> scopes the run to one wave of the approved
-// plan. Judge context is bounded by LLM4TS_JUDGE_SOURCES_LIMIT (chars).
+// launch dir, then against the flow's own directory — the built-in packs).
+// LLM4TS_WAVE=<name> scopes the run to one wave of the approved plan. Judge
+// context is bounded by LLM4TS_JUDGE_SOURCES_LIMIT (chars).
 import { join } from "node:path"
 import * as Effect from "effect/Effect"
 import { Sample, type EvalResult } from "@llm4ts/core/eval/Eval"
@@ -29,7 +30,7 @@ import type { JsonSchema } from "@llm4ts/core/Models"
 import { FlowAborted, FlowLlmError } from "@llm4ts/flow/FlowError"
 import { Info } from "@llm4ts/flow/FlowEvents"
 import { makeChat } from "@llm4ts/flow/Chat"
-import { loadPack, type Pack } from "@llm4ts/flow/Pack"
+import type { Pack } from "@llm4ts/flow/Pack"
 import { loadPatternCards, matchingPatternCards } from "@llm4ts/flow/Patterns"
 import { stage } from "@llm4ts/flow/PlanExecution"
 import { defaultPlanInstructions, planFrom } from "@llm4ts/flow/Planner"
@@ -48,6 +49,7 @@ import { runFlowMain, runNode } from "@llm4ts/runner/FlowRunner"
 import { reviewFingerprint } from "@llm4ts/runner/ReviewFingerprint"
 import { nodePlainFileStore } from "@llm4ts/runner/NodePlainFileStore"
 import { makeNodeWorkspace } from "@llm4ts/runner/NodeWorkspace"
+import { loadUniversalPatternCards, openPack } from "@llm4ts/runner/Packs"
 
 const ModDir = "docs/modernization"
 const MaxRounds = 3
@@ -202,7 +204,6 @@ const program = Effect.gen(function* () {
   const input = yield* resolveFlowInput(
     "Extract the complete behavioural spec pack for this legacy estate"
   )
-  const packDir = process.env.LLM4TS_PACK ?? "packs/cobol-springboot"
   const coder = coderFromEnv(process.env)
   const files = nodePlainFileStore
   const modDirAbs = join(input.workDir, ModDir)
@@ -218,9 +219,17 @@ const program = Effect.gen(function* () {
     },
     (context) =>
       Effect.gen(function* () {
-        const launchWorkspace = yield* makeNodeWorkspace(input.workspace)
         const repo = yield* makeNodeWorkspace(input.workDir)
-        const pack = yield* stage(context.events, "pack", loadPack(launchWorkspace, packDir))
+        const opened = yield* stage(
+          context.events,
+          "pack",
+          openPack({
+            environment: process.env,
+            launchDir: input.workspace,
+            flowDir: import.meta.dirname
+          })
+        )
+        const pack = opened.pack
         yield* stage(
           context.events,
           "branch",
@@ -273,8 +282,8 @@ const program = Effect.gen(function* () {
         // Pattern cards are selected deterministically from the SOURCE, never by
         // the model: implementation later injects exactly the cards cited here.
         const cards = [
-          ...(yield* loadPatternCards(launchWorkspace, `${packDir}/patterns`)),
-          ...(yield* loadPatternCards(launchWorkspace, "patterns"))
+          ...(yield* loadPatternCards(opened.workspace, `${opened.dir}/patterns`)),
+          ...(yield* loadUniversalPatternCards([input.workspace, import.meta.dirname]))
         ]
 
         // One structured analyst call per program, resumable per program: a rerun

package/flows/modernize-implement.ts

@@ -25,7 +25,6 @@ import { judge } from "@llm4ts/core/eval/Judge"
 import { makeChat } from "@llm4ts/flow/Chat"
 import { FlowAborted, FlowLlmError, type FlowError } from "@llm4ts/flow/FlowError"
 import { Info } from "@llm4ts/flow/FlowEvents"
-import { loadPack } from "@llm4ts/flow/Pack"
 import { loadPatternCards, taggedPatternIds } from "@llm4ts/flow/Patterns"
 import { makePlanStore } from "@llm4ts/flow/Persistence"
 import { implementTaskLoop, stage } from "@llm4ts/flow/PlanExecution"
@@ -44,6 +43,7 @@ import { runFlowMain, runNode } from "@llm4ts/runner/FlowRunner"
 import { nodePlainFileStore } from "@llm4ts/runner/NodePlainFileStore"
 import { nodeProcessExecutor } from "@llm4ts/runner/NodeProcessExecutor"
 import { makeNodeWorkspace } from "@llm4ts/runner/NodeWorkspace"
+import { loadUniversalPatternCards, openPack } from "@llm4ts/runner/Packs"
 
 const ModDir = "docs/modernization"
 
@@ -87,7 +87,6 @@ const issueText = (issues: ReadonlyArray<ReviewIssue>): string =>
 
 const program = Effect.gen(function* () {
   const input = yield* resolveFlowInput("Implement the seeded modernization plan")
-  const packDir = process.env.LLM4TS_PACK ?? "packs/cobol-springboot"
   const coder = coderFromEnv(process.env)
   const files = nodePlainFileStore
   const planPath = join(input.workDir, ModDir, "plan.md")
@@ -104,9 +103,17 @@ const program = Effect.gen(function* () {
     },
     (context) =>
       Effect.gen(function* () {
-        const launchWorkspace = yield* makeNodeWorkspace(input.workspace)
         const target = yield* makeNodeWorkspace(input.workDir)
-        const pack = yield* stage(context.events, "pack", loadPack(launchWorkspace, packDir))
+        const opened = yield* stage(
+          context.events,
+          "pack",
+          openPack({
+            environment: process.env,
+            launchDir: input.workspace,
+            flowDir: import.meta.dirname
+          })
+        )
+        const pack = opened.pack
 
         yield* stage(
           context.events,
@@ -161,8 +168,8 @@ const program = Effect.gen(function* () {
         // ids, and only the cited cards reach the brief.
         const specText = yield* gatherSpecs(target, pack.specsDir)
         const cards = [
-          ...(yield* loadPatternCards(launchWorkspace, `${packDir}/patterns`)),
-          ...(yield* loadPatternCards(launchWorkspace, "patterns"))
+          ...(yield* loadPatternCards(opened.workspace, `${opened.dir}/patterns`)),
+          ...(yield* loadUniversalPatternCards([input.workspace, import.meta.dirname]))
         ]
         const cited = new Set(taggedPatternIds(specText))
         const playbook = cards.filter((card) => cited.has(card.id))

package/flows/modernize-review.ts

@@ -22,7 +22,7 @@ import { judge } from "@llm4ts/core/eval/Judge"
 import type { JsonSchema } from "@llm4ts/core/Models"
 import { FlowAborted, FlowLlmError } from "@llm4ts/flow/FlowError"
 import { Info } from "@llm4ts/flow/FlowEvents"
-import { appendPackLesson, loadPack, type Pack } from "@llm4ts/flow/Pack"
+import { appendPackLesson, type Pack } from "@llm4ts/flow/Pack"
 import { makePlanStore } from "@llm4ts/flow/Persistence"
 import { Plan, Task } from "@llm4ts/flow/Plan"
 import { stage } from "@llm4ts/flow/PlanExecution"
@@ -40,6 +40,7 @@ import { resolveFlowInput } from "@llm4ts/runner/FlowArgs"
 import { runFlowMain, runNode } from "@llm4ts/runner/FlowRunner"
 import { nodePlainFileStore } from "@llm4ts/runner/NodePlainFileStore"
 import { makeNodeWorkspace } from "@llm4ts/runner/NodeWorkspace"
+import { openPack } from "@llm4ts/runner/Packs"
 
 const ModDir = "docs/modernization"
 
@@ -146,7 +147,6 @@ const distillPrompt = (
 
 const program = Effect.gen(function* () {
   const input = yield* resolveFlowInput("Review the modernization increment against its spec pack")
-  const packDir = process.env.LLM4TS_PACK ?? "packs/cobol-springboot"
   const coder = coderFromEnv(process.env)
   const files = nodePlainFileStore
   const planPath = join(input.workDir, ModDir, "plan.md")
@@ -163,9 +163,17 @@ const program = Effect.gen(function* () {
     },
     (context) =>
       Effect.gen(function* () {
-        const launchWorkspace = yield* makeNodeWorkspace(input.workspace)
         const target = yield* makeNodeWorkspace(input.workDir)
-        const pack = yield* stage(context.events, "pack", loadPack(launchWorkspace, packDir))
+        const opened = yield* stage(
+          context.events,
+          "pack",
+          openPack({
+            environment: process.env,
+            launchDir: input.workspace,
+            flowDir: import.meta.dirname
+          })
+        )
+        const pack = opened.pack
         const reviewService = context.reviewers[0] ?? context.reasoning
 
         yield* stage(
@@ -307,12 +315,12 @@ const program = Effect.gen(function* () {
               )
             }
             for (const lesson of outcome.lessons) {
-              yield* appendPackLesson(launchWorkspace, packDir, lesson)
+              yield* appendPackLesson(opened.workspace, opened.dir, lesson)
             }
             yield* context.events.publish(
               Info.make({
                 message:
-                  `${outcome.lessons.length} lesson(s) appended to ${packDir}/lessons.md — ` +
+                  `${outcome.lessons.length} lesson(s) appended to ${opened.dir}/lessons.md — ` +
                   "review and commit the pack change"
               })
             )

package/flows/modernize-seed.ts

@@ -24,7 +24,6 @@ import * as Schema from "effect/Schema"
 import { FlowAborted, PersistenceError } from "@llm4ts/flow/FlowError"
 import { Info } from "@llm4ts/flow/FlowEvents"
 import { packageVersion } from "@llm4ts/flow/Package"
-import { loadPack } from "@llm4ts/flow/Pack"
 import { parsePlan } from "@llm4ts/flow/Plan"
 import { stage } from "@llm4ts/flow/PlanExecution"
 import { Provenance, makeProvenanceStore } from "@llm4ts/flow/Provenance"
@@ -36,6 +35,7 @@ import { resolveFlowInput } from "@llm4ts/runner/FlowArgs"
 import { runFlowMain, runNode } from "@llm4ts/runner/FlowRunner"
 import { nodePlainFileStore } from "@llm4ts/runner/NodePlainFileStore"
 import { makeNodeWorkspace } from "@llm4ts/runner/NodeWorkspace"
+import { openPack } from "@llm4ts/runner/Packs"
 
 const ModDir = "docs/modernization"
 const skipped = new Set([".git", "target", "node_modules", "dist"])
@@ -84,7 +84,6 @@ const copyFile = Effect.fn("modernize-seed.copyFile")(function* (
 
 const program = Effect.gen(function* () {
   const input = yield* resolveFlowInput("Seed the target repository from the approved spec pack")
-  const packDir = process.env.LLM4TS_PACK ?? "packs/cobol-springboot"
   const legacyRepo = process.env.LLM4TS_LEGACY_REPO?.trim()
   const files = nodePlainFileStore
 
@@ -106,10 +105,18 @@ const program = Effect.gen(function* () {
               "set LLM4TS_LEGACY_REPO to the legacy repository holding the approved spec pack"
           })
         }
-        const launchWorkspace = yield* makeNodeWorkspace(input.workspace)
         const legacy = yield* makeNodeWorkspace(legacyRepo)
         const target = yield* makeNodeWorkspace(input.workDir)
-        const pack = yield* stage(context.events, "pack", loadPack(launchWorkspace, packDir))
+        const opened = yield* stage(
+          context.events,
+          "pack",
+          openPack({
+            environment: process.env,
+            launchDir: input.workspace,
+            flowDir: import.meta.dirname
+          })
+        )
+        const pack = opened.pack
         const specPackRoot = join(legacyRepo, ModDir)
 
         yield* stage(
@@ -138,7 +145,7 @@ const program = Effect.gen(function* () {
             }
             // The scaffold path is relative to the pack directory.
             const scaffoldRoot = join(pack.dir, pack.scaffold)
-            const scaffold = yield* makeNodeWorkspace(join(input.workspace, scaffoldRoot))
+            const scaffold = yield* makeNodeWorkspace(join(opened.workspace.root, scaffoldRoot))
             const paths = (yield* scaffold.discover()).filter((path) => !isLitter(path))
             for (const path of paths) {
               yield* target.write(path, yield* scaffold.read(path))

package/flows/modernize-verify.ts

@@ -34,7 +34,7 @@ import {
 import { renderEquivReport, VectorVerdict } from "@llm4ts/flow/EquivReport"
 import { FlowAborted, FlowLlmError, PlanParseError } from "@llm4ts/flow/FlowError"
 import { Info } from "@llm4ts/flow/FlowEvents"
-import { loadPack, type Pack } from "@llm4ts/flow/Pack"
+import type { Pack } from "@llm4ts/flow/Pack"
 import { makePlanStore } from "@llm4ts/flow/Persistence"
 import { stage } from "@llm4ts/flow/PlanExecution"
 import { Plan, Task } from "@llm4ts/flow/Plan"
@@ -49,6 +49,7 @@ import { runFlowMain, runNode } from "@llm4ts/runner/FlowRunner"
 import { nodePlainFileStore } from "@llm4ts/runner/NodePlainFileStore"
 import { nodeProcessExecutor } from "@llm4ts/runner/NodeProcessExecutor"
 import { makeNodeWorkspace } from "@llm4ts/runner/NodeWorkspace"
+import { openPack } from "@llm4ts/runner/Packs"
 
 const ModDir = "docs/modernization"
 
@@ -278,7 +279,6 @@ const specPrograms = Effect.fn("modernize-verify.specPrograms")(function* (
 
 const program = Effect.gen(function* () {
   const input = yield* resolveFlowInput("Prove the implementation equivalent to its spec pack")
-  const packDir = process.env.LLM4TS_PACK ?? "packs/cobol-springboot"
   const coder = coderFromEnv(process.env)
   const files = nodePlainFileStore
   const planPath = join(input.workDir, ModDir, "plan.md")
@@ -295,9 +295,16 @@ const program = Effect.gen(function* () {
     },
     (context) =>
       Effect.gen(function* () {
-        const launchWorkspace = yield* makeNodeWorkspace(input.workspace)
         const target = yield* makeNodeWorkspace(input.workDir)
-        const pack = yield* stage(context.events, "pack", loadPack(launchWorkspace, packDir))
+        const { pack } = yield* stage(
+          context.events,
+          "pack",
+          openPack({
+            environment: process.env,
+            launchDir: input.workspace,
+            flowDir: import.meta.dirname
+          })
+        )
 
         yield* stage(
           context.events,

package/flows/packs/ace-integration/lessons.md

@@ -0,0 +1,6 @@
+- ESQL routing ladders are business policy tables in disguise: extract them into the
+  spec AS TABLES and keep them as declarative data in the target service — once they
+  dissolve into nested ifs, nobody can verify them against the source again.
+- MQ failure terminals and reject queues are part of the contract: every failure
+  path in the msgflow needs a spec rule and a scenario, or it silently disappears in
+  the port.

package/flows/packs/ace-integration/pack.md

@@ -0,0 +1,29 @@
+# Pack: ace-integration
+
+source: ace
+scaffold: ../../fixtures/scaffolds/spring-boot-service
+sources: .*\.(msgflow|esql)
+specs-dir: docs/specs
+features-dir: src/test/resources/features
+
+## Gates
+
+- build: mvn -q -B test-compile
+- test: mvn -q -B test
+- verify: mvn -q -B verify
+
+## Judge
+
+- completeness (0..2): Every node in the message flow, every routing rule, validation, reject code, queue interface, message mapping, and threshold/flag in the msgflow/ESQL source is captured in the specs and BDD scenarios; the traceability matrix accounts for every flow node and ESQL module. Score 2 only if nothing material is missing.
+- faithfulness (0..2): Every statement is grounded in the source: reject codes, routing predicates, currency lists, thresholds, flag values, queue names, and field mappings match the ESQL exactly, and nothing is invented. Score 2 only if fully source-grounded.
+- testability (0..2): Scenarios are concrete message-in/outcome-out examples — specific payloads, amounts, currencies, and the exact destination or reject code expected; no vague language. Score 2 only if every scenario is directly encodable as a test.
+
+## Coverage: flow-node
+
+files: .*\.msgflow
+unit: <translation xmi:type="utility:ConstantString" string="([^"]+)"/>
+
+## Coverage: esql-module
+
+files: .*\.esql
+unit: ^CREATE (?:COMPUTE|FILTER|DATABASE) MODULE (\S+)

package/flows/packs/ace-integration/prompts/analysis.md

@@ -0,0 +1,21 @@
+You are an ESB reverse-engineering analyst. Extract the COMPLETE observable
+behaviour of the IBM ACE (IIB) message flows in this repository into a spec pack
+precise enough that a team who never sees this source can rebuild them as Spring
+Boot integration services.
+
+How to read the estate:
+
+- The .msgflow is the topology: nodes, their types (MQInput/MQOutput/Compute),
+  their labels, and the connections — including FAILURE terminals, which are error
+  handling and must be accounted for.
+- Queue names on input/output nodes are the INTERFACES: who sends, who consumes,
+  and what each queue means downstream (a CICS request queue means the mainframe is
+  the system of record — say so).
+- The ESQL carries the logic: validation rules with their reject codes, routing
+  predicates (read every CASE/IF — including account-prefix and currency
+  conditions), field-by-field message mappings, thresholds and the flags they set.
+- Static routing tables (SHARED ROW, CASE ladders) are business policy — reproduce
+  them as tables in the spec, not prose.
+- Reject envelopes are contract: code, reason, and what wraps the original payload.
+
+Never invent behaviour. Ambiguity goes in "Open questions", not guesses.

package/flows/packs/ace-integration/prompts/bdd.md

@@ -0,0 +1,13 @@
+Write Gherkin .feature files encoding the specs as executable message-in/outcome-out
+scenarios — these become the acceptance tests of the new integration service.
+
+- One feature per flow (or per coherent rule cluster within one).
+- Scenario shape: Given a payment message with concrete field values, When the
+  service processes it, Then it is delivered to <destination> with <mapped fields /
+  flags> — or rejected with code <code>.
+- Business vocabulary with the codes kept in the Then step (e.g. `Then the payment
+  is rejected with code V01 (unsupported currency)`).
+- Concrete values everywhere: real amounts, currencies, account numbers, IBANs.
+- Cover: every routing branch, EVERY reject code, every threshold boundary (a flag
+  at 10000.00 gets scenarios at 9999.99 and 10000.00 per its semantics), and the
+  field mappings of each destination message.

package/flows/packs/ace-integration/prompts/implement.md

@@ -0,0 +1,17 @@
+You implement one task at a time in a Spring Boot 3 / Java 21 integration service
+that replaces an IBM ACE message flow. The committed specs under docs/specs/ and the
+.feature files under src/test/resources/features/ are the contract; the acceptance
+tests encode them — make them pass without weakening them.
+
+Non-negotiables when porting ESQL semantics:
+
+- Validation order and reject codes match the spec exactly — first-failure-wins,
+  codes verbatim.
+- The routing table stays DATA (a declarative table/map the spec's table maps onto),
+  not a nest of ifs — reviewers must be able to diff it against the spec table.
+- Amount thresholds keep their inclusive/exclusive semantics; money and amounts are
+  BigDecimal — never float/double.
+- Destination messages are built by explicit field-by-field mapping per the spec —
+  no passthrough of unmapped fields.
+- Destinations are ports (interfaces); tests capture what was sent where. Keep the
+  scaffold's structure and idioms.

package/flows/packs/ace-integration/prompts/plan.md

@@ -0,0 +1,12 @@
+Derive the implementation task list for the target Spring Boot integration service
+from the spec pack. Constraints:
+
+- The FIRST task must be exactly: encode the BDD scenarios as failing JUnit 5
+  acceptance tests against the seeded .feature files, driving the service's
+  processing entry point with in-memory inputs/outputs (no production code).
+- Early tasks: the message model (typed payment/request/reject types mirroring the
+  spec's mappings — money as BigDecimal) and the ports for destinations (interfaces
+  the tests can capture; real MQ/HTTP adapters are out of scope for the slice).
+- Then one task per rule cluster in spec order: validation chain with reject codes,
+  the routing table, destination mappings, thresholds/flags.
+- Each task names the spec rules (R1, ...) and scenarios it covers.

package/flows/packs/ace-integration/prompts/review.md

@@ -0,0 +1,17 @@
+You review a finished modernization increment: a Spring Boot integration service
+built from specs reverse-engineered out of IBM ACE message flows. Judge against the
+committed spec pack, not your own taste.
+
+Look specifically for:
+
+- Routing drift: predicates, currency lists, or account-prefix rules differing from
+  the spec's routing table in any value or in evaluation order.
+- Reject-code drift: wrong codes, reordered validations, missing reject envelope
+  fields.
+- Threshold/flag drift: boundaries moved, flags set at the wrong amounts.
+- Mapping gaps: destination message fields missing, renamed, or silently passed
+  through unmapped.
+- Weakened tests: scenarios deleted, captured-destination assertions loosened.
+
+Classify each finding as FIX (violates the spec) or IMPROVEMENT (compliant but
+worth a follow-up).

package/flows/packs/ace-integration/prompts/spec.md

@@ -0,0 +1,29 @@
+Write one behavioural spec per message flow as Markdown with exactly these sections:
+
+# <Flow> — <one-line purpose>
+
+## Overview
+What the flow does, its trigger (input queue), and where messages can end up.
+
+## Interfaces
+Every queue (name, direction, who is on the other end) and the message format on
+each.
+
+## Routing rules
+Numbered (R1, R2, ...), in evaluation order: the predicate (exact values —
+currencies, prefixes, thresholds with boundary semantics) and the destination.
+Static routing tables reproduced AS TABLES.
+
+## Validation & rejects
+Each validation in order, its reject code, and the reject envelope structure.
+
+## Message mappings
+Field-by-field source→target mappings for each output (e.g. the CICS request built
+from the inbound payment), naming the exact target fields.
+
+## Thresholds & flags
+Every amount threshold and the flag/value it sets (priority, regulatory reporting),
+with inclusive/exclusive semantics.
+
+## Open questions
+Anything ambiguous in the source. Empty if none.

package/flows/packs/ace-integration/reviewers/routing-fidelity.md

@@ -0,0 +1,19 @@
+---
+files: .*\.java
+---
+You are the routing-fidelity reviewer for an ACE-to-Spring-Boot port. Your single
+concern: does the Java preserve the exact routing and rejection semantics the specs
+carried over from the ESQL?
+
+Flag as Critical:
+- Routing predicates or their evaluation order differing from the spec's routing
+  table in any value (currencies, prefixes, thresholds).
+- Reject codes differing in any character, or validations running out of spec
+  order.
+- Amount thresholds with drifted boundaries (>= where the spec says >), or
+  float/double anywhere amounts flow.
+- The routing table dissolved into scattered conditionals that can no longer be
+  diffed against the spec table.
+- Destination message mappings missing fields the spec maps.
+
+Ignore style, naming, and framework choices — other reviewers own those.

package/flows/packs/ace-integration/reviewers/traceability.md

@@ -0,0 +1,13 @@
+You are the traceability reviewer for a spec-driven modernization. Every behavioural
+change must be traceable to the committed spec pack.
+
+Flag as Critical:
+- Production behaviour with no corresponding spec rule (R-number) or BDD scenario —
+  either the spec pack is incomplete or the change is out of scope.
+- Changes to .feature files or acceptance tests that alter expected values or delete
+  scenarios (the contract must not be edited to fit the code).
+
+Flag as Warning:
+- Commits/tasks that do not state which spec rules they cover.
+
+Ignore refactors with no behavioural surface.

package/flows/packs/ace-kafka/lessons.md

@@ -0,0 +1,6 @@
+- ESQL routing ladders are business policy tables in disguise: extract them into the
+  spec AS TABLES and keep them as declarative data in the target service — once they
+  dissolve into nested ifs, nobody can verify them against the source again.
+- MQ failure terminals and reject queues are part of the contract: every failure
+  path in the msgflow needs a spec rule and a scenario, or it silently disappears in
+  the port.

package/flows/packs/ace-kafka/pack.md

@@ -0,0 +1,36 @@
+# Pack: ace-kafka
+
+source: ace
+scaffold: ../../fixtures/scaffolds/kafka-streams-service
+sources: .*\.(msgflow|esql)
+programs: .*\.(msgflow|esql)
+specs-dir: docs/specs
+features-dir: src/test/resources/features
+replay: scripts/replay.sh
+
+## Gates
+
+- build: mvn -q -B test-compile
+- test: mvn -q -B test
+- verify: mvn -q -B verify
+
+## Judge
+
+- completeness (0..2): Every node in the message flow, every routing rule, validation, reject code, interface, message mapping, and threshold/flag in the msgflow/ESQL source is captured in the specs and BDD scenarios — re-expressed as event contracts (topics, keys, event payloads); the traceability matrix accounts for every flow node and ESQL module. Score 2 only if nothing material is missing.
+- faithfulness (0..2): Every statement is grounded in the source: reject codes, routing predicates, currency lists, thresholds, flag values, and field mappings match the ESQL exactly, and nothing is invented — renaming a queue to a topic is mapping, changing its meaning is invention. Score 2 only if fully source-grounded.
+- testability (0..2): Scenarios are concrete event-in/events-out examples — specific payloads, amounts, currencies, correlation keys, and the exact output topic or reject code expected; no vague language. Score 2 only if every scenario is directly encodable as a TopologyTestDriver test.
+
+## Equivalence
+
+- ordering: per-key
+- ignore: TIMESTAMP, TS, PROCESSED_AT
+
+## Coverage: flow-node
+
+files: .*\.msgflow
+unit: <translation xmi:type="utility:ConstantString" string="([^"]+)"/>
+
+## Coverage: esql-module
+
+files: .*\.esql
+unit: ^CREATE (?:COMPUTE|FILTER|DATABASE) MODULE (\S+)

package/flows/packs/ace-kafka/prompts/analysis.md

@@ -0,0 +1,21 @@
+You are an ESB reverse-engineering analyst. Extract the COMPLETE observable
+behaviour of the IBM ACE (IIB) message flows in this repository into a spec pack
+precise enough that a team who never sees this source can rebuild them as Spring
+Boot integration services.
+
+How to read the estate:
+
+- The .msgflow is the topology: nodes, their types (MQInput/MQOutput/Compute),
+  their labels, and the connections — including FAILURE terminals, which are error
+  handling and must be accounted for.
+- Queue names on input/output nodes are the INTERFACES: who sends, who consumes,
+  and what each queue means downstream (a CICS request queue means the mainframe is
+  the system of record — say so).
+- The ESQL carries the logic: validation rules with their reject codes, routing
+  predicates (read every CASE/IF — including account-prefix and currency
+  conditions), field-by-field message mappings, thresholds and the flags they set.
+- Static routing tables (SHARED ROW, CASE ladders) are business policy — reproduce
+  them as tables in the spec, not prose.
+- Reject envelopes are contract: code, reason, and what wraps the original payload.
+
+Never invent behaviour. Ambiguity goes in "Open questions", not guesses.

package/flows/packs/ace-kafka/prompts/bdd.md

@@ -0,0 +1,13 @@
+Write Gherkin .feature files encoding the specs as executable message-in/outcome-out
+scenarios — these become the acceptance tests of the new integration service.
+
+- One feature per flow (or per coherent rule cluster within one).
+- Scenario shape: Given a payment event with concrete field values and key, When
+  the topology processes it, Then an event is emitted on <output topic> with
+  <mapped fields / flags> — or a reject event with code <code>.
+- Business vocabulary with the codes kept in the Then step (e.g. `Then the payment
+  is rejected with code V01 (unsupported currency)`).
+- Concrete values everywhere: real amounts, currencies, account numbers, IBANs.
+- Cover: every routing branch, EVERY reject code, every threshold boundary (a flag
+  at 10000.00 gets scenarios at 9999.99 and 10000.00 per its semantics), and the
+  field mappings of each destination message.

package/flows/packs/ace-kafka/prompts/implement.md

@@ -0,0 +1,34 @@
+You implement one task at a time in a Kafka Streams / Java 21 service that replaces
+an IBM ACE message flow with an event-streaming topology. The committed specs under
+docs/specs/ and the .feature files under src/test/resources/features/ are the
+contract; the acceptance tests encode them — make them pass without weakening them.
+
+Non-negotiables when porting ESQL semantics to a topology:
+
+- Queues become topics per the spec's interface mapping: one input topic for the
+  flow's trigger, one output topic per destination (CICS bridge, SEPA gateway,
+  rejects). The event KEY is the correlation identity the spec names (the payment's
+  debtor account unless the spec says otherwise) — per-key ordering is contract.
+- Validation order and reject codes match the spec exactly — first-failure-wins,
+  codes verbatim; a rejected payment emits ONE reject event and nothing else.
+- The routing table stays DATA (a declarative map the spec's table maps onto), not
+  a nest of ifs — reviewers must be able to diff it against the spec table.
+- Amount thresholds keep their inclusive/exclusive semantics; money is BigDecimal —
+  never float/double, and never a double-backed Serde.
+- Destination events are built by explicit field-by-field mapping per the spec — no
+  passthrough of unmapped fields.
+- The topology is built by a pure `Topology buildTopology()` factory the tests and
+  the replay harness drive with TopologyTestDriver — no broker in the test path.
+  Keep the scaffold's structure and idioms.
+
+Replay harness (equivalence verification — part of the contract, same rules as tests):
+
+- The scaffold ships scripts/replay.sh; it runs com.meridian.replay.ReplayHarness,
+  which YOU implement: read one equivalence vector as JSON on stdin, print a JSON
+  array of observations on stdout — nothing else on stdout, ever.
+- The vector's "inputs" is a flat string map: the inbound event's fields using the
+  specs' names, plus "topic:" for the input topic and "key:" for the event key.
+  Feed exactly one input event through TopologyTestDriver and emit every output
+  event, in per-key order, as:
+    {"type":"message","topic":"<output topic>","key":"<event key>","fields":{...}}
+- Amounts as plain scale-2 decimal strings, codes verbatim from the specs.

package/flows/packs/ace-kafka/prompts/plan.md

@@ -0,0 +1,12 @@
+Derive the implementation task list for the target Spring Boot integration service
+from the spec pack. Constraints:
+
+- The FIRST task must be exactly: encode the BDD scenarios as failing JUnit 5
+  acceptance tests against the seeded .feature files, driving the service's
+  processing entry point with in-memory inputs/outputs (no production code).
+- Early tasks: the message model (typed payment/request/reject types mirroring the
+  spec's mappings — money as BigDecimal) and the ports for destinations (interfaces
+  the tests can capture; real MQ/HTTP adapters are out of scope for the slice).
+- Then one task per rule cluster in spec order: validation chain with reject codes,
+  the routing table, destination mappings, thresholds/flags.
+- Each task names the spec rules (R1, ...) and scenarios it covers.

package/flows/packs/ace-kafka/prompts/review.md

@@ -0,0 +1,17 @@
+You review a finished modernization increment: a Spring Boot integration service
+built from specs reverse-engineered out of IBM ACE message flows. Judge against the
+committed spec pack, not your own taste.
+
+Look specifically for:
+
+- Routing drift: predicates, currency lists, or account-prefix rules differing from
+  the spec's routing table in any value or in evaluation order.
+- Reject-code drift: wrong codes, reordered validations, missing reject envelope
+  fields.
+- Threshold/flag drift: boundaries moved, flags set at the wrong amounts.
+- Mapping gaps: destination message fields missing, renamed, or silently passed
+  through unmapped.
+- Weakened tests: scenarios deleted, captured-destination assertions loosened.
+
+Classify each finding as FIX (violates the spec) or IMPROVEMENT (compliant but
+worth a follow-up).