@llm4ts/flow 0.17.0 → 0.18.1

package/dist/SpecChecks.d.ts

@@ -1,6 +1,6 @@
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
-import { ReviewResult } from "./Review.ts";
+import { ReviewIssue, ReviewResult } from "./Review.ts";
 import type { WorkspaceError, WorkspaceShape } from "./Workspace.ts";
 declare const CoverageRule_base: Schema.Class<CoverageRule, Schema.Struct<{
     readonly name: Schema.String;
@@ -15,8 +15,48 @@ export declare class CoverageRule extends CoverageRule_base {
  * candidate units, not every file that shares the tree with them.
  */
 export declare const matchingFiles: (workspace: WorkspaceShape, regex: string, exclude?: string) => Effect.Effect<ReadonlyArray<string>, WorkspaceError>;
+/** A unit a coverage rule captured, with every file it was captured from. */
+export interface CapturedUnit {
+    readonly rule: string;
+    readonly unit: string;
+    readonly paths: ReadonlyArray<string>;
+}
+/**
+ * Every unit each rule captures across the workspace, in first-seen order
+ * per rule, each with the files it was found in — the provenance a
+ * wave-scoped gate needs to tell a unit of this wave from one of another.
+ */
+export declare const capturedUnits: (workspace: WorkspaceShape, rules: readonly CoverageRule[]) => Effect.Effect<readonly CapturedUnit[], WorkspaceError, never>;
 export declare const coverageUnits: (workspace: WorkspaceShape, rules: readonly CoverageRule[]) => Effect.Effect<Readonly<Record<string, readonly string[]>>, WorkspaceError, never>;
-export declare const coverage: (workspace: WorkspaceShape, rules: readonly CoverageRule[], traceability: string) => Effect.Effect<ReviewResult, WorkspaceError, never>;
+export interface CoverageOptions {
+    /**
+     * Restricts the gate to units captured from at least one file this
+     * predicate accepts. A wave-scoped extraction passes the wave's program
+     * files here: a unit that lives only in another wave's sources (or in an
+     * estate-wide descriptor such as web.xml) is reported in `outOfScope`
+     * rather than failing this wave's gate. Absent: every unit gates.
+     */
+    readonly inScope?: (path: string) => boolean;
+}
+export interface CoverageReport {
+    readonly result: ReviewResult;
+    /** Uncovered units the scope excluded from the gate, as `rule: unit`. */
+    readonly outOfScope: ReadonlyArray<string>;
+}
+/** Coverage with the scope split: what gates, and what was left to a later wave. */
+export declare const coverageReport: (workspace: WorkspaceShape, rules: readonly CoverageRule[], traceability: string, options?: CoverageOptions | undefined) => Effect.Effect<CoverageReport, WorkspaceError, never>;
+export declare const coverage: (workspace: WorkspaceShape, rules: readonly CoverageRule[], traceability: string, options?: CoverageOptions | undefined) => Effect.Effect<ReviewResult, WorkspaceError, never>;
 export declare const features: (workspace: WorkspaceShape, directory: string) => Effect.Effect<ReviewResult, WorkspaceError, never>;
+/**
+ * Deterministic schema check of the specs a pack declares `spec-schema:`
+ * for: each program's spec must embed a block the schema decodes. A failure
+ * is a per-program Critical finding (titled like a judge finding, so the
+ * extraction gate's fix turn repairs that program), never a guess in a
+ * later phase — convert-page would otherwise be the first to notice.
+ */
+export declare const specSchemaIssues: (schema: string | undefined, specs: readonly {
+    readonly name: string;
+    readonly markdown: string | undefined;
+}[]) => Effect.Effect<readonly ReviewIssue[], never, never>;
 export {};
 //# sourceMappingURL=SpecChecks.d.ts.map

package/dist/SpecChecks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SpecChecks.d.ts","sourceRoot":"","sources":["../src/SpecChecks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAe,YAAY,EAAE,MAAM,aAAa,CAAA;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;;;;;;AAEpE,qBAAa,YAAa,SAAQ,iBAIhC;CAAG;AAcL;;;;GAIG;AACH,eAAO,MAAM,aAAa,GACxB,WAAW,cAAc,EACzB,OAAO,MAAM,EACb,UAAU,MAAM,KACf,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,cAAc,CAMH,CAAA;AAEnD,eAAO,MAAM,aAAa,kJAuBxB,CAAA;AAEF,eAAO,MAAM,QAAQ,yIAyBnB,CAAA;AA2BF,eAAO,MAAM,QAAQ,sGA+BnB,CAAA"}
+{"version":3,"file":"SpecChecks.d.ts","sourceRoot":"","sources":["../src/SpecChecks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;;;;;;AAEpE,qBAAa,YAAa,SAAQ,iBAIhC;CAAG;AAcL;;;;GAIG;AACH,eAAO,MAAM,aAAa,GACxB,WAAW,cAAc,EACzB,OAAO,MAAM,EACb,UAAU,MAAM,KACf,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,cAAc,CAMH,CAAA;AAEnD,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CACtC;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,8HAwBxB,CAAA;AAEF,eAAO,MAAM,aAAa,kJAYxB,CAAA;AAEF,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAA;CAC7C;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CAC3C;AAUD,oFAAoF;AACpF,eAAO,MAAM,cAAc,kLA0BzB,CAAA;AAEF,eAAO,MAAM,QAAQ,gLAOnB,CAAA;AA2BF,eAAO,MAAM,QAAQ,sGA+BnB,CAAA;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB;mBAEW,MAAM;uBAAqB,MAAM,GAAG,SAAS;2DAyBnF,CAAA"}

package/dist/SpecChecks.js

@@ -1,5 +1,6 @@
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
+import { pageSpecShapeHint, parsePageSpec } from "./PageSpec.js";
 import { ReviewIssue, ReviewResult } from "./Review.js";
 export class CoverageRule extends Schema.Class("CoverageRule")({
     name: Schema.String,
@@ -26,43 +27,75 @@ export const matchingFiles = (workspace, regex, exclude) => workspace
     ...(exclude === undefined ? {} : { excluding: new RegExp(exclude) })
 })
     .pipe(Effect.map((paths) => [...paths].sort()));
-export const coverageUnits = Effect.fn("@llm4ts/flow/SpecChecks.coverageUnits")(function* (workspace, rules) {
+/**
+ * Every unit each rule captures across the workspace, in first-seen order
+ * per rule, each with the files it was found in — the provenance a
+ * wave-scoped gate needs to tell a unit of this wave from one of another.
+ */
+export const capturedUnits = Effect.fn("@llm4ts/flow/SpecChecks.capturedUnits")(function* (workspace, rules) {
     const paths = yield* workspace.discover();
-    const result = {};
+    const result = [];
     for (const rule of rules) {
         const filePattern = new RegExp(rule.files);
         const unitPattern = new RegExp(rule.unit);
-        const units = [];
         for (const path of paths.filter((path) => filePattern.test(path))) {
             const contents = yield* workspace.read(path);
             for (const line of contents.split(/\r?\n/)) {
                 for (const unit of capture(unitPattern, line)) {
-                    if (!units.includes(unit)) {
-                        units.push(unit);
+                    const existing = result.find((entry) => entry.rule === rule.name && entry.unit === unit);
+                    if (existing === undefined) {
+                        result.push({ rule: rule.name, unit, paths: [path] });
+                    }
+                    else if (!existing.paths.includes(path)) {
+                        existing.paths.push(path);
                     }
                 }
             }
         }
-        result[rule.name] = units;
     }
     return result;
 });
-export const coverage = Effect.fn("@llm4ts/flow/SpecChecks.coverage")(function* (workspace, rules, traceability) {
-    const units = yield* coverageUnits(workspace, rules);
-    const issues = rules.flatMap((rule) => (units[rule.name] ?? []).flatMap((unit) => traceability.includes(unit)
-        ? []
-        : [
-            ReviewIssue.make({
-                severity: "Critical",
-                title: `uncovered ${rule.name}: ${unit}`,
-                description: `'${unit}' exists in the legacy source but does not ` +
-                    "appear in the traceability matrix."
-            })
-        ]));
-    return ReviewResult.make({
-        issues,
-        summary: issues.length === 0 ? "coverage complete" : `${issues.length} unit(s) uncovered`
-    });
+export const coverageUnits = Effect.fn("@llm4ts/flow/SpecChecks.coverageUnits")(function* (workspace, rules) {
+    const captured = yield* capturedUnits(workspace, rules);
+    const result = {};
+    for (const rule of rules) {
+        result[rule.name] = captured
+            .filter((entry) => entry.rule === rule.name)
+            .map((entry) => entry.unit);
+    }
+    return result;
+});
+const uncoveredIssue = (rule, unit) => ReviewIssue.make({
+    severity: "Critical",
+    title: `uncovered ${rule}: ${unit}`,
+    description: `'${unit}' exists in the legacy source but does not ` + "appear in the traceability matrix."
+});
+/** Coverage with the scope split: what gates, and what was left to a later wave. */
+export const coverageReport = Effect.fn("@llm4ts/flow/SpecChecks.coverageReport")(function* (workspace, rules, traceability, options = {}) {
+    const captured = yield* capturedUnits(workspace, rules);
+    const issues = [];
+    const outOfScope = [];
+    for (const entry of captured) {
+        if (traceability.includes(entry.unit)) {
+            continue;
+        }
+        if (options.inScope === undefined || entry.paths.some(options.inScope)) {
+            issues.push(uncoveredIssue(entry.rule, entry.unit));
+        }
+        else {
+            outOfScope.push(`${entry.rule}: ${entry.unit}`);
+        }
+    }
+    return {
+        result: ReviewResult.make({
+            issues,
+            summary: issues.length === 0 ? "coverage complete" : `${issues.length} unit(s) uncovered`
+        }),
+        outOfScope
+    };
+});
+export const coverage = Effect.fn("@llm4ts/flow/SpecChecks.coverage")(function* (workspace, rules, traceability, options = {}) {
+    return (yield* coverageReport(workspace, rules, traceability, options)).result;
 });
 const featureIssue = (path, contents) => {
     const lines = contents.split(/\r?\n/).map((line) => line.trim());
@@ -111,4 +144,30 @@ export const features = Effect.fn("@llm4ts/flow/SpecChecks.features")(function*
         summary: issues.length === 0 ? "features well-formed" : `${issues.length} malformed`
     });
 });
+/**
+ * Deterministic schema check of the specs a pack declares `spec-schema:`
+ * for: each program's spec must embed a block the schema decodes. A failure
+ * is a per-program Critical finding (titled like a judge finding, so the
+ * extraction gate's fix turn repairs that program), never a guess in a
+ * later phase — convert-page would otherwise be the first to notice.
+ */
+export const specSchemaIssues = Effect.fn("@llm4ts/flow/SpecChecks.specSchemaIssues")(function* (schema, specs) {
+    if (schema !== "pagespec") {
+        return [];
+    }
+    const issues = [];
+    for (const spec of specs) {
+        const problem = spec.markdown === undefined
+            ? "spec file is missing"
+            : yield* parsePageSpec(spec.markdown).pipe(Effect.map(() => undefined), Effect.catch((error) => Effect.succeed(error.message)));
+        if (problem !== undefined) {
+            issues.push(ReviewIssue.make({
+                severity: "Critical",
+                title: `judge[${spec.name}]: invalid pagespec block`,
+                description: `${problem}. ${pageSpecShapeHint}`
+            }));
+        }
+    }
+    return issues;
+});
 //# sourceMappingURL=SpecChecks.js.map

package/dist/SpecChecks.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/flow",
-  "version": "0.17.0",
+  "version": "0.18.1",
   "description": "Effect-native LLM workflow, persistence, review, and repository automation",
   "license": "MIT",
   "type": "module",
@@ -13,6 +13,8 @@
     "src"
   ],
   "exports": {
+    "./Approval": "./dist/Approval.js",
+    "./Artifacts": "./dist/Artifacts.js",
     "./package.json": "./package.json",
     "./Activity": "./dist/Activity.js",
     "./AzureDevOpsTool": "./dist/AzureDevOpsTool.js",
@@ -89,7 +91,7 @@
     "typescript"
   ],
   "dependencies": {
-    "@llm4ts/core": "0.17.0"
+    "@llm4ts/core": "0.18.1"
   },
   "peerDependencies": {
     "effect": "4.0.0-beta.102"

package/src/Approval.ts

@@ -0,0 +1,51 @@
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import type { FlowError } from "./FlowError.ts"
+import type { PlainFileStoreShape } from "./Persistence.ts"
+
+/**
+ * The human gates of the modernization phases: a markdown document ends
+ * with a draft marker the flow writes, and the next phase refuses to start
+ * until a person has ticked it. (Moved from `@llm4ts/modernize` in 0.18.0.)
+ */
+export class ApprovalRequired extends Schema.TaggedErrorClass<ApprovalRequired>()(
+  "ApprovalRequired",
+  {
+    path: Schema.String,
+    marker: Schema.String
+  }
+) {
+  get message(): string {
+    return `approval required in ${this.path}: set '${this.marker}'`
+  }
+}
+
+export class MissingModernizeArtifact extends Schema.TaggedErrorClass<MissingModernizeArtifact>()(
+  "MissingModernizeArtifact",
+  {
+    path: Schema.String,
+    message: Schema.String
+  }
+) {}
+
+export const ApprovedMarker = "- [x] Approved"
+export const DraftApprovalMarker = "- [ ] Approved"
+
+export const withDraftApproval = (markdown: string): string =>
+  `${markdown.trimEnd()}\n\n${DraftApprovalMarker}\n`
+
+export const requireApproval = Effect.fn("@llm4ts/flow/Approval.requireApproval")(function* (
+  files: PlainFileStoreShape,
+  path: string
+): Effect.fn.Return<void, FlowError | ApprovalRequired | MissingModernizeArtifact> {
+  const contents = yield* files.read(path)
+  if (contents === undefined) {
+    return yield* MissingModernizeArtifact.make({
+      path,
+      message: `approval document does not exist: ${path}`
+    })
+  }
+  if (!contents.includes(ApprovedMarker)) {
+    return yield* ApprovalRequired.make({ path, marker: ApprovedMarker })
+  }
+})

package/src/Artifacts.ts

@@ -0,0 +1,161 @@
+import * as Effect from "effect/Effect"
+import * as Ref from "effect/Ref"
+import * as Result from "effect/Result"
+import * as Schema from "effect/Schema"
+import type { FlowError } from "./FlowError.ts"
+import type { PlainFileStoreShape } from "./Persistence.ts"
+
+export class ProgramUnit extends Schema.Class<ProgramUnit>("ProgramUnit")({
+  name: Schema.String,
+  sourcePath: Schema.String
+}) {}
+
+export class ProgramArtifacts extends Schema.Class<ProgramArtifacts>("ProgramArtifacts")({
+  spec: Schema.String,
+  feature: Schema.String,
+  traceability: Schema.String,
+  mapping: Schema.String
+}) {}
+
+export class ResumeSummary extends Schema.Class<ResumeSummary>("ResumeSummary")({
+  created: Schema.Array(Schema.String),
+  skipped: Schema.Array(Schema.String)
+}) {}
+
+const programName = (name: string): string => name.toLowerCase()
+
+/** The four per-program artifact paths under `directory`, relative to the repository. */
+export const programArtifactPaths = (
+  unit: ProgramUnit,
+  directory = "docs/modernization"
+): ReadonlyArray<string> => [
+  `${directory}/specs/${unit.name}.md`,
+  `${directory}/features/${programName(unit.name)}.feature`,
+  `${directory}/traceability/${unit.name}.md`,
+  `${directory}/mapping/${unit.name}.md`
+]
+
+export interface ExtractProgramsOptions<E2, R2> {
+  /**
+   * How many programs extract at once (default 1: the sequential order the
+   * units were given in). The programs of a wave are independent — each
+   * analyst reads only its source and resolved closure and writes only its
+   * own four files — so the bound is about the model seat's quota, not about
+   * correctness.
+   */
+  readonly concurrency?: number
+  /**
+   * Runs after a program's four artifacts are on disk and before it counts as
+   * created — the seam for per-program post-processing (pattern tagging, the
+   * program's own commit). Runs under the same concurrency as extraction:
+   * anything in it that must not interleave (git) serialises itself.
+   */
+  readonly onCreated?: (unit: ProgramUnit) => Effect.Effect<void, E2, R2>
+}
+
+type Outcome = "created" | "skipped" | "not-started"
+
+/**
+ * Extracts every unit whose spec is missing, writes its four artifacts, and
+ * reports what was created and what was skipped. Resumable by construction:
+ * a rerun skips every program whose spec exists.
+ *
+ * Failure keeps finished work: a program that fails stops NEW programs from
+ * starting, but programs already in flight run to completion and land on
+ * disk (and through `onCreated`) before the first failure, in unit order, is
+ * re-raised. With `concurrency` 1 that is exactly fail-fast; above 1 a quota
+ * death costs only the programs it interrupted, and a rerun resumes the rest.
+ */
+export const extractProgramsResumably = Effect.fn(
+  "@llm4ts/flow/Artifacts.extractProgramsResumably"
+)(function* <E, R, E2 = never, R2 = never>(
+  files: PlainFileStoreShape,
+  units: ReadonlyArray<ProgramUnit>,
+  extract: (unit: ProgramUnit) => Effect.Effect<ProgramArtifacts, E, R>,
+  directory = "docs/modernization",
+  options: ExtractProgramsOptions<E2, R2> = {}
+): Effect.fn.Return<ResumeSummary, E | E2 | FlowError, R | R2> {
+  const concurrency = Math.max(1, Math.floor(options.concurrency ?? 1))
+  const halted = yield* Ref.make(false)
+
+  const extractOne = (unit: ProgramUnit): Effect.Effect<Outcome, E | E2 | FlowError, R | R2> =>
+    Effect.gen(function* () {
+      if (yield* Ref.get(halted)) {
+        return "not-started"
+      }
+      const [specPath, featurePath, traceabilityPath, mappingPath] = programArtifactPaths(
+        unit,
+        directory
+      )
+      if (
+        specPath === undefined ||
+        featurePath === undefined ||
+        traceabilityPath === undefined ||
+        mappingPath === undefined
+      ) {
+        return "not-started"
+      }
+      if ((yield* files.read(specPath)) !== undefined) {
+        return "skipped"
+      }
+      const artifacts = yield* extract(unit)
+      yield* files.writeAtomic(specPath, artifacts.spec)
+      yield* files.writeAtomic(featurePath, artifacts.feature)
+      yield* files.writeAtomic(traceabilityPath, artifacts.traceability)
+      yield* files.writeAtomic(mappingPath, artifacts.mapping)
+      if (options.onCreated !== undefined) {
+        yield* options.onCreated(unit)
+      }
+      return "created"
+    })
+
+  const outcomes = yield* Effect.forEach(
+    units,
+    (unit) =>
+      Effect.result(extractOne(unit)).pipe(
+        Effect.tap((outcome) => (Result.isFailure(outcome) ? Ref.set(halted, true) : Effect.void))
+      ),
+    { concurrency }
+  )
+
+  const firstFailure = outcomes.find(Result.isFailure)
+  if (firstFailure !== undefined) {
+    return yield* Effect.fail(firstFailure.failure)
+  }
+  const created: Array<string> = []
+  const skipped: Array<string> = []
+  for (const [index, outcome] of outcomes.entries()) {
+    const unit = units[index]
+    if (unit === undefined || Result.isFailure(outcome)) {
+      continue
+    }
+    if (outcome.success === "created") {
+      created.push(unit.name)
+    } else if (outcome.success === "skipped") {
+      skipped.push(unit.name)
+    }
+  }
+  return ResumeSummary.make({ created, skipped })
+})
+
+export const generateVectorsResumably = Effect.fn(
+  "@llm4ts/flow/Artifacts.generateVectorsResumably"
+)(function* <E, R>(
+  files: PlainFileStoreShape,
+  programs: ReadonlyArray<string>,
+  generate: (program: string) => Effect.Effect<string, E, R>,
+  directory = "docs/modernization/vectors"
+): Effect.fn.Return<ResumeSummary, E | FlowError, R> {
+  const created: Array<string> = []
+  const skipped: Array<string> = []
+  for (const program of programs) {
+    const path = `${directory}/${program}.jsonl`
+    if ((yield* files.read(path)) !== undefined) {
+      skipped.push(program)
+      continue
+    }
+    yield* files.writeAtomic(path, yield* generate(program))
+    created.push(program)
+  }
+  return ResumeSummary.make({ created, skipped })
+})

package/src/Pack.ts

@@ -41,6 +41,12 @@ export interface Pack {
   // paths), `<NAME>` substituted with the program name. The seam that makes
   // per-program judging possible.
   readonly programFiles: string | undefined
+  /**
+   * The schema every program spec must embed, validated deterministically
+   * by the extraction gate: `pagespec` (a ```json pagespec block decodable
+   * as `PageSpec`) is the only one today; absent means prose-only specs.
+   */
+  readonly specSchema: string | undefined
   readonly dir: string
   readonly gate: (name: string) => ReadonlyArray<string> | undefined
   readonly prompt: (name: string) => string | undefined
@@ -206,6 +212,12 @@ export const loadPack = Effect.fn("@llm4ts/flow/Pack.load")(function* (
       message: `pack manifest 'programFiles:' is not a valid regex template: ${programFiles}`
     })
   }
+  const specSchema = fields["spec-schema"]
+  if (specSchema !== undefined && specSchema !== "pagespec") {
+    return yield* PlanParseError.make({
+      message: `pack manifest 'spec-schema:' must be 'pagespec' when set, got: ${specSchema}`
+    })
+  }
   const exclude = fields.exclude
   if (exclude !== undefined && !isValidRegExp(exclude)) {
     return yield* PlanParseError.make({
@@ -239,6 +251,7 @@ export const loadPack = Effect.fn("@llm4ts/flow/Pack.load")(function* (
     lenses,
     lessons: lessons === undefined || lessons.length === 0 ? undefined : lessons,
     programFiles,
+    specSchema,
     dir: directory,
     gate: (name) => gates[name],
     prompt: (name) => prompts[name],