GnOuGo.Flow.Planning 0.20.0

GnOuGo.Flow.Planning

A separately publishable package depending only on Flow.Core.

Requirements → progressive discovery → LLM TaskPlan → deterministic compilation → PlanningGraph → YAML → validation → scoped TaskPlan repair → approval

Requirements are generated once, then host-owned until explicit user revision. Discovery and repair responses omit them. Historical responses use the original persisted schema and cannot change accepted requirements.

TaskPlan is editable business intent. PlanningGraph is the sole executable representation. HybridWorkflowPlanner uses one bounded discovery/planning/repair loop; resolving selected operations and compiling them do not call a model. Static validation and simulations do not establish external success.

Tasks declare stable IDs, objectives, operation IDs, named business bindings and dependencies. Sequence is the default; concurrency requires a parallel scope or parallel iteration. Conditional alternatives declare matching business outputs. Reusable groups declare their inputs and outputs. Iteration has finite item and concurrency ceilings, preserves order and duplicates, and validates the collection bound before dispatch. Each scope can own always tasks.

Task, group and choice declarations share one case-sensitive namespace throughout the TaskPlan, including nested scopes and reusable-group definitions. Their IDs and references use only nonempty ASCII letters, digits, underscores or hyphens, excluding the reserved __ prefix. Repeated calls do not redeclare a group. Alternative IDs remain local to each choice; business ports, operation IDs and requirement IDs are outside this namespace. Invalid declarations fail closed without normalization, automatic renaming or broader repair permissions. Existing malformed consumer references can be corrected only in their diagnosed binding slots. Recovered plans and approval verification use the same identity rules; regenerate a saved plan with invalid declarations.

TaskPlanCompiler owns executor selection, stable generated IDs, request envelopes, references, declared branch merges, collection projections, explicitly supplied literal defaults and cleanup guards. Transient symbol tables and source maps are not another persisted plan. Compilation diagnostics address business tasks and ports. Generated executor validation failures stop as compiler diagnostics; the model is never asked to repair generated plumbing.

ICapabilityCatalog exposes source summaries, paginated versioned operation summaries and exact contracts. Ordinary business ports come directly from authoritative schemas. Injected catalogs may supply PlanningOperation mappings to exact schema fields; mappings never come from names, descriptions or examples. Registered executors explicitly opt into planning through StepContract.PlanningEffectKind. Selected contracts resolve automatically and are revalidated before approval and execution. Discovery pages and resolved receipts survive repair; unavailable unrelated sources remain visible limitations.

value copies or assembles data; transform interprets named inputs using its objective and a declared resultType. Results must be nonempty closed objects with fully typed required fields, explicit nullable values, and no defaults or opaque types. The compiler emits fixed template.render prompt assembly and strict structured llm.call, using existing runtime configuration and budgets. The model never supplies templates, model settings or executor envelopes. Transform repairs edit diagnosed bindings or exact type slots without renaming business fields; replacing a value task requires explicit revision/regeneration.

String business types may include enum: ["allow", "deny"] (1–256 distinct strings). Omitting it preserves the unrestricted string contract; nullable remains independent. Generated structured results enforce these constraints before downstream calls. Diagnostics report the produced and required types and, when unambiguous, the exact producer enum/nullability slots implicated by its consumer. Objectives describing a decision never establish its finite domain. The final YAML validator recognizes runtime-checked structured results while rejecting unknown domains, optional/nullable selectors and unsafe error fallbacks.

Compact discovery entries expose declared enum/const constraints without full schemas. Resolved operation inputs constrain scalar literals in newly issued response schemas; typed references retain semantic compatibility checks. Index-only selections still resolve exact contracts before compilation. Identical schema fragments are shared without changing TaskPlan values. Successful discovery batches clear only their resolved response errors, preserving other findings, history and cumulative counters. See enum generation and repair evidence.

