@llm4ts/flow 0.2.2 → 0.3.0

package/dist/Package.d.ts

@@ -1,2 +1,4 @@
 export declare const packageName = "@llm4ts/flow";
+/** The published `@llm4ts/flow` version, recorded in provenance manifests. */
+export declare const packageVersion: string;
 //# sourceMappingURL=Package.d.ts.map

package/dist/Package.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Package.d.ts","sourceRoot":"","sources":["../src/Package.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,iBAAiB,CAAA"}
+{"version":3,"file":"Package.d.ts","sourceRoot":"","sources":["../src/Package.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,WAAW,iBAAiB,CAAA;AAEzC,8EAA8E;AAC9E,eAAO,MAAM,cAAc,EAAE,MAAyB,CAAA"}

package/dist/Package.js

@@ -1,2 +1,8 @@
+import { createRequire } from "node:module";
+import * as Schema from "effect/Schema";
+const Manifest = Schema.Struct({ version: Schema.String });
+const manifest = Schema.decodeUnknownSync(Manifest)(createRequire(import.meta.url)("../package.json"));
 export const packageName = "@llm4ts/flow";
+/** The published `@llm4ts/flow` version, recorded in provenance manifests. */
+export const packageVersion = manifest.version;
 //# sourceMappingURL=Package.js.map

package/dist/Package.js.map

@@ -1 +1 @@
-{"version":3,"file":"Package.js","sourceRoot":"","sources":["../src/Package.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAG,cAAc,CAAA"}
+{"version":3,"file":"Package.js","sourceRoot":"","sources":["../src/Package.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAA;AAE1D,MAAM,QAAQ,GAAG,MAAM,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CACjD,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,iBAAiB,CAAC,CAClD,CAAA;AAED,MAAM,CAAC,MAAM,WAAW,GAAG,cAAc,CAAA;AAEzC,8EAA8E;AAC9E,MAAM,CAAC,MAAM,cAAc,GAAW,QAAQ,CAAC,OAAO,CAAA"}

package/dist/Patterns.d.ts

@@ -0,0 +1,38 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import type { WorkspaceError, WorkspaceShape } from "./Workspace.ts";
+declare const PatternCard_base: Schema.Class<PatternCard, Schema.Struct<{
+    readonly id: Schema.String;
+    readonly matches: Schema.String;
+    readonly body: Schema.String;
+}>, {}>;
+/**
+ * One reusable modernization pattern: a legacy idiom, its target translation,
+ * and the known traps — knowledge as data, like packs and lessons, but
+ * universal and curated rather than estate-local and run-accumulated.
+ * `matches` is a regex over legacy source: extraction tags each program's
+ * traceability fragment with the ids of the cards that hit, and implementation
+ * injects only the cited cards into the coder's brief — deterministic
+ * selection, bounded context.
+ */
+export declare class PatternCard extends PatternCard_base {
+}
+export declare const parsePatternCard: (id: string, text: string) => PatternCard;
+/**
+ * All `*.md` cards under `directory`, sorted by id (the filename stem). An
+ * absent directory is an empty set — patterns are optional everywhere.
+ */
+export declare const loadPatternCards: (workspace: WorkspaceShape, directory: string) => Effect.Effect<readonly PatternCard[], WorkspaceError, never>;
+/**
+ * The cards whose `matches` regex hits anywhere in `source` — how extraction
+ * decides which patterns a program embodies. A card with no regex never
+ * matches; an invalid regex is skipped rather than failing the run.
+ */
+export declare const matchingPatternCards: (source: string, cards: ReadonlyArray<PatternCard>) => ReadonlyArray<PatternCard>;
+/**
+ * Every `PAT-…` id cited in a spec text, in order of first appearance — how
+ * implementation finds the cards its current task's specs were tagged with.
+ */
+export declare const taggedPatternIds: (spec: string) => ReadonlyArray<string>;
+export {};
+//# sourceMappingURL=Patterns.d.ts.map

package/dist/Patterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Patterns.d.ts","sourceRoot":"","sources":["../src/Patterns.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;;;;;;AAEpE;;;;;;;;GAQG;AACH,qBAAa,WAAY,SAAQ,gBAI/B;CAAG;AAYL,eAAO,MAAM,gBAAgB,GAAI,IAAI,MAAM,EAAE,MAAM,MAAM,KAAG,WAe3D,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,gHAY3B,CAAA;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,MAAM,EACd,OAAO,aAAa,CAAC,WAAW,CAAC,KAChC,aAAa,CAAC,WAAW,CAUxB,CAAA;AAEJ;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,aAAa,CAAC,MAAM,CAEnE,CAAA"}

package/dist/Patterns.js

@@ -0,0 +1,80 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+/**
+ * One reusable modernization pattern: a legacy idiom, its target translation,
+ * and the known traps — knowledge as data, like packs and lessons, but
+ * universal and curated rather than estate-local and run-accumulated.
+ * `matches` is a regex over legacy source: extraction tags each program's
+ * traceability fragment with the ids of the cards that hit, and implementation
+ * injects only the cited cards into the coder's brief — deterministic
+ * selection, bounded context.
+ */
+export class PatternCard extends Schema.Class("PatternCard")({
+    id: Schema.String,
+    matches: Schema.String,
+    body: Schema.String
+}) {
+}
+const frontmatterField = (front, key) => {
+    for (const line of front.split(/\r?\n/)) {
+        const index = line.indexOf(":");
+        if (index > 0 && line.slice(0, index).trim() === key) {
+            return line.slice(index + 1).trim();
+        }
+    }
+    return undefined;
+};
+export const parsePatternCard = (id, text) => {
+    const stripped = text.trim();
+    if (!stripped.startsWith("---")) {
+        return PatternCard.make({ id, matches: "", body: stripped });
+    }
+    const rest = stripped.slice(3);
+    const end = /^---[ \t]*$/m.exec(rest);
+    if (end === null) {
+        return PatternCard.make({ id, matches: "", body: stripped });
+    }
+    return PatternCard.make({
+        id,
+        matches: frontmatterField(rest.slice(0, end.index), "match") ?? "",
+        body: rest.slice(end.index + end[0].length).trim()
+    });
+};
+/**
+ * All `*.md` cards under `directory`, sorted by id (the filename stem). An
+ * absent directory is an empty set — patterns are optional everywhere.
+ */
+export const loadPatternCards = Effect.fn("@llm4ts/flow/Patterns.load")(function* (workspace, directory) {
+    const paths = yield* workspace.discover(`${directory}/*.md`).pipe(Effect.orElseSucceed(() => []));
+    const cards = [];
+    for (const path of [...paths].sort()) {
+        const file = path.split("/").at(-1) ?? path;
+        const text = yield* workspace.read(path).pipe(Effect.orElseSucceed(() => ""));
+        cards.push(parsePatternCard(file.replace(/\.md$/, ""), text));
+    }
+    return cards.sort((left, right) => left.id.localeCompare(right.id));
+});
+/**
+ * The cards whose `matches` regex hits anywhere in `source` — how extraction
+ * decides which patterns a program embodies. A card with no regex never
+ * matches; an invalid regex is skipped rather than failing the run.
+ */
+export const matchingPatternCards = (source, cards) => cards.filter((card) => {
+    if (card.matches.length === 0) {
+        return false;
+    }
+    try {
+        return new RegExp(card.matches, "m").test(source);
+    }
+    catch {
+        return false;
+    }
+});
+/**
+ * Every `PAT-…` id cited in a spec text, in order of first appearance — how
+ * implementation finds the cards its current task's specs were tagged with.
+ */
+export const taggedPatternIds = (spec) => [
+    ...new Set(spec.match(/PAT-[A-Za-z0-9-]+/g) ?? [])
+];
+//# sourceMappingURL=Patterns.js.map

package/dist/Patterns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Patterns.js","sourceRoot":"","sources":["../src/Patterns.ts"],"names":[],"mappings":"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"}

package/dist/Wall.d.ts

@@ -0,0 +1,30 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import type { WorkspaceError, WorkspaceShape } from "./Workspace.ts";
+declare const WallClean_base: Schema.Class<WallClean, Schema.TaggedStruct<"Clean", {}>, {}>;
+/**
+ * The enforced clean-room wall: target-phase flows (implement, verify, review)
+ * refuse to run when the target workspace contains anything matching the pack's
+ * legacy `sources:` regex, so the coder provably never has legacy source in
+ * reach. A breach is a recoverable, typed outcome — the caller decides to
+ * abort; only I/O failure fails the effect.
+ */
+export declare class WallClean extends WallClean_base {
+}
+declare const WallBreached_base: Schema.Class<WallBreached, Schema.TaggedStruct<"Breached", {
+    readonly paths: Schema.$Array<Schema.String>;
+}>, {}>;
+export declare class WallBreached extends WallBreached_base {
+}
+export declare const WallResult: Schema.Union<readonly [typeof WallClean, typeof WallBreached]>;
+export type WallResult = typeof WallResult.Type;
+/**
+ * Scans the working tree for files matching the pack's legacy `sourcesRegex`.
+ * `.git` is exempt — the wall is about the working tree, not repository
+ * internals.
+ */
+export declare const checkWall: (workspace: WorkspaceShape, sourcesRegex: string) => Effect.Effect<WallClean | WallBreached, WorkspaceError, never>;
+/** The one-line breach message every target-phase flow reports, capped at ten paths. */
+export declare const wallBreachMessage: (breach: WallBreached, consequence: string) => string;
+export {};
+//# sourceMappingURL=Wall.d.ts.map

package/dist/Wall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Wall.d.ts","sourceRoot":"","sources":["../src/Wall.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;;AAEpE;;;;;;GAMG;AACH,qBAAa,SAAU,SAAQ,cAA4C;CAAG;;;;AAE9E,qBAAa,YAAa,SAAQ,iBAEhC;CAAG;AAEL,eAAO,MAAM,UAAU,gEAA0C,CAAA;AACjE,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC,IAAI,CAAA;AAE/C;;;;GAIG;AACH,eAAO,MAAM,SAAS,qHAQpB,CAAA;AAEF,wFAAwF;AACxF,eAAO,MAAM,iBAAiB,GAAI,QAAQ,YAAY,EAAE,aAAa,MAAM,KAAG,MAI7E,CAAA"}

package/dist/Wall.js

@@ -0,0 +1,33 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { matchingFiles } from "./SpecChecks.js";
+/**
+ * The enforced clean-room wall: target-phase flows (implement, verify, review)
+ * refuse to run when the target workspace contains anything matching the pack's
+ * legacy `sources:` regex, so the coder provably never has legacy source in
+ * reach. A breach is a recoverable, typed outcome — the caller decides to
+ * abort; only I/O failure fails the effect.
+ */
+export class WallClean extends Schema.TaggedClass()("Clean", {}) {
+}
+export class WallBreached extends Schema.TaggedClass()("Breached", {
+    paths: Schema.Array(Schema.String)
+}) {
+}
+export const WallResult = Schema.Union([WallClean, WallBreached]);
+/**
+ * Scans the working tree for files matching the pack's legacy `sourcesRegex`.
+ * `.git` is exempt — the wall is about the working tree, not repository
+ * internals.
+ */
+export const checkWall = Effect.fn("@llm4ts/flow/Wall.check")(function* (workspace, sourcesRegex) {
+    const matches = (yield* matchingFiles(workspace, sourcesRegex)).filter((path) => !path.startsWith(".git/"));
+    return matches.length === 0 ? new WallClean() : new WallBreached({ paths: matches });
+});
+/** The one-line breach message every target-phase flow reports, capped at ten paths. */
+export const wallBreachMessage = (breach, consequence) => {
+    const shown = breach.paths.slice(0, 10).join(", ");
+    const more = breach.paths.length > 10 ? ` (+${breach.paths.length - 10} more)` : "";
+    return `clean-room wall breached — legacy source inside the target workspace: ${shown}${more}. ${consequence}`;
+};
+//# sourceMappingURL=Wall.js.map

package/dist/Wall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Wall.js","sourceRoot":"","sources":["../src/Wall.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAG/C;;;;;;GAMG;AACH,MAAM,OAAO,SAAU,SAAQ,MAAM,CAAC,WAAW,EAAa,CAAC,OAAO,EAAE,EAAE,CAAC;CAAG;AAE9E,MAAM,OAAO,YAAa,SAAQ,MAAM,CAAC,WAAW,EAAgB,CAAC,UAAU,EAAE;IAC/E,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;CACnC,CAAC;CAAG;AAEL,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,CAAA;AAGjE;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,EAAE,CAAC,yBAAyB,CAAC,CAAC,QAAQ,CAAC,EACrE,SAAyB,EACzB,YAAoB;IAEpB,MAAM,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,aAAa,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC,MAAM,CACpE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CACpC,CAAA;IACD,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,SAAS,EAAE,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAA;AACtF,CAAC,CAAC,CAAA;AAEF,wFAAwF;AACxF,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,MAAoB,EAAE,WAAmB,EAAU,EAAE;IACrF,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAClD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAA;IACnF,OAAO,yEAAyE,KAAK,GAAG,IAAI,KAAK,WAAW,EAAE,CAAA;AAChH,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/flow",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Effect-native LLM workflow, persistence, review, and repository automation",
   "license": "MIT",
   "type": "module",
@@ -36,6 +36,7 @@
     "./Mermaid": "./dist/Mermaid.js",
     "./Pack": "./dist/Pack.js",
     "./Package": "./dist/Package.js",
+    "./Patterns": "./dist/Patterns.js",
     "./Persistence": "./dist/Persistence.js",
     "./Plan": "./dist/Plan.js",
     "./PlanExecution": "./dist/PlanExecution.js",
@@ -50,6 +51,7 @@
     "./SpecChecks": "./dist/SpecChecks.js",
     "./Survey": "./dist/Survey.js",
     "./TransientRetry": "./dist/TransientRetry.js",
+    "./Wall": "./dist/Wall.js",
     "./Workspace": "./dist/Workspace.js",
     "./WorkspaceLayout": "./dist/WorkspaceLayout.js",
     "./WorkspaceTools": "./dist/WorkspaceTools.js"
@@ -76,7 +78,7 @@
     "typescript"
   ],
   "dependencies": {
-    "@llm4ts/core": "0.2.2"
+    "@llm4ts/core": "0.3.0"
   },
   "peerDependencies": {
     "effect": "^4.0.0-beta.102"

package/src/Package.ts

@@ -1 +1,13 @@
+import { createRequire } from "node:module"
+import * as Schema from "effect/Schema"
+
+const Manifest = Schema.Struct({ version: Schema.String })
+
+const manifest = Schema.decodeUnknownSync(Manifest)(
+  createRequire(import.meta.url)("../package.json")
+)
+
 export const packageName = "@llm4ts/flow"
+
+/** The published `@llm4ts/flow` version, recorded in provenance manifests. */
+export const packageVersion: string = manifest.version

package/src/Patterns.ts

@@ -0,0 +1,91 @@
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import type { WorkspaceError, WorkspaceShape } from "./Workspace.ts"
+
+/**
+ * One reusable modernization pattern: a legacy idiom, its target translation,
+ * and the known traps — knowledge as data, like packs and lessons, but
+ * universal and curated rather than estate-local and run-accumulated.
+ * `matches` is a regex over legacy source: extraction tags each program's
+ * traceability fragment with the ids of the cards that hit, and implementation
+ * injects only the cited cards into the coder's brief — deterministic
+ * selection, bounded context.
+ */
+export class PatternCard extends Schema.Class<PatternCard>("PatternCard")({
+  id: Schema.String,
+  matches: Schema.String,
+  body: Schema.String
+}) {}
+
+const frontmatterField = (front: string, key: string): string | undefined => {
+  for (const line of front.split(/\r?\n/)) {
+    const index = line.indexOf(":")
+    if (index > 0 && line.slice(0, index).trim() === key) {
+      return line.slice(index + 1).trim()
+    }
+  }
+  return undefined
+}
+
+export const parsePatternCard = (id: string, text: string): PatternCard => {
+  const stripped = text.trim()
+  if (!stripped.startsWith("---")) {
+    return PatternCard.make({ id, matches: "", body: stripped })
+  }
+  const rest = stripped.slice(3)
+  const end = /^---[ \t]*$/m.exec(rest)
+  if (end === null) {
+    return PatternCard.make({ id, matches: "", body: stripped })
+  }
+  return PatternCard.make({
+    id,
+    matches: frontmatterField(rest.slice(0, end.index), "match") ?? "",
+    body: rest.slice(end.index + end[0].length).trim()
+  })
+}
+
+/**
+ * All `*.md` cards under `directory`, sorted by id (the filename stem). An
+ * absent directory is an empty set — patterns are optional everywhere.
+ */
+export const loadPatternCards = Effect.fn("@llm4ts/flow/Patterns.load")(function* (
+  workspace: WorkspaceShape,
+  directory: string
+): Effect.fn.Return<ReadonlyArray<PatternCard>, WorkspaceError> {
+  const paths = yield* workspace.discover(`${directory}/*.md`).pipe(Effect.orElseSucceed(() => []))
+  const cards: Array<PatternCard> = []
+  for (const path of [...paths].sort()) {
+    const file = path.split("/").at(-1) ?? path
+    const text = yield* workspace.read(path).pipe(Effect.orElseSucceed(() => ""))
+    cards.push(parsePatternCard(file.replace(/\.md$/, ""), text))
+  }
+  return cards.sort((left, right) => left.id.localeCompare(right.id))
+})
+
+/**
+ * The cards whose `matches` regex hits anywhere in `source` — how extraction
+ * decides which patterns a program embodies. A card with no regex never
+ * matches; an invalid regex is skipped rather than failing the run.
+ */
+export const matchingPatternCards = (
+  source: string,
+  cards: ReadonlyArray<PatternCard>
+): ReadonlyArray<PatternCard> =>
+  cards.filter((card) => {
+    if (card.matches.length === 0) {
+      return false
+    }
+    try {
+      return new RegExp(card.matches, "m").test(source)
+    } catch {
+      return false
+    }
+  })
+
+/**
+ * Every `PAT-…` id cited in a spec text, in order of first appearance — how
+ * implementation finds the cards its current task's specs were tagged with.
+ */
+export const taggedPatternIds = (spec: string): ReadonlyArray<string> => [
+  ...new Set(spec.match(/PAT-[A-Za-z0-9-]+/g) ?? [])
+]

package/src/Wall.ts

@@ -0,0 +1,42 @@
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { matchingFiles } from "./SpecChecks.ts"
+import type { WorkspaceError, WorkspaceShape } from "./Workspace.ts"
+
+/**
+ * The enforced clean-room wall: target-phase flows (implement, verify, review)
+ * refuse to run when the target workspace contains anything matching the pack's
+ * legacy `sources:` regex, so the coder provably never has legacy source in
+ * reach. A breach is a recoverable, typed outcome — the caller decides to
+ * abort; only I/O failure fails the effect.
+ */
+export class WallClean extends Schema.TaggedClass<WallClean>()("Clean", {}) {}
+
+export class WallBreached extends Schema.TaggedClass<WallBreached>()("Breached", {
+  paths: Schema.Array(Schema.String)
+}) {}
+
+export const WallResult = Schema.Union([WallClean, WallBreached])
+export type WallResult = typeof WallResult.Type
+
+/**
+ * Scans the working tree for files matching the pack's legacy `sourcesRegex`.
+ * `.git` is exempt — the wall is about the working tree, not repository
+ * internals.
+ */
+export const checkWall = Effect.fn("@llm4ts/flow/Wall.check")(function* (
+  workspace: WorkspaceShape,
+  sourcesRegex: string
+): Effect.fn.Return<WallResult, WorkspaceError> {
+  const matches = (yield* matchingFiles(workspace, sourcesRegex)).filter(
+    (path) => !path.startsWith(".git/")
+  )
+  return matches.length === 0 ? new WallClean() : new WallBreached({ paths: matches })
+})
+
+/** The one-line breach message every target-phase flow reports, capped at ten paths. */
+export const wallBreachMessage = (breach: WallBreached, consequence: string): string => {
+  const shown = breach.paths.slice(0, 10).join(", ")
+  const more = breach.paths.length > 10 ? ` (+${breach.paths.length - 10} more)` : ""
+  return `clean-room wall breached — legacy source inside the target workspace: ${shown}${more}. ${consequence}`
+}