feat: complete uk companies house handler v2a (#220)

[Areen-09]

Description

Completes Phase v2a of the UK Companies House skill upgrade.

• Context/State tracking: The skill now extracts and expects a strict 5-key context schema to carry forward company_number, company_name, last_action, officer_filter, and selected_transaction_id between steps without forcing the LLM to repeatedly extract and pass them. _get_officers safely falls back on company_name via context to save API calls.
• Partial/Pipeline support: Added partial envelope status and pipeline parameter schema in preparation for the upcoming Phase v2b orchestration.
• Examples Update: Modernized gemini_uk_companies_house_handler.py to be a fully interactive chat loop, and updated uk_companies_house_handler_common.py to natively demonstrate context passing across actions.

Type of Change

• New Skill — new registry bundle under skills/
• Skill Upgrade — changes to an existing skill under skills/
• Bug Fix — incorrect runtime or framework behavior
• Documentation — docs, README, CONTRIBUTING only
• Framework Feature — skillware/core/ loader, env, adapters
• CLI — skillware/cli.py, docs/usage/cli.md
• Examples — examples/*.py, agent loops, examples/README.md
• Packaging — PyPI wheel, pyproject.toml, MANIFEST.in
• RFC / meta — templates, labels, CI, or large design doc

Checklist (all PRs)

• Linked GitHub issue (Fixes #… or Refs #…)
• Scope matches the issue — no unrelated refactors
• python -m black --check . and flake8 pass locally (or CI-equivalent subset)
• pytest skills/ and pytest tests/ pass locally when relevant
• CHANGELOG.md updated under [Unreleased] when user-visible behavior changes
• examples/README.md updated if this PR adds, renames, or removes a runnable script
• Ran pytest tests/test_registry_docs.py when skills, examples index, or agent-loops matrix changed

New or updated skill

Skip unless this PR adds or changes files under skills/.

Bundle and metadata

• Skill at skills/<category>/<skill_name>/ (from templates/python_skill/ or equivalent)
• manifest.yaml: name (full ID), version, description, parameters, constitution, real issuer
• Optional: short_description, issuer.github, issuer.org, requirements, env_vars

Logic, cognition, tests

• Deterministic skill.py (no ad-hoc LLM-generated execution paths)
• instructions.md explains when and how to use the skill
• card.json issuer matches manifest when present
• test_skill.py covers execution and schema expectations
• SkillLoader.load_skill("<category>/<skill_name>") succeeds (or deps documented)

Documentation and catalog

• docs/skills/<skill_name>.md and row in docs/skills/README.md
• Usage Examples for Gemini, Claude, OpenAI, DeepSeek, Ollama per skill usage template

Constitution and safety (skills only)

No safety or constitution changes. The skill remains strictly read-only for public company data.

Related Issues

Completes #220 v2a

[rosspeili]

Hey @Areen-09, thanks for this, looks clean and good as always!

A few small things before merge:

1. Update docstring in gemini_uk_companies_house_handler.py, still says "non-interactive" but it's now an interactive REPL
2. Clarify pipeline / partial, both are v2b prep but not used yet. Add a quick note in instructions.md so agents don't expect them, or if you will work on v2b right after, maybe ignore this and patch in next pr?
3. Add a couple new tests:
   • get_officers with context-only company_number
   • officer company_name fallback via profile fetch

After this merges, you can tackle v2b (pipeline) and v2f (agent playbook) in follow-up PRs or a signle PR, up to you.

Nice work keeping it focused. Merge once those small fixes are in <3

[Areen-09]

Thanks so much for the detailed review @rosspeili ! <3

I've addressed all the requested changes:

• Updated the docstring to reflect the interactive REPL.

• Added a note in instructions.md clarifying that pipeline/partial are v2b preparation and aren't used yet.

• Added the new tests for:

  • get_officers with context-only company_number
  • company_name fallback via profile fetch

Once this PR is merged, I'll start working on the next phases (v2b pipeline and then v2f agent playbook). Thanks again for the review!

[Areen-09]

Hi @rosspeili ! Just a quick update, this PR had a merge conflict after some newer changes were merged into main, so I've now rebased the branch, resolved the conflict, and force-pushed the updated branch. Everything should be up to date now.

Whenever you have a chance, I'd really appreciate another look. Thanks!

[rosspeili]

Thanks @Areen-09, this looks great and addresses everything from the review.

Small nits, non-blocking, but consider for next PR:

• Optional one-liner in examples/README.md — Gemini example is now interactive REPL, README still reads generic.
• Tiny follow-up: consider tightening the bare except on profile fallback in _get_officers when you touch v2b.
• I would try to open subissues as described in 220, then PRs that would close each, just for reference and better audit trail.

Still, happy to merge this once CI is green. 🙏