Catalog FixedInput and RequestBindings remain host-owned. Editable operation ports exclude their decoded paths; partial object assembly may supply unrelated fields. Explicit assignments (even equal values) and opaque ancestor bindings are rejected before lowering. The compiler injects the declared values, then existing graph/runtime checks validate the complete effective request. Resolved operation variants constrain input names; index-only selections receive the same ownership checks after exact resolution. Historical discovery receipts and pending schemas are unchanged. See catalog-owned binding evidence.

Declared artifact metadata is retained in versioned capability summaries and presented as business ports and kinds in both compact indexes and exact contracts. Semantic preflight checks consumer bindings against the declared producer origin, including explicit scope exports and captures; matching strings or types are insufficient. Checked value.project, array.project and identity validation preserve origin, with every possible projection path checked. Graph validation remains independent. Unconstrained capability results use the existing opaque schema representation when forwarded; they grant no typed field access. A resolved plan with no declared producer of a required kind stops as TASK_ARTIFACT_PREREQUISITE_MISSING before another binding repair; an explicit semantic revision is required. Unknown/ambiguous contracts do not prove absence, and optional bindings remain removable under their contracts. See prerequisite discovery and repair evidence and artifact provenance regression evidence.

A repair may explicitly omit a diagnosed optional operation argument when its exact contract permits omission. Null is not omission. All remaining bindings keep their values and relative ordering; required arguments, unrelated inputs and producer fields remain fixed. A diagnosed catalog-owned binding permits removal only, preserving unrelated members. Full request validation still enforces conditional requiredness. Producer-constraint findings expose only incompatible enum/nullability leaves, never automatic narrowing or invented values. See the retained optional-input repair regression.

{ "kind": "field", "items": [{ "kind": "item" }], "port": "message" } selects the declared message field of the current typed loop record. The same value works on typed inputs and business outputs; nested field values select nested objects. port is an exact field name, never a dotted/wire path. The compiler checks the authoritative object/field contracts and lowers the complete selection to the existing checked value.project at consumption. Missing fields fail, null remains subject to the declared type, and opaque objects cannot supply fields. No transform, coercion, fallback or extra inference is involved. Selection preserves the exact nested transform type location through iteration and captures, so an incompatible enum diagnoses only that producer slot and its consumer binding. Existing repair scopes do not authorize task insertion or unrelated changes.

{ "kind": "json", "items": [<business value>] } deterministically encodes one value as JSON text. The compiler materializes the value with existing typed set stages and invokes the existing json runtime function on that direct reference. It adds no inference, executor type or arbitrary expression syntax to TaskPlan. Encoding never grants access to undeclared fields of opaque outputs and is not a literal agent scope or choice alternative.

Discovery proposals use discoveryRequests: one to four page/query or exact-contract inspection requests, exclusive with a TaskPlan. An operationIds list selects already-discovered operations from its source, with cursor and query null; it replaces that source’s inspection selection, and an empty list clears it. Ordinary pagination preserves selections. This uses the same call allowance and grants no execution permission. The complete batch is validated before sequential metadata reads. Recovery reuses the recorded model response and identity. Superseded pending singular-source requests fail closed with a regeneration instruction and retained accounting. Contract fetching is deterministic; inspection selections use existing discovery responses, not an added model phase.

An optional producedArtifactKind on catalog paging and discovery requests filters the complete selected-source metadata by exact declared kind before pagination. New generation requests may automatically read at most one first filtered page per already-inspected source on each advance for uncovered prerequisites; empty/unavailable results are cached, and expansion to newly found dependencies waits for a later advance. No read contacts an uninspected source. Matching search results have priority over unrelated optional contracts within the existing token allowance; they do not select executable operations. Filter/query/snapshot-specific cursors support ordinary bounded continuation and refinement. Pending requests retain their original schemas and metadata effects.

