Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .autoskillit/recipes/eval/agent-eval.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,7 @@ steps:
provider: minimax
with:
skill_command: "placeholder — see note for orchestration logic"
cwd: "${{ inputs.source_dir }}"
on_success: compile_scorecard
on_failure: escalate
note: >-
Expand Down
3 changes: 2 additions & 1 deletion .autoskillit/recipes/eval/skill-eval.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ ingredients:
required: true
source_dir:
description: Path to the source project directory (for judge-eval CWD).
default: ""
required: true
output_dir:
description: >-
Base directory for eval run output. Defaults to
Expand Down Expand Up @@ -76,6 +76,7 @@ steps:
tool: run_skill
with:
skill_command: "placeholder — see note for orchestration logic"
cwd: "${{ inputs.source_dir }}"
on_success: compile_scorecard
on_failure: escalate
note: >-
Expand Down
2 changes: 1 addition & 1 deletion docs/recipes/authoring.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ The rule families live in `src/autoskillit/recipe/rules_*.py` (28 files):
| `rules_skill_content.py` | SKILL.md bash-block placeholder validation (`undefined-bash-placeholder`) |
| `rules_temp_path.py` | Temp-path hygiene: steps that write to paths outside `.autoskillit/temp/` |
| `rules_skills.py` | `skill_command` resolvability against the bundled skill registry (`unknown-skill-command`) |
| `rules_tools.py` | MCP tool name and parameter validity (`unknown-tool`, `dead-with-param`) |
| `rules_tools.py` | MCP tool name and parameter validity (`unknown-tool`, `dead-with-param`, `invalid-tool-invocation-binding`) |
| `rules_verdict.py` | Skill verdict routing completeness — every emitted verdict value must be routed |
| `rules_worktree.py` | Worktree retry lifecycle — every step that creates a worktree must have a downstream merge or cleanup |

Expand Down
4 changes: 4 additions & 0 deletions docs/recipes/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,12 +127,16 @@ ingredients:
task:
description: What to do
required: true
source_dir:
description: Absolute path to the repository root
required: true

