| name | operation-authoring-and-diagnostics |
| description | Read this before safely changing operation YAML, project workflow authoring paths, source-aware operationRef handling, facet source resolution, output contracts, output placeholders, or workflow-related tests. |
Operation Authoring And Diagnostics
Purpose
This document organizes the authoring rules and diagnostic viewpoints needed to safely change builtin or project-authored operations and facets in this repository.
Refer to it when changing operation YAML, facet files, output contracts, placeholder behavior, or workflow-related tests.
Change Surfaces
- Changes to step ownership, rules, or source objects in operation YAML
- Changes to facet file contents or paths
- Changes to output contracts or placeholder references
- Changes that affect the source-aware catalog, operation selector, or operation-debug filter
- Changes that affect the prompt builder, composer, or report routing
- Changes to workflow-related tests
Runtime-Relevant Authoring Rules
The schema fields you should review most often are:
initial_step
steps[]
steps[].job
steps[].instruction
steps[].skills
steps[].policies
steps[].delegation.allowed_workers
steps[].delegation.worker_job
steps[].delegation.worker_instruction
steps[].delegation.worker_skills
steps[].delegation.worker_policies
steps[].output_contracts.report[].format
steps[].rules[]
The semantic roles of those fields differ as follows:
job: the stable role, responsibility, decision principles, and prohibitions for the step
instruction: the step-specific execution procedure and references
skills: background skills or reference material required to execute the current step
policies: constraints and conventions that the current step must follow
delegation.*: the allowed targets and prompt material used when a Noctis-owned step delegates a child task to a worker
output_contracts.report[].format: the format definition for report artifacts
Canonical source forms are:
job.file / job.inline
instruction.file / instruction.inline
skills[].file
policies[].file / policies[].inline
output_contracts.report[].format.file / output_contracts.report[].format.inline
Canonical authored locations and identity are:
- builtin workflow:
builtins/<lang>/operations/*.yaml
- project workflow:
projects/<project-id>/operations/*.yaml
- builtin facets:
builtins/<lang>/facets/**
- project facets:
projects/<project-id>/facets/**
- canonical identity:
operationRef (builtin:<lang>:<fileName> or project:<projectId>:<fileName>)
The following constraints often map directly to runtime failure, so check them early in design:
initial_step should point to a noctis step
- List-based facets preserve authored order
file sources resolve relative to the operation YAML path
- Even when same-name workflows exist across builtin and project sources, selector and debug preview must not collapse them
- Auto activation from a message body succeeds only when the catalog match is unambiguous
- Runtime state, the Noctis Team selector, and operation-debug preview use
operationRef as the canonical key, not plain operation name
output_contracts.report[].format must stay consistent with the output filename and any downstream references
steps[].delegation.allowed_workers is the authored upper bound, while the runtime effective set is the intersection with the mission's allowed worker set
rules may be omitted only for an autonomous delegation step where Noctis remains on the same parent step
Legacy fields such as initial_movement, movements, max_movements, edit, handoff_mode, job_file, and knowledge_files are not canonical.
When changing prompts, always inspect both the operation YAML and the referenced facet files together.