Selected sources are indexed from their complete tool listing before paging. Case/accent/identifier-normalized token overlap uses inverse document frequency (names ×3, declared field names ×2, descriptions ×1), with capability-ID ties. This ranking establishes no contract or permission. Catalog pages contain eight candidates; new prompts present a bounded directory of retained identities/port names and a token-budgeted global shortlist, plus TaskPlan-required and explicitly inspected contracts. Global ranking uses shared inverse document frequency over all retained discovered candidates, with no source quotas. Earlier-page candidates remain visible in the retained directory when space permits. The directory is budgeted against mandatory context before optional contracts; omitted entries are counted. Detailed contracts do not duplicate their index summaries. Closed discovery omits unusable source descriptions, queries and continuations. Conflicting versions cannot be automatically shortlisted or reused as an unambiguous selection. Query text defaults to the user request plus accepted requirements; a non-null query refines the search. The user request and accepted requirements always remain the global base. Each source adds only its own latest effective receipt query; overlapping terms count once. The historical batch query is retained for recovery but cannot replace the ranking base. Use a null query with continuation cursors, which bind to the effective query and metadata snapshot. Continuation eventually visits every tool; low relevance never means unsupported.

Full metadata and resolved contracts remain in session state. Prompts show coverage, the retained compact directory, exact active-shortlist contracts and contracts required by inspections or the current TaskPlan/revision baseline. Historical full pages are not repeated. Directory entries carry identities, names and business-port names; ranking still uses full metadata text. Optional candidates are admitted in relevance order only while the complete request, including its response schema, fits 90% of the saved input allowance (21,600 at 24,000). Oversized or unavailable optional contracts are skipped so smaller candidates can use the remaining space; omitted operations remain discoverable and selectable. Required contracts are never pruned; oversized mandatory context still stops admission. For fresh responses, shortlist resolution completes before the discovery checkpoint so new per-advance host adapters can reuse receipts. Recovering an issued response preserves its schema and discovery effects; optional presentation is recomputed before the next new request. Unselected resolved candidates never enter the executable catalog. Fixed-operation repairs omit unusable discovery indexes, alternatives and source descriptions, retaining coverage limitations and all required contracts. Pending requests retain their original prompts, schemas, numeric cursors where applicable, identities and budgets.

Earlier deterministic discovery measurements compare the frozen coding/review requests; no live output-size or reliability claim is made.

New requests reserve one proposal call and one repair when repair allowance remains: with eight calls and two repairs, at most six calls may request discovery before the first TaskPlan. The repair limit is a maximum; earlier proposals may use both repairs if calls remain. Explicit zero-repair settings and smaller call ceilings remain authoritative. Repairs cannot use their final attempt for discovery. The issued schema closes discoveryRequests to null; it then permits plan: null as a terminal DISCOVERY_INCOMPLETE outcome. Returning discovery against that restriction stops with DISCOVERY_NOT_ALLOWED, without another metadata fetch or automatic repair. Historical schemas retain their original interpretation. No call ceiling or accounting is reset. See the retained exhaustion regression.

Explicit string literals retain their const contract through named values and scope captures. Runtime inputs (including inputs with defaults) and transform results keep their declared types. Producer-supplied patterns and string bounds are checked by the existing generic validators and appear in input diagnostics; Flow does not interpret tool names or filesystem rules. Declare a fixed resource location once and reuse its business binding for creation and cleanup, including partial failure. This guidance does not prove resource ownership or automatically reconcile independent paths.

Generation requests concise objectives and only necessary inputs/outputs, direct bindings and consumable intermediate data shapes. value is assembly; transform is interpretation/conversion, never an adapter for simple wiring. No post-generation task rewriting is performed. The strict wire schema omits unused type fields, fixed transform-field declarations, host-owned choice selections and unused explanation. New wire schemas also omit nullable: false, required: true and absent default: null. Existing DTO defaults restore these representation constants only; nullable: true, optionality, array item types and actual defaults remain explicit. Every optional workflow/group input still requires a literal default. Representation compaction preserves TaskPlan semantics and planning storage format 10.