steps:
step_one:
tool: run_skill
with:
skill_command: "/autoskillit:investigate ${{ inputs.task }}"
cwd: "${{ inputs.source_dir }}"
capture:
investigation_path: "${{ result.investigation_path }}"
on_success: done
Expand Down
1 change: 1 addition & 0 deletions src/autoskillit/cli/prompts/_prompts_kitchen.py
Original file line number Diff line number Diff line change
Expand Up @@ -298,6 +298,7 @@ def _build_fleet_dispatch_prompt(
ingredients={{
"issue_urls": "<comma-separated issue URLs>",
"base_branch": "<target branch, e.g. main>",
"source_dir": "{project_root}",
}},
capture={{"execution_map": "${{{{ result.execution_map }}}}"}},
dispatch_name="bem-pre-step",
Expand Down
22 changes: 11 additions & 11 deletions src/autoskillit/core/tool_registry.py
Original file line number Diff line number Diff line change
Expand Up @@ -75,10 +75,7 @@ def food_truck_visibility_tags(packs: Collection[str] | None) -> tuple[str, ...]
"delegate_evidence_reader",
("role", "role_data"),
required=("role", "role_data"),
wire_types={
"role": ToolWireType.STRING,
"role_data": ToolWireType.OBJECT,
},
wire_types={"role": ToolWireType.STRING, "role_data": ToolWireType.OBJECT},
),
_tool(
"read_authorized_artifact",
Expand All @@ -89,10 +86,7 @@ def food_truck_visibility_tags(packs: Collection[str] | None) -> tuple[str, ...]
"get_authorized_artifact_page",
("continuation", "page_size"),
required=("continuation",),
wire_types={
"continuation": ToolWireType.STRING,
"page_size": ToolWireType.INTEGER,
},
wire_types={"continuation": ToolWireType.STRING, "page_size": ToolWireType.INTEGER},
),
_tool("unlock_agent_pack", ("pack_name",), required=("pack_name",)),
_tool(
Expand Down Expand Up @@ -380,7 +374,7 @@ def food_truck_visibility_tags(packs: Collection[str] | None) -> tuple[str, ...]
"commit_files",
("paths", "message", "cwd", "step_name", "self_revert_base_sha"),
required=("paths", "message", "cwd"),
wire_types={"self_revert_base_sha": ToolWireType.STRING},
wire_types={"paths": ToolWireType.ARRAY, "self_revert_base_sha": ToolWireType.STRING},
),
_tool(
"write_audit_semantic_result",
Expand Down Expand Up @@ -459,6 +453,7 @@ def food_truck_visibility_tags(packs: Collection[str] | None) -> tuple[str, ...]
"prepare_issue",
("title", "body", "repo", "labels", "dry_run", "split"),
required=("title", "body"),
wire_types={"labels": ToolWireType.ARRAY},
),
_tool("claim_issue", ("issue_url", "label", "allow_reentry"), required=("issue_url",)),
_tool(
Expand Down Expand Up @@ -492,7 +487,11 @@ def food_truck_visibility_tags(packs: Collection[str] | None) -> tuple[str, ...]
("project_dir", "_autoskillit_exploration_request_token"),
roles={"_autoskillit_exploration_request_token": ToolParamRole.ORCHESTRATOR_SCOPING},
),
_tool("lock_ingredients", ("locked", "pipeline_id", "unlock")),
_tool(
"lock_ingredients",
("locked", "pipeline_id", "unlock"),
wire_types={"locked": ToolWireType.OBJECT, "unlock": ToolWireType.ARRAY},
),
_tool(
"declare_join_batch",
("skill_name", "assignments", "session_id", "top_level_parent"),
Expand All @@ -517,6 +516,7 @@ def food_truck_visibility_tags(packs: Collection[str] | None) -> tuple[str, ...]
"record_pipeline_step",
("pipeline_id", "op", "dependencies", "step_name"),
roles={"step_name": ToolParamRole.CHILD_INPUT},
wire_types={"dependencies": ToolWireType.OBJECT},
),
_tool("get_pr_reviews", ("pr_number", "cwd", "repo"), required=("pr_number", "cwd")),
_verify_review_receipt(),
Expand Down Expand Up @@ -637,7 +637,7 @@ def food_truck_visibility_tags(packs: Collection[str] | None) -> tuple[str, ...]
"read_db",
("db_path", "query", "params", "timeout"),
required=("db_path", "query"),
wire_types={"params": ToolWireType.ARRAY},
wire_types={"params": ToolWireType.STRING},
),
_tool(
"test_check",
Expand Down
31 changes: 31 additions & 0 deletions src/autoskillit/migrations/0.0.0-to-0.10.1293.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
from_version: "0.0.0"
to_version: "0.10.1293"
description: "Declare required tool parameters and match registered wire types."
changes:
- id: required-tool-parameters-declared
description: >-
Quoted numerals and booleans on INTEGER and BOOLEAN parameters, such as
stale_threshold: "30", are now rejected even where FastMCP previously coerced
them. Recipe validation also rejects missing required tool parameters and
values with the wrong wire shape before execution. Whole-value ${{ }} templates
on list or mapping parameters were already invalid at runtime and now receive
an earlier validation error.
instruction: >-
Write integer and boolean literals without quotes. Add cwd (usually
"${{ inputs.source_dir }}") under with: for every run_skill and run_cmd step,
and callable for every run_python step. When using inputs.source_dir, declare
source_dir as a required ingredient for the repository root path; alternatively,
bind cwd to another declared input containing the intended worktree path.
Supply actual lists or mappings for
ARRAY and OBJECT parameters, then run validate_recipe.
example_before: |
run:
tool: run_cmd
with:
cmd: git status
example_after: |
run:
tool: run_cmd
with:
cmd: git status
cwd: "${{ inputs.source_dir }}"
11 changes: 9 additions & 2 deletions src/autoskillit/recipe/api/_api_listing.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,10 @@
)
from autoskillit.recipe.analysis._analysis import make_validation_context
from autoskillit.recipe.contracts.contracts import load_recipe_card, validate_recipe_cards
from autoskillit.recipe.helpers._rule_helpers import filter_pruning_false_positives
from autoskillit.recipe.helpers._rule_helpers import (
filter_pruning_false_positives,
retain_declaration_findings,
)
from autoskillit.recipe.ingredients._recipe_composition import _prune_skipped_steps
from autoskillit.recipe.ingredients._recipe_ingredients import RecipeListItem
from autoskillit.recipe.io import (
Expand Down Expand Up @@ -178,6 +181,8 @@ def validate_from_path(
# this rule. The filter remains useful for other rules like
# dead-output where pruning genuinely introduces new findings.
semantic_findings = filter_pruning_false_positives(semantic_findings, _pre_prune_findings)
if ingredient_overrides:
semantic_findings = retain_declaration_findings(semantic_findings, _pre_prune_findings)

quality = build_quality_dict(report)
semantic = findings_to_dicts(semantic_findings)
Expand All @@ -189,7 +194,9 @@ def validate_from_path(
if contract:
contract_findings = validate_recipe_cards(recipe, contract)

valid = compute_recipe_validity(errors, semantic_findings, contract_findings)
valid = compute_recipe_validity(
errors, semantic_findings, contract_findings, binding_projection=ctx.binding_projection
)

return {
"valid": valid,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,10 @@
_LoadPipelineInputs,
_ValidationResult,
)
from autoskillit.recipe.helpers._rule_helpers import filter_pruning_false_positives
from autoskillit.recipe.helpers._rule_helpers import (
filter_pruning_false_positives,
retain_declaration_findings,
)
from autoskillit.recipe.ingredients._recipe_composition import (
_analysis_edges_from_effective_routes,
_assert_content_integrity,
Expand All @@ -51,15 +54,13 @@
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"]


def _reconcile_semantic_findings(
semantic_findings: list[_RuleFinding],
semantic_suggestions: list[dict[str, Any]],
*,
pre_prune_findings: list[_RuleFinding],
skip_resolutions: dict[str, bool | None],
Expand All @@ -69,7 +70,6 @@ def _reconcile_semantic_findings(
"""Reconcile pruning diagnostics and suppress displayed version findings."""
if skip_resolutions and any(value is not True for value in skip_resolutions.values()):
semantic_findings = filter_pruning_false_positives(semantic_findings, pre_prune_findings)
semantic_suggestions = _orch.findings_to_dicts(semantic_findings)
graph_aware_rules = {"capture-inversion-detection", "dead-output"}
pre_prune_keys = {(finding.rule, finding.step_name) for finding in pre_prune_findings}
for finding in semantic_findings:
Expand All @@ -85,14 +85,12 @@ def _reconcile_semantic_findings(
message=finding.message,
)

semantic_findings = retain_declaration_findings(semantic_findings, pre_prune_findings)
retained_pre_prune_findings = [
finding
for finding in pre_prune_findings
if finding.rule == STEP_IDENTITY_MISMATCH_RULE
or (
finding.rule == STAGE_OBLIGATION_GATE_DOMINANCE_RULE
and "cannot declare skip_when_false" in finding.message
)
if 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
Expand All @@ -102,8 +100,7 @@ def _reconcile_semantic_findings(
for finding in retained_pre_prune_findings
if (finding.rule, finding.step_name, finding.message) not in retained_keys
)
if retained_pre_prune_findings:
semantic_suggestions = _orch.findings_to_dicts(semantic_findings)
semantic_suggestions = _orch.findings_to_dicts(semantic_findings)

if recipe_name in (suppressed or ()):
from autoskillit.recipe.validator import filter_version_rule
Expand Down Expand Up @@ -314,11 +311,9 @@ def _run_validation_pipeline(
effective_routing_edges=_effective_analysis_edges,
)
semantic_findings = _orch.run_semantic_rules(val_ctx)
semantic_suggestions = _orch.findings_to_dicts(semantic_findings)
t0 = _orch._t("semantic_rules", t0, name)
semantic_findings, semantic_suggestions = _reconcile_semantic_findings(
semantic_findings,
semantic_suggestions,
pre_prune_findings=_pre_prune_findings,
skip_resolutions=_skip_resolutions,
recipe_name=name,
Expand Down Expand Up @@ -358,7 +353,9 @@ def _run_validation_pipeline(
if check_diagram_staleness(name, recipes_dir, match.path):
suggestions.extend(diagram_stale_to_suggestions(name))
t0 = _orch._t("diagram", t0, name)
valid = _orch.compute_recipe_validity(errors, semantic_findings, contract_findings)
valid = _orch.compute_recipe_validity(
errors, semantic_findings, contract_findings, binding_projection=_post_prune_bindings
)

except YAMLError as exc:
_orch.logger.warning("Recipe YAML parse error", name=name, exc_info=True)
Expand Down
12 changes: 12 additions & 0 deletions src/autoskillit/recipe/helpers/_rule_helpers.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@

from autoskillit.core import get_logger
from autoskillit.recipe.analysis._analysis import ValidationContext
from autoskillit.recipe.registry import declaration_scoped_rule_names
from autoskillit.recipe.schema import (
extract_sentinel_json_blocks,
)
Expand Down Expand Up @@ -236,6 +237,17 @@ def _identify_optional_output_fields(contract: SkillContract) -> set[str]:
return optional


def retain_declaration_findings(
post_prune_findings: list[RuleFinding],
pre_prune_findings: list[RuleFinding],
) -> list[RuleFinding]:
"""Keep declaration diagnostics from the original recipe, including pruned steps."""
declaration_rules = declaration_scoped_rule_names()
return [f for f in post_prune_findings if f.rule not in declaration_rules] + [
f for f in pre_prune_findings if f.rule in declaration_rules
]


def filter_pruning_false_positives(
post_prune_findings: list[RuleFinding],
pre_prune_findings: list[RuleFinding],
Expand Down
38 changes: 34 additions & 4 deletions src/autoskillit/recipe/registry.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
from collections.abc import Callable
from dataclasses import dataclass

from autoskillit.core import Severity
from autoskillit.core import RecipeBindingProjection, Severity

# Imported at module level for type annotations (no circular import: _analysis.py does
# not import registry.py). The runtime isinstance() check in run_semantic_rules also
Expand Down Expand Up @@ -54,6 +54,7 @@ class RuleDef:
description: str
severity: Severity
check: Callable[[ValidationContext], list[RuleFinding]]
declaration_scoped: bool = False


_RULE_REGISTRY: list[RuleDef] = []
Expand Down Expand Up @@ -89,6 +90,8 @@ def semantic_rule(
name: str,
description: str,
severity: Severity = Severity.WARNING,
*,
declaration_scoped: bool = False,
) -> Callable:
"""Decorator that registers a semantic validation rule."""

Expand All @@ -100,13 +103,29 @@ def decorator(
return fn
raise RuntimeError(f"Cannot register rule {name!r} after registry finalization")
_RULE_REGISTRY.append(
RuleDef(name=name, description=description, severity=severity, check=fn)
RuleDef(
name=name,
description=description,
severity=severity,
check=fn,
declaration_scoped=declaration_scoped,
)
)
return fn

return decorator


def declaration_scoped_rule_names() -> frozenset[str]:
"""Return rules that validate declarations independently of surviving pruning.

Their pre-prune findings are authoritative because that pass sees every
declared step. Finding text may describe the unpruned context, such as the
prior captures suggested by ``missing-ingredient``.
"""
return frozenset(rule.name for rule in _RULE_REGISTRY if rule.declaration_scoped)


def make_finding(
rule_name: str,
step_name: str,
Expand Down Expand Up @@ -257,9 +276,20 @@ def compute_recipe_validity(
errors: list[str],
semantic_findings: list[RuleFinding],
contract_findings: list[dict],
*,
binding_projection: RecipeBindingProjection,
) -> bool:
"""Return True if no schema, semantic, or contract errors are present."""
"""Require no errors and an installable post-prune binding projection.

This projection is the object ``build_recipe_execution_snapshot`` installs,
so validity includes installability.
"""
has_schema_errors = bool(errors)
has_semantic_errors = any(f.severity == Severity.ERROR for f in semantic_findings)
has_contract_errors = any(f.get("severity") == "error" for f in contract_findings)
return not has_schema_errors and not has_semantic_errors and not has_contract_errors
return (
not has_schema_errors
and not has_semantic_errors
and not has_contract_errors
and not binding_projection.failures
)
4 changes: 2 additions & 2 deletions src/autoskillit/recipe/rules/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,6 @@ Files with no registration support their folder; files with several registration
- `rules_skill_content_shell_safety.py` — Registers SKILL.md shell-safety semantic rules.
- `rules_skill_content_skill_contract.py` — Registers SKILL.md skill-contract semantic rules.
- `rules_skills.py` — Registers semantic rules for skill_command resolvability.
- `rules_tools.py` — Registers semantic rules for MCP tool name validity.
- `rules_tools.py` — Registers semantic rules for MCP tool name and invocation binding validity.
- `rules_verdict.py` — Registers semantic rules for skill verdict routing completeness and consistency.
- `rules_worktree.py` — Registers worktree and retry validation rules for recipe pipelines.
- `rules_worktree.py` — Registers worktree and retry validation rules for recipe pipelines.
Loading
Loading