[rosspeili]

• Lazily initialize Draft7Validator in manifest_schema.py to eliminate 4.8s Lark/RFC 3987 regex compilation on startup.
• Scope iter_skillware_distributions() in version_policy.py to targeted sys.path globbing, avoiding linear disk scans across unrelated site-packages.
• Defers requests import in cli.py via module-level __getattr__ to eliminate urllib3/certifi startup overhead while preserving test mock compatibility.
• Rename skills/security/deepfake_guard/guard.py to deepfake_engine.py to resolve sys.modules["guard"] namespace collision with deceptive_ui_guard.
• Distinguish fatal doctor errors (SCHEMA, DEPS, LOAD) from missing runtime secrets (ENVS), printing an informational advisory and exiting 0 when code is intact.
• Update docs/usage/cli.md history table with missing release commits (f522b17, 831856d) and document doctor exit code behavior.

Description

Resolves CLI cold-start latency (~9.5s down to <1s), eliminates unnecessary full-environment package scans, prevents dynamic skill import namespace collisions in doctor, and cleans up doctor exit code handling for unconfigured environment keys.

Changes Mapped to Files and Tests

1. CLI Startup Latency (skillware/core/manifest_schema.py, skillware/cli.py):

   • Eager Draft7Validator instantiation triggered Lark RFC 3987 URI grammar compilation on every startup (4.8s). Moved behind lazy getter _get_manifest_validator() with backward-compatible __getattr__.
   • Top-level import requests in cli.py deferred via module __getattr__.
   • Startup cold launch drops from ~9.5s to <1s.
   • Tested by tests/test_cli.py and tests/test_manifest_schema.py.

2. Targeted Install Conflict Resolution (skillware/version_policy.py):

   • Startup advisories (emit_install_conflict_advisory and emit_upgrade_advisory) ran sequential un-cached importlib.metadata.distributions() passes over all installed packages on the interpreter (~1.5s per pass).
   • Scoped iter_skillware_distributions() to targeted filesystem globbing matching skillware*.dist-info and skillware*.egg-info directly across sys.path.
   • Preserves duplicate distribution and editable vs wheel overlap detection while dropping scan time to ~90ms.
   • Tested by tests/test_version_policy.py (21/21 passed in 1.1s, down from 5.6s).

3. security/deepfake_guard Dynamic Load Collision (skills/security/deepfake_guard/):

   • Sequential dynamic loading in skillware doctor collided on sys.modules["guard"] with security/deceptive_ui_guard.
   • Renamed skills/security/deepfake_guard/guard.py to deepfake_engine.py and updated skill.py.
   • Tested by skills/security/deepfake_guard/test_skill.py (17/17 passed) and sequential diagnosis in tests/test_cli.py.

4. Doctor Missing ENVS Error Handling (skillware/cli.py, tests/test_cli.py):

   • Missing required API keys previously triggered failures += 1 and exit code 1 in doctor.
   • Doctor now separates hard code integrity failures (SCHEMA, DEPS, LOAD) from missing runtime secrets (ENVS). Unset keys print an informational notice (Notice: N skill(s) declare required environment variables not set in this environment) and return exit code 0.
   • Tested by tests/test_cli.py::test_cmd_doctor_reports_missing_env_vars.

5. CLI Documentation & History (docs/usage/cli.md):

   • Added missing release commits f522b17 (v0.5.9 release) and 831856d to the CLI history table.
   • Documented doctor exit code behavior for ENVS.

Type of Change

• Bug Fix — incorrect runtime or framework behavior
• CLI — skillware/cli.py, docs/usage/cli.md
• Skill Upgrade — changes to an existing skill under skills/
• Documentation — docs, README, CONTRIBUTING only

Checklist (all PRs)

• Linked GitHub issue (Refs #433, Refs #440)
• Scope matches the issue — no unrelated refactors
• Contribution complies with Legal notice and code ownership (original work, MIT license grant, no malicious logic)
• python -m black --check ., flake8, and python scripts/sync_extras.py --check pass locally (206 files clean)
• pytest skills/ and pytest tests/ pass locally (100% pass rate)
• CHANGELOG.md updated under [Unreleased]
• Ran pytest tests/test_registry_docs.py (20/20 passed)
• Ran pytest tests/test_spdx_headers.py (2/2 passed)

New or updated skill

Bundle and metadata

• Skill at skills/security/deepfake_guard/
• manifest.yaml: name, version, description, parameters, constitution, real issuer, requirements: [numpy, pillow]

Effect, Directive, Assurance

• Deterministic skill.py (Effect; no ad-hoc LLM-generated execution paths)
• instructions.md (Directive) explains when and how to use the skill
• card.json (Presentation) issuer matches manifest
• test_skill.py (Assurance) covers execution and schema expectations (17/17 passed)
• SkillLoader.load_skill("security/deepfake_guard") succeeds cleanly in isolation and sequentially after security/deceptive_ui_guard

Related Issues

Refs #433, Refs #440