skillware 0.5.2__tar.gz → 0.5.3__tar.gz

{skillware-0.5.2/skillware.egg-info → skillware-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: skillware
-Version: 0.5.2
+Version: 0.5.3
 Summary: A framework for modular, self-contained AI skills.
 Author-email: ARPA Hellenic Logical Systems <skillware-os@arpacorp.net>
 License: MIT License
@@ -105,6 +105,7 @@ Requires-Dist: web3>=6.0.0; extra == "defi-evm-tx-handler"
 Provides-Extra: dev-tools-issue-resolver
 Provides-Extra: finance-uk-companies-house-handler
 Provides-Extra: finance-wallet-screening
+Provides-Extra: monitoring-kpi-gate
 Provides-Extra: monitoring-token-limiter
 Provides-Extra: office-gmail-handler
 Provides-Extra: office-pdf-form-filler
@@ -170,10 +171,13 @@ The AI ecosystem is fragmented. Developers often re-invent tool definitions, sys
 
 A **Skill** in this framework provides everything an Agent needs to master a domain:
 
-1. **Logic**: Executable Python so agents run real work, not guess it.
-2. **Cognition**: System instructions and cognitive maps so any logical system uses the capability as intended.
-3. **Governance**: Constitution, safety boundaries, and hard limits baked into the bundle.
-4. **Interface**: Standardized tool schemas for any LLM or agent runtime.
+1. **Contract**: Constitution, safety boundaries, and typed I/O baked into the bundle.
+2. **Effect**: Executable Python so agents run real work, not guess it.
+3. **Directive**: System instructions and cognitive maps so any host uses the capability as intended.
+4. **Assurance**: Offline tests that Effect honors Contract before a skill joins the registry.
+5. **Interface**: Standardized tool schemas for any LLM or agent runtime.
+
+Optional **Corpus**, **Reference**, and **Presentation** assets extend bundles when needed. Full reference: [Introduction — Skill anatomy](docs/introduction.md#skill-anatomy).
 
 ### Skill library
 
@@ -184,12 +188,10 @@ Browse capabilities by category in the [Skill library](docs/skills/README.md) or
 ```mermaid
 flowchart LR
     Registry[Registry] -->|Load| Loader[Loader]
-    Loader -->|Adapt| Host[Host]
-    Host -->|Prompt + Tools| LogicalSystems([Logical Systems])
-    LogicalSystems -->|Tool Call| Host
+    Loader -->|Adapt| AnyHost([Any Host])
 ```
 
-Install the registry once. Skillware loads a bundle and adapts it to your model's tool format — you run the loop. For details on how the loader turns the manifest into a tool, see the [Introduction](docs/introduction.md).
+Install the registry once. Skillware loads a bundle, adapts it to your host's tool format, and your app runs the agent loop (Gemini, Claude, Ollama, custom scripts, …). For details on how the loader turns the manifest into a tool, see the [Introduction](docs/introduction.md).
 
 ## Architecture
 
@@ -204,11 +206,11 @@ Skillware/
 ├── skills/                     # Skill Registry
 │   └── category/               # Domain boundaries (e.g., finance)
 │       └── skill_name/         # The Skill bundle
-│           ├── manifest.yaml   # Definition, schema, and constitution
-│           ├── skill.py        # Executable Python logic
-│           ├── instructions.md # Cognitive map for the LLM
-│           ├── card.json       # Optional UI presentation metadata
-│           └── test_skill.py   # Bundle test (required for new skills; see docs/TESTING.md)
+│           ├── manifest.yaml   # Contract: schema, constitution, issuer
+│           ├── skill.py        # Effect: deterministic execution
+│           ├── instructions.md # Directive: host guidance
+│           ├── card.json       # Presentation (optional)
+│           └── test_skill.py   # Assurance (required for registry skills)
 ├── skillware/                  # Core Framework Package
 │   ├── cli.py                  # Command-line interface
 │   └── core/
@@ -315,7 +317,7 @@ skill = skill_bundle["class"](
 # 2. Client & Tool Setup
 client = genai.Client()
 tool = SkillLoader.to_gemini_tool(skill_bundle)       # The "Adapter"
-system_instruction = skill_bundle['instructions']     # The "Mind"
+system_instruction = skill_bundle['instructions']     # Directive
 
 # 3. Agent Loop
 response = client.models.generate_content(
@@ -392,7 +394,7 @@ PyPI download counts show how often `skillware` is installed from the package in
 
 <a href="https://doi.org/10.5281/zenodo.21552745"><img src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.21552745-c7d2fe?style=flat-square" alt="DOI 10.5281/zenodo.21552745"></a>
 
-If you use Skillware in research or products, please cite it using [CITATION.cff](CITATION.cff) (GitHub **Cite this repository**) or the Zenodo **concept DOI** above. That DOI is stable across releases. For reproducibility, also record the **Skillware version** you used (PyPI or Git tag, for example `0.5.2`).
+If you use Skillware in research or products, please cite it using [CITATION.cff](CITATION.cff) (GitHub **Cite this repository**) or the Zenodo **concept DOI** above. That DOI is stable across releases. For reproducibility, also record the **Skillware version** you used (PyPI or Git tag, for example `0.5.3`).
 
 ## Contact
 

{skillware-0.5.2 → skillware-0.5.3}/README.md

@@ -41,10 +41,13 @@ The AI ecosystem is fragmented. Developers often re-invent tool definitions, sys
 
 A **Skill** in this framework provides everything an Agent needs to master a domain:
 
-1. **Logic**: Executable Python so agents run real work, not guess it.
-2. **Cognition**: System instructions and cognitive maps so any logical system uses the capability as intended.
-3. **Governance**: Constitution, safety boundaries, and hard limits baked into the bundle.
-4. **Interface**: Standardized tool schemas for any LLM or agent runtime.
+1. **Contract**: Constitution, safety boundaries, and typed I/O baked into the bundle.
+2. **Effect**: Executable Python so agents run real work, not guess it.
+3. **Directive**: System instructions and cognitive maps so any host uses the capability as intended.
+4. **Assurance**: Offline tests that Effect honors Contract before a skill joins the registry.
+5. **Interface**: Standardized tool schemas for any LLM or agent runtime.
+
+Optional **Corpus**, **Reference**, and **Presentation** assets extend bundles when needed. Full reference: [Introduction — Skill anatomy](docs/introduction.md#skill-anatomy).
 
 ### Skill library
 
@@ -55,12 +58,10 @@ Browse capabilities by category in the [Skill library](docs/skills/README.md) or
 ```mermaid
 flowchart LR
     Registry[Registry] -->|Load| Loader[Loader]
-    Loader -->|Adapt| Host[Host]
-    Host -->|Prompt + Tools| LogicalSystems([Logical Systems])
-    LogicalSystems -->|Tool Call| Host
+    Loader -->|Adapt| AnyHost([Any Host])
 ```
 
-Install the registry once. Skillware loads a bundle and adapts it to your model's tool format — you run the loop. For details on how the loader turns the manifest into a tool, see the [Introduction](docs/introduction.md).
+Install the registry once. Skillware loads a bundle, adapts it to your host's tool format, and your app runs the agent loop (Gemini, Claude, Ollama, custom scripts, …). For details on how the loader turns the manifest into a tool, see the [Introduction](docs/introduction.md).
 
 ## Architecture
 
@@ -75,11 +76,11 @@ Skillware/
 ├── skills/                     # Skill Registry
 │   └── category/               # Domain boundaries (e.g., finance)
 │       └── skill_name/         # The Skill bundle
-│           ├── manifest.yaml   # Definition, schema, and constitution
-│           ├── skill.py        # Executable Python logic
-│           ├── instructions.md # Cognitive map for the LLM
-│           ├── card.json       # Optional UI presentation metadata
-│           └── test_skill.py   # Bundle test (required for new skills; see docs/TESTING.md)
+│           ├── manifest.yaml   # Contract: schema, constitution, issuer
+│           ├── skill.py        # Effect: deterministic execution
+│           ├── instructions.md # Directive: host guidance
+│           ├── card.json       # Presentation (optional)
+│           └── test_skill.py   # Assurance (required for registry skills)
 ├── skillware/                  # Core Framework Package
 │   ├── cli.py                  # Command-line interface
 │   └── core/
@@ -186,7 +187,7 @@ skill = skill_bundle["class"](
 # 2. Client & Tool Setup
 client = genai.Client()
 tool = SkillLoader.to_gemini_tool(skill_bundle)       # The "Adapter"
-system_instruction = skill_bundle['instructions']     # The "Mind"
+system_instruction = skill_bundle['instructions']     # Directive
 
 # 3. Agent Loop
 response = client.models.generate_content(
@@ -263,7 +264,7 @@ PyPI download counts show how often `skillware` is installed from the package in
 
 <a href="https://doi.org/10.5281/zenodo.21552745"><img src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.21552745-c7d2fe?style=flat-square" alt="DOI 10.5281/zenodo.21552745"></a>
 
-If you use Skillware in research or products, please cite it using [CITATION.cff](CITATION.cff) (GitHub **Cite this repository**) or the Zenodo **concept DOI** above. That DOI is stable across releases. For reproducibility, also record the **Skillware version** you used (PyPI or Git tag, for example `0.5.2`).
+If you use Skillware in research or products, please cite it using [CITATION.cff](CITATION.cff) (GitHub **Cite this repository**) or the Zenodo **concept DOI** above. That DOI is stable across releases. For reproducibility, also record the **Skillware version** you used (PyPI or Git tag, for example `0.5.3`).
 
 ## Contact
 

{skillware-0.5.2 → skillware-0.5.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "skillware"
-version = "0.5.2"
+version = "0.5.3"
 description = "A framework for modular, self-contained AI skills."
 readme = "README.md"
 authors = [
@@ -140,6 +140,8 @@ finance_uk_companies_house_handler = []
 
 finance_wallet_screening = []
 
+monitoring_kpi_gate = []
+
 monitoring_token_limiter = []
 
 office_gmail_handler = []

{skillware-0.5.2 → skillware-0.5.3}/skills/creative/bg_remover/card.json

@@ -5,7 +5,7 @@
     "name": "Ayush Srivastava",
     "email": "ayush.sri0705@gmail.com",
     "github": "AyushSrivastava1818",
-    "org": ""
+    "org": "ARPAHLS"
   },
   "icon": "photo",
   "color": "violet",

{skillware-0.5.2 → skillware-0.5.3}/skills/creative/bg_remover/manifest.yaml

@@ -7,7 +7,7 @@ issuer:
   name: Ayush Srivastava
   email: "ayush.sri0705@gmail.com"
   github: AyushSrivastava1818
-  org: ""
+  org: ARPAHLS
 
 category: "creative"
 

{skillware-0.5.2 → skillware-0.5.3}/skills/data_engineering/novelty_extractor/card.json

@@ -32,6 +32,7 @@
   "issuer": {
     "name": "Martin Rizzo Lozano",
     "email": "rizzolozanomartin@gmail.com",
-    "github": "rizzoMartin"
+    "github": "rizzoMartin",
+    "org": "ARPAHLS"
   }
-}
+}

{skillware-0.5.2 → skillware-0.5.3}/skills/data_engineering/novelty_extractor/manifest.yaml

@@ -6,7 +6,7 @@ issuer:
   name: Martin Rizzo Lozano
   email: rizzolozanomartin@gmail.com
   github: rizzoMartin
-  org: ""
+  org: ARPAHLS
 parameters:
   type: object
   properties:

skillware-0.5.3/skills/monitoring/kpi_gate/__init__.py

@@ -0,0 +1,5 @@
+# Deterministic business-KPI gate skill package.
+
+from .skill import KpiGateSkill
+
+__all__ = ["KpiGateSkill"]

skillware-0.5.3/skills/monitoring/kpi_gate/card.json

@@ -0,0 +1,33 @@
+{
+    "name": "KPI Gate",
+    "description": "Deterministic business-KPI gate: metrics snapshot vs policy charter with fail-closed findings.",
+    "issuer": {
+        "name": "Masa",
+        "email": "masa88keith@gmail.com",
+        "github": "mrmasa88",
+        "org": "AO"
+    },
+    "icon": "gauge",
+    "color": "#0f766e",
+    "ui_schema": {
+        "type": "card",
+        "fields": [
+            {
+                "key": "status",
+                "label": "Status"
+            },
+            {
+                "key": "policy_id",
+                "label": "Policy"
+            },
+            {
+                "key": "benchmark_version",
+                "label": "Benchmark Version"
+            },
+            {
+                "key": "findings",
+                "label": "Findings"
+            }
+        ]
+    }
+}

skillware-0.5.3/skills/monitoring/kpi_gate/fixtures/benchmarks_missing_ref.json

@@ -0,0 +1,11 @@
+{
+  "schema_version": 1,
+  "benchmark_version": "demo-missing-ref",
+  "as_of": "2026-08-01",
+  "sources": [
+    "https://github.com/ARPAHLS/skillware/issues/317"
+  ],
+  "values": {
+    "some_other_benchmark_pct": {"value": 10.0, "unit": "pct"}
+  }
+}

skillware-0.5.3/skills/monitoring/kpi_gate/fixtures/charter_floor_boundary.yaml

@@ -0,0 +1,10 @@
+schema_version: 2
+policy_id: floor_boundary_demo
+metrics: [replies, reply_to_booking_rate_pct]
+rules:
+  - id: BOOKING_CONVERSION_TRACKED
+    metric: reply_to_booking_rate_pct
+    check: {op: gte, threshold: 10}
+    severity: warning
+    requires: {denominator_metric: replies, min_denominator: 25,
+               granularity: weekly, reason_code: cohort_attribution_unavailable}

skillware-0.5.3/skills/monitoring/kpi_gate/fixtures/example_charter.yaml

@@ -0,0 +1,19 @@
+schema_version: 2
+policy_id: coaching_funnel_demo_v1
+metrics: [outreach_sends, replies, bookings, lp_sessions, downloads,
+          download_rate_pct, reply_to_booking_rate_pct]
+rules:
+  - id: NO_BOOKING
+    metric: bookings
+    check: {op: gte, threshold: 1}
+    severity: error
+  - id: DOWNLOAD_RATE_BELOW_DOCTRINE
+    metric: download_rate_pct
+    check: {op: gte, benchmark_ref: lead_magnet_download_rate_pct}
+    severity: warning
+  - id: BOOKING_CONVERSION_TRACKED
+    metric: reply_to_booking_rate_pct
+    check: {op: gte, threshold: 10}
+    severity: warning
+    requires: {denominator_metric: replies, min_denominator: 25,
+               granularity: weekly, reason_code: cohort_attribution_unavailable}

skillware-0.5.3/skills/monitoring/kpi_gate/fixtures/example_snapshot.json

@@ -0,0 +1,13 @@
+{
+  "schema_version": 1,
+  "period": {"start": "2026-08-17", "end": "2026-08-23", "granularity": "weekly"},
+  "metrics": {
+    "outreach_sends": 40,
+    "replies": 6,
+    "bookings": 0,
+    "lp_sessions": 180,
+    "downloads": 22,
+    "download_rate_pct": 12.2,
+    "reply_to_booking_rate_pct": 0
+  }
+}

skillware-0.5.3/skills/monitoring/kpi_gate/fixtures/expected_findings.json

@@ -0,0 +1,24 @@
+{
+  "status": "completed",
+  "policy_id": "coaching_funnel_demo_v1",
+  "benchmark_version": "demo-1",
+  "findings": [
+    {
+      "finding": "NO_BOOKING",
+      "severity": "error",
+      "detail": {"metric": "bookings", "threshold": ">= 1", "observed": 0},
+      "action": "blocked — requires operator override"
+    },
+    {
+      "finding": "DOWNLOAD_RATE_BELOW_DOCTRINE",
+      "severity": "warning",
+      "detail": {"metric": "download_rate_pct", "threshold": ">= 25.0 (benchmark)", "observed": 12.2},
+      "action": "none — surfaced for the operator"
+    },
+    {
+      "state": "insufficient_data",
+      "detail": {"metric": "reply_to_booking_rate_pct"},
+      "reason": "cohort_attribution_unavailable"
+    }
+  ]
+}

skillware-0.5.3/skills/monitoring/kpi_gate/fixtures/invalid_benchmarks_schema.json

@@ -0,0 +1,9 @@
+{
+  "schema_version": 1,
+  "benchmark_version": "demo-broken",
+  "as_of": "2026-08-01",
+  "sources": [],
+  "values": {
+    "lead_magnet_download_rate_pct": {"value": 25.0}
+  }
+}

skillware-0.5.3/skills/monitoring/kpi_gate/fixtures/invalid_charter_dependent_required.yaml

@@ -0,0 +1,9 @@
+schema_version: 2
+policy_id: dependent_required_violation_demo
+metrics: [replies, reply_to_booking_rate_pct]
+rules:
+  - id: BOOKING_CONVERSION_TRACKED
+    metric: reply_to_booking_rate_pct
+    check: {op: gte, threshold: 10}
+    severity: warning
+    requires: {min_denominator: 25, reason_code: cohort_attribution_unavailable}

skillware-0.5.3/skills/monitoring/kpi_gate/fixtures/invalid_charter_schema.yaml

@@ -0,0 +1,8 @@
+schema_version: 2
+policy_id: invalid_rule_shape_demo
+metrics: [bookings]
+rules:
+  - id: lower_case_bad_id
+    metric: bookings
+    check: {op: between, threshold: 1}
+    severity: error

skillware-0.5.3/skills/monitoring/kpi_gate/fixtures/invalid_charter_unknown_denominator.yaml

@@ -0,0 +1,9 @@
+schema_version: 2
+policy_id: unknown_denominator_demo
+metrics: [reply_to_booking_rate_pct]
+rules:
+  - id: BOOKING_CONVERSION_TRACKED
+    metric: reply_to_booking_rate_pct
+    check: {op: gte, threshold: 10}
+    severity: warning
+    requires: {denominator_metric: replies, min_denominator: 25}

skillware-0.5.3/skills/monitoring/kpi_gate/fixtures/invalid_charter_unknown_rule_metric.yaml

@@ -0,0 +1,8 @@
+schema_version: 2
+policy_id: unknown_rule_metric_demo
+metrics: [bookings]
+rules:
+  - id: NO_SIGNED_CONTRACT
+    metric: signed_contracts
+    check: {op: gte, threshold: 1}
+    severity: error

skillware-0.5.3/skills/monitoring/kpi_gate/fixtures/invalid_snapshot_schema.json

@@ -0,0 +1,5 @@
+{
+  "schema_version": 1,
+  "period": {"start": "2026-08-17", "end": "2026-08-23"},
+  "metrics": {"outreach_sends": -3}
+}

skillware-0.5.3/skills/monitoring/kpi_gate/fixtures/snapshot_empty_metrics.json

@@ -0,0 +1,5 @@
+{
+  "schema_version": 1,
+  "period": {"start": "2026-08-17", "end": "2026-08-23", "granularity": "weekly"},
+  "metrics": {}
+}

skillware-0.5.3/skills/monitoring/kpi_gate/fixtures/snapshot_floor_at_min.json

@@ -0,0 +1,5 @@
+{
+  "schema_version": 1,
+  "period": {"start": "2026-08-17", "end": "2026-08-23", "granularity": "weekly"},
+  "metrics": {"replies": 25, "reply_to_booking_rate_pct": 4.0}
+}

skillware-0.5.3/skills/monitoring/kpi_gate/fixtures/snapshot_floor_below_min.json

@@ -0,0 +1,5 @@
+{
+  "schema_version": 1,
+  "period": {"start": "2026-08-17", "end": "2026-08-23", "granularity": "weekly"},
+  "metrics": {"replies": 24, "reply_to_booking_rate_pct": 4.0}
+}

skillware-0.5.3/skills/monitoring/kpi_gate/fixtures/snapshot_unknown_key.json

@@ -0,0 +1,14 @@
+{
+  "schema_version": 1,
+  "period": {"start": "2026-08-17", "end": "2026-08-23", "granularity": "weekly"},
+  "metrics": {
+    "outreach_sends": 40,
+    "replies": 6,
+    "bookings": 0,
+    "lp_sessions": 180,
+    "downloads": 22,
+    "download_rate_pct": 12.2,
+    "reply_to_booking_rate_pct": 0,
+    "undeclared_extra_metric": 7
+  }
+}

skillware-0.5.3/skills/monitoring/kpi_gate/instructions.md

@@ -0,0 +1,97 @@
+# Cognition Instructions: KPI Gate
+
+You have access to the `monitoring/kpi_gate` tool.
+
+This skill is a **deterministic, offline KPI gate**: a metrics snapshot plus a
+policy charter (and optional versioned benchmark data) go in, structured
+findings come out. `execute()` is a pure function with no network calls and no
+side effects; identical input always returns identical output.
+
+Limits: it is an auditor, not a data pipeline. It never fetches CRM, email, or
+analytics data, never estimates missing values, and never optimizes thresholds.
+
+## Agent-loop contract
+
+- `error` finding → the host blocks the dependent action until an operator
+  override is recorded.
+- `warning` finding → surface to the operator; never block on a warning.
+- `insufficient_data` → treat the metric as absent. The host must not
+  substitute, estimate, or backfill a value.
+
+## When to invoke
+
+- Gating a scheduled action (send, publish, spend) on business-KPI health
+- Auditing a periodic metrics snapshot against operator-declared thresholds
+- Comparing observed metrics against versioned benchmark doctrine
+
+Do not invoke it to collect metrics, to explain why a metric moved (no causal
+inference), or to pick thresholds (no optimization).
+
+## Inputs
+
+- `metrics` (required): snapshot object — `schema_version: 1`, a `period`
+  (`start`, `end`, `granularity`), and a map of `lower_snake_case` keys to
+  non-negative numbers. Every key must be declared by the policy.
+- `policy` (required): charter object — `schema_version: 2`, `policy_id`, the
+  closed `metrics` declaration, and ordered `rules`. Finding ids (for example
+  `NO_BOOKING`) are declared here, not in the skill. Typically maintained as
+  versioned YAML and parsed by the host before the call.
+- `benchmarks` (optional): versioned benchmark data — required only when a
+  rule uses `benchmark_ref`. A demo file ships at `kb/benchmarks_demo.json`.
+
+Reference JSON Schemas for all three inputs ship under `schemas/` in this
+bundle. The skill enforces the same constraints with explicit stdlib checks
+(`requirements: []` is deliberate); the schema files are documentation, not a
+runtime dependency. Hosts that call `validate_params()` also get top-level
+argument validation from the manifest.
+
+## How to interpret results
+
+A completed run returns `status: "completed"` with `policy_id`,
+`benchmark_version` (`null` when no benchmarks input was supplied), and
+`findings` in rule-declaration order:
+
+- Rule finding: `finding` (charter-declared id), `severity`, `detail`
+  (`metric`, `threshold`, `observed`), `action`
+  (`blocked — requires operator override` or
+  `none — surfaced for the operator`).
+- Refusal: `state: "insufficient_data"`, `detail.metric`, and `reason` — the
+  rule's declared `reason_code`, or `honesty_floor_unmet` when the rule
+  declared none, or `metric_missing_from_snapshot` when the rule's metric is
+  absent from the snapshot. When a granularity floor or a missing denominator
+  caused the refusal, `detail.unmet_floor` names it (`granularity` or
+  `denominator`); the canonical below-minimum-denominator refusal keeps the
+  exact shape pinned by issue #317.
+
+A contract violation returns `status: "error"` with
+`error.code` from the closed registry (`INVALID_METRICS_SCHEMA`,
+`INVALID_POLICY_SCHEMA`, `INVALID_BENCHMARKS_SCHEMA`, `NO_METRICS_PROVIDED`,
+`UNKNOWN_METRIC_KEY`, `UNKNOWN_RULE_METRIC`, `UNKNOWN_DENOMINATOR_METRIC`,
+`BENCHMARK_VERSION_MISSING`, `BENCHMARK_REF_UNRESOLVED`) and a deterministic
+`error.detail`. Errors and honest non-computability never mix: a refusal is a
+finding inside a completed run, never an error envelope.
+
+## Reserved fields (v1)
+
+`check.applies_to` is shape-validated and echoed into `detail.applies_to` on a
+finding, but carries no evaluation semantics in v1. Do not assume it filters
+or scopes rule evaluation.
+
+## Validation order (fail-closed)
+
+1. Strict schema checks on `metrics`, then `policy`, then `benchmarks` — the
+   first violation returns a contract error.
+2. Cross-checks: rule metrics and denominator metrics must be declared by the
+   policy; snapshot keys must be declared by the policy; every
+   `benchmark_ref` must resolve.
+3. Honesty floors: declared preconditions only — the evaluator never infers
+   which metric backs a rate. An unmet floor refuses with the declared reason
+   code.
+4. Rules evaluate in declared order; a passing rule emits nothing.
+
+## What this skill cannot do
+
+- Data acquisition: it never fetches, scrapes, or polls anything.
+- Causal inference: it reports threshold breaches, not why they happened.
+- Threshold optimization: thresholds come from the charter and benchmarks;
+  the skill never tunes them.

skillware-0.5.3/skills/monitoring/kpi_gate/kb/benchmarks_demo.json

@@ -0,0 +1,15 @@
+{
+  "schema_version": 1,
+  "benchmark_version": "demo-1",
+  "as_of": "2026-08-01",
+  "sources": [
+    "https://github.com/ARPAHLS/skillware/issues/317"
+  ],
+  "values": {
+    "lead_magnet_download_rate_pct": {
+      "value": 25.0,
+      "unit": "pct",
+      "denominator_scope": "unique landing-page sessions"
+    }
+  }
+}

skillware-0.5.3/skills/monitoring/kpi_gate/manifest.yaml

@@ -0,0 +1,67 @@
+name: monitoring/kpi_gate
+version: 0.1.0
+description: >
+  Deterministic business-KPI gate. Evaluates a metrics snapshot against an
+  operator-maintained policy charter and optional versioned benchmark data,
+  returning structured findings with two severities (error, warning) and one
+  honest third state (insufficient_data with reason codes). Strict schemas on
+  all three inputs, a closed rule set, and fail-closed contract errors from a
+  closed registry. Pure evaluation only: no network calls, no data fetching,
+  no side effects; identical input always returns identical output.
+short_description: "Deterministic KPI gate: metrics snapshot vs policy charter, fail-closed findings."
+issuer:
+  name: Masa
+  email: masa88keith@gmail.com
+  github: mrmasa88
+  org: AO
+category: monitoring
+parameters:
+  type: object
+  properties:
+    metrics:
+      type: object
+      description: >
+        Metrics snapshot object (metrics schema v1): schema_version, period
+        (start, end, granularity), and a metrics map of lower_snake_case keys
+        to non-negative numbers. Assembled upstream; this skill never fetches data.
+    policy:
+      type: object
+      description: >
+        Policy charter object (policy schema v2): schema_version, policy_id, the
+        closed declaration of metric keys, and the ordered rule list. Typically
+        maintained as versioned YAML and parsed by the host before the call.
+    benchmarks:
+      type: object
+      description: >
+        Optional benchmark data object (benchmarks schema v1) with
+        benchmark_version, as_of date, sources, and named values. Required only
+        when the policy references benchmark_ref checks.
+  required:
+    - metrics
+    - policy
+  additionalProperties: false
+outputs:
+  status:
+    type: string
+    description: completed for an evaluation run; error for a contract violation.
+  policy_id:
+    type: string
+    description: The policy_id of the evaluated charter.
+  benchmark_version:
+    type: string
+    description: benchmark_version of the supplied benchmark data, or null when none was supplied.
+  findings:
+    type: array
+    description: >
+      Ordered findings. Rule findings carry finding, severity, detail, and
+      action; refusals carry state insufficient_data, detail, and reason.
+requirements: []
+constitution: |
+  1. Evaluate only - no data fetching, no side effects, no automated remediation.
+  2. Deterministic, offline core - no network in execute(); identical input returns identical output.
+  3. Refuse rather than guess - what cannot be computed honestly returns insufficient_data with a reason code; no default substitution.
+  4. Every finding explained - code, metric, threshold, and observed value always attached.
+  5. Honest limits documented - what this skill does not do (data acquisition, causal inference, threshold optimization) is stated explicitly.
+presentation:
+  icon: gauge
+  color: "#0f766e"

skillware-0.5.3/skills/monitoring/kpi_gate/schemas/benchmarks.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "skillware:monitoring/kpi_gate:benchmarks:1",
+  "type": "object",
+  "required": ["schema_version", "benchmark_version", "as_of", "sources", "values"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {"const": 1},
+    "benchmark_version": {"type": "string"},
+    "as_of": {"type": "string", "format": "date"},
+    "sources": {"type": "array", "minItems": 1, "items": {"type": "string", "format": "uri"}},
+    "values": {
+      "type": "object", "minProperties": 1,
+      "patternProperties": {
+        "^[a-z][a-z0-9_]*$": {
+          "type": "object", "required": ["value"], "additionalProperties": false,
+          "properties": {"value": {"type": "number"},
+                         "unit": {"type": "string"},
+                         "denominator_scope": {"type": "string"}}
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}