Values allow literals, named business references, declared field selection, deterministic JSON encoding and closed typed predicates. An output reference uses a task ID and business port; a null port selects its whole business result. Opaque results have no typed fields. Null-only contracts lower through Flow's existing schema-backed port representation: the complete JSON Schema remains authoritative, including recursively nested nulls. No unsupported shorthand type: null or unconstrained fallback is emitted. Presence tests only whether a task produced a non-null result; it proves neither payload shape nor external success. JavaScript, executor types, wire paths, projection recipes and schema pointers are absent from the model response contract. Authored YAML retains the existing runtime language.

Generated agent stages require literal objective, nonempty workspace, capabilities, budgets, output contract and verification requirements. Agent workspace bindings may reuse available semantic value constants, including literal object assembly and field selection. Compilation emits a literal before approval; it does not establish filesystem existence. Runtime inputs, transforms, operations, choices and loop-derived values remain forbidden scope sources. Other scope fields remain literal. See workspace and producer contract migration. A business choice cannot select these scope fields. The injected runner still enforces paths, permissions, filesystem and inference policy.

PlanningChoice binds exactly one business value slot. It declares typed literal alternatives, a recommended ID and a host-owned selected ID. Interactive mode presents alternatives; auto mode validates and records the recommendation without another model call. Selection recompiles locally. Choices never approve execution or replace runtime confirmation.

The model schema restricts alternatives recursively to literals, requires at least two alternatives or parallel branches, and requires nonblank questions/objectives. It expresses item ceilings of 1–10,000, concurrency ceilings of 1–100, predicate arity (one for not, two otherwise), and array item types. Identity patterns use explicit ASCII alternatives and ordinary anchors without lookaround or engine-specific escapes. Tests cover JavaScript Unicode regex syntax and .NET; the compiler independently enforces exact lexical checks, including trailing line breaks where regex anchors differ. Semantic validation still enforces identity uniqueness, reference visibility, typed contracts and recommendation membership.

Permanent typed model-provider rejections produce MODEL_REQUEST_REJECTED with safe classification/status/code metadata, never a raw provider body. The Agent host blocks unchanged retries of these requests. After correcting the request/configuration, create a new planning session; retained requests and cumulative accounting are not reset. Unknown transport outcomes keep their existing recovery rules.

MODEL_INPUT_LIMIT instead stops locally before dispatch when the conservative full-prompt plus response-schema estimate exceeds the saved input allowance. No additional call or repair is consumed. Standalone Flow defaults to 12,000 input / 8,192 output tokens per request; new Agent.Server Designer sessions default to 24,000 input / 32,768 output, subject to explicit host overrides. Existing sessions keep saved limits, shown directly by Designer. Output budgets can include reasoning; serialization headroom does not guarantee generation completion. A revision-checked configure_generation command can resume a stopped session with no pending request and remaining call allowance, retaining discovery and cumulative budgets. Token-only changes and revisions cannot restart a call-exhausted session; Designer displays calls used / ceiling and directs the user to a new session. No automatic limit escalation, authoritative-contract truncation or model retry is performed; later calls still require budget admission.

Compiler preflight validates TaskPlan identities, scopes, business ports and contracts before emitting graph nodes. It collects independent diagnostics, including every invalid cross-scope consumer and required export boundary; unavailable prerequisite contracts suppress cascading errors. Children can capture available ancestor values. Parents consume explicitly declared exports, and parallel siblings cannot directly consume each other. The compiler never invents exports or fallback values.

Repairs edit diagnosed business slots and the explicit export chains needed by their consumers. Conditional counterparts require explicit values. Revalidating dependent tasks does not authorize changing them; unknown locations never expand the scope to the whole plan. Unrelated tasks, interfaces, choices, ordering and compiled stages remain fixed. Rejected repairs retain their immutable baseline. Discovery, retries and revisions share cumulative budgets. Defaults remain eight model calls and two repairs. Approval hashes intent, choices, mappings, exact contracts, graph/YAML and ceilings. Approval verification recompiles and requires the reviewed artifact to match exactly.

