@wildo-ai/saas-models 1.1.3 → 1.1.5

package/dist/esm/meta-workflows/orchestration.meta-workflows.shared.schemas.js

@@ -0,0 +1,638 @@
+/**
+ * Playbook-step ORCHESTRATION vocabulary: how a step is executed, gated, budgeted, contracted and
+ * deliberated over — independent of what is being built.
+ *
+ * ## Why these are here and not in application creation
+ *
+ * They were declared in `@wildo-ai/saas-specifications/application-creation` until 2026-09-19
+ * (#1342), which meant a generic orchestration engine could not type a step graph, an executor
+ * tier, a budget, a choreography or a deliberation without importing the app-creation domain. The
+ * `MetaWorkflow_` prefix these symbols already carried was asserting membership of the shared
+ * domain while the declaration sat on the other side of the package line.
+ *
+ * ## What deliberately did NOT come with them
+ *
+ * `MetaWorkflow_Phase` (top-down / bottom-up / refinement) and `MetaWorkflow_FunctionalTopic` (the
+ * seven-topic app-build taxonomy) name app-creation METHODOLOGY and stay there, as does
+ * `MetaWorkflowPlaybookSchema` itself — a playbook is an app-creation artifact composed FROM this
+ * vocabulary, which is the dependency running the right way.
+ *
+ * `MetaWorkflow_ArtifactIntent` DID come, against #1342's own table, and the enum's own heading is
+ * why: "A cross-family shorthand, answered by the aspect registry". Its four members — audience,
+ * value, voice, full (`plan` was removed, #1421) — are cross-family requests, so no per-family
+ * vocabulary lives here: each family answers them through `FamilyAspectDeclaration.servesIntents`
+ * in saas-specifications, and `MetaWorkflow_ArtifactSelectorSchema` cannot be typed without the enum. It
+ * was the single backwards edge in the split, and the classification rather than the code was what
+ * turned out to be wrong.
+ *
+ * ## The elicitation question kind is no longer aliased
+ *
+ * `MetaWorkflow_ElicitationQuestionKind` was `typeof HumanDecision_FieldKind` — a second name for an
+ * engine enum, reached for by the companion specifically to dodge a `TS2742`. On this side of the
+ * line the spec names {@link HumanDecision_FieldKind} directly, which is the door that always owned
+ * the vocabulary.
+ */
+import { z } from "zod";
+import { ExpertWorkDomain } from "../flows-actors/deliberation.shared.schemas.js";
+import { HumanDecision_FieldKind } from "../flows-actors/human-decision.shared.schemas.js";
+/**
+ * Which execution tier runs a playbook (design plan D4):
+ * - COMPANION_AGENT — API-transport LLM agent invoked by the companion
+ *   (definition work: market analysis, requirements drafting, judging).
+ * - CODING_AGENT — CLI coding agent (Claude Code) dispatched one-shot into
+ *   the project workspace with app-knowledge loaded.
+ * - HUMAN — the creator performs the step (interview answers, reviews).
+ * - DETERMINISTIC_CLI — a non-LLM `wildo` command (config sync, validate…).
+ *
+ * There is deliberately NO `COMPOSITE`. It was removed 2026-08-29 (issue #115): it answered a
+ * different question from every other member — not *which tier runs this step* but *this is not one
+ * step* — so it became the catch-all, and four playbooks carried it meaning three different things
+ * (a real choreography, a bespoke deterministic executor, and two coding-agent dispatches). Nothing
+ * ever branched on it; composition is read from `method.choreography`, and the child dispatch keys
+ * there deliberately. Splitting it was rejected too: `CHOREOGRAPHY` / `DETERMINISTIC_EXECUTOR` are
+ * the two arms of the engine's `FlowActorSystem` union, and this contract stays engine-agnostic (see
+ * P-1 above).
+ *
+ * The runtime honours FOUR of these five by branching, and refuses the fifth by name. Re-measured
+ * 2026-09-02 against `playbook-run.companion.service.ts`:
+ *
+ * | tier | how it is honoured | authors |
+ * |---|---|---|
+ * | `COMPANION_AGENT` | the DEFAULT path — right without branching | 17 declared + 2 undeclared |
+ * | `RESEARCH_AGENT` | `runChoreographyChild` routes the read-only lane (`:928`) | 1 |
+ * | `CODING_AGENT` | dispatches the next build task via `ApplicationBuildDispatchService` (`:2022`), and carries child step outputs (`:959`) | 2 |
+ * | `DETERMINISTIC_CLI` | runs the host-owned check set for the playbook's ref (`:2087`) | 1 |
+ * | `HUMAN` | REFUSES by name (`:2131`) — the contract is undecided, and silence was the defect | 0 |
+ *
+ * A tier is therefore a real routing key: any playbook declaring `CODING_AGENT` or
+ * `DETERMINISTIC_CLI` gets that mechanism with no host edit, which is precisely what separates a TIER
+ * from the bespoke executor keyed to `bottom_up.foundation`'s ref.
+ *
+ * ## What this paragraph used to say, and why it is worth recording
+ *
+ * Until 2026-09-02 it said the runtime honours ONE of the five, that `CODING_AGENT` is "honoured by
+ * nothing — reachable only through its own companion HTTP endpoints", and that `HUMAN` and
+ * `DETERMINISTIC_CLI` "have no authors at all". All three were true when written (2026-08-29, issue
+ * #119) and all three were fixed within days: #119 wired the executor branch, and `assemble-verify`
+ * came back with `DETERMINISTIC_CLI` (`11b78bb5`). Nothing updated the sentence.
+ *
+ * It then did real damage: a session planning new work read this paragraph, concluded a playbook
+ * could not reach the coding lane by declaring a tier, and reported that constraint as measured fact.
+ * The runtime had disagreed for days. **Prose describing what the runtime does is an artifact that
+ * goes stale exactly like a compiled one** — see `.claude/rules/staleness-presents-as-a-logic-defect.md`
+ * — and a docstring stating a NEGATIVE capability is the most dangerous shape, because a reader who
+ * believes it stops looking. Verify against the branch, not against this comment.
+ */
+export var MetaWorkflow_Executor;
+(function (MetaWorkflow_Executor) {
+    MetaWorkflow_Executor["COMPANION_AGENT"] = "companion_agent";
+    MetaWorkflow_Executor["CODING_AGENT"] = "coding_agent";
+    /**
+     * READ-ONLY agent with web access — the evidence lane.
+     *
+     * Distinct from {@link CODING_AGENT} despite sharing the transport, because the two have opposite
+     * postures and the difference is enforced, not stylistic: a research run is admitted under a
+     * permission ceiling that pre-approves only the protocol's NON-MUTATING tool kinds, and its
+     * dispatch refuses every filesystem path. Distinct from {@link COMPANION_AGENT} because that is an
+     * API call with no tools at all — which is precisely what left `top_down.market-analysis` claiming
+     * derivation from "sealed research evidence" while its executing agent could reach nothing but its
+     * own training data.
+     */
+    MetaWorkflow_Executor["RESEARCH_AGENT"] = "research_agent";
+    MetaWorkflow_Executor["HUMAN"] = "human";
+    MetaWorkflow_Executor["DETERMINISTIC_CLI"] = "deterministic_cli";
+})(MetaWorkflow_Executor || (MetaWorkflow_Executor = {}));
+/** @wildo_source:part:start saas.specifications.playbook-approval-and-failure-policies facet:layer:shared facet:audience:app-developer */
+/**
+ * Per-playbook approval posture (design plan OQ-3).
+ *
+ * ⚠️ **Read since 2026-09-22 (#111) at ONE KIND of place: the boundary of a COMPOSITE run.** When a
+ * lane (a playbook declaring `method.choreography`) ends, ITS OWN `approval` decides whether the run
+ * leaves a person an `approve_result` decision on the decision plane about the files its children
+ * landed — `auto` owes nothing, `notify` owes a record, `approve_result` and `approve_before` owe the
+ * decision (nothing suspends BEFORE a run, so the stronger reading of `approve_before` is honoured
+ * at the boundary that exists). One run can therefore leave SEVERAL: a root composite's own, plus
+ * one for every nested lane that owed one, because a lane is where the question genuinely arises —
+ * inside one run a lane lands the domain plan and the next builds on it. The autonomy posture
+ * decides what a decision DOES: under the decided YOLO posture it is recorded on the run's row and
+ * the run concludes — a marked gate that notifies and proceeds; holding the run for it is the GUIDED
+ * posture's and is not built.
+ *
+ * On a LEAF playbook the field is still authored intent only: a leaf run is not gated, and a leaf
+ * whose JSON reads `"approval": "approve_before"` runs when it is asked to run. Do not tell a creator
+ * a leaf run is held pending approval. The same holds for the failure policy below, which the same
+ * lane boundary reads to frame the decision (discard first under `revert_changeset`) and never to
+ * revert on its own.
+ *
+ * **Measured 2026-08-29 alongside issue #103,** before the boundary existed:
+ * `MetaWorkflow_ApprovalPolicy` had zero consumers outside this file and the 20 playbook
+ * definitions that author it. The same is true of the journey-level `Journey_AutonomyPreset` that
+ * was to map over it, and of the `wildo journey set-autonomy` command its JSDoc names — that
+ * command exists in no CLI. So a playbook declaring `APPROVE_BEFORE` is not gated, and one
+ * declaring `AUTO` is not thereby unattended.
+ *
+ * It is kept rather than deleted because — unlike the `qualityGates` field removed in the same
+ * pass — nothing else delivers it. `qualityGates` was a second description of live checks;
+ * this is a real posture nobody has built, and deleting it would discard the design rather than
+ * the duplication. Build-or-delete is a decision, tracked as its own issue (#111).
+ *
+ * **DECIDED 2026-08-30: DEFERRED, and the deferral is the point.** Not "we did not get to it" —
+ * `application-creation-directive.md` says the system must WORK first and that restrictions arrive
+ * later, from a real incident, as judge-style guards rather than ceremony wired into the mechanism.
+ * An inert approval policy is therefore the INTENDED posture right now, not a hole to plug.
+ *
+ * So read the effective state precisely, because the two halves differ:
+ *
+ * - **Running is unattended.** Nothing gates a playbook run — no preset, no policy, no failure
+ *   handling. That is full-YOLO behaviour, arrived at by absence rather than by declaration.
+ * - **Accepting is not — but by ABSENCE, not by rule.** Nothing in the runtime performs a commit
+ *   (re-verified 2026-09-06), so acceptance is a human `git commit` because no other path exists.
+ *
+ * The rule conflict this comment used to record — `one-source-of-truth.md` Rule 3 read as "only a
+ * human commits" against the directive's YOLO row — was SETTLED by D5's amendment on 2026-09-03: the
+ * autonomy posture governs who commits, the posture is YOLO for all, and "only a human commits"
+ * describes GUIDED rather than a floor. So this is now a missing mechanism, not an undecided rule;
+ * see `journey.application-creation.schemas.ts` for what building it still owes.
+ *
+ * The paragraph here claimed until 2026-08-29 that "the non-bypassable floor (budgets,
+ * destructive operations, off-machine effects — implementation-spec P-28) hard-gates in ALL
+ * presets regardless of this field." Do not restore that sentence: no such gate runs, and a
+ * safety claim is the worst thing to leave standing on an unbuilt mechanism.
+ */
+export var MetaWorkflow_ApprovalPolicy;
+(function (MetaWorkflow_ApprovalPolicy) {
+    MetaWorkflow_ApprovalPolicy["AUTO"] = "auto";
+    MetaWorkflow_ApprovalPolicy["NOTIFY"] = "notify";
+    MetaWorkflow_ApprovalPolicy["APPROVE_RESULT"] = "approve_result";
+    MetaWorkflow_ApprovalPolicy["APPROVE_BEFORE"] = "approve_before";
+})(MetaWorkflow_ApprovalPolicy || (MetaWorkflow_ApprovalPolicy = {}));
+/**
+ * What the runner does when a playbook run fails mid-flight (review F-5) —
+ * a failed CODING_AGENT run must never leave a silent half-applied
+ * change-set: it is either reverted or kept and flagged for human triage.
+ */
+/**
+ * What a playbook run does with its partial work when it fails.
+ *
+ * **Read at the lane boundary since 2026-09-22 (#111), and only there.** A composite run that ended
+ * with every child of an iteration failed carries this policy into the boundary decision it leaves
+ * for a person: `revert_changeset` puts DISCARD first among the options, `keep_and_flag` keeps the
+ * landings and flags the failure. Neither is performed by the runtime — git already makes every
+ * landing visible and reversible, and a lane that failed on its last iteration may have landed good
+ * work before it — so the reader decides. On a LEAF run the field is still authored intent only
+ * (measured 2026-08-29, issue #103: zero consumers then), and `revert_changeset` has never been
+ * performed by anything.
+ */
+export var MetaWorkflow_FailurePolicy;
+(function (MetaWorkflow_FailurePolicy) {
+    MetaWorkflow_FailurePolicy["REVERT_CHANGESET"] = "revert_changeset";
+    MetaWorkflow_FailurePolicy["KEEP_AND_FLAG"] = "keep_and_flag";
+})(MetaWorkflow_FailurePolicy || (MetaWorkflow_FailurePolicy = {}));
+/** @wildo_source:part:end saas.specifications.playbook-approval-and-failure-policies */
+/**
+ * Discriminant vocabulary for journey-snapshot predicates.
+ *
+ * Three of these gate on an artifact family and they are NOT interchangeable — the difference is the
+ * PRECONDITION CLASS the runtime assigns each of them (`PRECONDITION_CLASS_BY_KIND`, application-creation
+ * runtime), which decides whether a human may deliberately proceed past an unmet one:
+ *
+ * | kind | asks | class |
+ * |---|---|---|
+ * | {@link MetaWorkflow_PredicateKind.ARTIFACT_EXISTS} | does the family have content? | READINESS — nobody proceeds |
+ * | {@link MetaWorkflow_PredicateKind.ARTIFACT_VALID} | …and does it pass its validator? | READINESS — nobody proceeds |
+ * | {@link MetaWorkflow_PredicateKind.ARTIFACT_EXPECTED} | it SHOULD come first | SEQUENCING — a human may proceed |
+ * | {@link MetaWorkflow_PredicateKind.ARTIFACT_STALE} | the family's landed output was derived from inputs that have since MOVED | READINESS — nobody proceeds |
+ */
+export var MetaWorkflow_PredicateKind;
+(function (MetaWorkflow_PredicateKind) {
+    MetaWorkflow_PredicateKind["ARTIFACT_EXISTS"] = "artifact_exists";
+    /**
+     * The family's landed output is DERIVED-STALE: an input it was derived from has a commit newer
+     * than the output's, carries uncommitted edits, or the creator answered the producing interview
+     * after the output was committed (#57 — the loop-back gate; the annotation `staleOutputs` already
+     * computed the fact, this lets a lane AUTHOR route on it).
+     *
+     * Declared on the child that would RE-DERIVE the family, NEVER on the one that first produces it:
+     * a family with no committed version has no derivation to compare against, so the gate is
+     * unsatisfied and the child never runs. It is read against THAT child's own `inputs[]` — "stale"
+     * means stale for the purpose of the playbook about to re-derive it — so a re-derive child with an
+     * incomplete `inputs[]` under-reports exactly as the annotation does.
+     *
+     * READINESS: unsatisfied means "the output is current, so re-deriving it would produce the same
+     * thing from the same inputs", and nobody proceeds past that — not the loop, not a human. A human
+     * who wants a fresh derivation runs the PRODUCING playbook, which this gate never touches. (It was
+     * SEQUENCING for one day. Inside a choreography every lane child is admitted past SEQUENCING —
+     * the one production caller hardcodes it — so the gate was inert in the one place it exists for.)
+     *
+     * Git-derived and never stored (`one-source-of-truth.md`, Rule 0): the same tree yields the same
+     * answer after any merge, and an UNCOMMITTED output is a working edit, not a stale one.
+     */
+    MetaWorkflow_PredicateKind["ARTIFACT_STALE"] = "artifact_stale";
+    /**
+     * A SIBLING step in the same choreography has returned, and optionally returned a particular value.
+     *
+     * READINESS: a child gated on a sibling's return genuinely cannot run without it. It reads the
+     * parent run's step results — data that lives for the run and is never written to the tree — and
+     * NOT `artifactsByFamily`, which holds durable families. Keeping them in separate maps is what
+     * makes "a step result can never be mistaken for an artifact" a property of the type rather than a
+     * rule someone has to remember.
+     */
+    MetaWorkflow_PredicateKind["STEP_AVAILABLE"] = "step_available";
+    MetaWorkflow_PredicateKind["ARTIFACT_VALID"] = "artifact_valid";
+    /**
+     * This family is expected to be produced FIRST, and running without it is a legitimate choice.
+     *
+     * Added 2026-08-28 for a gap the vocabulary could not express. A compliance-document draft is better
+     * when the application's document facts already exist — but it must still be producible without them,
+     * with the statements it could not establish marked incomplete rather than refused. Neither existing
+     * artifact kind can say that: both are READINESS, so an unmet one blocks unconditionally, and simply
+     * dropping the precondition loses the ordering signal (`unmet` stops explaining WHY a run is early).
+     *
+     * Content-wise this asks exactly what {@link MetaWorkflow_PredicateKind.ARTIFACT_EXISTS} asks — one
+     * shared check answers both — so the ONLY difference is the class. Use it whenever running early
+     * degrades the output rather than invalidating it.
+     */
+    MetaWorkflow_PredicateKind["ARTIFACT_EXPECTED"] = "artifact_expected";
+})(MetaWorkflow_PredicateKind || (MetaWorkflow_PredicateKind = {}));
+/**
+ * Selects definition artifacts from the journey's artifact graph.
+ *
+ * `family` is a kebab-case artifact-family id (e.g. `market-snapshot`,
+ * `requirements`, `vision-brief`, `roadmap`, `business-model`). It is intentionally an open string in
+ * v1: artifact families grow with the methodology and per-app overrides;
+ * the canonical family registry is owned by the assertion surface
+ * (AssertionSpecification family, saas-specifications `_core/assertions/`)
+ * rather than frozen in this enum. Precondition evaluation fails closed on
+ * unknown families at runtime.
+ */
+/**
+ * WHAT a consumer needs from an artifact family — a request, answered per family by the renderer
+ * that composes it into a prompt.
+ *
+ * ## Why this exists
+ *
+ * Measured on wonder-crm (2026-08-28): the market snapshot renders at **41KB** across 16
+ * collections, and is an input to 10 of the 27 playbooks (re-measured 2026-09-21). A consumer that
+ * needs one part of it still received all of it, next to vision, requirements, roadmap and feature
+ * drafts, before its method and workspace truth are added.
+ *
+ * (An earlier revision gave `bottom_up.domain-plan` as the example, saying it "needs `icps` + `jobs`".
+ * Its method names neither: its load-bearing market input is the BENEFITS wired to their delivering
+ * features. The slice built from that sentence removed exactly the benefits — #1428. When a slice is
+ * justified by a consumer's need, quote the consumer's method, not a summary of it.)
+ *
+ * A playbook was previously unable to say what it wanted, so the composer could only hand over
+ * everything. That is not merely expensive: an artifact's most relevant paragraph competes for
+ * attention with fifteen collections that have nothing to do with the task.
+ *
+ * ## A cross-family shorthand, answered by the aspect registry
+ *
+ * Since #1420 a playbook can name the exact aspects it reads (`inputs[].aspects`). Intent stays as the
+ * coarse CROSS-FAMILY shorthand, and since #1421 it has no table of its own: each aspect declaration in
+ * `FAMILY_ASPECTS_REGISTRY` (saas-specifications) states which intents it serves (`servesIntents`),
+ * beside the schema that says what the aspect means. An intent resolves to the family's aspects that
+ * declare it. A family none of whose aspects declares the intent renders in full: the request is
+ * honoured or answered with everything, never silently narrowed to nothing.
+ *
+ * ABSENT means {@link MetaWorkflow_ArtifactIntent.FULL} — a playbook that has not been given an
+ * intent keeps exactly the behaviour it had.
+ */
+export var MetaWorkflow_ArtifactIntent;
+(function (MetaWorkflow_ArtifactIntent) {
+    /** Who the product is for. Market segments, personas, the jobs they are hiring it to do. */
+    MetaWorkflow_ArtifactIntent["AUDIENCE"] = "audience";
+    /** What it must deliver and why that matters. Benefits, the jobs they advance, pains, gains, requirements. */
+    MetaWorkflow_ArtifactIntent["VALUE"] = "value";
+    /** How it is described and sold. Positioning, tone, messaging, objections, pricing. */
+    MetaWorkflow_ArtifactIntent["VOICE"] = "voice";
+    /*
+     * `PLAN` ("what is sequenced and when") was REMOVED 2026-09-21 (#1421). No playbook declared it and
+     * no family narrowed under it: its intended family, `build-plan`, is `{ version, tasks }`, so a PLAN
+     * slice kept everything, and its bulk is answered by the build-plan RENDERER instead. A member that
+     * looks like a narrowing and never narrows is a control that does nothing.
+     */
+    /** Everything the family holds. The default, and the honest answer when no aspect serves the request. */
+    MetaWorkflow_ArtifactIntent["FULL"] = "full";
+})(MetaWorkflow_ArtifactIntent || (MetaWorkflow_ArtifactIntent = {}));
+/**
+ * Whether gathered evidence is sufficient to derive an artifact from — the adequacy verdict.
+ *
+ * Small and deliberately reusable: market analysis is the first consumer, but `compliance-posture`
+ * (which regimes apply, in which jurisdictions) and `business-model` (pricing benchmarks) have the
+ * same hole and will ask the same question of the same shape.
+ *
+ * It is a STEP output, never a landed family. The verdict decides whether a sibling may run and is
+ * then discarded with the run; nothing downstream reads it, nobody commits it, and giving it a
+ * durable home would be inventing a record with a lifecycle to hold a boolean that lived for ninety
+ * seconds.
+ */
+export var MetaWorkflow_EvidenceAdequacyVerdict;
+(function (MetaWorkflow_EvidenceAdequacyVerdict) {
+    /** Enough to derive from. The dependant step may run. */
+    MetaWorkflow_EvidenceAdequacyVerdict["ADEQUATE"] = "adequate";
+    /** Not enough yet. `gaps` says what is missing, so the next research round is aimed rather than repeated. */
+    MetaWorkflow_EvidenceAdequacyVerdict["INSUFFICIENT"] = "insufficient";
+})(MetaWorkflow_EvidenceAdequacyVerdict || (MetaWorkflow_EvidenceAdequacyVerdict = {}));
+export const MetaWorkflow_EvidenceAdequacySchema = z.object({
+    verdict: z.enum(MetaWorkflow_EvidenceAdequacyVerdict),
+    /**
+     * What is still missing, in the assessor's own words — the input to the NEXT round's objective.
+     *
+     * Required when INSUFFICIENT and the reason the loop is a loop rather than a retry: a re-run
+     * against the same objective asks the same question again, and the measured failure of that shape
+     * is two attempts spending real tokens to converge on nothing.
+     */
+    gaps: z.array(z.string().min(1)).default([]),
+    /** Why this verdict, against what was actually gathered. */
+    rationale: z.string().min(1),
+});
+export const MetaWorkflow_ArtifactSelectorSchema = z.object({
+    family: z.string().min(1),
+    /**
+     * What this consumer needs from the family. Absent = {@link MetaWorkflow_ArtifactIntent.FULL}.
+     *
+     * Advisory to the COMPOSER, never to eligibility: a precondition asks whether an artifact is
+     * present and valid, which no intent changes. Narrowing what a playbook READS must never narrow
+     * what it WAITS FOR.
+     */
+    intent: z.enum(MetaWorkflow_ArtifactIntent).optional(),
+    /*
+     * `refs` and `pathHint` were REMOVED 2026-09-21 (#1420). Nothing read either — the same search that
+     * finds the real `selector.family` readers found none — and 0 of 63 compiled inputs authored one.
+     *
+     * Narrowing what a playbook reads does not belong here at all, because this selector also types
+     * PRECONDITIONS: a ref or an aspect on it would read as a readiness gate that eligibility never
+     * honours. The input-only narrowing (`aspects`, `render`, `related`) lives on
+     * `MetaWorkflowPlaybookInputSchema` in `@wildo-ai/saas-specifications/application-creation`, and it
+     * narrows by ASPECT, never by ref: a playbook is application-agnostic and cannot know element refs.
+     */
+});
+/**
+ * Contract for an artifact a playbook produces: which family it lands in,
+ * which Zod contract validates it, and where it is placed.
+ *
+ * `schemaRef` uses the pinned `<package-short>:<ExportName>` vocabulary
+ * (implementation-spec P-33), e.g.
+ * `saas-specifications:AssertionSpecificationSnapshot`. The framework-
+ * knowledge audit format-checks it; the generator Zod-validates the whole
+ * playbook against this schema.
+ */
+export const MetaWorkflow_ArtifactContractSchema = z.object({
+    family: z.string().min(1),
+    schemaRef: z
+        .string()
+        .regex(/^(saas-models|saas-specifications):[A-Za-z0-9_]+$/)
+        .optional(),
+    description: z.string().optional(),
+});
+/**
+ * Contract for a value a playbook returns to its PARENT choreography rather than landing as a file.
+ *
+ * ## The one field it does not have is the point
+ *
+ * There is no `family`. The landing service is the only thing that writes specification files, it is
+ * driven by {@link MetaWorkflow_ArtifactContract}, and every landing target is resolved by FAMILY —
+ * so a step output cannot be constructed into a landing request. "A step result never becomes an
+ * application artifact" is therefore a property of the TYPE, not a convention. (TypeScript erases, so
+ * the landing service also refuses a step ref at runtime; the type is the first line, not the whole
+ * guarantee.)
+ *
+ * This paragraph credited `placement` until 2026-08-30, when that field was deleted for never having
+ * been read. The invariant did not depend on it — `family` is required here too and a step output has
+ * `ref` instead — but the prose had to be corrected rather than left pointing at a deleted field,
+ * because a type-level guarantee nobody can locate is one the next author will remove by accident.
+ *
+ * A run's step results live in memory, feed the siblings that declared them as preconditions, and are
+ * discarded when the run ends. Deleting all of them costs a re-run and never a fact
+ * (`one-source-of-truth.md`, Rule 5) — which is exactly why they need no digest, receipt, acceptance
+ * or lifecycle, and why introducing one would be the ceremony this whole design exists to avoid.
+ *
+ * ## `condensation` is required, and that is deliberate
+ *
+ * A parent's context is finite. The published multi-agent research architecture has subagents "act
+ * as intelligent filters" precisely so the lead is not flooded, and `app-creation-dynamic-context.md`
+ * design 4 says the same in our own words: a parent gets summaries at ITS resolution, not the child's
+ * whole working set. A schema that permits an unbounded dump will receive one, so the contract asks
+ * the producer to state what it is returning and how much.
+ */
+export const MetaWorkflow_StepOutputContractSchema = z.object({
+    /** Stable ref a sibling names in a {@link MetaWorkflow_PredicateKind.STEP_AVAILABLE} precondition. */
+    ref: z.string().min(1),
+    /** The `<package-short>:<ExportName>` contract the returned value is validated against, in memory. */
+    schemaRef: z
+        .string()
+        .regex(/^(saas-models|saas-specifications):[A-Za-z0-9_]+$/)
+        .optional(),
+    /** What this step returns, and at what resolution — the CONDENSATION contract, not a description of the work. */
+    condensation: z.string().min(1),
+    description: z.string().optional(),
+});
+/**
+ * A value assertion on a sibling's step result — the EVALUATOR-OPTIMIZER half.
+ *
+ * An adequacy gate that merely RAN is not the same as one that PASSED, and a loop that cannot tell
+ * them apart is not a loop. The canonical pattern makes the evaluator's verdict a structured value
+ * the loop condition READS, rather than prose narrated to a model that then decides whether it was
+ * serious. Reading one declared field of a schema-validated result is not a ceremony.
+ */
+export const MetaWorkflow_StepValueAssertionSchema = z.object({
+    /** Dot path into the step result (e.g. `verdict`, `adequacy.verdict`). */
+    path: z.string().min(1),
+    /** The value that satisfies the gate. Absent means presence alone is enough. */
+    equals: z.union([z.string(), z.number(), z.boolean()]),
+});
+/**
+ * Typed predicates over the Journey Snapshot — playbook ELIGIBILITY gates
+ * (design plan D2/KD-F). The choreographer LLM chooses among *eligible*
+ * playbooks; it can never skip these gates. Predicates are evaluated
+ * deterministically by the PlaybookRegistryService against the derived
+ * snapshot; LLM interpretation cannot soften a failing predicate (S1
+ * held-condition (a)).
+ */
+const _MetaWorkflow_JourneyPredicateSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal(MetaWorkflow_PredicateKind.ARTIFACT_EXISTS),
+        selector: MetaWorkflow_ArtifactSelectorSchema,
+    }),
+    z.object({
+        kind: z.literal(MetaWorkflow_PredicateKind.ARTIFACT_VALID),
+        selector: MetaWorkflow_ArtifactSelectorSchema,
+    }),
+    z.object({
+        kind: z.literal(MetaWorkflow_PredicateKind.ARTIFACT_EXPECTED),
+        selector: MetaWorkflow_ArtifactSelectorSchema,
+    }),
+    z.object({
+        kind: z.literal(MetaWorkflow_PredicateKind.ARTIFACT_STALE),
+        /** The family whose landed output must be derived-stale for this playbook to be eligible. */
+        selector: MetaWorkflow_ArtifactSelectorSchema,
+    }),
+    z.object({
+        kind: z.literal(MetaWorkflow_PredicateKind.STEP_AVAILABLE),
+        /**
+         * The sibling's declared {@link MetaWorkflow_StepOutputContract.ref} — or the DERIVED ref under
+         * which a sibling leaf's advisory judge verdict is readable, `judge:<playbookRef>` (#1498, spelled
+         * by the runtime's `judgeVerdictStepRef`). That value is `{ definitionRef, overall, criteria }`
+         * with `criteria` keyed by criterion ref, so a revise child gates on
+         * `requires: { path: 'criteria.<criterionRef>', equals: 'GAP' }` and a waterfall gate on
+         * `requires: { path: 'overall', equals: 'PASS' }`. An unjudged landing stores nothing there: a
+         * technical failure is never a verdict and routes nowhere.
+         */
+        ref: z.string().min(1),
+        /** Optional value assertion. Absent = presence is enough. */
+        requires: MetaWorkflow_StepValueAssertionSchema.optional(),
+    }),
+]);
+export const MetaWorkflow_JourneyPredicateSchema = _MetaWorkflow_JourneyPredicateSchema;
+export const MetaWorkflow_ElicitationSpecSchema = z.object({
+    questions: z
+        .array(z.object({
+        ref: z.string().min(1),
+        question: z.string().min(1),
+        kind: z.enum(HumanDecision_FieldKind),
+        /** Required when kind = CHOICE. */
+        options: z.array(z.string().min(1)).optional(),
+    }))
+        .min(1),
+});
+/**
+ * Per-playbook budget ceilings a playbook may AUTHOR. No runtime currently
+ * enforces them: the PlaybookRunner that was to be their enforcer was deleted
+ * at the first-activation hard cut, and the demolition removed the budget
+ * machinery with it — today the only live bound on unattended work is the
+ * loop's iteration ceiling. Wiring an enforcer for these fields is tracked as
+ * open work (spend ceiling for the unattended loop). CLI-transport coding
+ * runs report no token usage, so cost accounting there would use wall-time +
+ * run-count proxies.
+ */
+export const MetaWorkflow_PlaybookBudgetSchema = z.object({
+    maxCostUsd: z.number().positive().optional(),
+    /** Aggregate input allowance across a bounded working episode. */
+    maxInputTokens: z.number().int().positive().optional(),
+    /** Aggregate output allowance across a bounded working episode. */
+    maxOutputTokens: z.number().int().positive().optional(),
+    /** Model calls within an episode; intentionally separate from high-level candidate iterations. */
+    maxModelCalls: z.number().int().positive().optional(),
+    maxDurationMs: z.number().int().positive().optional(),
+    maxRuns: z.number().int().positive().optional(),
+});
+/**
+ * THE playbook contract (design plan D2, verbatim). See the file-header
+ * narrative for what a playbook is and where instances live.
+ *
+ * Field notes:
+ * - `ref` is dot-namespaced `<phase-slug>.<name>` (e.g.
+ *   `refinement.compliance-document-candidate`); `ref@version` is unique across the
+ *   compiled catalog (audit rule R15).
+ * - `method.guidance` is the refinable methodology prose (compiled from
+ *   the playbook's `method.md`); `method.skillRefs` point at app-knowledge
+ *   skills that carry the technical HOW — never inline it here.
+ * - Journey-level autonomy PRESETS are NOT a playbook field — playbooks
+ *   carry only their `approval` policy (review F-11).
+ */
+/**
+ * A playbook that ORCHESTRATES other playbooks instead of producing an artifact itself.
+ *
+ * ## Why this is an admissible SET and never a sequence
+ *
+ * `admits` is unordered by contract. Order comes from the children's own preconditions, re-evaluated
+ * against the tree and the run's step results at every iteration, plus the model's selection among
+ * whatever is eligible. That is the difference between a choreography and a workflow, and it is the
+ * property the whole design turns on: *"Playbooks are choreography guides, not static workflows. The
+ * system plays a choreography REACTIVELY to determine what should be done"*
+ * (`.claude/rules/application-creation-directive.md`).
+ *
+ * A recursive `children[]` was considered and rejected in the mined corpus for exactly this reason —
+ * the name invites a fixed sequence and the next author writes one. So does an ordered array here.
+ *
+ * ## The model invents the TASK; code gates only the KIND of work and the bounds
+ *
+ * A child is dispatched against an OBJECTIVE the model composes for that dispatch, adapted to what
+ * earlier rounds returned — which is what makes a research→reframe→re-search loop possible at all,
+ * and what would be thrown away by a schema that enumerated the tasks. This is the published
+ * orchestrator-worker shape: a lead agent INVENTS its workers' objectives rather than selecting them
+ * from a menu; what is authored is the worker's SHAPE.
+ *
+ * ⚠ An earlier draft of this design put a `MetaWorkflow_ChildKind` enum between `admits` and the
+ * playbooks, so a composite named KINDS and a kind resolved to a playbook. It is not built: no
+ * playbook implements more than one kind and no kind has more than one playbook, so the vocabulary
+ * would have been a 1:1 indirection over the refs — speculative structure, which this plan's own
+ * rule ("no schema without a consumer") forbids. The anti-sequence property comes from the SET plus
+ * the eligibility mechanism, never from the vocabulary. Add the enum when two playbooks genuinely
+ * implement one shape of work.
+ */
+export const MetaWorkflow_ChoreographySchema = z.object({
+    /**
+     * Playbook refs this composite may run. UNORDERED — a set, not a sequence.
+     *
+     * At least two: a composite over one child is that child with extra machinery, and the machinery is
+     * the thing worth not having.
+     */
+    admits: z.array(z.string().min(1)).min(2),
+    /**
+     * Iteration ceiling for the child loop — a CIRCUIT BREAKER, deliberately generous.
+     *
+     * It exists to stop a loop spinning, never to refuse work for want of budget. Nothing here or
+     * anywhere else in this lane refuses on grounds of SPEND: a fail-closed accounting guard already
+     * cost this framework a live application once, and CLI-transport runs report no token usage at all,
+     * so a token ceiling on an agent lane is unmeasurable by construction. Spend is measured and
+     * reported; it is never a gate.
+     */
+    maximumIterations: z.number().int().positive().max(20).default(6),
+    /** Children per iteration. Research is breadth-first, so the default matches the journey loop's 3. */
+    maximumLanesPerIteration: z.number().int().positive().max(5).default(3),
+    /**
+     * How deep composition may nest BELOW this composite — a CIRCUIT BREAKER on recursion.
+     *
+     * `1` (the default) means this composite's children may not themselves be composites; `2` admits
+     * a lane of leaves under it, and so on. A nested composite runs through the same choreography
+     * service one level down (#1497): its exported step values return into this run's scope under the
+     * refs its own `stepOutputs[]` declare, its landings report through the same channel, and its
+     * checkpoint nests inside this one so a resumed parent resumes the child.
+     *
+     * The ceiling is INHERITED downward and the tightest ancestor wins: a lane declaring `2` under a
+     * root declaring `2` still cannot open a third level, because the root's breaker is the outer
+     * breaker. A composite selected past the ceiling is withheld from the eligible set (traced, never
+     * silent), and a run started past it stops at once with the `DEPTH_CEILING` stop reason — the
+     * guard the runtime cannot be talked out of by a caller threading the wrong depth.
+     *
+     * It was removed on 2026-09-08 (#488) because the runtime took a `depth` its one caller never
+     * passed, so the ceiling bounded nothing and read as a control. It is back with the recursion
+     * that gives it something to bound, and with the caller that threads depth — the two came back
+     * together, as the removal note required.
+     */
+    maximumDepth: z.number().int().positive().max(5).default(1),
+    /** Wall-clock breaker for the whole composite. A hung agent is the runaway a count cannot catch. */
+    maximumDurationMs: z.number().int().positive().default(30 * 60_000),
+});
+/**
+ * The panel a deliberated playbook convenes.
+ *
+ * Role refs resolve against `EXPERT_ROLE_TEMPLATES`, and the narrowness gate is
+ * TWO-AXIS: the rubric-deriver must OWN `workDomain` (`template.workDomains`), while
+ * every reviewer need only REVIEW it (`template.reviewScopes`) — which is what lets a
+ * design-system guardian sit on an information-architecture panel as the coherence
+ * memory without owning the domain.
+ */
+export const MetaWorkflow_PlaybookDeliberationSchema = z.object({
+    /** The routing axis. Every reviewer's role must have this in its review scopes. */
+    workDomain: z.enum(ExpertWorkDomain),
+    /** The reviewing panel — at least two, because one reviewer is a judge, not a deliberation. */
+    reviewerRoleRefs: z.array(z.string().min(1)).min(2),
+    /** The coordinator: shortlist, convergence, synthesis. Not domain-gated — it is the manager hat. */
+    coordinatorRoleRef: z.string().min(1),
+    /** Who derives the rubric. Must OWN the domain. Defaults to the first reviewer. */
+    rubricDeriverRoleRef: z.string().min(1).optional(),
+    /**
+     * How many distinct candidates to generate before the panel sees anything.
+     *
+     * Bounded at 2–5: one candidate is nothing to deliberate over, and past five the
+     * cost grows faster than the disagreement does.
+     */
+    candidateCount: z.number().int().min(2).max(5).default(3),
+    /** Max rounds before forced synthesis. The engine's own default is 2. */
+    roundBudget: z.number().int().min(1).max(3).optional(),
+    /** Top-K candidates revised per round. */
+    shortlistSize: z.number().int().min(1).optional(),
+});
+//# sourceMappingURL=orchestration.meta-workflows.shared.schemas.js.map