Upload 13 files

.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.mypy_cache/
+.ruff_cache/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Runtime artifacts (per CLAUDE.md)
+runs/

CLAUDE.md

@@ -0,0 +1,267 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+Passive OSINT Control Panel — a Gradio-based Hugging Face Space for drift-aware,
+passive-first OSINT enrichment. Inputs are validated, sanitised, normalised, and
+HMAC-hashed before any logging or enrichment. External-target interaction is
+gated behind explicit authorization.
+
+- **Entry point:** `app.py` (Gradio `demo.launch()`)
+- **Runtime:** Python 3.11+, Gradio 6.13.x, HF Space SDK `gradio`
+- **Version:** `0.1.0` (`APP_VERSION` in `app.py`, `__version__` in `osint_core/__init__.py`)
+- **License:** Apache-2.0
+- **HF Space front matter** lives at the top of `README.md` — do not strip it.
+
+## Repository layout
+
+```
+.
+├── app.py                    # Monolithic Gradio UI + full pipeline (current prod)
+├── osint_core/               # Modular refactor of app.py's logic (preferred for new code)
+│   ├── __init__.py           # Public API: validate_indicator, create_orchestrator, ...
+│   ├── validators.py         # Input validation + normalisation (pure, no I/O)
+│   ├── policy.py             # Module authorization boundary + correction verb gate
+│   ├── orchestrator.py       # Agent-based workflow coordination
+│   └── drift.py              # DRIFT LAYER — currently PSEUDOCODE, not runnable (see below)
+├── agent/                    # Claude-powered OSINT expert agent (NEW)
+│   ├── __init__.py           # Exports OSINTAgent
+│   ├── osint_agent.py        # OSINTAgent class — claude-opus-4-7, adaptive thinking, prompt caching
+│   └── cli.py                # argparse CLI: --target, --type, --iocs, --explain, interactive mode
+├── tests/
+│   ├── test_policy.py        # Passes against osint_core.policy
+│   ├── test_orchestrator.py  # Passes against osint_core.orchestrator
+│   └── test_drift.py         # Contract tests — FAIL until drift.py is implemented
+├── data/sources.yaml         # OSINT source registry (subset; app.py has its own inline copy)
+├── policy.yaml               # Declarative policy snapshot (mirrors osint_core.policy)
+├── manifest.json             # Artifact manifest skeleton
+├── golden_tests.json         # Smoke-test fixtures for classification
+├── requirements.txt          # Python deps (pinned ranges)
+├── packages.txt              # HF Space apt packages (dnsutils, whois, libmagic1)
+└── README.md                 # User/operator docs + HF Space config
+```
+
+Two layers coexist:
+- `app.py` is self-contained and ships the running Space today.
+- `osint_core/` is the modular refactor targeted by the test suite. New logic
+  should land in `osint_core/` and be wired into `app.py` rather than expanded
+  in `app.py` directly.
+
+## Orchestrator agent architecture
+
+The `osint_core/orchestrator.py` module provides an agent-based workflow
+coordination system. It separates concerns into:
+
+- **Agent**: `OrchestratorAgent` coordinates the full enrichment workflow
+- **Skills**: High-level capabilities (e.g., "Resolve DNS", "Fetch WHOIS")
+- **Tools**: Atomic external actions (e.g., DNS query, HTTP request, subprocess)
+- **Execution context**: Tracks state through validation → policy → enrichment → drift → audit
+
+### Key data structures
+
+- `Tool`: Atomic capability (subprocess, network, file, computation)
+- `Skill`: Composed capability with required indicator types and tools
+- `ExecutionContext`: Per-request state (run ID, normalized indicator, policy eval, errors)
+- `SkillResult`: Result from executing a skill (status, data, error, duration)
+- `EnrichmentWorkflow`: Complete workflow result with all execution details
+
+### Workflow execution pattern
+
+```python
+from osint_core import create_orchestrator
+
+agent = create_orchestrator()
+workflow = agent.execute_workflow(
+    raw_indicator="example.com",
+    indicator_type_hint="Domain",
+    requested_modules=["resource_links", "dns_records"],
+    authorized_target=False,
+    passive_only=True,
+)
+
+# workflow.validation_result → ValidationResult
+# workflow.policy_evaluation → PolicyEvaluation
+# workflow.skill_results → list[SkillResult]
+# workflow.drift_vector → dict[str, float]
+# workflow.correction_verb → "ADAPT" | "CONSTRAIN" | "REVERT" | "OBSERVE"
+```
+
+### Adding new skills
+
+1. Define a `Tool` with type, description, auth requirements, timeout
+2. Create a `Skill` that references the tool(s) and required indicator types
+3. Register the skill in `SKILLS_REGISTRY` with a canonical name
+4. Add skill execution logic in `OrchestratorAgent._execute_skill`
+5. Add corresponding test in `tests/test_orchestrator.py`
+
+Do not add skills directly to `app.py`; add them to `orchestrator.py` and wire
+them through the orchestrator API.
+
+## AI Agent (Claude-powered)
+
+`agent/osint_agent.py` — `OSINTAgent` wraps `claude-opus-4-7` with adaptive thinking
+and prompt caching (the ~2000-token system prompt is cached via `cache_control: ephemeral`,
+cutting input costs ~90% after the first turn).
+
+```python
+from agent import OSINTAgent
+
+agent = OSINTAgent()  # reads ANTHROPIC_API_KEY from env
+result = agent.analyze_target("example.com", analysis_type="passive")  # or: full|threat|footprint|breach|darkweb|socmint
+report = agent.generate_ioc_report(["1.2.3.4", "evil.com"])
+```
+
+CLI: `python -m agent.cli --target example.com --type passive`
+or interactive: `python -m agent.cli`
+
+Conversation history preserves full `response.content` blocks (including thinking blocks)
+for correct multi-turn context propagation.
+
+## Known state / critical gotchas
+
+1. **`osint_core/drift.py` is pseudocode, not Python.** It uses `DEFINE`,
+   `FUNCTION`, `RETURN`, `FOR … IN` as bare keywords and will raise
+   `SyntaxError` on import. `tests/test_drift.py` imports
+   `DriftAssessment`, `DriftSignal`, `DriftType`, `DriftVector`,
+   `TelemetrySnapshot`, `aggregate_signals`, `assess_drift`,
+   `choose_dominant_drift_type`, `estimate_confidence`, and
+   `recommend_correction` — these are not yet implemented in Python. Treat
+   `drift.py` as a spec to implement against the tests, not as working code
+   to edit in-place.
+2. **Two module registries.** `app.py` hard-codes `OSINT_LINKS`,
+   `PASSIVE_MODULES`, `AUTHORIZED_ONLY_MODULES`. `osint_core/policy.py` has
+   the canonical `MODULE_POLICIES` registry plus `ALIASES`. When adding a
+   module, update the `osint_core` registry first; mirror into `app.py` only
+   if the UI needs it.
+3. **Two validators.** `app.py` has inline `sanitize_text` /
+   `classify_and_normalize` / `validate_as_type`. `osint_core/validators.py`
+   is the stricter, structured replacement (`ValidationResult`,
+   `ValidationErrorCode`). Prefer `osint_core` for new code paths.
+4. **`OSINT_HASH_SALT` is required.** `app.py:get_hash_salt` raises on
+   startup without it. For local/dev only, set `ALLOW_DEV_SALT=true`. Never
+   commit a salt value.
+5. **Correction verbs are a closed set:** `ADAPT`, `CONSTRAIN`, `REVERT`,
+   `OBSERVE`. Do not introduce new verbs; `policy.enforce_correction_verb`
+   rejects anything else.
+6. **`policy.yaml` says `immutable: true`.** Policy changes require the
+   out-of-band gate in `policy.enforce_policy_mutation_gate`. Do not silently
+   broaden rules.
+
+## Design invariants (must not be violated)
+
+From `policy.yaml`, `manifest.json`, and `app.py:make_manifest`:
+
+- Passive by default. No scanning, brute forcing, credential testing, or
+  exploitation — these are `risk="forbidden"` in `MODULE_POLICIES` and must
+  stay that way.
+- Validation runs before anything else. Downstream code does not re-validate.
+- Hash (HMAC-SHA256 with `OSINT_HASH_SALT`, lowercased input) before writing
+  to audit logs. Raw indicators never enter audit payloads —
+  `policy.enforce_audit_payload` rejects `raw_indicator`, `raw_input`,
+  `indicator`, `email`, `domain`, `username`, `url`, `ip` keys.
+- Authorized-only modules (`http_headers`, `robots_txt`, `screenshot`) stay
+  blocked unless the caller asserts `authorized_target=True` AND
+  `passive_only=False`.
+- Drift detection is pure — it does not mutate telemetry, baseline, manifest,
+  or policy input. See `test_assess_drift_is_pure_and_does_not_mutate_inputs`.
+- Correction priority: **policy > structural > behavioral > adversarial >
+  operational > statistical.** Adversarial CONSTRAINs before the system
+  ADAPTs. Statistical drift may ADAPT only when nothing higher-priority fires.
+
+## Development workflow
+
+### Setup
+
+```bash
+pip install -r requirements.txt
+# pytest and lint tooling are not in requirements.txt — install ad hoc:
+pip install pytest ruff bandit pip-audit
+export OSINT_HASH_SALT="$(python -c 'import secrets;print(secrets.token_hex(32))')"
+# or for local-only:
+export ALLOW_DEV_SALT=true
+# for agent/ module:
+export ANTHROPIC_API_KEY=<your-key>
+```
+
+### Run the app
+
+```bash
+python app.py
+# Gradio binds to 127.0.0.1:7860 by default.
+```
+
+### Test
+
+```bash
+pytest                    # expect test_policy to pass; test_drift will fail
+pytest tests/test_policy.py -v
+pytest tests/test_policy.py::TestPolicyEnforcement::test_passive_only -v  # single test
+```
+
+Before claiming drift work is done, `pytest tests/test_drift.py` must pass.
+
+### Lint / security scan (per README)
+
+```bash
+ruff check .
+bandit -r osint_core/
+pip-audit
+```
+
+None of these are wired into CI yet — run locally.
+
+## Conventions
+
+- **Python:** type hints throughout, `from __future__ import annotations`,
+  `@dataclass(frozen=True)` for value objects, `Literal[...]` for closed
+  enums. Match the existing style in `osint_core/validators.py` and
+  `osint_core/policy.py`.
+- **Errors:** structured exceptions with an error-code enum
+  (`ValidationErrorCode`, `PolicyErrorCode`). Prefer returning a result
+  dataclass (`ValidationResult`, `PolicyEvaluation`) over raising for
+  expected failure paths; raise only at enforcement boundaries
+  (`assert_valid_or_raise`, `enforce_*`).
+- **Module naming:** UI labels are human (`"HTTP Headers"`); canonical names
+  are snake_case (`"http_headers"`). Route every UI input through
+  `canonicalize_module_name` before policy checks.
+- **No new dependencies without reason.** `requirements.txt` uses pinned
+  ranges; preserve the lower/upper bounds when bumping.
+- **Never log raw indicators.** Add a test in the style of
+  `test_audit_payload_blocks_raw_indicator_fields` when introducing new
+  audit sinks.
+- **Docstrings:** module-level docstrings state design intent (see
+  `validators.py`, `policy.py`). Keep that pattern for new modules.
+
+## Git workflow
+
+- Default branch: `main`.
+- Claude work branch (this environment): `claude/skills-agent-osint-4zbxP`.
+  Push only to the designated feature branch; never force-push `main`.
+- GitHub repo scope for MCP tools: `canstralian/passiveosintcontrolpanel`
+  only. Other repos are denied.
+- After pushing, open a **draft** PR if one does not already exist.
+- Commit style from `git log`: short imperative titles
+  (`Create osint_core/policy.py`, `Update requirements.txt`).
+
+## Where to make common changes
+
+| Task | File(s) |
+| --- | --- |
+| Add a new OSINT source link | `app.py:OSINT_LINKS` and `data/sources.yaml` |
+| Add / change a module's risk or auth requirement | `osint_core/policy.py:MODULE_POLICIES` + test in `tests/test_policy.py` + mirror in `policy.yaml` |
+| Tighten input validation | `osint_core/validators.py` (regexes, `DANGEROUS_PATTERNS`, `PRIVATE_NETS`) |
+| Implement drift detection | `osint_core/drift.py` — rewrite the pseudocode to satisfy `tests/test_drift.py` |
+| Change correction verbs | Forbidden without out-of-band approval; touches `osint_core/policy.py:ALLOWED_CORRECTION_VERBS`, `app.py:CorrectionVerb`, and `policy.yaml` |
+| Wire a new module into the UI | `app.py:PASSIVE_MODULES`, `run_enrichment`, and the Gradio `CheckboxGroup` |
+| Change audit schema | `app.py:TelemetryEvent` + `write_audit` + any consumer in `export_audit_index` |
+| Add a new orchestrator skill | `osint_core/orchestrator.py:SKILLS_REGISTRY` + tool definition + test in `tests/test_orchestrator.py` |
+| Extend the AI agent's analysis types | `agent/osint_agent.py:_build_analysis_prompt` (add to the `prompts` dict) |
+| Adjust the AI agent's OSINT persona / knowledge | `agent/osint_agent.py:OSINT_SYSTEM_PROMPT` (re-cache will happen automatically on next call) |
+
+## Runtime artifacts (gitignored-ish)
+
+`app.py` creates `runs/reports/` and `runs/audit/` on import and writes per-run
+`.md` and `.json` files there. These directories are not tracked; do not
+commit their contents.

