docs: annotate v1-only code for removal after migration

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) <[email protected]>

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

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;

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;
 

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

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;