@wildo-ai/saas-models 1.1.4 → 1.1.6

package/dist/esm/meta-workflows/orchestration.meta-workflows.shared.schemas.d.ts

@@ -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";
+import { HumanDecision_FieldKind } from "../flows-actors/human-decision.shared.schemas";
+import { MetaWorkflow_EvaluationVerdict } from "./decisions.meta-workflows.shared.schemas";
+/**
+ * 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 declare enum MetaWorkflow_Executor {
+    COMPANION_AGENT = "companion_agent",
+    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.
+     */
+    RESEARCH_AGENT = "research_agent",
+    HUMAN = "human",
+    DETERMINISTIC_CLI = "deterministic_cli"
+}
+/** @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 declare enum MetaWorkflow_ApprovalPolicy {
+    AUTO = "auto",
+    NOTIFY = "notify",
+    APPROVE_RESULT = "approve_result",
+    APPROVE_BEFORE = "approve_before"
+}
+/**
+ * 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 declare enum MetaWorkflow_FailurePolicy {
+    REVERT_CHANGESET = "revert_changeset",
+    KEEP_AND_FLAG = "keep_and_flag"
+}
+/** @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 |
+ * | {@link MetaWorkflow_PredicateKind.ARTIFACT_DECIDES} | a landed family DECIDED a given value | READINESS — nobody proceeds |
+ * | {@link MetaWorkflow_PredicateKind.STEP_AVAILABLE} | a sibling in this choreography returned (a value) | READINESS — nobody proceeds |
+ */
+export declare enum 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.
+     */
+    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.
+     */
+    STEP_AVAILABLE = "step_available",
+    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.
+     */
+    ARTIFACT_EXPECTED = "artifact_expected",
+    /**
+     * A landed family DECIDED something, and decided it one given way (#1606): "run the website plan only
+     * when the capability composition says the website is NEEDED".
+     *
+     * The other artifact kinds ask whether a family exists, is valid or moved. None can ask what it SAID, so
+     * a playbook whose work an earlier decision declined still ran, only to land "not applicable".
+     *
+     * `decision` names a DECLARED decision of that family and `equals` one member of its vocabulary. The
+     * declarations live with the families, in `@wildo-ai/saas-specifications`
+     * (`APPLICATION_SPECIFICATION_FAMILY_DECISIONS`), whose playbook contract refuses a decision or a value
+     * they do not declare: a typo here would otherwise make a playbook ineligible forever with nothing
+     * reporting it. A playbook is application-agnostic, so a decision is keyed by a FRAMEWORK vocabulary
+     * (a scenario ref), never by an element one application authored.
+     *
+     * READINESS: a declined website is not an ordering question a person may proceed past. The way forward
+     * is to change what the family decided, which the unmet verdict names.
+     */
+    ARTIFACT_DECIDES = "artifact_decides"
+}
+/**
+ * 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 declare enum MetaWorkflow_ArtifactIntent {
+    /** Who the product is for. Market segments, personas, the jobs they are hiring it to do. */
+    AUDIENCE = "audience",
+    /** What it must deliver and why that matters. Benefits, the jobs they advance, pains, gains, requirements. */
+    VALUE = "value",
+    /** How it is described and sold. Positioning, tone, messaging, objections, pricing. */
+    VOICE = "voice",
+    /** Everything the family holds. The default, and the honest answer when no aspect serves the request. */
+    FULL = "full"
+}
+/**
+ * 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 declare enum MetaWorkflow_EvidenceAdequacyVerdict {
+    /** Enough to derive from. The dependant step may run. */
+    ADEQUATE = "adequate",
+    /** Not enough yet. `gaps` says what is missing, so the next research round is aimed rather than repeated. */
+    INSUFFICIENT = "insufficient"
+}
+export declare const MetaWorkflow_EvidenceAdequacySchema: z.ZodObject<{
+    verdict: z.ZodEnum<typeof MetaWorkflow_EvidenceAdequacyVerdict>;
+    gaps: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    rationale: z.ZodString;
+}, z.core.$strip>;
+export type MetaWorkflow_EvidenceAdequacy = z.infer<typeof MetaWorkflow_EvidenceAdequacySchema>;
+export declare const MetaWorkflow_ArtifactSelectorSchema: z.ZodObject<{
+    family: z.ZodString;
+    intent: z.ZodOptional<z.ZodEnum<typeof MetaWorkflow_ArtifactIntent>>;
+}, z.core.$strip>;
+export type MetaWorkflow_ArtifactSelector = z.infer<typeof MetaWorkflow_ArtifactSelectorSchema>;
+/**
+ * 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 declare const MetaWorkflow_ArtifactContractSchema: z.ZodObject<{
+    family: z.ZodString;
+    schemaRef: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type MetaWorkflow_ArtifactContract = z.infer<typeof MetaWorkflow_ArtifactContractSchema>;
+/**
+ * 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 declare const MetaWorkflow_StepOutputContractSchema: z.ZodObject<{
+    ref: z.ZodString;
+    schemaRef: z.ZodOptional<z.ZodString>;
+    condensation: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type MetaWorkflow_StepOutputContract = z.infer<typeof MetaWorkflow_StepOutputContractSchema>;
+/**
+ * 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 declare const MetaWorkflow_StepValueAssertionSchema: z.ZodObject<{
+    path: z.ZodString;
+    equals: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+}, z.core.$strip>;
+export type MetaWorkflow_StepValueAssertion = z.infer<typeof MetaWorkflow_StepValueAssertionSchema>;
+/**
+ * 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)).
+ */
+declare const _MetaWorkflow_JourneyPredicateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<MetaWorkflow_PredicateKind.ARTIFACT_EXISTS>;
+    selector: z.ZodObject<{
+        family: z.ZodString;
+        intent: z.ZodOptional<z.ZodEnum<typeof MetaWorkflow_ArtifactIntent>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<MetaWorkflow_PredicateKind.ARTIFACT_VALID>;
+    selector: z.ZodObject<{
+        family: z.ZodString;
+        intent: z.ZodOptional<z.ZodEnum<typeof MetaWorkflow_ArtifactIntent>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<MetaWorkflow_PredicateKind.ARTIFACT_EXPECTED>;
+    selector: z.ZodObject<{
+        family: z.ZodString;
+        intent: z.ZodOptional<z.ZodEnum<typeof MetaWorkflow_ArtifactIntent>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<MetaWorkflow_PredicateKind.ARTIFACT_STALE>;
+    selector: z.ZodObject<{
+        family: z.ZodString;
+        intent: z.ZodOptional<z.ZodEnum<typeof MetaWorkflow_ArtifactIntent>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<MetaWorkflow_PredicateKind.ARTIFACT_DECIDES>;
+    selector: z.ZodObject<{
+        family: z.ZodString;
+        intent: z.ZodOptional<z.ZodEnum<typeof MetaWorkflow_ArtifactIntent>>;
+    }, z.core.$strip>;
+    decision: z.ZodString;
+    equals: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<MetaWorkflow_PredicateKind.STEP_AVAILABLE>;
+    ref: z.ZodString;
+    requires: z.ZodOptional<z.ZodObject<{
+        path: z.ZodString;
+        equals: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    }, z.core.$strip>>;
+}, z.core.$strip>], "kind">;
+export declare const MetaWorkflow_JourneyPredicateSchema: typeof _MetaWorkflow_JourneyPredicateSchema;
+export type MetaWorkflow_JourneyPredicate = z.infer<typeof _MetaWorkflow_JourneyPredicateSchema>;
+export declare const MetaWorkflow_ElicitationSpecSchema: z.ZodObject<{
+    questions: z.ZodArray<z.ZodObject<{
+        ref: z.ZodString;
+        question: z.ZodString;
+        kind: z.ZodEnum<typeof HumanDecision_FieldKind>;
+        options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        sameDecisionAs: z.ZodOptional<z.ZodObject<{
+            playbookRef: z.ZodString;
+            questionRef: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type MetaWorkflow_ElicitationSpec = z.infer<typeof MetaWorkflow_ElicitationSpecSchema>;
+/**
+ * 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 declare const MetaWorkflow_PlaybookBudgetSchema: z.ZodObject<{
+    maxCostUsd: z.ZodOptional<z.ZodNumber>;
+    maxInputTokens: z.ZodOptional<z.ZodNumber>;
+    maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+    maxModelCalls: z.ZodOptional<z.ZodNumber>;
+    maxDurationMs: z.ZodOptional<z.ZodNumber>;
+    maxRuns: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type MetaWorkflow_PlaybookBudget = z.infer<typeof MetaWorkflow_PlaybookBudgetSchema>;
+/**
+ * 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 composite's LOOP-BACK: when an assessing child's verdict faults, children that already landed in
+ * this run are offered again.
+ *
+ * ## Why the runtime has to do this, and a revise child cannot
+ *
+ * Within one run a child that LANDED is delivered and never re-offered — landing it again from the
+ * same inputs is waste the fourth live run measured. So a gate's GAP on "requirement coverage" could
+ * reach the reader and route nothing: the leaf that must answer it had landed before the gate ran. A
+ * dedicated revise playbook was the other shape, and it was rejected: it restates the leaf's inputs,
+ * outputs and skills as a second description that drifts (one per criterion), or claims every family
+ * a gate can fault and re-derives all of them when one faulted. The criterion → leaf map already
+ * existed as a table in the lane's method, read by a person; this makes that table the mechanism.
+ *
+ * ## What a reopening does, exactly
+ *
+ * After the assessing child settles with a routable verdict, every reopening naming it whose verdict
+ * (the criterion's, or the overall one when no criterion is named) is in `verdicts` removes the
+ * `reopen` children from the run's delivered set. They are then eligible like any other child, and the
+ * selector sees why. It re-offers; it never forces a dispatch, and it deletes no artifact. A PASS
+ * re-opens nothing, so a lane that passes ends as it did before.
+ *
+ * ## Across lanes — `via`
+ *
+ * A verdict raised INSIDE a nested lane stays in that lane's scope unless the lane exports it: a lane
+ * that lists the derived ref `judge:<leaf>` in its own `stepOutputs` returns that verdict to its parent
+ * like any exported value. The parent then declares the reopening with `via: <that lane>`, and may
+ * re-open a SIBLING lane. What the sibling re-runs is not forced from here: the round history tells
+ * its selector which verdict re-opened it and on which criterion, and its own selection picks the leaf
+ * (#1627). Code gates the kind of work; the model composes the task, as everywhere else in a composite.
+ *
+ * Refs must be admitted by the same composite (`whenVerdictOf` only when there is no `via`), refused
+ * at parse rather than discovered as a loop-back that silently never fires. A child may re-open ITSELF: a leaf that lands and is judged (the business
+ * model is both) is re-offered on its own GAP, which is the plainest loop-back there is.
+ */
+export declare const MetaWorkflow_ChoreographyReopeningSchema: z.ZodObject<{
+    /** The ASSESSING playbook whose verdict decides, e.g. `top_down.phase-gate` — admitted here, or inside `via`. */
+    whenVerdictOf: z.ZodString;
+    /** The admitted LANE through which that verdict arrives, when the assessing playbook is inside it. */
+    via: z.ZodOptional<z.ZodString>;
+    /** One criterion's verdict, e.g. `application-creation:criterion/requirement-coverage`. Absent: the overall verdict. */
+    criterionRef: z.ZodOptional<z.ZodString>;
+    /** The verdicts that re-open — usually `[GAP]`. */
+    verdicts: z.ZodArray<z.ZodEnum<typeof MetaWorkflow_EvaluationVerdict>>;
+    /** The admitted children offered again, e.g. `['top_down.scope-roadmap']`. */
+    reopen: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type MetaWorkflow_ChoreographyReopening = z.infer<typeof MetaWorkflow_ChoreographyReopeningSchema>;
+/**
+ * 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 declare const MetaWorkflow_ChoreographySchema: z.ZodObject<{
+    admits: z.ZodArray<z.ZodString>;
+    maximumIterations: z.ZodDefault<z.ZodNumber>;
+    maximumLanesPerIteration: z.ZodDefault<z.ZodNumber>;
+    maximumDepth: z.ZodDefault<z.ZodNumber>;
+    maximumDurationMs: z.ZodDefault<z.ZodNumber>;
+    reopenOnVerdict: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        /** The ASSESSING playbook whose verdict decides, e.g. `top_down.phase-gate` — admitted here, or inside `via`. */
+        whenVerdictOf: z.ZodString;
+        /** The admitted LANE through which that verdict arrives, when the assessing playbook is inside it. */
+        via: z.ZodOptional<z.ZodString>;
+        /** One criterion's verdict, e.g. `application-creation:criterion/requirement-coverage`. Absent: the overall verdict. */
+        criterionRef: z.ZodOptional<z.ZodString>;
+        /** The verdicts that re-open — usually `[GAP]`. */
+        verdicts: z.ZodArray<z.ZodEnum<typeof MetaWorkflow_EvaluationVerdict>>;
+        /** The admitted children offered again, e.g. `['top_down.scope-roadmap']`. */
+        reopen: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>>;
+    actsOnApplication: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type MetaWorkflow_Choreography = z.infer<typeof MetaWorkflow_ChoreographySchema>;
+/**
+ * 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 declare const MetaWorkflow_PlaybookDeliberationSchema: z.ZodObject<{
+    workDomain: z.ZodEnum<typeof ExpertWorkDomain>;
+    reviewerRoleRefs: z.ZodArray<z.ZodString>;
+    coordinatorRoleRef: z.ZodString;
+    rubricDeriverRoleRef: z.ZodOptional<z.ZodString>;
+    candidateCount: z.ZodDefault<z.ZodNumber>;
+    roundBudget: z.ZodOptional<z.ZodNumber>;
+    shortlistSize: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type MetaWorkflow_PlaybookDeliberation = z.infer<typeof MetaWorkflow_PlaybookDeliberationSchema>;
+export {};
+//# sourceMappingURL=orchestration.meta-workflows.shared.schemas.d.ts.map

package/dist/esm/meta-workflows/orchestration.meta-workflows.shared.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestration.meta-workflows.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/meta-workflows/orchestration.meta-workflows.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,MAAM,6CAA6C,CAAC;AAC/E,OAAO,EAAE,uBAAuB,EAAE,MAAM,+CAA+C,CAAC;AACxF,OAAO,EAAE,8BAA8B,EAAE,MAAM,2CAA2C,CAAC;AAE3F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,oBAAY,qBAAqB;IAC/B,eAAe,oBAAoB;IACnC,YAAY,iBAAiB;IAC7B;;;;;;;;;;OAUG;IACH,cAAc,mBAAmB;IACjC,KAAK,UAAU;IACf,iBAAiB,sBAAsB;CACxC;AAED,0IAA0I;AAC1I;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,oBAAY,2BAA2B;IACrC,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,cAAc,mBAAmB;IACjC,cAAc,mBAAmB;CAClC;AAED;;;;GAIG;AACH;;;;;;;;;;;GAWG;AACH,oBAAY,0BAA0B;IACpC,gBAAgB,qBAAqB;IACrC,aAAa,kBAAkB;CAChC;AACD,wFAAwF;AAExF;;;;;;;;;;;;;;;GAeG;AACH,oBAAY,0BAA0B;IACpC,eAAe,oBAAoB;IACnC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,cAAc,mBAAmB;IACjC;;;;;;;;OAQG;IACH,cAAc,mBAAmB;IACjC,cAAc,mBAAmB;IACjC;;;;;;;;;;;;OAYG;IACH,iBAAiB,sBAAsB;IACvC;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,qBAAqB;CACtC;AAED;;;;;;;;;;GAUG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,oBAAY,2BAA2B;IACrC,4FAA4F;IAC5F,QAAQ,aAAa;IACrB,8GAA8G;IAC9G,KAAK,UAAU;IACf,uFAAuF;IACvF,KAAK,UAAU;IAOf,yGAAyG;IACzG,IAAI,SAAS;CACd;AAED;;;;;;;;;;;GAWG;AACH,oBAAY,oCAAoC;IAC9C,yDAAyD;IACzD,QAAQ,aAAa;IACrB,6GAA6G;IAC7G,YAAY,iBAAiB;CAC9B;AAED,eAAO,MAAM,mCAAmC;;;;iBAY9C,CAAC;AACH,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mCAAmC,CAAC,CAAC;AAEhG,eAAO,MAAM,mCAAmC;;;iBAoB9C,CAAC;AACH,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mCAAmC,CAAC,CAAC;AAEhG;;;;;;;;;GASG;AACH,eAAO,MAAM,mCAAmC;;;;iBAO9C,CAAC;AACH,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mCAAmC,CAAC,CAAC;AAEhG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,qCAAqC;;;;;iBAWhD,CAAC;AACH,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qCAAqC,CAAC,CAAC;AAEpG;;;;;;;GAOG;AACH,eAAO,MAAM,qCAAqC;;;iBAKhD,CAAC;AACH,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qCAAqC,CAAC,CAAC;AAEpG;;;;;;;GAOG;AACH,QAAA,MAAM,oCAAoC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BA0CxC,CAAC;AACH,eAAO,MAAM,mCAAmC,EAAE,OAAO,oCACnB,CAAC;AACvC,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oCAAoC,CAAC,CAAC;AAEjG,eAAO,MAAM,kCAAkC;;;;;;;;;;;iBA2B7C,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAE9F;;;;;;;;;GASG;AACH,eAAO,MAAM,iCAAiC;;;;;;;iBAU5C,CAAC;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAE5F;;;;;;;;;;;;;GAaG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,wCAAwC;IACnD,iHAAiH;;IAEjH,sGAAsG;;IAEtG,wHAAwH;;IAExH,mDAAmD;;IAEnD,8EAA8E;;kBAE9E,CAAC;AACH,MAAM,MAAM,kCAAkC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wCAAwC,CAAC,CAAC;AAE1G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,+BAA+B;;;;;;;QA5C1C,iHAAiH;;QAEjH,sGAAsG;;QAEtG,wHAAwH;;QAExH,mDAAmD;;QAEnD,8EAA8E;;;;iBA4G9E,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF;;;;;;;;GAQG;AACH,eAAO,MAAM,uCAAuC;;;;;;;;iBAoBlD,CAAC;AACH,MAAM,MAAM,iCAAiC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uCAAuC,CAAC,CAAC"}