README.md

@@ -2,24 +2,30 @@
 title: Passive OSINT Control Panel
 emoji: 🛰️
 colorFrom: gray
-colorTo: purple
+colorTo: indigo
 sdk: gradio
 sdk_version: 6.13.0
 app_file: app.py
 pinned: false
 license: apache-2.0
 short_description: Drift-aware, passive OSINT control system.
-models:
-- berkeley-nest/WhiteRabbitNeo-8B
-- cybertronai/cybertron-1.1-7b
-- S-Dreamer/PyCodeT5
-datasets:
-- agentlans/HuggingFaceFW-finewiki-sample
-- qywang1106/arxiv_number_small
-- DanielPFlorian/Transformers-Github-Issues
-- John6666/knowledge_base_md_for_rag_1
 ---
 
+<p align="center">
+  <img src="https://img.shields.io/badge/Hugging%20Face-Space-yellow?logo=huggingface" alt="Hugging Face Space">
+  <img src="https://img.shields.io/badge/SDK-Gradio%206.13.0-orange?logo=gradio" alt="Gradio SDK">
+  <img src="https://img.shields.io/badge/Python-3.13-blue?logo=python" alt="Python">
+  <img src="https://img.shields.io/badge/License-Apache--2.0-green" alt="Apache 2.0 License">
+  <img src="https://img.shields.io/badge/OSINT-Passive%20by%20Default-indigo" alt="Passive OSINT">
+  <img src="https://img.shields.io/badge/Drift--Aware-Control%20Loop-purple" alt="Drift-Aware Control Loop">
+  <img src="https://img.shields.io/github/actions/workflow/status/canstralian/PassiveOSINTControlPanel/ci.yml?branch=main&label=CI&logo=github" alt="CI Status">
+  <img src="https://img.shields.io/github/actions/workflow/status/canstralian/PassiveOSINTControlPanel/sync-huggingface.yml?branch=main&label=Sync&logo=github" alt="HF Sync Status">
+  <img src="https://img.shields.io/github/last-commit/canstralian/PassiveOSINTControlPanel?logo=github" alt="Last Commit">
+  <img src="https://img.shields.io/github/issues/canstralian/PassiveOSINTControlPanel?logo=github" alt="Open Issues">
+  <img src="https://img.shields.io/github/license/canstralian/PassiveOSINTControlPanel" alt="License">
+  ![Sync](https://img.shields.io/badge/Sync-setup-lightgrey)
+</p>
+
 # Passive OSINT Control Panel (Hugging Face Space)
 
 ## Overview

SECURITY.md

@@ -2,17 +2,17 @@
 
 ## Reporting a Vulnerability
 
-If you discover a security vulnerability in this repository, do **not** open a public issue.
+If you believe you have discovered a security vulnerability in this repository, please do **not** open a public issue, discussion, or pull request describing the vulnerability.
 
-Use one of the following channels instead:
+Use a private reporting channel instead:
 
-1. GitHub Security Advisories  
-   Go to **Security → Report a vulnerability** in this repository.
+1. **GitHub Private Vulnerability Reporting**  
+   Go to **Security → Report a vulnerability** in this repository, if available.
 
-2. Direct contact  
-   Email: `security@example.com`
+2. **Direct security contact**  
+   Email: `security@yourdomain.com`
 
-Replace the email above with the correct security contact before production use.
+Replace the email address above with the correct production security contact before publishing this repository.
 
 ## Project Scope
 
@@ -22,91 +22,172 @@ The system is designed around the following control path:
 
 ```text
 Validation → Policy → Execution → Drift → Audit
+````
+
+The default operating mode is passive. Any active interaction with a user-provided target must be explicitly authorized before execution.
+
+Security reports are most valuable when they help strengthen validation, authorization, policy enforcement, drift detection, audit integrity, or safe handling of indicators.
+
+## Security Model
+
+The project is built around the following invariants:
+
+```text
+No raw indicators in audit logs.
+No conditional modules without explicit authorization.
+No forbidden modules.
+No policy mutation without out-of-band approval.
+No correction outside the approved verbs: ADAPT, CONSTRAIN, REVERT, OBSERVE.
+```
+
+The intended trust boundary is:
+
+```text
+User Input → Validation → Policy Decision → Approved Execution → Drift Check → Audit Record
 ```
 
-The default operating mode is passive. Active interaction with user-provided targets must be gated by explicit authorization.
+Any bypass, mutation, or unsafe shortcut in this chain may be security-relevant.
 
 ## In-Scope Vulnerabilities
 
 High-priority reports include:
 
-- Input validation or sanitisation bypass
-- Raw indicator leakage before hashing
-- `OSINT_HASH_SALT` or other secret exposure
-- Authorization gate bypass
-- Execution of conditional modules without approval
-- Audit log tampering or deletion
-- Policy mutation without out-of-band approval
-- Drift detection manipulation that hides unsafe behavior
-- Dependency behavior that creates structural drift or unsafe execution
+* Input validation or sanitization bypass
+* Raw indicator leakage before hashing or redaction
+* Exposure of `OSINT_HASH_SALT` or other secrets
+* Authorization gate bypass
+* Execution of conditional modules without approval
+* Audit log tampering, deletion, or suppression
+* Policy mutation without out-of-band approval
+* Drift detection manipulation that hides unsafe behavior
+* Introduction of forbidden modules or active tooling
+* Dependency behavior that causes unsafe execution or structural drift
 
 Medium-priority reports include:
 
-- Incorrect module risk classification
-- Unsafe report generation
-- Overly permissive source registry behavior
-- Inconsistent correction-verb enforcement
-- Unhandled exceptions that expose sensitive runtime details
+* Incorrect module risk classification
+* Unsafe report generation
+* Overly permissive source registry behavior
+* Inconsistent correction-verb enforcement
+* Unhandled exceptions that expose sensitive runtime details
+* Incomplete audit records for security-relevant actions
+* Configuration behavior that weakens passive-first guarantees
 
 Low-priority reports include:
 
-- UI-only issues without security impact
-- Non-sensitive error message quality
-- Documentation inconsistencies
+* UI-only issues without security impact
+* Non-sensitive error message quality
+* Documentation inconsistencies
+* Minor logging or formatting issues that do not affect audit integrity
 
 ## Out of Scope
 
 The following are not considered vulnerabilities in this repository:
 
-- Issues in third-party OSINT services linked by the application
-- Social engineering attacks
-- Denial-of-service attempts
-- Vulnerabilities requiring unauthorized access to third-party systems
-- Reports involving active scanning or exploitation of targets not owned by the reporter
-- Misuse of the tool by end users outside the intended authorization model
+* Issues in third-party OSINT services linked by the application
+* Social engineering attacks
+* Denial-of-service attempts
+* Physical attacks
+* Spam or phishing reports unrelated to this codebase
+* Vulnerabilities requiring unauthorized access to third-party systems
+* Reports involving active scanning or exploitation of targets not owned or explicitly controlled by the reporter
+* Misuse of the tool by end users outside the intended authorization model
+* Findings based only on hypothetical impact without a realistic path to exploitation
+
+## Testing Rules
+
+Security testing must be safe, authorized, and non-destructive.
+
+Do not:
+
+* Use real user data
+* Submit secrets, credentials, or unauthorized target data
+* Perform active scanning against third-party systems
+* Attempt persistence, privilege escalation, or data exfiltration
+* Degrade service availability
+* Run destructive payloads
+* Chain exploits against systems outside your authorization scope
+
+If sensitive data is encountered during testing, stop immediately and report the exposure through a private channel.
 
 ## Report Requirements
 
-Please include:
+Please include as much of the following as possible:
 
-- Summary of the issue
-- Affected component, if known
-- Steps to reproduce
-- Expected behavior
-- Actual behavior
-- Security impact
-- Safe proof of concept, if applicable
-- Suggested mitigation, if known
+* Summary of the issue
+* Affected component, file, or control path
+* Steps to reproduce
+* Expected behavior
+* Actual behavior
+* Security impact
+* Safe proof of concept, if applicable
+* Suggested mitigation, if known
+* Whether the issue affects validation, policy, execution, drift detection, or audit integrity
 
-Do not include real user data, secrets, unauthorized target data, destructive payloads, or exploit chains against third-party systems.
+Please avoid including real user data, live secrets, unauthorized target data, destructive payloads, or exploit chains against third-party systems.
 
 ## Response Process
 
 Expected response timeline:
 
-- Acknowledgement: within 48 hours
-- Initial triage: within 5 business days
-- Fix plan: after validation and severity assessment
-- Coordinated disclosure: if applicable
+* **Acknowledgement:** within 48 hours
+* **Initial triage:** within 5 business days
+* **Severity assessment:** after reproduction and impact review
+* **Fix plan:** after validation of the issue
+* **Coordinated disclosure:** when applicable
+
+Timelines may vary depending on complexity, severity, and maintainer availability.
+
+## Coordinated Disclosure
+
+Please give the maintainers reasonable time to investigate and remediate confirmed vulnerabilities before public disclosure.
+
+If a vulnerability affects users, deployment safety, secrets, or audit integrity, coordinated disclosure may include:
+
+* Patch development
+* Regression tests
+* Security advisory publication
+* Versioned release notes
+* Mitigation guidance
 
 ## Safe Harbor
 
-Security research is welcome when performed in good faith.
+Good-faith security research is welcome when it follows this policy.
+
+The project will not pursue action against researchers who:
+
+* Act in good faith
+* Stay within authorized scope
+* Avoid privacy violations
+* Avoid service degradation
+* Avoid persistence or exfiltration
+* Report vulnerabilities promptly and privately
+* Stop testing if sensitive data is encountered
 
-You are expected to avoid privacy violations, avoid service degradation, avoid persistence or exfiltration, use only systems and data you are authorized to test, and stop testing if sensitive data is encountered.
+Safe harbor does not apply to activity that targets third-party systems without authorization, uses destructive techniques, or attempts to access, retain, or disclose data that does not belong to the researcher.
 
-## Security Architecture
+## Preferred Areas of Review
 
-This project treats security as a feedback circuit.
+Reports are especially useful when they improve:
 
-Core invariants:
+* Indicator validation
+* Hashing and redaction behavior
+* Authorization gating
+* Passive-first enforcement
+* Conditional module controls
+* Source registry constraints
+* Drift attribution
+* Audit log integrity
+* Policy mutation safeguards
+* Dependency and supply-chain safety
+
+## Security Contact
+
+Primary security contact:
 
 ```text
-No raw indicators in audit logs.
-No conditional modules without authorization.
-No forbidden modules.
-No policy mutation without out-of-band approval.
-No correction outside the approved verbs: ADAPT, CONSTRAIN, REVERT, OBSERVE.
+distortedprojection@gmail.com
 ```
 
-Reports that improve validation, policy enforcement, drift attribution, or audit integrity are especially valuable.
+```
+```

assistant.prompt.yml

@@ -0,0 +1,79 @@
+messages:
+  - role: system
+    content: >-
+      You are a security-focused GitHub Actions remediation assistant.
+
+
+      Your task is to inspect a GitHub Actions workflow file and produce the
+      smallest safe patch that resolves CodeQL alerts without changing the
+      intended behavior of the workflow.
+
+
+      Focus specifically on the CodeQL alert: “Workflow does not contain
+      permissions.”
+
+
+      Apply least privilege to the GITHUB_TOKEN. Prefer read-only permissions at
+      the workflow level, and only add job-level write permissions when the
+      workflow clearly requires them.
+
+
+      Do not suggest broad permissions such as `write-all` unless there is no
+      safer alternative. Do not modify unrelated workflow logic. Preserve
+      existing jobs, steps, triggers, names, and formatting as much as possible.
+
+
+      Return:
+
+      1. A short diagnosis.
+
+      2. The exact YAML patch or corrected workflow block.
+
+      3. A brief explanation of why each permission is needed.
+
+      4. Any risky assumptions or follow-up checks.
+  - role: user
+    content: >-
+      Fix the CodeQL alert in this GitHub Actions workflow.
+
+
+      Alert:
+
+      “Workflow does not contain permissions”
+
+
+      Affected file:
+
+      .github/workflows/ci.yml
+
+
+      Affected lines:
+
+      11 and 61
+
+
+      Goal:
+
+      Add explicit least-privilege `permissions:` blocks so the workflow no
+      longer relies on inherited default GITHUB_TOKEN permissions.
+
+
+      Constraints:
+
+      - Preserve existing workflow behavior.
+
+      - Do not add unnecessary write permissions.
+
+      - Prefer `contents: read` globally.
+
+      - Use job-level permissions only where a job actually needs more access.
+
+      - Return the corrected YAML or a minimal patch.
+
+
+      Workflow file:
+
+      {{input}}
+model: openai/gpt-4o
+modelParameters:
+  temperature: 0.73

requirements.txt

@@ -1,9 +1,10 @@
-pyyaml>=6.0.2,<7
+pyyaml>=6.0.3,<7
 httpx>=0.27.1,<1.0
 tldextract>=5.1.2,<6
-dnspython>=2.6.1,<3
-python-whois>=0.9.4,<1
-markdown-it-py>=3.0.0,<4
-email-validator>=2.1.1,<3
-cachetools>=5.3.3,<7
-pydantic>=2.11.10,<=2.12.5
+dnspython>=2.8.0,<3
+python-whois>=0.9.6,<1
+markdown-it-py>=4.0.0,<5
+email-validator>=2.3.0,<3
+cachetools>=7.0.6,<8
+pydantic<=2.13.3,>=2.13.3
+anthropic>=0.50.0,<1.0.0

semantic-versioning.prompt.yml

@@ -0,0 +1,72 @@
+messages:
+  - role: system
+    content: >
+      "You are a Semantic Versioning Agent, meticulously adhering to the SemVer
+      2.0.0 specification. Your expertise lies in analyzing changes and
+      determining the correct version increment (MAJOR, MINOR, or PATCH) based
+      on the nature of those changes. You will also identify if pre-release or
+      build metadata labels are necessary.
+
+
+      Here's the format you will use to analyze the changes and provide the
+      correct version increment:
+
+
+      ---
+
+
+      ## Current Version
+
+      $current_version (e.g., 1.2.3)
+
+
+      ## Description of Changes
+
+      $description_of_changes (Detailed explanation of the modifications made)
+
+
+      ## SemVer Analysis
+
+      *   **MAJOR Increment Required?** (Yes/No - Explain why or why not)
+
+      *   **MINOR Increment Required?** (Yes/No - Explain why or why not)
+
+      *   **PATCH Increment Required?** (Yes/No - Explain why or why not)
+
+      *   **Pre-release Label Recommended?** (Yes/No - If yes, suggest a label
+      and explain why)
+
+      *   **Build Metadata Recommended?** (Yes/No - If yes, suggest metadata and
+      explain why)
+
+
+      ## Recommended Version Increment
+
+      $recommended_increment (MAJOR, MINOR, or PATCH)
+
+
+      ## New Version
+
+      $new_version (e.g., 2.0.0, 1.3.0, 1.2.4, 1.2.3-alpha.1, 1.2.3+build.123)
+
+
+      ## Justification
+
+      $justification (A concise explanation of why the recommended increment and
+      new version are correct according to SemVer 2.0.0)
+
+
+      ---
+
+
+      Here is the challenge you are tasked with: [ENTER YOUR DESCRIPTION OF
+      CHANGES HERE]
+
+      "
+  - role: user
+    content: |-
+      Current version: {{current_version}}
+
+      Description of changes:
+      {{description_of_changes}}
+model: openai/gpt-4o