From a7e31a0e609b09d7c693315c10e1fe176e83f89a Mon Sep 17 00:00:00 2001 From: "ilblackdragon@gmail.com" Date: Fri, 27 Mar 2026 20:02:34 -0700 Subject: [PATCH] docs: annotate v1-only code for removal after migration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mark modules and functions that exist solely for the v1 agent with "remove after v1 migration" notes: - src/skills/mod.rs ��� shim, attenuation, credential registration - src/skills/attenuation.rs — trust-based tool filtering (v1 only) - ironclaw_skills: selector, gating, registry, catalog modules - ironclaw_engine: skill_selector.rs (superseded by Python orchestrator) - src/bridge/skill_migration.rs — one-time v1→v2 conversion Co-Authored-By: Claude Opus 4.6 (1M context) --- .../src/capability/skill_selector.rs | 8 ++++- crates/ironclaw_skills/src/lib.rs | 31 ++++++++++++++++--- src/bridge/skill_migration.rs | 6 ++++ src/skills/attenuation.rs | 6 ++++ src/skills/mod.rs | 18 +++++++++++ 5 files changed, 64 insertions(+), 5 deletions(-) diff --git a/crates/ironclaw_engine/src/capability/skill_selector.rs b/crates/ironclaw_engine/src/capability/skill_selector.rs index 99a7e14c..6cf6eed5 100644 --- a/crates/ironclaw_engine/src/capability/skill_selector.rs +++ b/crates/ironclaw_engine/src/capability/skill_selector.rs @@ -1,4 +1,10 @@ -//! Skill selection for the v2 engine. +//! Skill selection for the v2 engine (Rust-side). +//! +//! **Superseded** — skill selection moved to the Python orchestrator +//! (`orchestrator/default.py`: `select_skills()`, `score_skill()`). +//! This module is no longer called from production code. It remains for +//! reference and its unit tests. Remove when the Python implementation +//! is fully validated and this Rust fallback is no longer needed. //! //! Bridges `MemoryDoc` (the engine's storage primitive) to `LoadedSkill` //! (the skills crate's scoring primitive), then delegates to the shared diff --git a/crates/ironclaw_skills/src/lib.rs b/crates/ironclaw_skills/src/lib.rs index b98cfa94..290b72e4 100644 --- a/crates/ironclaw_skills/src/lib.rs +++ b/crates/ironclaw_skills/src/lib.rs @@ -1,8 +1,30 @@ -//! Skill selection, scoring, and management for IronClaw. +//! Skill types, parsing, selection, and management for IronClaw. //! //! Skills are SKILL.md files (YAML frontmatter + markdown prompt) that extend the //! agent's behavior through prompt-level instructions. This crate provides the core -//! types, deterministic selection pipeline, and filesystem management. +//! types, SKILL.md parser, and filesystem management. +//! +//! # V2 Engine +//! +//! In the v2 engine, skill **selection and scoring** happen in the Python orchestrator +//! (`orchestrator/default.py`), not in Rust. The engine uses this crate only for: +//! - **`types`** + **`v2`** — Data structures (`SkillManifest`, `V2SkillMetadata`, etc.) +//! - **`parser`** — Parsing SKILL.md files during v1→v2 migration +//! - **`validation`** — Name/content escaping, credential spec validation +//! +//! # V1 Agent (remove after migration) +//! +//! The following modules are used **only by the v1 agent** (`src/agent/`). Once +//! the v1 agent is removed, they can be deleted or feature-gated: +//! +//! - **`selector`** — Rust-side deterministic scoring (`prefilter_skills`). In v2, +//! the equivalent logic lives in `orchestrator/default.py:score_skill()`. +//! - **`gating`** — Binary/env/config requirement checks at load time. In v2, +//! skills are stored as MemoryDocs and gating is not applicable. +//! - **`registry`** (feature-gated) — Filesystem discovery and install/remove. +//! In v2, skills are managed as MemoryDocs via the Store. +//! - **`catalog`** (feature-gated) — ClawHub HTTP catalog. In v2, skill +//! installation happens through the skill-extraction mission or direct API. //! //! # Trust Model //! @@ -10,8 +32,9 @@ //! - **Trusted**: User-placed skills (local/workspace) with full tool access //! - **Installed**: Registry/external skills, restricted to read-only tools //! -//! The effective tool ceiling is determined by the *lowest-trust* active skill, -//! preventing privilege escalation through skill mixing. +//! In v1, trust-based tool filtering happens via `src/skills/attenuation.rs`. +//! In v2, the Python orchestrator handles trust labels and the policy engine +//! controls tool access via capability leases. pub mod gating; pub mod parser; diff --git a/src/bridge/skill_migration.rs b/src/bridge/skill_migration.rs index de2c1634..e8b50078 100644 --- a/src/bridge/skill_migration.rs +++ b/src/bridge/skill_migration.rs @@ -3,6 +3,12 @@ //! Converts v1 `LoadedSkill` instances (from filesystem SKILL.md files) into //! v2 `MemoryDoc` with `DocType::Skill` and structured `V2SkillMetadata`. //! The migration is idempotent: skills with unchanged content_hash are skipped. +//! +//! **Remove after v1 migration is complete.** Once all users are on ENGINE_V2 +//! and SKILL.md files are authored directly as v2 MemoryDocs (or via the +//! skill-extraction mission), this one-time migration code is unnecessary. +//! The `migrate_v1_skills` / `migrate_v1_skill_list` functions and the call +//! site in `bridge/router.rs:init_engine()` can all be deleted. use std::sync::Arc; diff --git a/src/skills/attenuation.rs b/src/skills/attenuation.rs index 08b6f0d7..6544dda5 100644 --- a/src/skills/attenuation.rs +++ b/src/skills/attenuation.rs @@ -1,5 +1,11 @@ //! Trust-based tool filtering (authority attenuation). //! +//! **V1 only** — remove when the v1 agent (`src/agent/`) is deleted. +//! +//! In v2, the Python orchestrator handles skill trust via `format_skills()` +//! and the policy engine handles tool access via capability leases. This +//! module is only called from `src/agent/dispatcher.rs`. +//! //! The core defense mechanism: the minimum trust level of any active skill //! determines a *tool ceiling* -- tools above the ceiling are removed from //! the LLM's tool list entirely. The LLM cannot be manipulated into calling diff --git a/src/skills/mod.rs b/src/skills/mod.rs index 6ad8ab64..117a5dfa 100644 --- a/src/skills/mod.rs +++ b/src/skills/mod.rs @@ -6,6 +6,24 @@ //! //! The `attenuation` submodule remains here because it depends on //! `crate::llm::ToolDefinition` which is a main-crate type. +//! +//! # V1 migration notes +//! +//! The following items in this module exist **only for the v1 agent** (`src/agent/`). +//! Once the v1 agent is removed and all users are on ENGINE_V2, they can be deleted: +//! +//! - **`attenuation` module** — Trust-based tool filtering. In v2, the Python +//! orchestrator handles skill trust via the `format_skills()` function and +//! the policy engine handles tool access via capability leases. +//! - **`register_skill_credentials()`** — Registers credential mappings from v1 +//! `LoadedSkill` into `SharedCredentialRegistry`. In v2, credentials are declared +//! in the SKILL.md frontmatter and registered at migration time in `skill_migration.rs`. +//! - **`credential_spec_to_mapping()` / `convert_credential_location()`** — Conversion +//! helpers used by `register_skill_credentials()`. Same lifecycle. +//! - **This entire shim module** — Once v1 is gone, callers import from +//! `ironclaw_skills` directly and this file is deleted. +//! +//! The `ironclaw_skills` crate itself remains (types, parser, validation, v2 types). pub mod attenuation;