Initial generation returns a full TaskPlan. Newly issued semantic repairs return a private RepairPatch: typed host-issued slots derived from the immutable baseline and existing revision scope. Each slot permits only its declared replace/add/remove action; null is never removal. Local binding, constraint, dependency and export edits cannot insert, delete, rename or reorder tasks. The host applies edits to a clone, checks the existing revision permissions, then recompiles and validates the entire plan. Unknown/duplicate/conflicting slots and unauthorized changes fail atomically; empty or unchanged patches stop without progress.

Repair prompts contain affected task fragments, immutable objectives, relevant contracts and necessary scope/dependency context. Read-only producers contribute exact output contracts, not their creation arguments. The complete baseline and discovery journal remain host-owned. Binding-only repairs omit discovery navigation; operation-changing repairs retain the existing bounded discovery action. The saved request binds its slots to baseline/scope/contract/policy fingerprints. Recovery uses that original schema and identity without rebasing; historical full-plan responses remain valid only for requests originally issued with that schema. Budgets and hard admission checks are unchanged. See bounded patch evidence.

Optional workflow and group inputs require literal defaults; optional fields inside an object do not. Independent input errors are reported together, with group-qualified locations. Discovery responses select uncached query pages or refine an inspected source with more candidates; small completed sources may still be refined when their tools fall outside the global shortlist; empty or unavailable sources offer no continuation. Composite scope outputs are assembled by typed set stages after cleanup, preserving their nested contracts. Successful value.project and array.project stages provide non-null result envelopes for guarded export assembly, including when their checked payload is nullable. Failed, skipped, cyclic or unsafe continued producers do not establish availability. Repair rejections identify the changed business slots without accepting the rejected proposal as a new baseline. Presence sources remain exact task IDs, not dotted payload addresses.

Planning storage format 10 rejects prior planning sessions and approvals without modifying their encrypted records. Execution journal schema 9 is unchanged. AI revision requires a saved TaskPlan or fresh requirements and renewed approval; YAML import into the planner has been removed.

Consuming an optional operation port emits a checked value.project at the consumer. The full authoritative container crosses scope boundaries; the check stays inside the consuming branch, iteration or cleanup. Missing fields fail, nullable values remain nullable, and unused ports need no projection. Optional-port checks require no fallback or model call; explicit nested business-field selection uses the field value described above.

dotnet build src/GnOuGo.Flow.Planning -c Release -warnaserror
dotnet test tests/GnOuGo.Flow.Planning.Tests -c Release -warnaserror
dotnet run --project tests/GnOuGo.Flow.Planning.Smoke -c Release
dotnet pack src/GnOuGo.Flow.Planning -c Release

The eight frozen business requests and independent execution oracles remain in tests/Shared/PlanningBenchmarkCases.cs. Small synthetic fixtures keep planner/AOT tests independent. Host product-query tests replay unchanged historical model responses against saved request schemas with actual Browser/Document registrations and real XLSX writing. A separately labelled synthetic compact response tests serialization headroom and the same independent business outcomes using direct query binding and scalar URL iteration. Neither fixture is supplied to live planning; synthetic results are not model reliability evidence. See the contract diagnosis and replay limitations. Historical cohort evidence remains 8/9, without a new reliability claim. Real Copilot command edit/test execution remains unverified under the available sandbox policy; do not bypass it. See architecture and migration.

Repository agents must use $gnougo-planning, the portable planning skill, as required by the root AGENTS.md.

See the typed record-field diagnosis and deterministic replay for the retained review failure, corrected binding contract and execution limitations.

Explicitly requested inspection contracts are never silently pruned. Unknown, ambiguous, cross-source or policy-excluded IDs invalidate the whole batch before fetching. An unavailable requested contract stops with DISCOVERY_CONTRACT_UNAVAILABLE; mandatory context exceeding the saved ceiling stops through MODEL_INPUT_LIMIT. Pending requests keep their original schemas and identities. See targeted discovery evidence for retained failures, deterministic results and Designer inspection.