From 7c962332ccdff3fbbbbf3cfddfb44aca4c88e6db Mon Sep 17 00:00:00 2001 From: Trecek Date: Sat, 24 Oct 2026 08:32:23 -0700 Subject: [PATCH 01/14] fix: make finalized YAML keys the recipe step identity --- docs/recipes/composition.md | 2 + .../core/_tool_registry_builders.py | 10 +- src/autoskillit/core/tool_registry.py | 7 +- .../core/types/recipe/_type_recipe_binding.py | 19 +- .../migrations/0.10.1288-to-0.10.1289.yaml | 28 +++ .../_api_orchestration_validate.py | 13 +- .../recipe/ingredients/_recipe_composition.py | 21 ++ .../recipe/ingredients/_recipe_merge.py | 6 +- src/autoskillit/recipe/rules/rules_tools.py | 36 ++++ .../recipes/diagrams/implementation-groups.md | 2 +- .../recipes/diagrams/implementation.md | 2 +- src/autoskillit/recipes/diagrams/merge-prs.md | 2 +- .../recipes/diagrams/remediation.md | 2 +- .../recipes/implementation-groups.json | 10 +- .../recipes/implementation-groups.yaml | 10 +- src/autoskillit/recipes/implementation.json | 10 +- src/autoskillit/recipes/implementation.yaml | 10 +- src/autoskillit/recipes/merge-prs.json | 2 +- src/autoskillit/recipes/merge-prs.yaml | 2 +- src/autoskillit/recipes/remediation.json | 10 +- src/autoskillit/recipes/remediation.yaml | 10 +- .../recipes/research-implement.json | 6 +- .../recipes/research-implement.yaml | 6 +- .../tools_execution/_run_skill_dispatch.py | 8 +- src/autoskillit/server/tools/tools_github.py | 2 +- src/autoskillit/skills/sous-chef/SKILL.md | 21 +- .../skills_extended/write-recipe/SKILL.md | 2 +- tests/cli/test_food_truck_prompt.py | 14 ++ .../contracts/test_run_skill_kwarg_ledger.py | 2 +- .../test_sous_chef_parameter_forwarding.py | 13 ++ tests/contracts/test_tool_param_roles.py | 57 +++++ tests/infra/test_pretty_output_recipe.py | 6 +- tests/recipe/test_anti_pattern_guards.py | 33 +++ .../recipe/test_composition_step_identity.py | 94 +++++++++ tests/recipe/test_rules_step_identity.py | 195 ++++++++++++++++++ .../test_attestation_delivery_reachability.py | 13 ++ tests/server/test_run_skill_docstring.py | 6 + 37 files changed, 614 insertions(+), 78 deletions(-) create mode 100644 src/autoskillit/migrations/0.10.1288-to-0.10.1289.yaml create mode 100644 tests/recipe/test_composition_step_identity.py create mode 100644 tests/recipe/test_rules_step_identity.py diff --git a/docs/recipes/composition.md b/docs/recipes/composition.md index e8867bab9e..cf537c50b3 100644 --- a/docs/recipes/composition.md +++ b/docs/recipes/composition.md @@ -43,6 +43,8 @@ declared `on_success` continuation. When the gate ingredient is `"true"`, the sub-recipe's steps are **merged inline** at the attachment point, with step names prefixed to avoid collisions. The sub-recipe's kitchen rules are merged with the parent's kitchen rules. +When names are prefixed, a composed step's key and its `with.step_name` are prefixed +together. Incoming routes and the ordered entry attachment target the first prefixed child step. This gate rewrite is separate from optional-step pruning and does not use `on_skip` as a runtime event. diff --git a/src/autoskillit/core/_tool_registry_builders.py b/src/autoskillit/core/_tool_registry_builders.py index 0a289af0a4..f3ae10d06b 100644 --- a/src/autoskillit/core/_tool_registry_builders.py +++ b/src/autoskillit/core/_tool_registry_builders.py @@ -200,7 +200,12 @@ def _tool( param, wire_type=declared_wire_types.get(param, ToolWireType.SCALAR), required=param in required_set, - role=declared_roles.get(param, ToolParamRole.CHILD_INPUT), + role=declared_roles.get( + param, + ToolParamRole.STEP_IDENTITY + if param == "step_name" + else ToolParamRole.CHILD_INPUT, + ), ) for param in params ), @@ -301,7 +306,6 @@ def _verify_review_receipt() -> ToolDef: "post_state": ToolWireType.STRING, "step_name": ToolWireType.STRING, }, - roles={"step_name": ToolParamRole.PROTOCOL}, recovery_recipe_delivery=True, ) @@ -315,7 +319,7 @@ def _verify_review_receipt() -> ToolDef: "skill_command": ToolParamRole.CHILD_INPUT, "cwd": ToolParamRole.CHILD_INPUT, "model": ToolParamRole.EXECUTION_TUNING, - "step_name": ToolParamRole.PROTOCOL, + "step_name": ToolParamRole.STEP_IDENTITY, "recipe_execution_id": ToolParamRole.PROTOCOL, "invocation_template_digest": ToolParamRole.PROTOCOL, "step_provider": ToolParamRole.EXECUTION_TUNING, diff --git a/src/autoskillit/core/tool_registry.py b/src/autoskillit/core/tool_registry.py index 286ed65488..5a0bf890b3 100644 --- a/src/autoskillit/core/tool_registry.py +++ b/src/autoskillit/core/tool_registry.py @@ -512,7 +512,12 @@ def food_truck_visibility_tags(packs: Collection[str] | None) -> tuple[str, ...] wire_types={"offset": ToolWireType.INTEGER, "page_size": ToolWireType.INTEGER}, ), _tool("reload_session"), - _tool("record_pipeline_step", ("pipeline_id", "op", "dependencies", "step_name")), + # step_name identifies the tracked target step being marked. + _tool( + "record_pipeline_step", + ("pipeline_id", "op", "dependencies", "step_name"), + roles={"step_name": ToolParamRole.CHILD_INPUT}, + ), _tool("get_pr_reviews", ("pr_number", "cwd", "repo"), required=("pr_number", "cwd")), _verify_review_receipt(), _tool( diff --git a/src/autoskillit/core/types/recipe/_type_recipe_binding.py b/src/autoskillit/core/types/recipe/_type_recipe_binding.py index 988e1249ef..2c2ec0f4bf 100644 --- a/src/autoskillit/core/types/recipe/_type_recipe_binding.py +++ b/src/autoskillit/core/types/recipe/_type_recipe_binding.py @@ -90,20 +90,16 @@ class ToolInitializationOperation(StrEnum): class ToolParamRole(StrEnum): - """The classification authority for what a tool parameter is for. - - The runtime gate's always-admit set and ``RecipeStep`` execution-tuning - fallback obligations derive from this field; kwarg membership comes - from ``ToolDef.mcp_kwarg_names``. The - per-role runtime-admission *policy* is declared once, alongside this - enum, in ``RUNTIME_ADMISSION_BY_ROLE`` — see ``runtime_exempt_param_names`` - (core/tool_registry.py) and ``bind_runtime_skill_invocation`` - (recipe/_binding.py) for its consumers. + """Parameter purposes governing runtime admission and RecipeStep tuning. + MCP membership comes from ToolDef.mcp_kwarg_names; admission policy lives + in RUNTIME_ADMISSION_BY_ROLE, consumed by runtime_exempt_param_names. """ PROTOCOL = "protocol" - """Attestation identity (step_name, recipe_execution_id, invocation_template_digest); - always admitted.""" + """Attestation credentials and step guard values; always admitted.""" + + STEP_IDENTITY = "step_identity" + """The invoking step's YAML key; declared values must match; always admitted.""" CHILD_INPUT = "child_input" """Child-skill inputs; admitted iff with:-compiled.""" @@ -128,6 +124,7 @@ class RuntimeAdmission(StrEnum): RUNTIME_ADMISSION_BY_ROLE: Mapping[ToolParamRole, RuntimeAdmission] = MappingProxyType( { ToolParamRole.PROTOCOL: RuntimeAdmission.ALWAYS, + ToolParamRole.STEP_IDENTITY: RuntimeAdmission.ALWAYS, ToolParamRole.ORCHESTRATOR_SCOPING: RuntimeAdmission.ALWAYS, ToolParamRole.CHILD_INPUT: RuntimeAdmission.WITH_DECLARED_ONLY, ToolParamRole.EXECUTION_TUNING: RuntimeAdmission.WITH_DECLARED_ONLY, diff --git a/src/autoskillit/migrations/0.10.1288-to-0.10.1289.yaml b/src/autoskillit/migrations/0.10.1288-to-0.10.1289.yaml new file mode 100644 index 0000000000..f16d68f9c8 --- /dev/null +++ b/src/autoskillit/migrations/0.10.1288-to-0.10.1289.yaml @@ -0,0 +1,28 @@ +from_version: "0.10.1288" +to_version: "0.10.1289" +description: Require each recipe step's with.step_name to match its YAML key. +changes: + - id: step-name-equals-step-key + description: | + Per-variant model.step_overrides and providers.* pins now match + analyze_pipeline_health_* variants by their own YAML keys (#4706). + Recipe declarations on telemetry-only tools also require the invoking + YAML key; free-form cross-step grouping labels are not valid + with.step_name values. Distinct analyze_pipeline_health_* keys now use + separate token and timing rows, so the former family-level aggregation + is lost; no additional label parameter is introduced. + instruction: | + Every with.step_name on a recipe step (any tool except record_pipeline_step) + must equal that step's YAML key; set it to the key or remove it. + example_before: | + steps: + decompose_phases: + tool: run_skill + with: + step_name: decompose + example_after: | + steps: + decompose_phases: + tool: run_skill + with: + step_name: decompose_phases diff --git a/src/autoskillit/recipe/api_orchestration/_api_orchestration_validate.py b/src/autoskillit/recipe/api_orchestration/_api_orchestration_validate.py index e556ae281c..b651fbe193 100644 --- a/src/autoskillit/recipe/api_orchestration/_api_orchestration_validate.py +++ b/src/autoskillit/recipe/api_orchestration/_api_orchestration_validate.py @@ -84,21 +84,24 @@ def _reconcile_semantic_findings( message=finding.message, ) - gate_skip_findings = [ + retained_pre_prune_findings = [ finding for finding in pre_prune_findings - if finding.rule == STAGE_OBLIGATION_GATE_DOMINANCE_RULE - and "cannot declare skip_when_false" in finding.message + if finding.rule == "step-identity-mismatch" + or ( + finding.rule == STAGE_OBLIGATION_GATE_DOMINANCE_RULE + and "cannot declare skip_when_false" in finding.message + ) ] retained_keys = { (finding.rule, finding.step_name, finding.message) for finding in semantic_findings } semantic_findings.extend( finding - for finding in gate_skip_findings + for finding in retained_pre_prune_findings if (finding.rule, finding.step_name, finding.message) not in retained_keys ) - if gate_skip_findings: + if retained_pre_prune_findings: semantic_suggestions = _orch.findings_to_dicts(semantic_findings) if recipe_name in (suppressed or ()): diff --git a/src/autoskillit/recipe/ingredients/_recipe_composition.py b/src/autoskillit/recipe/ingredients/_recipe_composition.py index fdcca565ce..a22e6037e0 100644 --- a/src/autoskillit/recipe/ingredients/_recipe_composition.py +++ b/src/autoskillit/recipe/ingredients/_recipe_composition.py @@ -16,7 +16,9 @@ RECIPE_TERMINAL_TARGETS, SKILL_TOOLS, RecipeFlowEdge, + ToolParamRole, YAMLError, + get_tool_def, load_yaml, ) from autoskillit.core import ( @@ -380,6 +382,25 @@ def rewrite(target: str | None) -> str | None: ) +def _rekey_composed_step( + step: RecipeStep, old_key: str, new_key: str, redirects: dict[str, str] +) -> RecipeStep: + rewritten = _rewrite_step_routes(step, redirects) + with_args = dict(rewritten.with_args) + declared_with_args = dict(rewritten.declared_with_args or {}) + tool_def = get_tool_def(step.tool) if step.tool else None + if tool_def is not None: + for param in tool_def.params: + if param.role is not ToolParamRole.STEP_IDENTITY: + continue + for args in (with_args, declared_with_args): + if args.get(param.name) == old_key: + args[param.name] = new_key + return dataclasses.replace( + rewritten, name=new_key, with_args=with_args, declared_with_args=declared_with_args + ) + + def _resolve_skip_redirects( steps: dict[str, RecipeStep], resolutions: dict[str, bool | None] ) -> dict[str, str]: diff --git a/src/autoskillit/recipe/ingredients/_recipe_merge.py b/src/autoskillit/recipe/ingredients/_recipe_merge.py index 2cd324fdaa..d12db12aa7 100644 --- a/src/autoskillit/recipe/ingredients/_recipe_merge.py +++ b/src/autoskillit/recipe/ingredients/_recipe_merge.py @@ -35,6 +35,7 @@ def _merge_sub_recipe(parent: Any, placeholder_name: str, sub: Any) -> Any: Algorithm: 1. Compute a safe name prefix from the sub-recipe name. 2. For each step in sub, create a prefixed copy with routing fixed: + - Key, name and invoking-step identity parameter are prefixed together - Routes to "done" → parent placeholder's on_success - Routes to "escalate" → parent placeholder's on_failure - Routes to other sub-recipe step names → add prefix @@ -44,6 +45,7 @@ def _merge_sub_recipe(parent: Any, placeholder_name: str, sub: Any) -> Any: """ # Lazy import to break the ``_recipe_composition`` ↔ ``_recipe_merge`` cycle. from autoskillit.recipe.ingredients._recipe_composition import ( + _rekey_composed_step, _rewrite_step_routes, ) @@ -69,7 +71,9 @@ def _merge_sub_recipe(parent: Any, placeholder_name: str, sub: Any) -> Any: prefixed_steps: dict[str, Any] = {} for sub_step_name, sub_step in sub.steps.items(): new_name = prefix + sub_step_name - prefixed_steps[new_name] = _rewrite_step_routes(sub_step, redirects) + prefixed_steps[new_name] = _rekey_composed_step( + sub_step, sub_step_name, new_name, redirects + ) # Assemble new steps dict: sub-recipe steps injected in place of placeholder new_steps: dict[str, Any] = {} diff --git a/src/autoskillit/recipe/rules/rules_tools.py b/src/autoskillit/recipe/rules/rules_tools.py index bc24840b33..3f54e67b02 100644 --- a/src/autoskillit/recipe/rules/rules_tools.py +++ b/src/autoskillit/recipe/rules/rules_tools.py @@ -12,6 +12,7 @@ TOOL_SUBSET_TAGS, BindingFailureCode, Severity, + ToolParamRole, get_logger, get_tool_def, ) @@ -203,6 +204,41 @@ def _check_dead_with_params(ctx: ValidationContext) -> list[RuleFinding]: return findings +@semantic_rule( + name="step-identity-mismatch", + description="A step's with: identity parameter must equal its YAML step key", + severity=Severity.ERROR, +) +def _check_step_identity(ctx: ValidationContext) -> list[RuleFinding]: + findings: list[RuleFinding] = [] + for key, step in ctx.recipe.steps.items(): + tool_def = get_tool_def(step.tool) if step.tool else None + if tool_def is None: + continue + for param in tool_def.params: + if param.role is not ToolParamRole.STEP_IDENTITY: + continue + mismatches = [ + f"{name}[{param.name!r}]={args[param.name]!r}" + for name, args in ( + ("with_args", step.with_args), + ("declared_with_args", step.declared_with_args or {}), + ) + if args.get(param.name, key) != key + ] + if mismatches: + findings.append( + make_finding( + rule_name="step-identity-mismatch", + step_name=key, + message=f"step '{key}': {'; '.join(mismatches)} must equal " + f"the YAML step key '{key}'", + remedy="set with.step_name to the step's YAML key, or remove it", + ) + ) + return findings + + @semantic_rule( name="rebase-then-push-requires-force", description=( diff --git a/src/autoskillit/recipes/diagrams/implementation-groups.md b/src/autoskillit/recipes/diagrams/implementation-groups.md index ae5711701b..193d7183b7 100644 --- a/src/autoskillit/recipes/diagrams/implementation-groups.md +++ b/src/autoskillit/recipes/diagrams/implementation-groups.md @@ -1,4 +1,4 @@ - + ## implementation-groups diff --git a/src/autoskillit/recipes/diagrams/implementation.md b/src/autoskillit/recipes/diagrams/implementation.md index 81e1ef70f2..ba9593d058 100644 --- a/src/autoskillit/recipes/diagrams/implementation.md +++ b/src/autoskillit/recipes/diagrams/implementation.md @@ -1,4 +1,4 @@ - + ## implementation diff --git a/src/autoskillit/recipes/diagrams/merge-prs.md b/src/autoskillit/recipes/diagrams/merge-prs.md index 7c7f32948c..13944979f8 100644 --- a/src/autoskillit/recipes/diagrams/merge-prs.md +++ b/src/autoskillit/recipes/diagrams/merge-prs.md @@ -1,4 +1,4 @@ - + ## merge-prs Merge multiple PRs into an integration branch with conflict resolution and CI gates. diff --git a/src/autoskillit/recipes/diagrams/remediation.md b/src/autoskillit/recipes/diagrams/remediation.md index 6a141b3c6a..4e1eb26d77 100644 --- a/src/autoskillit/recipes/diagrams/remediation.md +++ b/src/autoskillit/recipes/diagrams/remediation.md @@ -1,4 +1,4 @@ - + ## remediation diff --git a/src/autoskillit/recipes/implementation-groups.json b/src/autoskillit/recipes/implementation-groups.json index 1b6ec50933..8c30b1c786 100644 --- a/src/autoskillit/recipes/implementation-groups.json +++ b/src/autoskillit/recipes/implementation-groups.json @@ -141,7 +141,7 @@ "source_dir": "${{ inputs.source_dir }}", "run_name": "${{ inputs.run_name }}", "base_branch": "${{ inputs.base_branch }}", - "step_name": "bootstrap_clone" + "step_name": "clone" }, "capture": { "work_dir": "${{ result.work_dir }}", @@ -191,7 +191,7 @@ "issue_number": "${{ context.issue_number }}", "work_dir": "${{ context.work_dir }}", "remote_url": "${{ context.remote_url }}", - "step_name": "create_and_publish_branch" + "step_name": "create_and_publish" }, "capture": { "merge_target": "${{ result.merge_target }}" @@ -2209,7 +2209,7 @@ "diagnostics_log_dir": "${{ inputs.diagnostics_log_dir }}" }, "cwd": "${{ context.work_dir }}", - "step_name": "analyze_pipeline_health" + "step_name": "analyze_pipeline_health_no_ci" }, "on_success": "escalate_stop_no_ci", "on_failure": "escalate_stop_no_ci", @@ -3237,7 +3237,7 @@ "diagnostics_log_dir": "${{ inputs.diagnostics_log_dir }}" }, "cwd": "${{ context.work_dir }}", - "step_name": "analyze_pipeline_health" + "step_name": "analyze_pipeline_health_unconfirmed" }, "on_success": "done_unconfirmed", "on_failure": "done_unconfirmed", @@ -3449,7 +3449,7 @@ "diagnostics_log_dir": "${{ inputs.diagnostics_log_dir }}" }, "cwd": "${{ context.work_dir }}", - "step_name": "analyze_pipeline_health" + "step_name": "analyze_pipeline_health_error" }, "on_success": "escalate_stop", "on_failure": "escalate_stop", diff --git a/src/autoskillit/recipes/implementation-groups.yaml b/src/autoskillit/recipes/implementation-groups.yaml index 7f40203fbc..436b220811 100644 --- a/src/autoskillit/recipes/implementation-groups.yaml +++ b/src/autoskillit/recipes/implementation-groups.yaml @@ -141,7 +141,7 @@ steps: source_dir: ${{ inputs.source_dir }} run_name: ${{ inputs.run_name }} base_branch: ${{ inputs.base_branch }} - step_name: bootstrap_clone + step_name: clone capture: work_dir: ${{ result.work_dir }} remote_url: ${{ result.remote_url }} @@ -191,7 +191,7 @@ steps: issue_number: ${{ context.issue_number }} work_dir: ${{ context.work_dir }} remote_url: ${{ context.remote_url }} - step_name: create_and_publish_branch + step_name: create_and_publish capture: merge_target: ${{ result.merge_target }} on_success: group @@ -1851,7 +1851,7 @@ steps: dispatch_id: ${{ inputs.dispatch_id }} diagnostics_log_dir: ${{ inputs.diagnostics_log_dir }} cwd: ${{ context.work_dir }} - step_name: analyze_pipeline_health + step_name: analyze_pipeline_health_no_ci on_success: escalate_stop_no_ci on_failure: escalate_stop_no_ci on_context_limit: escalate_stop_no_ci @@ -2711,7 +2711,7 @@ steps: dispatch_id: ${{ inputs.dispatch_id }} diagnostics_log_dir: ${{ inputs.diagnostics_log_dir }} cwd: ${{ context.work_dir }} - step_name: analyze_pipeline_health + step_name: analyze_pipeline_health_unconfirmed on_success: done_unconfirmed on_failure: done_unconfirmed on_context_limit: done_unconfirmed @@ -2920,7 +2920,7 @@ steps: dispatch_id: ${{ inputs.dispatch_id }} diagnostics_log_dir: ${{ inputs.diagnostics_log_dir }} cwd: ${{ context.work_dir }} - step_name: analyze_pipeline_health + step_name: analyze_pipeline_health_error on_success: escalate_stop on_failure: escalate_stop on_context_limit: escalate_stop diff --git a/src/autoskillit/recipes/implementation.json b/src/autoskillit/recipes/implementation.json index 1260ce6eef..ea7a55dd32 100644 --- a/src/autoskillit/recipes/implementation.json +++ b/src/autoskillit/recipes/implementation.json @@ -2527,7 +2527,7 @@ "diagnostics_log_dir": "${{ inputs.diagnostics_log_dir }}" }, "cwd": "${{ context.work_dir }}", - "step_name": "analyze_pipeline_health" + "step_name": "analyze_pipeline_health_no_ci" }, "on_success": "escalate_stop_no_ci", "on_failure": "escalate_stop_no_ci", @@ -3680,7 +3680,7 @@ "diagnostics_log_dir": "${{ inputs.diagnostics_log_dir }}" }, "cwd": "${{ context.work_dir }}", - "step_name": "analyze_pipeline_health" + "step_name": "analyze_pipeline_health_unconfirmed" }, "on_success": "done_unconfirmed", "on_failure": "done_unconfirmed", @@ -3790,7 +3790,7 @@ "diagnostics_log_dir": "${{ inputs.diagnostics_log_dir }}" }, "cwd": "${{ context.work_dir }}", - "step_name": "analyze_pipeline_health" + "step_name": "analyze_pipeline_health_error" }, "on_success": "escalate_stop", "on_failure": "escalate_stop", @@ -3823,7 +3823,7 @@ "diagnostics_log_dir": "${{ inputs.diagnostics_log_dir }}" }, "cwd": "${{ context.work_dir }}", - "step_name": "analyze_pipeline_health" + "step_name": "analyze_pipeline_health_no_changes" }, "on_success": "done_no_changes", "on_failure": "done_no_changes", @@ -3856,7 +3856,7 @@ "diagnostics_log_dir": "${{ inputs.diagnostics_log_dir }}" }, "cwd": "${{ context.work_dir }}", - "step_name": "analyze_pipeline_health" + "step_name": "analyze_pipeline_health_already_done" }, "on_success": "done_already_done", "on_failure": "done_already_done", diff --git a/src/autoskillit/recipes/implementation.yaml b/src/autoskillit/recipes/implementation.yaml index aa06d6d792..8f2e45b913 100644 --- a/src/autoskillit/recipes/implementation.yaml +++ b/src/autoskillit/recipes/implementation.yaml @@ -2080,7 +2080,7 @@ steps: dispatch_id: ${{ inputs.dispatch_id }} diagnostics_log_dir: ${{ inputs.diagnostics_log_dir }} cwd: ${{ context.work_dir }} - step_name: analyze_pipeline_health + step_name: analyze_pipeline_health_no_ci on_success: escalate_stop_no_ci on_failure: escalate_stop_no_ci on_context_limit: escalate_stop_no_ci @@ -3062,7 +3062,7 @@ steps: dispatch_id: ${{ inputs.dispatch_id }} diagnostics_log_dir: ${{ inputs.diagnostics_log_dir }} cwd: ${{ context.work_dir }} - step_name: analyze_pipeline_health + step_name: analyze_pipeline_health_unconfirmed on_success: done_unconfirmed on_failure: done_unconfirmed on_context_limit: done_unconfirmed @@ -3165,7 +3165,7 @@ steps: dispatch_id: ${{ inputs.dispatch_id }} diagnostics_log_dir: ${{ inputs.diagnostics_log_dir }} cwd: ${{ context.work_dir }} - step_name: analyze_pipeline_health + step_name: analyze_pipeline_health_error on_success: escalate_stop on_failure: escalate_stop on_context_limit: escalate_stop @@ -3193,7 +3193,7 @@ steps: dispatch_id: ${{ inputs.dispatch_id }} diagnostics_log_dir: ${{ inputs.diagnostics_log_dir }} cwd: ${{ context.work_dir }} - step_name: analyze_pipeline_health + step_name: analyze_pipeline_health_no_changes on_success: done_no_changes on_failure: done_no_changes on_context_limit: done_no_changes @@ -3224,7 +3224,7 @@ steps: dispatch_id: ${{ inputs.dispatch_id }} diagnostics_log_dir: ${{ inputs.diagnostics_log_dir }} cwd: ${{ context.work_dir }} - step_name: analyze_pipeline_health + step_name: analyze_pipeline_health_already_done on_success: done_already_done on_failure: done_already_done on_context_limit: done_already_done diff --git a/src/autoskillit/recipes/merge-prs.json b/src/autoskillit/recipes/merge-prs.json index 20752178b6..671a8d820b 100644 --- a/src/autoskillit/recipes/merge-prs.json +++ b/src/autoskillit/recipes/merge-prs.json @@ -2349,7 +2349,7 @@ "diagnostics_log_dir": "${{ inputs.diagnostics_log_dir }}" }, "cwd": "${{ context.work_dir }}", - "step_name": "analyze_pipeline_health" + "step_name": "analyze_pipeline_health_error" }, "on_success": "escalate_stop", "on_failure": "escalate_stop", diff --git a/src/autoskillit/recipes/merge-prs.yaml b/src/autoskillit/recipes/merge-prs.yaml index bdc44ad3fc..c7c8aeafbb 100644 --- a/src/autoskillit/recipes/merge-prs.yaml +++ b/src/autoskillit/recipes/merge-prs.yaml @@ -2012,7 +2012,7 @@ steps: dispatch_id: ${{ inputs.dispatch_id }} diagnostics_log_dir: ${{ inputs.diagnostics_log_dir }} cwd: ${{ context.work_dir }} - step_name: analyze_pipeline_health + step_name: analyze_pipeline_health_error on_success: escalate_stop on_failure: escalate_stop on_context_limit: escalate_stop diff --git a/src/autoskillit/recipes/remediation.json b/src/autoskillit/recipes/remediation.json index 6c6ef8cd58..b360b3878a 100644 --- a/src/autoskillit/recipes/remediation.json +++ b/src/autoskillit/recipes/remediation.json @@ -3044,7 +3044,7 @@ "diagnostics_log_dir": "${{ inputs.diagnostics_log_dir }}" }, "cwd": "${{ context.work_dir }}", - "step_name": "analyze_pipeline_health" + "step_name": "analyze_pipeline_health_no_ci" }, "on_success": "escalate_stop_no_ci", "on_failure": "escalate_stop_no_ci", @@ -4144,7 +4144,7 @@ "diagnostics_log_dir": "${{ inputs.diagnostics_log_dir }}" }, "cwd": "${{ context.work_dir }}", - "step_name": "analyze_pipeline_health" + "step_name": "analyze_pipeline_health_unconfirmed" }, "on_success": "done_unconfirmed", "on_failure": "done_unconfirmed", @@ -4307,7 +4307,7 @@ "diagnostics_log_dir": "${{ inputs.diagnostics_log_dir }}" }, "cwd": "${{ context.work_dir }}", - "step_name": "analyze_pipeline_health" + "step_name": "analyze_pipeline_health_error" }, "on_success": "escalate_stop", "on_failure": "escalate_stop", @@ -4340,7 +4340,7 @@ "diagnostics_log_dir": "${{ inputs.diagnostics_log_dir }}" }, "cwd": "${{ context.work_dir }}", - "step_name": "analyze_pipeline_health" + "step_name": "analyze_pipeline_health_no_changes" }, "on_success": "done_no_changes", "on_failure": "done_no_changes", @@ -4373,7 +4373,7 @@ "diagnostics_log_dir": "${{ inputs.diagnostics_log_dir }}" }, "cwd": "${{ context.work_dir }}", - "step_name": "analyze_pipeline_health" + "step_name": "analyze_pipeline_health_already_done" }, "on_success": "done_already_done", "on_failure": "done_already_done", diff --git a/src/autoskillit/recipes/remediation.yaml b/src/autoskillit/recipes/remediation.yaml index 36b387505c..42e315422e 100644 --- a/src/autoskillit/recipes/remediation.yaml +++ b/src/autoskillit/recipes/remediation.yaml @@ -2293,7 +2293,7 @@ steps: dispatch_id: ${{ inputs.dispatch_id }} diagnostics_log_dir: ${{ inputs.diagnostics_log_dir }} cwd: ${{ context.work_dir }} - step_name: analyze_pipeline_health + step_name: analyze_pipeline_health_no_ci on_success: escalate_stop_no_ci on_failure: escalate_stop_no_ci on_context_limit: escalate_stop_no_ci @@ -3104,7 +3104,7 @@ steps: dispatch_id: ${{ inputs.dispatch_id }} diagnostics_log_dir: ${{ inputs.diagnostics_log_dir }} cwd: ${{ context.work_dir }} - step_name: analyze_pipeline_health + step_name: analyze_pipeline_health_unconfirmed on_success: done_unconfirmed on_failure: done_unconfirmed on_context_limit: done_unconfirmed @@ -3251,7 +3251,7 @@ steps: dispatch_id: ${{ inputs.dispatch_id }} diagnostics_log_dir: ${{ inputs.diagnostics_log_dir }} cwd: ${{ context.work_dir }} - step_name: analyze_pipeline_health + step_name: analyze_pipeline_health_error on_success: escalate_stop on_failure: escalate_stop on_context_limit: escalate_stop @@ -3279,7 +3279,7 @@ steps: dispatch_id: ${{ inputs.dispatch_id }} diagnostics_log_dir: ${{ inputs.diagnostics_log_dir }} cwd: ${{ context.work_dir }} - step_name: analyze_pipeline_health + step_name: analyze_pipeline_health_no_changes on_success: done_no_changes on_failure: done_no_changes on_context_limit: done_no_changes @@ -3310,7 +3310,7 @@ steps: dispatch_id: ${{ inputs.dispatch_id }} diagnostics_log_dir: ${{ inputs.diagnostics_log_dir }} cwd: ${{ context.work_dir }} - step_name: analyze_pipeline_health + step_name: analyze_pipeline_health_already_done on_success: done_already_done on_failure: done_already_done on_context_limit: done_already_done diff --git a/src/autoskillit/recipes/research-implement.json b/src/autoskillit/recipes/research-implement.json index d6faf2f411..40052480e9 100644 --- a/src/autoskillit/recipes/research-implement.json +++ b/src/autoskillit/recipes/research-implement.json @@ -151,7 +151,7 @@ "source_doc": "${{ inputs.experiment_plan }}" }, "cwd": "${{ inputs.worktree_path }}", - "step_name": "decompose", + "step_name": "decompose_phases", "output_dir": "{{AUTOSKILLIT_TEMP}}/make-groups" }, "capture": { @@ -708,7 +708,7 @@ "adjust": true }, "cwd": "${{ context.worktree_path }}", - "step_name": "adjust", + "step_name": "adjust_experiment", "output_dir": "." }, "capture": { @@ -870,7 +870,7 @@ "worktree_path": "${{ context.worktree_path }}" }, "cwd": "${{ inputs.source_dir }}", - "step_name": "fix", + "step_name": "fix_tests", "output_dir": "." }, "capture": { diff --git a/src/autoskillit/recipes/research-implement.yaml b/src/autoskillit/recipes/research-implement.yaml index 8ca237853f..b17ec5e20d 100644 --- a/src/autoskillit/recipes/research-implement.yaml +++ b/src/autoskillit/recipes/research-implement.yaml @@ -153,7 +153,7 @@ steps: skill_inputs: source_doc: ${{ inputs.experiment_plan }} cwd: ${{ inputs.worktree_path }} - step_name: decompose + step_name: decompose_phases output_dir: '{{AUTOSKILLIT_TEMP}}/make-groups' capture: group_files: ${{ result.group_files }} @@ -588,7 +588,7 @@ steps: worktree_path: ${{ context.worktree_path }} adjust: true cwd: ${{ context.worktree_path }} - step_name: adjust + step_name: adjust_experiment output_dir: . capture: experiment_results: ${{ result.results_path }} @@ -720,7 +720,7 @@ steps: base_branch: ${{ inputs.base_branch }} worktree_path: ${{ context.worktree_path }} cwd: ${{ inputs.source_dir }} - step_name: fix + step_name: fix_tests output_dir: . capture: verdict: ${{ result.verdict }} diff --git a/src/autoskillit/server/tools/tools_execution/_run_skill_dispatch.py b/src/autoskillit/server/tools/tools_execution/_run_skill_dispatch.py index eda77c382e..e9eb8fbf2d 100644 --- a/src/autoskillit/server/tools/tools_execution/_run_skill_dispatch.py +++ b/src/autoskillit/server/tools/tools_execution/_run_skill_dispatch.py @@ -279,8 +279,12 @@ async def run_skill( with: block declares model — the step's model: field is normally resolved server-side instead. For unattested calls, where the recipe-step gate does not apply, it is a caller override. - step_name: Optional YAML step key (e.g. "implement"). When set, token usage is - accumulated in the server-side token log, grouped by this name. + step_name: The recipe's YAML step key. It is required for attested calls; an + empty value is denied at attestation admission with + `recipe_execution_step_missing`. On a fresh unattested call, omission is + resolved only when exactly one active recipe step matches the skill_command + prefix; ambiguous matches do not resolve. Dependency authority or locks can + require an explicit key. Token and timing usage are grouped by this key. order_id: Optional per-issue/order identifier for token telemetry scoping. When set, token and timing entries are keyed by this value, enabling per-issue isolation in get_token_summary/get_timing_summary and in the token_summary_appender hook. diff --git a/src/autoskillit/server/tools/tools_github.py b/src/autoskillit/server/tools/tools_github.py index 92a137d776..f542530b17 100644 --- a/src/autoskillit/server/tools/tools_github.py +++ b/src/autoskillit/server/tools/tools_github.py @@ -211,7 +211,7 @@ async def report_bug( cwd: Working directory for the headless session. severity: "non_blocking" (fire-and-forget) or "blocking" (await completion). model: Model override. Empty string = config default. - step_name: Optional label for token tracking. + step_name: Optional YAML step key; groups token usage under that step. Never raises. """ diff --git a/src/autoskillit/skills/sous-chef/SKILL.md b/src/autoskillit/skills/sous-chef/SKILL.md index c4efc23573..c7fe440e48 100644 --- a/src/autoskillit/skills/sous-chef/SKILL.md +++ b/src/autoskillit/skills/sous-chef/SKILL.md @@ -530,11 +530,18 @@ When dispatching from an execution map: ## STEP NAME IMMUTABILITY — MANDATORY The `step_name` passed to `run_skill` (and all other recipe-step tools that accept -`step_name`) must be the **exact value from the recipe YAML `with:` block**. +`step_name`) must be the step's **YAML key** — its name under `steps:` — on every +call, even when the step's `with:` block declares no `step_name`. A declared +invoking-step `with.step_name` is validated to equal that key. + +Exception: `record_pipeline_step.step_name` names the target tracked step; pass +that target's YAML key rather than the invoking tool-step key. **NEVER** append clone numbers, instance indices, retry counts, or any other -disambiguation strings. The telemetry layer aggregates all invocations of the same -logical step automatically — suffixing produces garbage rows in token and timing tables. +disambiguation strings. +Repeated executions of the same YAML step key use that key without clone or retry +suffixes. Distinct YAML step keys remain separate telemetry rows, even when they +invoke the same skill. Correct: ```yaml @@ -555,10 +562,10 @@ parallel run of the same step reports under the same canonical step name. ## PARAMETER FORWARDING — step_name, output_dir -When a recipe step's `with:` block contains `step_name`, you MUST pass it as the -`step_name` parameter of `run_skill`. This enables ingredient lock enforcement, -pipeline dependency checks, and all per-step parameter auto-fills. Omitting it -degrades enforcement and may cause the call to be denied when locks are active. +Always pass the step's YAML key as the `step_name` parameter of `run_skill`. This +enables ingredient lock enforcement, pipeline dependency checks, and all per-step +parameter auto-fills. Omitting it degrades enforcement and may cause the call to be +denied when locks are active. When a recipe step's `with:` block contains `output_dir`, you MUST pass it as the `output_dir` parameter of `run_skill`. This controls the write guard — omitting it diff --git a/src/autoskillit/skills_extended/write-recipe/SKILL.md b/src/autoskillit/skills_extended/write-recipe/SKILL.md index 4dc81d5a26..26d5d7fac9 100644 --- a/src/autoskillit/skills_extended/write-recipe/SKILL.md +++ b/src/autoskillit/skills_extended/write-recipe/SKILL.md @@ -231,7 +231,7 @@ Available tools for use in `tool:` fields: | Tool | Arguments (`with:`) | Purpose | |------|---------------------|---------| -| `run_skill` | `skill_command`, `cwd`, `model` (optional), `step_name` (optional) | Run a Claude Code headless session with a skill | +| `run_skill` | `skill_command`, `cwd`, `model` (optional), `step_name` (optional; when present must equal the step's YAML key) | Run a Claude Code headless session with a skill | | `test_check` | `worktree_path` | Run test suite, returns PASS/FAIL | | `merge_worktree` | `worktree_path`, `base_branch` | Merge after test gate | | `reset_test_dir` | `test_dir`, `force` (optional, default false) | Clear test directory (requires reset guard marker) | diff --git a/tests/cli/test_food_truck_prompt.py b/tests/cli/test_food_truck_prompt.py index 3c46f627b1..e0bf869949 100644 --- a/tests/cli/test_food_truck_prompt.py +++ b/tests/cli/test_food_truck_prompt.py @@ -87,6 +87,20 @@ def test_retains_exactly_six_sections(self) -> None: assert title in block, f"Missing retained section: {title}" assert len(re.findall(r"^## ", block, re.MULTILINE)) == 6 + def test_step_name_contract_is_in_delivered_section(self) -> None: + match = re.search( + r"(?ms)^## STEP NAME IMMUTABILITY[^\n]*\n.*?(?=^## |\Z)", + _get_admiral_block(), + ) + assert match is not None + section = match.group(0).casefold() + + assert "yaml step key" in section + assert "even when" in section + assert "`with:`" in section + assert "record_pipeline_step.step_name names the target tracked step" in section + assert "distinct yaml step keys remain separate telemetry rows" in section + def test_excludes_five_sections(self) -> None: block = _get_admiral_block() for title in ( diff --git a/tests/contracts/test_run_skill_kwarg_ledger.py b/tests/contracts/test_run_skill_kwarg_ledger.py index d2a856e686..5c96f41245 100644 --- a/tests/contracts/test_run_skill_kwarg_ledger.py +++ b/tests/contracts/test_run_skill_kwarg_ledger.py @@ -49,7 +49,7 @@ "skill_inputs": ToolParamRole.CHILD_INPUT, "stale_threshold": ToolParamRole.EXECUTION_TUNING, "step_guard_value": ToolParamRole.PROTOCOL, - "step_name": ToolParamRole.PROTOCOL, + "step_name": ToolParamRole.STEP_IDENTITY, "step_provider": ToolParamRole.EXECUTION_TUNING, } diff --git a/tests/contracts/test_sous_chef_parameter_forwarding.py b/tests/contracts/test_sous_chef_parameter_forwarding.py index 1a293fc948..b48a9c7973 100644 --- a/tests/contracts/test_sous_chef_parameter_forwarding.py +++ b/tests/contracts/test_sous_chef_parameter_forwarding.py @@ -54,3 +54,16 @@ def test_sous_chef_skill_md_mentions_step_name(): "The LLM must be instructed to forward step_name from recipe " "step with: blocks to run_skill for lock enforcement." ) + + +def test_step_name_immutability_requires_the_yaml_key() -> None: + skill_md = ( + Path(__file__).parents[2] / "src/autoskillit/skills/sous-chef/SKILL.md" + ).read_text() + start = skill_md.index("## STEP NAME IMMUTABILITY") + end = skill_md.find("\n## ", start + 1) + section = skill_md[start : end if end >= 0 else None] + + assert "YAML key" in section + assert "even when" in section + assert "`with:`" in section diff --git a/tests/contracts/test_tool_param_roles.py b/tests/contracts/test_tool_param_roles.py index a5a7e473cd..f3407f8a10 100644 --- a/tests/contracts/test_tool_param_roles.py +++ b/tests/contracts/test_tool_param_roles.py @@ -23,6 +23,7 @@ EXECUTION_TUNING_STEP_FIELDS, RUN_SKILL_ATTESTATION_PARAMS, RUNTIME_ADMISSION_BY_ROLE, + TOOL_REGISTRY, RuntimeAdmission, ToolParamRole, ToolWireType, @@ -205,3 +206,59 @@ def test_contract_identity_excludes_role() -> None: assert compute_tool_contract_identity(reroled_tool_def) == compute_tool_contract_identity( tool_def ), "role changed compute_tool_contract_identity's output — it must be excluded by construction" + + +def test_step_name_role_and_tool_membership_are_reviewed() -> None: + """Every invoking-step reference is a step identity; the tracker target is an input.""" + expected_step_identity_tools = { + "batch_cleanup_clones", + "bind_plan_set", + "bootstrap_clone", + "check_pr_mergeable", + "check_repo_merge_state", + "claim_and_resolve_issue", + "classify_fix", + "clone_repo", + "commit_files", + "create_and_publish_branch", + "create_unique_branch", + "enqueue_pr", + "merge_worktree", + "push_to_remote", + "release_issue", + "register_clone_status", + "remove_clone", + "report_bug", + "reset_test_dir", + "run_cmd", + "run_python", + "run_skill", + "test_check", + "verify_review_receipt", + "wait_for_ci", + "wait_for_merge_queue", + "write_audit_disposition_bundle", + "write_audit_semantic_result", + "write_standalone_audit_evidence", + } + step_name_roles = { + tool.name: param.role + for tool in TOOL_REGISTRY.values() + if (param := tool.param_def("step_name")) is not None + } + + assert set(step_name_roles) == expected_step_identity_tools | {"record_pipeline_step"} + assert { + name for name, role in step_name_roles.items() if role is ToolParamRole.STEP_IDENTITY + } == expected_step_identity_tools + assert step_name_roles["record_pipeline_step"] is ToolParamRole.CHILD_INPUT + + +def test_run_skill_exempt_set_unchanged() -> None: + assert runtime_exempt_param_names(_run_skill_tool_def()) == { + "step_name", + "recipe_execution_id", + "invocation_template_digest", + "step_guard_value", + "order_id", + } diff --git a/tests/infra/test_pretty_output_recipe.py b/tests/infra/test_pretty_output_recipe.py index 871d17f306..ce5f0465ca 100644 --- a/tests/infra/test_pretty_output_recipe.py +++ b/tests/infra/test_pretty_output_recipe.py @@ -1375,9 +1375,9 @@ def test_pretty_output_recipe_grid_preserves_semantics_and_budgets(tmp_path, mon f"ingredients_only=both; actual={measured_modes!r}; limit=all registry modes" ) assert maxima == { - "get_recipe_section": (187_443, "remediation", "all_truthy"), - "load_recipe": (187_443, "remediation", "all_truthy"), - "open_kitchen": (187_497, "remediation", "all_truthy"), + "get_recipe_section": (187_491, "remediation", "all_truthy"), + "load_recipe": (187_491, "remediation", "all_truthy"), + "open_kitchen": (187_545, "remediation", "all_truthy"), }, ( "property=canonical baseline maxima; recipe=all; mode=all; tool=all; " f"ingredients_only=both; actual={maxima!r}; limit=measured current baseline" diff --git a/tests/recipe/test_anti_pattern_guards.py b/tests/recipe/test_anti_pattern_guards.py index 3606261a1a..29192e11a7 100644 --- a/tests/recipe/test_anti_pattern_guards.py +++ b/tests/recipe/test_anti_pattern_guards.py @@ -6,6 +6,7 @@ import pytest +from autoskillit.core import ToolParamRole, get_tool_def from autoskillit.core.io import load_yaml from autoskillit.core.types import RecipeSource from autoskillit.recipe.io import builtin_recipes_dir, load_recipe @@ -53,6 +54,38 @@ def test_all_run_cmd_steps_have_step_name(recipe_path): ) +@pytest.mark.parametrize( + "recipe_path", tracked_recipe_paths(_PROJECT_ROOT), ids=lambda path: path.stem +) +def test_every_declared_step_identity_equals_its_key(recipe_path): + """Every raw tracked step identity parameter must equal the YAML step key.""" + raw = load_yaml(recipe_path) + violations = [] + for step_name, step_data in raw.get("steps", {}).items(): + if not isinstance(step_data, dict): + continue + tool_name = step_data.get("tool") + if not isinstance(tool_name, str): + continue + tool_def = get_tool_def(tool_name) + if tool_def is None: + continue + identity_params = [ + param.name for param in tool_def.params if param.role is ToolParamRole.STEP_IDENTITY + ] + with_args = step_data.get("with", {}) + if not isinstance(with_args, dict): + continue + for param_name in identity_params: + if param_name in with_args and with_args[param_name] != step_name: + violations.append( + f"{recipe_path}:{step_name} has {param_name}={with_args[param_name]!r}" + ) + assert not violations, "tracked recipe step identities differ from their keys:\n" + "\n".join( + violations + ) + + def test_implementation_ci_failure_routes_to_diagnose_ci(): """AP1: implementation.yaml ci_watch failure must route through detect_ci_conflict gate. diff --git a/tests/recipe/test_composition_step_identity.py b/tests/recipe/test_composition_step_identity.py new file mode 100644 index 0000000000..c5d5512968 --- /dev/null +++ b/tests/recipe/test_composition_step_identity.py @@ -0,0 +1,94 @@ +"""Composition tests for re-keyed step identities.""" + +from __future__ import annotations + +import shutil +from pathlib import Path +from typing import Any + +import pytest + +from autoskillit.recipe._api import load_and_validate +from autoskillit.recipe.ingredients._recipe_composition import _build_active_recipe +from autoskillit.recipe.ingredients._recipe_merge import _merge_sub_recipe +from autoskillit.recipe.io import load_recipe + +pytestmark = [pytest.mark.layer("recipe"), pytest.mark.small] + +_RECIPE_NAME = "composed-projection-parent" +_COMPOSED_STEP_NAME = "composed_projection_child_child_step" +_CHILD_IDENTITY_LINE = " step_name: child_step\n" + + +def _install_composed_recipe(tmp_path: Path, *, child_identity: str | None) -> tuple[Path, Path]: + fixture_dir = Path(__file__).parent / "fixtures" + recipes_dir = tmp_path / ".autoskillit" / "recipes" + recipes_dir.mkdir(parents=True) + parent_path = recipes_dir / f"{_RECIPE_NAME}.yaml" + shutil.copy2(fixture_dir / "composed_projection_parent.yaml", parent_path) + sub_recipe_dir = recipes_dir / "sub-recipes" + sub_recipe_dir.mkdir() + child_path = sub_recipe_dir / "composed-projection-child.yaml" + child_content = (fixture_dir / "composed_projection_child.yaml").read_text() + assert child_content.count(_CHILD_IDENTITY_LINE) == 1 + replacement = "" if child_identity is None else f" step_name: {child_identity}\n" + child_path.write_text(child_content.replace(_CHILD_IDENTITY_LINE, replacement)) + return parent_path, child_path + + +def _identity_suggestions(result: dict[str, Any]) -> list[dict[str, Any]]: + return [ + suggestion + for suggestion in result.get("suggestions", []) + if suggestion.get("rule") == "step-identity-mismatch" + ] + + +@pytest.mark.parametrize( + ("child_identity", "declared"), + [("child_step", True), (None, False)], + ids=["declared", "omitted"], +) +def test_composed_step_carries_one_identity( + tmp_path: Path, child_identity: str | None, declared: bool +) -> None: + parent_path, _ = _install_composed_recipe(tmp_path, child_identity=child_identity) + active = _build_active_recipe(load_recipe(parent_path), {}, tmp_path)[0] + step = active.steps[_COMPOSED_STEP_NAME] + + assert step.name == _COMPOSED_STEP_NAME + if declared: + assert step.with_args["step_name"] == _COMPOSED_STEP_NAME + assert step.declared_with_args is not None + assert step.declared_with_args["step_name"] == _COMPOSED_STEP_NAME + else: + assert "step_name" not in step.with_args + assert step.declared_with_args is None or "step_name" not in step.declared_with_args + + +def test_divergent_child_identity_is_still_reported(tmp_path: Path) -> None: + _install_composed_recipe(tmp_path, child_identity="other") + + result = load_and_validate(_RECIPE_NAME, project_dir=tmp_path) + findings = _identity_suggestions(result) + + assert result["valid"] is False + assert len(findings) == 1 + assert findings[0]["step"] == _COMPOSED_STEP_NAME + + +def test_composition_does_not_mutate_child_step_maps(tmp_path: Path) -> None: + parent_path, child_path = _install_composed_recipe(tmp_path, child_identity="child_step") + parent = load_recipe(parent_path) + child = load_recipe(child_path) + source_step = child.steps["child_step"] + original_name = source_step.name + original_with_args = dict(source_step.with_args) + original_declared_with_args = dict(source_step.declared_with_args or {}) + + merged = _merge_sub_recipe(parent, "child_placeholder", child) + + assert merged.steps[_COMPOSED_STEP_NAME] is not source_step + assert source_step.name == original_name + assert source_step.with_args == original_with_args + assert source_step.declared_with_args == original_declared_with_args diff --git a/tests/recipe/test_rules_step_identity.py b/tests/recipe/test_rules_step_identity.py new file mode 100644 index 0000000000..af495f4e1e --- /dev/null +++ b/tests/recipe/test_rules_step_identity.py @@ -0,0 +1,195 @@ +"""Tests for step-identity-mismatch semantic validation.""" + +from __future__ import annotations + +from pathlib import Path +from typing import Any + +import pytest + +from autoskillit.core import Severity +from autoskillit.recipe import make_validation_context +from autoskillit.recipe._api import load_and_validate +from autoskillit.recipe.registry import run_semantic_rules +from autoskillit.recipe.schema import Recipe, RecipeStep + +pytestmark = [pytest.mark.layer("recipe"), pytest.mark.small] + +RULE_NAME = "step-identity-mismatch" +_RUN_SKILL_KEY = "decompose_phases" + + +def _make_recipe( + step_name: str, + tool: str, + with_args: dict[str, Any], + declared_with_args: dict[str, Any], +) -> Recipe: + return Recipe( + name="step-identity-test", + description="Test recipe for step identity validation.", + version="0.2.0", + kitchen_rules="test", + steps={ + step_name: RecipeStep( + tool=tool, + with_args=with_args, + declared_with_args=declared_with_args, + ), + }, + ) + + +def _identity_findings(recipe: Recipe): + ctx = make_validation_context(recipe) + return [finding for finding in run_semantic_rules(ctx) if finding.rule == RULE_NAME] + + +@pytest.mark.parametrize( + ("effective_value", "declared_value", "map_terms", "bad_values"), + [ + ("decompose", "decompose", (("with", "effective"), ("declared",)), ("decompose",)), + ( + "decompose", + _RUN_SKILL_KEY, + (("with", "effective"),), + ("decompose",), + ), + ( + _RUN_SKILL_KEY, + "decompose", + (("declared",),), + ("decompose",), + ), + ], +) +def test_divergent_run_skill_identity_is_an_error( + effective_value: str, + declared_value: str, + map_terms: tuple[tuple[str, ...], ...], + bad_values: tuple[str, ...], +) -> None: + base_args = { + "skill_command": "/autoskillit:make-groups", + "skill_inputs": {"source_doc": "/tmp/doc.md"}, + "cwd": "/tmp/ws", + } + findings = _identity_findings( + _make_recipe( + _RUN_SKILL_KEY, + "run_skill", + {**base_args, "step_name": effective_value}, + {**base_args, "step_name": declared_value}, + ) + ) + + assert len(findings) == 1 + finding = findings[0] + assert finding.severity is Severity.ERROR + assert finding.step_name == _RUN_SKILL_KEY + assert _RUN_SKILL_KEY in finding.message + for terms in map_terms: + assert any(term in finding.message for term in terms) + for value in bad_values: + assert value in finding.message + + +def test_divergent_non_skill_tool_identity_is_an_error() -> None: + args = {"step_name": "bootstrap_clone"} + findings = _identity_findings(_make_recipe("clone", "bootstrap_clone", args, dict(args))) + + assert len(findings) == 1 + assert findings[0].severity is Severity.ERROR + assert findings[0].step_name == "clone" + + +def test_target_step_reference_is_not_identity() -> None: + args = {"step_name": "some_other_step"} + recipe = _make_recipe("record_result", "record_pipeline_step", args, dict(args)) + + assert _identity_findings(recipe) == [] + + +def _identity_recipe_yaml(step_identity: str, *, guarded: bool) -> str: + ingredient_block = ( + "ingredients:\n" + " enabled:\n" + " description: Run the optional step.\n" + ' default: "false"\n' + " type: boolean\n" + if guarded + else "" + ) + guard_fields = ( + " optional: true\n skip_when_false: inputs.enabled\n on_skip: done_step\n" + if guarded + else "" + ) + return ( + "name: step-identity-pair\n" + "description: Paired control for step identity validation.\n" + "kitchen_rules:\n - Use declared routes.\n" + f"{ingredient_block}" + "steps:\n" + " run_step:\n" + " tool: run_cmd\n" + " with:\n" + " cmd: echo hi\n" + " cwd: /tmp\n" + f" step_name: {step_identity}\n" + f"{guard_fields}" + " on_success: done_step\n" + " on_failure: escalate\n" + " done_step:\n" + " action: stop\n" + " message: Emit the L3 sentinel block with success=true and reason=Completed.\n" + ) + + +def _stage_recipe_pair(tmp_path: Path, *, guarded: bool) -> tuple[Path, Path]: + project_dirs = (tmp_path / "control", tmp_path / "divergent") + for project_dir, identity in zip(project_dirs, ("run_step", "other_step"), strict=True): + recipes_dir = project_dir / ".autoskillit" / "recipes" + recipes_dir.mkdir(parents=True) + (recipes_dir / "step-identity-pair.yaml").write_text( + _identity_recipe_yaml(identity, guarded=guarded) + ) + return project_dirs + + +def _identity_suggestions(result: dict[str, Any]) -> list[dict[str, Any]]: + return [ + suggestion + for suggestion in result.get("suggestions", []) + if suggestion.get("rule") == RULE_NAME + ] + + +def test_identity_mismatch_alone_invalidates_a_recipe(tmp_path: Path) -> None: + control_project, divergent_project = _stage_recipe_pair(tmp_path, guarded=False) + + control = load_and_validate("step-identity-pair", project_dir=control_project) + divergent = load_and_validate("step-identity-pair", project_dir=divergent_project) + + assert control["valid"] is True, control.get("suggestions") + assert divergent["valid"] is False + assert any(finding.get("severity") == "error" for finding in _identity_suggestions(divergent)) + + +@pytest.mark.parametrize("enabled", [False, True], ids=["pruned", "retained"]) +def test_gated_identity_mismatch_is_rejected_before_pruning(tmp_path: Path, enabled: bool) -> None: + control_project, divergent_project = _stage_recipe_pair(tmp_path, guarded=True) + overrides = {"enabled": str(enabled).lower()} + control = load_and_validate( + "step-identity-pair", project_dir=control_project, ingredient_overrides=overrides + ) + divergent = load_and_validate( + "step-identity-pair", project_dir=divergent_project, ingredient_overrides=overrides + ) + identity_findings = _identity_suggestions(divergent) + + assert control["valid"] is True, control.get("suggestions") + assert divergent["valid"] is False + assert len(identity_findings) == 1 + assert identity_findings[0]["step"] == "run_step" + assert identity_findings[0]["severity"] == "error" diff --git a/tests/server/test_attestation_delivery_reachability.py b/tests/server/test_attestation_delivery_reachability.py index 50941aed3f..ab7ec63c1f 100644 --- a/tests/server/test_attestation_delivery_reachability.py +++ b/tests/server/test_attestation_delivery_reachability.py @@ -331,6 +331,19 @@ async def test_ready_recipe_load_uses_worker_cache_without_sharing_context( }, ), ("planner", "elaborate_phases", {"task": "test task", "source_dir": "."}), + ( + "research-implement", + "decompose_phases", + { + "task": "test task", + "source_dir": ".", + "worktree_path": "/tmp/autoskillit-step-identity/worktree", + "research_dir_rel": "research", + "research_dir": "/tmp/autoskillit-step-identity/worktree/research", + "experiment_plan": "/tmp/autoskillit-step-identity/experiment-plan.md", + "visualization_plan_path": "/tmp/autoskillit-step-identity/visualization-plan.md", + }, + ), ], indirect=True, ) diff --git a/tests/server/test_run_skill_docstring.py b/tests/server/test_run_skill_docstring.py index 0c22239939..250303e7fa 100644 --- a/tests/server/test_run_skill_docstring.py +++ b/tests/server/test_run_skill_docstring.py @@ -36,6 +36,12 @@ def test_docstring_routes_retry_through_recipe(self) -> None: assert "needs_retry" in docstring assert "recipe's declared retry route" in docstring + def test_step_name_doc_states_attested_key_requirement(self) -> None: + docstring = _run_skill_docstring() + step_name_doc = docstring.split("step_name:", 1)[1].split("\n order_id:", 1)[0] + assert "YAML step key" in step_name_doc + assert "attested" in step_name_doc + def test_docstring_has_positive_and_negative_selection_boundaries(self) -> None: docstring = _run_skill_docstring().casefold() assert "already-selected recipe step" in docstring From 981d58ad36fafa93366d05a4becb36787b3e18bb Mon Sep 17 00:00:00 2001 From: Trecek Date: Sat, 24 Oct 2026 08:33:58 -0700 Subject: [PATCH 02/14] test: distinguish step-key prose from embedded recipe YAML --- tests/cli/test_cook_order_prompt.py | 3 ++- tests/cli/test_food_truck_prompt.py | 4 +++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/tests/cli/test_cook_order_prompt.py b/tests/cli/test_cook_order_prompt.py index 10c5085a98..5cc79cbc99 100644 --- a/tests/cli/test_cook_order_prompt.py +++ b/tests/cli/test_cook_order_prompt.py @@ -2,6 +2,7 @@ from __future__ import annotations +import re import shutil from pathlib import Path from unittest.mock import MagicMock, patch @@ -263,7 +264,7 @@ def test_order_system_prompt_does_not_contain_recipe_yaml( assert "test-script" in system_prompt assert "--- RECIPE ---" not in system_prompt assert "--- END RECIPE ---" not in system_prompt - assert "steps:" not in system_prompt + assert re.search(r"(?m)^\s*steps:\s*$", system_prompt) is None assert "on_success:" not in system_prompt @patch("autoskillit.cli.subprocess.Popen") diff --git a/tests/cli/test_food_truck_prompt.py b/tests/cli/test_food_truck_prompt.py index e0bf869949..52e626cbac 100644 --- a/tests/cli/test_food_truck_prompt.py +++ b/tests/cli/test_food_truck_prompt.py @@ -98,7 +98,9 @@ def test_step_name_contract_is_in_delivered_section(self) -> None: assert "yaml step key" in section assert "even when" in section assert "`with:`" in section - assert "record_pipeline_step.step_name names the target tracked step" in section + assert "record_pipeline_step.step_name names the target tracked step" in section.replace( + "`", "" + ) assert "distinct yaml step keys remain separate telemetry rows" in section def test_excludes_five_sections(self) -> None: From 4f446725059fadd3e67389d146718e293d02ce7f Mon Sep 17 00:00:00 2001 From: Trecek Date: Sat, 24 Oct 2026 09:46:53 -0700 Subject: [PATCH 03/14] fix(review): share the step identity validation rule identifier --- .../recipe/api_orchestration/_api_orchestration_validate.py | 3 ++- src/autoskillit/recipe/rules/rules_tools.py | 5 +++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/src/autoskillit/recipe/api_orchestration/_api_orchestration_validate.py b/src/autoskillit/recipe/api_orchestration/_api_orchestration_validate.py index b651fbe193..794a13ad14 100644 --- a/src/autoskillit/recipe/api_orchestration/_api_orchestration_validate.py +++ b/src/autoskillit/recipe/api_orchestration/_api_orchestration_validate.py @@ -51,6 +51,7 @@ from autoskillit.recipe.ingredients._recipe_raw_repair import _resolve_skip_guards_in_content from autoskillit.recipe.registry import RuleFinding as _RuleFinding from autoskillit.recipe.rules.rules_plan_set_gate import STAGE_OBLIGATION_GATE_DOMINANCE_RULE +from autoskillit.recipe.rules.rules_tools import STEP_IDENTITY_MISMATCH_RULE from autoskillit.recipe.schema import Recipe, RecipeStep __all__ = ["_record_pipeline_error", "_run_validation_pipeline"] @@ -87,7 +88,7 @@ def _reconcile_semantic_findings( retained_pre_prune_findings = [ finding for finding in pre_prune_findings - if finding.rule == "step-identity-mismatch" + if finding.rule == STEP_IDENTITY_MISMATCH_RULE or ( finding.rule == STAGE_OBLIGATION_GATE_DOMINANCE_RULE and "cannot declare skip_when_false" in finding.message diff --git a/src/autoskillit/recipe/rules/rules_tools.py b/src/autoskillit/recipe/rules/rules_tools.py index 3f54e67b02..79aed09edf 100644 --- a/src/autoskillit/recipe/rules/rules_tools.py +++ b/src/autoskillit/recipe/rules/rules_tools.py @@ -28,6 +28,7 @@ logger = get_logger(__name__) _ALL_TOOLS: frozenset[str] = frozenset(TOOL_REGISTRY) +STEP_IDENTITY_MISMATCH_RULE = "step-identity-mismatch" # Registry of context variables that are captured upstream and MUST be forwarded # to any tool step that accepts them. Each entry maps a tool name to the set of @@ -205,7 +206,7 @@ def _check_dead_with_params(ctx: ValidationContext) -> list[RuleFinding]: @semantic_rule( - name="step-identity-mismatch", + name=STEP_IDENTITY_MISMATCH_RULE, description="A step's with: identity parameter must equal its YAML step key", severity=Severity.ERROR, ) @@ -229,7 +230,7 @@ def _check_step_identity(ctx: ValidationContext) -> list[RuleFinding]: if mismatches: findings.append( make_finding( - rule_name="step-identity-mismatch", + rule_name=STEP_IDENTITY_MISMATCH_RULE, step_name=key, message=f"step '{key}': {'; '.join(mismatches)} must equal " f"the YAML step key '{key}'", From 927811c8cc2ae3657e71ac1f1495de9a9e3190d4 Mon Sep 17 00:00:00 2001 From: Trecek Date: Sat, 24 Oct 2026 09:48:47 -0700 Subject: [PATCH 04/14] refactor(review): share the tool step identity parameter query --- src/autoskillit/core/types/recipe/_type_recipe_binding.py | 5 +++++ src/autoskillit/recipe/ingredients/_recipe_composition.py | 5 +---- src/autoskillit/recipe/rules/rules_tools.py | 5 +---- 3 files changed, 7 insertions(+), 8 deletions(-) diff --git a/src/autoskillit/core/types/recipe/_type_recipe_binding.py b/src/autoskillit/core/types/recipe/_type_recipe_binding.py index 2c2ec0f4bf..8b04ea4214 100644 --- a/src/autoskillit/core/types/recipe/_type_recipe_binding.py +++ b/src/autoskillit/core/types/recipe/_type_recipe_binding.py @@ -248,6 +248,11 @@ def _validate_recipe_delivery_outcome(self) -> None: def param_names(self) -> tuple[str, ...]: return tuple(param.name for param in self.params) + @property + def step_identity_params(self) -> tuple[ToolParamDef, ...]: + """Parameters carrying the invoking recipe step's YAML key.""" + return tuple(param for param in self.params if param.role is ToolParamRole.STEP_IDENTITY) + @property def param_set(self) -> frozenset[str]: return frozenset(self.param_names) diff --git a/src/autoskillit/recipe/ingredients/_recipe_composition.py b/src/autoskillit/recipe/ingredients/_recipe_composition.py index a22e6037e0..3acbb0f461 100644 --- a/src/autoskillit/recipe/ingredients/_recipe_composition.py +++ b/src/autoskillit/recipe/ingredients/_recipe_composition.py @@ -16,7 +16,6 @@ RECIPE_TERMINAL_TARGETS, SKILL_TOOLS, RecipeFlowEdge, - ToolParamRole, YAMLError, get_tool_def, load_yaml, @@ -390,9 +389,7 @@ def _rekey_composed_step( declared_with_args = dict(rewritten.declared_with_args or {}) tool_def = get_tool_def(step.tool) if step.tool else None if tool_def is not None: - for param in tool_def.params: - if param.role is not ToolParamRole.STEP_IDENTITY: - continue + for param in tool_def.step_identity_params: for args in (with_args, declared_with_args): if args.get(param.name) == old_key: args[param.name] = new_key diff --git a/src/autoskillit/recipe/rules/rules_tools.py b/src/autoskillit/recipe/rules/rules_tools.py index 79aed09edf..c5d40ded99 100644 --- a/src/autoskillit/recipe/rules/rules_tools.py +++ b/src/autoskillit/recipe/rules/rules_tools.py @@ -12,7 +12,6 @@ TOOL_SUBSET_TAGS, BindingFailureCode, Severity, - ToolParamRole, get_logger, get_tool_def, ) @@ -216,9 +215,7 @@ def _check_step_identity(ctx: ValidationContext) -> list[RuleFinding]: tool_def = get_tool_def(step.tool) if step.tool else None if tool_def is None: continue - for param in tool_def.params: - if param.role is not ToolParamRole.STEP_IDENTITY: - continue + for param in tool_def.step_identity_params: mismatches = [ f"{name}[{param.name!r}]={args[param.name]!r}" for name, args in ( From 086ba5c1afad78792bfd218321dac529c6a43ea1 Mon Sep 17 00:00:00 2001 From: Trecek Date: Sat, 24 Oct 2026 09:50:35 -0700 Subject: [PATCH 05/14] fix(review): target the step identity migration at the next release --- ....1289.yaml => 0.10.1288-to-0.10.1290.yaml} | 2 +- .../test_step_identity_migration_note.py | 20 +++++++++++++++++++ 2 files changed, 21 insertions(+), 1 deletion(-) rename src/autoskillit/migrations/{0.10.1288-to-0.10.1289.yaml => 0.10.1288-to-0.10.1290.yaml} (97%) create mode 100644 tests/migration/test_step_identity_migration_note.py diff --git a/src/autoskillit/migrations/0.10.1288-to-0.10.1289.yaml b/src/autoskillit/migrations/0.10.1288-to-0.10.1290.yaml similarity index 97% rename from src/autoskillit/migrations/0.10.1288-to-0.10.1289.yaml rename to src/autoskillit/migrations/0.10.1288-to-0.10.1290.yaml index f16d68f9c8..8b437e075d 100644 --- a/src/autoskillit/migrations/0.10.1288-to-0.10.1289.yaml +++ b/src/autoskillit/migrations/0.10.1288-to-0.10.1290.yaml @@ -1,5 +1,5 @@ from_version: "0.10.1288" -to_version: "0.10.1289" +to_version: "0.10.1290" description: Require each recipe step's with.step_name to match its YAML key. changes: - id: step-name-equals-step-key diff --git a/tests/migration/test_step_identity_migration_note.py b/tests/migration/test_step_identity_migration_note.py new file mode 100644 index 0000000000..9ba8d2971f --- /dev/null +++ b/tests/migration/test_step_identity_migration_note.py @@ -0,0 +1,20 @@ +"""The step identity migration reaches recipes on the preceding release.""" + +import pytest + +from autoskillit.migration.loader import applicable_migrations + +pytestmark = [pytest.mark.layer("migration"), pytest.mark.small] + + +@pytest.mark.parametrize("recipe_version", ["0.10.1288", "0.10.1289"]) +def test_step_identity_migration_applies_on_upgrade(recipe_version: str) -> None: + notes = applicable_migrations(recipe_version, "0.10.1290") + matching = [ + note + for note in notes + if any(change.id == "step-name-equals-step-key" for change in note.changes) + ] + + assert len(matching) == 1 + assert matching[0].to_version == "0.10.1290" From d547c1c4009559587d6454fb13c94ddcc0070156 Mon Sep 17 00:00:00 2001 From: Trecek Date: Sat, 24 Oct 2026 09:50:48 -0700 Subject: [PATCH 06/14] test(review): share the recipe identity suggestion helper --- tests/recipe/conftest.py | 10 ++++++++++ tests/recipe/test_composition_step_identity.py | 10 +--------- tests/recipe/test_rules_step_identity.py | 17 +++++++---------- 3 files changed, 18 insertions(+), 19 deletions(-) diff --git a/tests/recipe/conftest.py b/tests/recipe/conftest.py index 3cedc0abaf..c710cc1388 100644 --- a/tests/recipe/conftest.py +++ b/tests/recipe/conftest.py @@ -4,6 +4,7 @@ from collections.abc import Iterator from pathlib import Path +from typing import Any import pytest import yaml @@ -11,6 +12,7 @@ from autoskillit.core.types import Severity from autoskillit.recipe.io import _parse_step, builtin_recipes_dir, load_recipe from autoskillit.recipe.registry import RuleFinding +from autoskillit.recipe.rules.rules_tools import STEP_IDENTITY_MISMATCH_RULE from autoskillit.recipe.schema import Recipe, RecipeStep BUNDLED_RECIPE_NAMES: list[str] = [ @@ -22,6 +24,14 @@ ] +def identity_suggestions(result: dict[str, Any]) -> list[dict[str, Any]]: + return [ + suggestion + for suggestion in result.get("suggestions", []) + if suggestion.get("rule") == STEP_IDENTITY_MISMATCH_RULE + ] + + def assert_no_rule_errors( findings: list[RuleFinding], *, diff --git a/tests/recipe/test_composition_step_identity.py b/tests/recipe/test_composition_step_identity.py index c5d5512968..ae27154153 100644 --- a/tests/recipe/test_composition_step_identity.py +++ b/tests/recipe/test_composition_step_identity.py @@ -4,7 +4,6 @@ import shutil from pathlib import Path -from typing import Any import pytest @@ -12,6 +11,7 @@ from autoskillit.recipe.ingredients._recipe_composition import _build_active_recipe from autoskillit.recipe.ingredients._recipe_merge import _merge_sub_recipe from autoskillit.recipe.io import load_recipe +from tests.recipe.conftest import identity_suggestions as _identity_suggestions pytestmark = [pytest.mark.layer("recipe"), pytest.mark.small] @@ -36,14 +36,6 @@ def _install_composed_recipe(tmp_path: Path, *, child_identity: str | None) -> t return parent_path, child_path -def _identity_suggestions(result: dict[str, Any]) -> list[dict[str, Any]]: - return [ - suggestion - for suggestion in result.get("suggestions", []) - if suggestion.get("rule") == "step-identity-mismatch" - ] - - @pytest.mark.parametrize( ("child_identity", "declared"), [("child_step", True), (None, False)], diff --git a/tests/recipe/test_rules_step_identity.py b/tests/recipe/test_rules_step_identity.py index af495f4e1e..faea87e327 100644 --- a/tests/recipe/test_rules_step_identity.py +++ b/tests/recipe/test_rules_step_identity.py @@ -11,11 +11,12 @@ from autoskillit.recipe import make_validation_context from autoskillit.recipe._api import load_and_validate from autoskillit.recipe.registry import run_semantic_rules +from autoskillit.recipe.rules.rules_tools import STEP_IDENTITY_MISMATCH_RULE from autoskillit.recipe.schema import Recipe, RecipeStep +from tests.recipe.conftest import identity_suggestions as _identity_suggestions pytestmark = [pytest.mark.layer("recipe"), pytest.mark.small] -RULE_NAME = "step-identity-mismatch" _RUN_SKILL_KEY = "decompose_phases" @@ -42,7 +43,11 @@ def _make_recipe( def _identity_findings(recipe: Recipe): ctx = make_validation_context(recipe) - return [finding for finding in run_semantic_rules(ctx) if finding.rule == RULE_NAME] + return [ + finding + for finding in run_semantic_rules(ctx) + if finding.rule == STEP_IDENTITY_MISMATCH_RULE + ] @pytest.mark.parametrize( @@ -157,14 +162,6 @@ def _stage_recipe_pair(tmp_path: Path, *, guarded: bool) -> tuple[Path, Path]: return project_dirs -def _identity_suggestions(result: dict[str, Any]) -> list[dict[str, Any]]: - return [ - suggestion - for suggestion in result.get("suggestions", []) - if suggestion.get("rule") == RULE_NAME - ] - - def test_identity_mismatch_alone_invalidates_a_recipe(tmp_path: Path) -> None: control_project, divergent_project = _stage_recipe_pair(tmp_path, guarded=False) From f40bad495cf816075e26bfc583fb06b22ae145b4 Mon Sep 17 00:00:00 2001 From: Trecek Date: Sat, 24 Oct 2026 09:51:49 -0700 Subject: [PATCH 07/14] test(review): assert the offending step identity values precisely --- tests/recipe/test_rules_step_identity.py | 27 ++++++------------------ 1 file changed, 7 insertions(+), 20 deletions(-) diff --git a/tests/recipe/test_rules_step_identity.py b/tests/recipe/test_rules_step_identity.py index faea87e327..e09f783f13 100644 --- a/tests/recipe/test_rules_step_identity.py +++ b/tests/recipe/test_rules_step_identity.py @@ -51,28 +51,17 @@ def _identity_findings(recipe: Recipe): @pytest.mark.parametrize( - ("effective_value", "declared_value", "map_terms", "bad_values"), + ("effective_value", "declared_value", "mismatched_maps"), [ - ("decompose", "decompose", (("with", "effective"), ("declared",)), ("decompose",)), - ( - "decompose", - _RUN_SKILL_KEY, - (("with", "effective"),), - ("decompose",), - ), - ( - _RUN_SKILL_KEY, - "decompose", - (("declared",),), - ("decompose",), - ), + ("wrong_step", "wrong_step", ("with_args", "declared_with_args")), + ("wrong_step", _RUN_SKILL_KEY, ("with_args",)), + (_RUN_SKILL_KEY, "wrong_step", ("declared_with_args",)), ], ) def test_divergent_run_skill_identity_is_an_error( effective_value: str, declared_value: str, - map_terms: tuple[tuple[str, ...], ...], - bad_values: tuple[str, ...], + mismatched_maps: tuple[str, ...], ) -> None: base_args = { "skill_command": "/autoskillit:make-groups", @@ -93,10 +82,8 @@ def test_divergent_run_skill_identity_is_an_error( assert finding.severity is Severity.ERROR assert finding.step_name == _RUN_SKILL_KEY assert _RUN_SKILL_KEY in finding.message - for terms in map_terms: - assert any(term in finding.message for term in terms) - for value in bad_values: - assert value in finding.message + for map_name in mismatched_maps: + assert f"{map_name}['step_name']='wrong_step'" in finding.message def test_divergent_non_skill_tool_identity_is_an_error() -> None: From 8eea609d5fc4afcd811c6319301a85700e631942 Mon Sep 17 00:00:00 2001 From: Trecek Date: Sat, 24 Oct 2026 09:52:21 -0700 Subject: [PATCH 08/14] docs(review): clarify invoking step identity in tool parameters --- src/autoskillit/server/tools/tools_clone.py | 12 ++++++++---- src/autoskillit/server/tools/tools_git.py | 6 ++++-- src/autoskillit/server/tools/tools_github.py | 3 ++- src/autoskillit/server/tools/tools_workspace.py | 6 ++++-- 4 files changed, 18 insertions(+), 9 deletions(-) diff --git a/src/autoskillit/server/tools/tools_clone.py b/src/autoskillit/server/tools/tools_clone.py index 4beba38d39..9d175607e2 100644 --- a/src/autoskillit/server/tools/tools_clone.py +++ b/src/autoskillit/server/tools/tools_clone.py @@ -63,7 +63,8 @@ async def clone_repo( via 'git remote set-url origin' after cloning, absorbing the need for a separate git remote set-url step. Empty string (default) uses the source repo's detected origin. - step_name: Optional YAML step key for wall-clock timing accumulation. + step_name: When called from a recipe, the invoking step's YAML key for timing. + Optional for direct calls. SOURCE ISOLATION: Once this tool returns, source_dir must not be touched for any purpose except reading its remote URL in push_to_remote. Never run git @@ -152,7 +153,8 @@ async def remove_clone( Args: clone_path: Absolute path to the clone directory to remove. keep: Pass "true" to preserve the directory (debugging). Default "false". - step_name: Optional YAML step key for wall-clock timing accumulation. + step_name: When called from a recipe, the invoking step's YAML key for timing. + Optional for direct calls. infrastructure_fault_override_reason: Required to proceed when the most recently completed step ended in an infrastructure fault. Absent by default so refusal is the default path, not an opt-in. @@ -335,7 +337,8 @@ async def register_clone_status( yet confirmed — in-progress label is retained on the issue). registry_path: Absolute path to the shared registry file. Defaults to .autoskillit/temp/clone-cleanup-registry.json in cwd. - step_name: Optional YAML step key for wall-clock timing accumulation. + step_name: When called from a recipe, the invoking step's YAML key for timing. + Optional for direct calls. Never raises. """ @@ -430,7 +433,8 @@ async def batch_cleanup_clones( all success-status entries including legacy orphans. owner_filter: Explicit owner string for campaign-scoped cleanup. When non-empty, overrides kitchen_id scoping. Ignored when all_owners="true". - step_name: Optional YAML step key for wall-clock timing accumulation. + step_name: When called from a recipe, the invoking step's YAML key for timing. + Optional for direct calls. """ try: if (gate := _require_enabled()) is not None: diff --git a/src/autoskillit/server/tools/tools_git.py b/src/autoskillit/server/tools/tools_git.py index fade8a2808..d17d324a49 100644 --- a/src/autoskillit/server/tools/tools_git.py +++ b/src/autoskillit/server/tools/tools_git.py @@ -136,7 +136,8 @@ async def classify_fix( Args: worktree_path: Path to the git worktree with the implemented fix. base_branch: The branch the worktree was created from (for merge-base). - step_name: Optional YAML step key for wall-clock timing accumulation. + step_name: When called from a recipe, the invoking step's YAML key for timing. + Optional for direct calls. Never raises. """ @@ -305,7 +306,8 @@ async def create_unique_branch( remote: Git remote to check for existing branches (default: "origin"). base_branch_name: When provided, use this directly as the base name instead of composing from slug+issue_number. - step_name: Optional YAML step key for wall-clock timing accumulation. + step_name: When called from a recipe, the invoking step's YAML key for timing. + Optional for direct calls. Never raises. """ diff --git a/src/autoskillit/server/tools/tools_github.py b/src/autoskillit/server/tools/tools_github.py index f542530b17..0da3517c98 100644 --- a/src/autoskillit/server/tools/tools_github.py +++ b/src/autoskillit/server/tools/tools_github.py @@ -211,7 +211,8 @@ async def report_bug( cwd: Working directory for the headless session. severity: "non_blocking" (fire-and-forget) or "blocking" (await completion). model: Model override. Empty string = config default. - step_name: Optional YAML step key; groups token usage under that step. + step_name: When called from a recipe, the invoking step's YAML key for token usage. + Optional for direct calls. Never raises. """ diff --git a/src/autoskillit/server/tools/tools_workspace.py b/src/autoskillit/server/tools/tools_workspace.py index f93bd3601a..939551aa50 100644 --- a/src/autoskillit/server/tools/tools_workspace.py +++ b/src/autoskillit/server/tools/tools_workspace.py @@ -351,7 +351,8 @@ async def commit_files( paths: List of file paths (relative to cwd) to stage and commit. message: Commit message. cwd: Absolute path to the git worktree. - step_name: Optional YAML step key for wall-clock timing accumulation. + step_name: When called from a recipe, the invoking step's YAML key for timing. + Optional for direct calls. self_revert_base_sha: Optional ancestor commit from which to scan for inverse hunks. Never raises. @@ -456,7 +457,8 @@ async def reset_test_dir( test_dir: Path to the test directory to clear. Must contain the reset guard marker. force: Override the marker check. When True, all contents are deleted including the marker file itself. - step_name: Optional YAML step key for wall-clock timing accumulation. + step_name: When called from a recipe, the invoking step's YAML key for timing. + Optional for direct calls. Never raises. """ From 4c650e4e5a94248cd93e1944f575622730cef028 Mon Sep 17 00:00:00 2001 From: Trecek Date: Sat, 24 Oct 2026 09:52:50 -0700 Subject: [PATCH 09/14] docs(review): consolidate step identity guidance and explain telemetry grouping --- src/autoskillit/skills/sous-chef/SKILL.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/autoskillit/skills/sous-chef/SKILL.md b/src/autoskillit/skills/sous-chef/SKILL.md index c7fe440e48..f6e71814b1 100644 --- a/src/autoskillit/skills/sous-chef/SKILL.md +++ b/src/autoskillit/skills/sous-chef/SKILL.md @@ -539,9 +539,9 @@ that target's YAML key rather than the invoking tool-step key. **NEVER** append clone numbers, instance indices, retry counts, or any other disambiguation strings. -Repeated executions of the same YAML step key use that key without clone or retry -suffixes. Distinct YAML step keys remain separate telemetry rows, even when they -invoke the same skill. +The telemetry layer aggregates invocations of the same logical step automatically; +suffixes fragment its token and timing rows. Distinct YAML step keys remain separate +telemetry rows, even when they invoke the same skill. Correct: ```yaml @@ -562,8 +562,8 @@ parallel run of the same step reports under the same canonical step name. ## PARAMETER FORWARDING — step_name, output_dir -Always pass the step's YAML key as the `step_name` parameter of `run_skill`. This -enables ingredient lock enforcement, pipeline dependency checks, and all per-step +The STEP NAME IMMUTABILITY rule above enables ingredient lock enforcement, +pipeline dependency checks, and all per-step parameter auto-fills. Omitting it degrades enforcement and may cause the call to be denied when locks are active. From bd8301e39bfeebb6943556ec8e22bfa3ba62ff34 Mon Sep 17 00:00:00 2001 From: Trecek Date: Sat, 24 Oct 2026 09:53:28 -0700 Subject: [PATCH 10/14] test(review): cover missing and ambiguous recipe step identities --- ...st_attested_param_admission_conformance.py | 21 +++++++++++++++++++ tests/server/test_run_skill_docstring.py | 10 ++++++++- .../test_tools_execution_step_resolution.py | 15 +++++++++++++ 3 files changed, 45 insertions(+), 1 deletion(-) diff --git a/tests/server/test_attested_param_admission_conformance.py b/tests/server/test_attested_param_admission_conformance.py index 87d8acb0a2..de1961f668 100644 --- a/tests/server/test_attested_param_admission_conformance.py +++ b/tests/server/test_attested_param_admission_conformance.py @@ -50,6 +50,27 @@ def _write_tracker_for(ready) -> None: ) +async def test_attested_call_without_step_name_is_denied(tool_ctx_ready_recipe, tmp_path) -> None: + from autoskillit.server.tools.tools_execution import run_skill + from tests.fakes import InMemoryHeadlessExecutor + + ready = tool_ctx_ready_recipe + executor = InMemoryHeadlessExecutor() + ready.tool_ctx.executor = executor + result = json.loads( + await run_skill( + ready.with_args["skill_command"], + str(tmp_path), + recipe_execution_id=ready.credential["execution_id"], + invocation_template_digest=ready.template_digest, + ) + ) + + assert result["stage"] == "preflight:recipe_execution" + assert "recipe_execution_step_missing" in json.dumps(result) + assert not executor.calls + + @pytest.mark.parametrize("param_name", sorted(_DENIAL_TEST_VALUES)) async def test_forwarding_execution_tuning_param_is_denied_with_actionable_message( param_name: str, diff --git a/tests/server/test_run_skill_docstring.py b/tests/server/test_run_skill_docstring.py index 250303e7fa..54d6cc18ea 100644 --- a/tests/server/test_run_skill_docstring.py +++ b/tests/server/test_run_skill_docstring.py @@ -2,6 +2,8 @@ from __future__ import annotations +import inspect + import pytest pytestmark = [pytest.mark.layer("server"), pytest.mark.small] @@ -38,7 +40,13 @@ def test_docstring_routes_retry_through_recipe(self) -> None: def test_step_name_doc_states_attested_key_requirement(self) -> None: docstring = _run_skill_docstring() - step_name_doc = docstring.split("step_name:", 1)[1].split("\n order_id:", 1)[0] + args = inspect.cleandoc(docstring).split("\nArgs:\n", 1)[1] + parameter_lines = args.split("\n step_name:", 1)[1].splitlines() + step_name_doc = parameter_lines[0] + for line in parameter_lines[1:]: + if line and not line.startswith(" "): + break + step_name_doc += "\n" + line assert "YAML step key" in step_name_doc assert "attested" in step_name_doc diff --git a/tests/server/test_tools_execution_step_resolution.py b/tests/server/test_tools_execution_step_resolution.py index a452ee4bbe..9ab13a9c52 100644 --- a/tests/server/test_tools_execution_step_resolution.py +++ b/tests/server/test_tools_execution_step_resolution.py @@ -34,6 +34,21 @@ def _install_active_step(ctx, step) -> None: ctx.active_recipe_steps = {step.name: step for step in projection.ordered_steps} +@pytest.mark.parametrize("ambiguous", [False, True], ids=["unique", "ambiguous"]) +def test_step_name_inference_requires_a_unique_command_prefix(ambiguous: bool) -> None: + names = ("verify", "verify_again") if ambiguous else ("verify",) + active = { + name: FinalizedRecipeStep( + name=name, tool="run_skill", with_args={"skill_command": "/dry-walkthrough old-plan"} + ) + for name in names + } + + result = tools_execution._resolve_step_name_from_recipe("/dry-walkthrough new-plan", active) + + assert result == (("", True) if ambiguous else ("verify", False)) + + @pytest.mark.anyio async def test_run_skill_resolves_output_dir_from_recipe_step( tool_ctx_kitchen_open, monkeypatch, tmp_path From 1bf0b67dfd57d82db0f8653cb9de0e639c4808f2 Mon Sep 17 00:00:00 2001 From: Trecek Date: Sat, 24 Oct 2026 09:54:01 -0700 Subject: [PATCH 11/14] test(review): retain the delivered step identity contract without duplicate prose checks --- .../test_sous_chef_parameter_forwarding.py | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/tests/contracts/test_sous_chef_parameter_forwarding.py b/tests/contracts/test_sous_chef_parameter_forwarding.py index b48a9c7973..1a293fc948 100644 --- a/tests/contracts/test_sous_chef_parameter_forwarding.py +++ b/tests/contracts/test_sous_chef_parameter_forwarding.py @@ -54,16 +54,3 @@ def test_sous_chef_skill_md_mentions_step_name(): "The LLM must be instructed to forward step_name from recipe " "step with: blocks to run_skill for lock enforcement." ) - - -def test_step_name_immutability_requires_the_yaml_key() -> None: - skill_md = ( - Path(__file__).parents[2] / "src/autoskillit/skills/sous-chef/SKILL.md" - ).read_text() - start = skill_md.index("## STEP NAME IMMUTABILITY") - end = skill_md.find("\n## ", start + 1) - section = skill_md[start : end if end >= 0 else None] - - assert "YAML key" in section - assert "even when" in section - assert "`with:`" in section From a898800f0d7455c910e6ee7241d7d8364893787e Mon Sep 17 00:00:00 2001 From: Trecek Date: Sat, 24 Oct 2026 10:04:59 -0700 Subject: [PATCH 12/14] fix(review): preserve the delivered telemetry contract phrase --- src/autoskillit/skills/sous-chef/SKILL.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/autoskillit/skills/sous-chef/SKILL.md b/src/autoskillit/skills/sous-chef/SKILL.md index f6e71814b1..d07a8f070c 100644 --- a/src/autoskillit/skills/sous-chef/SKILL.md +++ b/src/autoskillit/skills/sous-chef/SKILL.md @@ -540,8 +540,9 @@ that target's YAML key rather than the invoking tool-step key. **NEVER** append clone numbers, instance indices, retry counts, or any other disambiguation strings. The telemetry layer aggregates invocations of the same logical step automatically; -suffixes fragment its token and timing rows. Distinct YAML step keys remain separate -telemetry rows, even when they invoke the same skill. +suffixes fragment its token and timing rows. +Distinct YAML step keys remain separate telemetry rows, even when they +invoke the same skill. Correct: ```yaml From 1a546842eca03edc1cb09020e546e01cc2b99846 Mon Sep 17 00:00:00 2001 From: Trecek Date: Sat, 24 Oct 2026 11:00:57 -0700 Subject: [PATCH 13/14] test: retire resolved step identity admission replay bridges --- .../server/test_attested_admission_replay.py | 36 ------------------- 1 file changed, 36 deletions(-) diff --git a/tests/server/test_attested_admission_replay.py b/tests/server/test_attested_admission_replay.py index 28bce5bbb3..fe52d281bd 100644 --- a/tests/server/test_attested_admission_replay.py +++ b/tests/server/test_attested_admission_replay.py @@ -108,42 +108,6 @@ reason="Blocked by #5306: merge item placeholders compile as static inputs", ), ), - ("research-implement", "decompose_phases"): pytest.param( - "research-implement", - "decompose_phases", - "recipe_execution_step_mismatch", - "step is not present in the active compiled execution", - id="research-implement-decompose_phases", - marks=pytest.mark.xfail( - strict=True, - raises=AdmissionDefect, - reason="Blocked by #5305: delivered step_name differs from the recipe step key", - ), - ), - ("research-implement", "adjust_experiment"): pytest.param( - "research-implement", - "adjust_experiment", - "recipe_execution_step_mismatch", - "step is not present in the active compiled execution", - id="research-implement-adjust_experiment", - marks=pytest.mark.xfail( - strict=True, - raises=AdmissionDefect, - reason="Blocked by #5305: delivered step_name differs from the recipe step key", - ), - ), - ("research-implement", "fix_tests"): pytest.param( - "research-implement", - "fix_tests", - "recipe_execution_step_mismatch", - "step is not present in the active compiled execution", - id="research-implement-fix_tests", - marks=pytest.mark.xfail( - strict=True, - raises=AdmissionDefect, - reason="Blocked by #5305: delivered step_name differs from the recipe step key", - ), - ), ("bem-wrapper", "run_bem"): pytest.param( "bem-wrapper", "run_bem", From 0036be19969687cc64f280ab1032767a7def1188 Mon Sep 17 00:00:00 2001 From: Trecek Date: Sat, 24 Oct 2026 11:00:59 -0700 Subject: [PATCH 14/14] fix: carry the step identity migration past the updated base release --- ...0.1288-to-0.10.1290.yaml => 0.10.1288-to-0.10.1291.yaml} | 2 +- tests/migration/test_step_identity_migration_note.py | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) rename src/autoskillit/migrations/{0.10.1288-to-0.10.1290.yaml => 0.10.1288-to-0.10.1291.yaml} (97%) diff --git a/src/autoskillit/migrations/0.10.1288-to-0.10.1290.yaml b/src/autoskillit/migrations/0.10.1288-to-0.10.1291.yaml similarity index 97% rename from src/autoskillit/migrations/0.10.1288-to-0.10.1290.yaml rename to src/autoskillit/migrations/0.10.1288-to-0.10.1291.yaml index 8b437e075d..5c3c5ff16c 100644 --- a/src/autoskillit/migrations/0.10.1288-to-0.10.1290.yaml +++ b/src/autoskillit/migrations/0.10.1288-to-0.10.1291.yaml @@ -1,5 +1,5 @@ from_version: "0.10.1288" -to_version: "0.10.1290" +to_version: "0.10.1291" description: Require each recipe step's with.step_name to match its YAML key. changes: - id: step-name-equals-step-key diff --git a/tests/migration/test_step_identity_migration_note.py b/tests/migration/test_step_identity_migration_note.py index 9ba8d2971f..014817e7c7 100644 --- a/tests/migration/test_step_identity_migration_note.py +++ b/tests/migration/test_step_identity_migration_note.py @@ -7,9 +7,9 @@ pytestmark = [pytest.mark.layer("migration"), pytest.mark.small] -@pytest.mark.parametrize("recipe_version", ["0.10.1288", "0.10.1289"]) +@pytest.mark.parametrize("recipe_version", ["0.10.1288", "0.10.1289", "0.10.1290"]) def test_step_identity_migration_applies_on_upgrade(recipe_version: str) -> None: - notes = applicable_migrations(recipe_version, "0.10.1290") + notes = applicable_migrations(recipe_version, "0.10.1291") matching = [ note for note in notes @@ -17,4 +17,4 @@ def test_step_identity_migration_applies_on_upgrade(recipe_version: str) -> None ] assert len(matching) == 1 - assert matching[0].to_version == "0.10.1290" + assert matching[0].to_version == "0.10.1291"