@klickd/core 4.0.0-preview.1 → 4.0.1

package/starter-skills/README.md

@@ -0,0 +1,98 @@
+# `examples/v4/starter-skills/` — Starter `.klickd` skills
+
+> **Status:** Starter / sample artefacts. **Non-normative.** **Pre-release.** **Not v4.1 GA.**
+>
+> **Triggers no release.** No tag, no `latest` on npm or PyPI, no DOI on Zenodo, no IANA action, no SDK bump.
+
+This directory ships four real, structured `.klickd` files — starter skills on top of the **v4.0 envelope**. They are downloadable starter `.klickd` files — not relabelled v4-preview personas, not host-side skills, not v4.1 GA packs.
+
+## Files
+
+| File | Skill id | Domain | Hash (sha256_file) |
+|---|---|---|---|
+| [`user.klickd`](./user.klickd) | `x.klickd/user` | transversal (base) | `19121af045f6dd3537aa9bd4372edfaed5097b8436f026a8e9c585abbac6c80a` |
+| [`student.klickd`](./student.klickd) | `x.klickd/student` | education | `ffea74552ecedc9076d6468cb10214586632163f073a8c7975642e272464dba4` |
+| [`research.klickd`](./research.klickd) | `x.klickd/research` | research / evidence | `571bd07773caff23d08fe6857bbf696dd6e49f701aab750fa7b261345285ce63` |
+| [`coding.klickd`](./coding.klickd) | `x.klickd/coding` | software engineering | `1aab06122d8b6c7ed45737aa3b6becad3ae33badb5ad893cc7788ad6dd1481f4` |
+| [`manifest.json`](./manifest.json) | — | sha256 manifest of the four skills above | (regenerable via `scripts/verify_starter_skills.py`) |
+
+## What these skills *are*
+
+Each file is a real structured JSON document that carries:
+
+- the **v4.0 envelope** (`klickd_version`, `payload_schema_version`, `domain`, `profile_kind`, `created_at`, `encrypted`) — so an existing v4.0 reader round-trips it without breaking;
+- the **`x_klickd_pack` block** carrying:
+  - `pack`, `pack_version`, `spec_ref`, `publisher`
+  - `frameworks[]` (ESCO / DigComp / LifeComp / EQF / CEFR / SFIA depending on the skill)
+  - `base_transversal_core`
+  - domain-specific `competencies[]` anchored to authoritative framework IRIs
+  - `levels[]` with framework-anchored `level_label` (e.g. `EQF level 4`, `EQF level 6`, `EQF level 7`)
+  - `mastery[]` (empty in starter; pointer-only when populated by a carrier)
+  - `source_policy`, `evidence_policy` (RFC-002 §8b)
+  - `verification_gates` and per-skill `gates.verification_gates_default` (RFC-002, `raise_only: true`)
+  - `human_authority` (`final_decision_owner: human_carrier`, `agent_role: advisory`)
+  - `structured_memory` block scoped to `memory.x_klickd.<pack>`
+  - `router_cost` (deterministic heuristic, RFC-003)
+  - `forbidden_fields` literal (enforces the carrier-vs-skill split)
+
+## What these skills are NOT
+
+- **Not v4.1 GA.** `klickd_version: "4.0"`, `_pack_metadata.claims_v41_ga: false`. No public catalog is implied.
+- **Not relabelled personas.** They are *new artefacts* authored against frameworks. They do **not** harvest `knowledge.mastered[]` / `mastered_topics` from the v4-preview persona fixtures under [`../personas/`](../personas/) (clean-architecture invariant).
+- **Not host-side skills.** The `forbidden_fields` literal is the carrier-vs-skill firewall. Pedagogy, scoring rubrics, prompt strategies, tone rules — those belong in a `host_skill` on the agent side, not in the starter file.
+- **Not personal data.** No PII, no secrets, no real user state. `display_name: null`, `school_or_institution_ref: null`, `mastery: []`, `history: []`. The starter files are *publisher-owned starter shapes* a carrier can adopt and personalise locally.
+
+## How to verify
+
+Offline verification of structure, fields, anti-PII guard, anti-host_skill guard, and hash stability:
+
+```bash
+python3 scripts/verify_starter_skills.py
+# or via pytest
+pytest tests/test_starter_skills.py
+```
+
+The general starter-pack validator (`scripts/validate_starter_packs.py`) is
+v4.1-native by default — it expects the v4.1-shaped fields at the top level
+of each file. For the v4.0 starter `.klickd` files in this directory (which
+nest those fields under `x_klickd_pack` so the v4.0 envelope round-trips
+unchanged) run it with the `--v40-envelope` flag:
+
+```bash
+# v4.0-envelope mode — unwraps `x_klickd_pack` before validation
+python3 scripts/validate_starter_packs.py \
+    --dir examples/v4/starter-skills \
+    --v40-envelope
+```
+
+The two scripts are complementary: `verify_starter_skills.py` covers the v4.0
+envelope, persona-isolation, and hash-stability checks specific to this
+directory; `validate_starter_packs.py --v40-envelope` covers the shared
+v4.1-shaped field/forbidden-field/PII checks against the same files.
+
+## How to use
+
+These are downloadable starter `.klickd` files. A carrier can:
+
+1. Open the file matching their context (`user.klickd` as the always-on base, plus one of `student.klickd` / `research.klickd` / `coding.klickd`).
+2. Personalise *locally* — fill in `language_proficiency[]`, `subjects[].current_chapter_ref`, mastery entries (pointer-only), exam targets, etc. Personalisation never weakens gates (`raise_only: true`).
+3. Carry the file between agents. `human_authority.final_decision_owner = "human_carrier"` is non-negotiable across hosts.
+
+## Relation to internal spec work
+
+These starter `.klickd` files implement the **shape** described in the internal spec work at [`docs/rfcs/RFC-009-chimera-v4.1.md`](../../../docs/rfcs/RFC-009-chimera-v4.1.md) on top of the **v4.0 envelope**. They are starter artefacts for reviewers and integrators to see the architecture working end-to-end *before* the strict v4.1 schema is promoted past `Draft`. Promotion of the strict v4.1 schema and any catalog surface remains gated by `ACCEPTANCE_CHECKLIST_V4.md`.
+
+## Relation to existing personas
+
+| `examples/v4/personas/*.klickd` | `examples/v4/starter-skills/*.klickd` |
+|---|---|
+| Persona anchors / v4-preview demo fixtures. | Starter `.klickd` skills on the v4.0 envelope. |
+| Free-text `knowledge.mastered[]`, narrative `level`. | Framework-anchored `competencies[]`, framework-anchored `levels[]`. |
+| Carry tutor-style fields (`teaching_mode`, `agent_instructions`). | Carry **state only**; `forbidden_fields` block forbids host-side skill fields. |
+| Inspiration material for skill authors. | Real downloadable starter `.klickd` files. |
+
+The personas remain non-normative anchors. The starter `.klickd` files in this directory are the canonical starter artefacts going forward.
+
+## Release status
+
+No tag, no release. The live npm package (`@klickd/core`) and PyPI package (`klickd`) **do not yet ship these starter `.klickd` files as package data** — a future patch release will be required to update those live pages. This directory and the GitHub raw URLs are the source of truth until then.

package/starter-skills/coding.klickd

@@ -0,0 +1,177 @@
+{
+  "klickd_version": "4.0",
+  "preview": "4.0.0-chimera-starter.1",
+  "payload_schema_version": "4.0.0-preview.1",
+  "domain_schema_version": "chimera-starter-1.0",
+  "created_at": "2026-05-26T00:00:00Z",
+  "encrypted": false,
+  "domain": "software_engineering",
+  "profile_kind": "developer",
+  "_pack_metadata": {
+    "kind": "chimera_starter_pack",
+    "non_normative": true,
+    "claims_v41_ga": false,
+    "contains_real_pii": false,
+    "contains_secrets": false,
+    "see_readme": "examples/v4/starter-skills/README.md",
+    "spec_ref": "docs/rfcs/RFC-009-chimera-v4.1.md",
+    "note": "Real structured Chimera-aligned starter pack on the v4.0 envelope. Not a v4.1 GA pack."
+  },
+  "x_klickd_pack": {
+    "pack": "x.klickd/coding",
+    "pack_version": "0.1.0-starter",
+    "spec_ref": "docs/rfcs/RFC-009-chimera-v4.1.md",
+    "publisher": {
+      "name": "klickd",
+      "ref": "https://klickd.app"
+    },
+    "frameworks": [
+      {
+        "scheme": "esco",
+        "version": "v1.1.1",
+        "iri_prefix": "http://data.europa.eu/esco/skill/",
+        "canonical_url": "https://esco.ec.europa.eu/en/classification/skill_main"
+      },
+      {
+        "scheme": "digcomp",
+        "version": "2.2",
+        "iri_prefix": "https://joint-research-centre.ec.europa.eu/digcomp/2.2/",
+        "canonical_url": "https://joint-research-centre.ec.europa.eu/digcomp_en"
+      },
+      {
+        "scheme": "sfia",
+        "version": "8",
+        "iri_prefix": "https://sfia-online.org/en/sfia-8/",
+        "canonical_url": "https://sfia-online.org/en/sfia-8"
+      },
+      {
+        "scheme": "eqf",
+        "version": "2017",
+        "iri_prefix": "https://europa.eu/europass/eqf/",
+        "canonical_url": "https://europa.eu/europass/en/europass-tools/european-qualifications-framework"
+      }
+    ],
+    "base_transversal_core": {
+      "frameworks": [
+        { "scheme": "esco", "version": "v1.1.1" },
+        { "scheme": "digcomp", "version": "2.2" },
+        { "scheme": "eqf", "version": "2017" }
+      ],
+      "transversal_refs": [
+        { "competency_ref": "esco:S5", "scheme": "esco", "prefLabel": "working with computers" },
+        { "competency_ref": "digcomp:3.4", "scheme": "digcomp", "prefLabel": "Programming" },
+        { "competency_ref": "digcomp:4.2", "scheme": "digcomp", "prefLabel": "Protecting personal data and privacy" }
+      ]
+    },
+    "competencies": [
+      { "competency_ref": "esco:S5", "scheme": "esco", "prefLabel": "working with computers" },
+      { "competency_ref": "digcomp:3.4", "scheme": "digcomp", "prefLabel": "Programming" },
+      { "competency_ref": "digcomp:4.1", "scheme": "digcomp", "prefLabel": "Protecting devices" },
+      { "competency_ref": "digcomp:4.2", "scheme": "digcomp", "prefLabel": "Protecting personal data and privacy" },
+      { "competency_ref": "sfia:PROG", "scheme": "sfia", "prefLabel": "Programming/software development" },
+      { "competency_ref": "sfia:TEST", "scheme": "sfia", "prefLabel": "Systems and software testing" }
+    ],
+    "levels": [
+      {
+        "framework_ref": "https://europa.eu/europass/eqf/level/6",
+        "level_label": "EQF level 6",
+        "effective_at": "2026-05-26"
+      }
+    ],
+    "language_proficiency": [],
+    "mastery": [],
+    "engineering_discipline": {
+      "code_review_required_before_merge": true,
+      "tests_required_for_new_logic": true,
+      "typecheck_required_for_typed_languages": true,
+      "secrets_handling": "pointer_only_never_inline",
+      "supply_chain_awareness": "verify_provenance_when_adding_dependency",
+      "reversibility_default": "prefer_reversible_changes"
+    },
+    "gates": {
+      "verification_gates_default": {
+        "raise_only": true,
+        "claim_grounding_required": true,
+        "reversibility_threshold": "low"
+      },
+      "human_veto_policy": {
+        "owner": "human_carrier",
+        "scope": ["force_push", "dependency_addition", "secret_handling", "production_deploy"]
+      }
+    },
+    "human_authority": {
+      "final_decision_owner": "human_carrier",
+      "agent_role": "advisory",
+      "escalation": "human_carrier_only"
+    },
+    "memory_scope": "memory.x_klickd.coding",
+    "structured_memory": {
+      "scope": "memory.x_klickd.coding",
+      "policy": "pack_scoped_only",
+      "entries": []
+    },
+    "evidence_policy": {
+      "required_for_claims": true,
+      "pointer_only": true,
+      "attestation_shape_ref": "rfc-002#8b"
+    },
+    "source_policy": {
+      "frameworks_offline_bundle": "docs/rfcs/chimera/frameworks/base_transversal_core.bundle.json",
+      "allow_inline_definitions": false,
+      "language_tags": ["en", "fr"]
+    },
+    "verification_gates": {
+      "version": 1,
+      "user_default": "silent",
+      "gates": [
+        {
+          "id": "force-push",
+          "action_class": "force_push",
+          "level": "block",
+          "reason": "Force push is destructive; requires explicit human authorisation."
+        },
+        {
+          "id": "dependency-add",
+          "action_class": "dependency_addition",
+          "level": "confirm",
+          "reason": "New dependencies expand the supply-chain surface; confirm provenance before adding."
+        },
+        {
+          "id": "secrets",
+          "action_class": "secret_handling",
+          "level": "block",
+          "reason": "Secrets never inline; pointer-only handling enforced at gate level."
+        },
+        {
+          "id": "production-deploy",
+          "action_class": "production_deploy",
+          "level": "block",
+          "reason": "Deploys touch shared infrastructure; reversibility threshold low."
+        },
+        {
+          "id": "destructive-git",
+          "action_class": "destructive_git",
+          "level": "confirm",
+          "reason": "Destructive git operations (reset --hard, branch -D) require confirmation."
+        }
+      ]
+    },
+    "router_cost": {
+      "tokens_estimate": 900,
+      "baseline": "base_plus_one",
+      "source_row": "docs/rfcs/chimera/packs/router_cost.md"
+    },
+    "forbidden_fields": [
+      "pedagogy",
+      "teaching_method",
+      "socratic_steps",
+      "prompt_strategy",
+      "scoring_rubric",
+      "intervention_policy",
+      "tone_rules",
+      "system_prompt_overrides",
+      "knowledge.mastered",
+      "mastered_topics"
+    ]
+  }
+}

package/starter-skills/manifest.json

@@ -0,0 +1,45 @@
+{
+  "manifest_version": "1.0",
+  "kind": "klickd_starter_skill_manifest",
+  "non_normative": true,
+  "claims_v41_ga": false,
+  "spec_ref": "docs/rfcs/RFC-009-chimera-v4.1.md",
+  "see_readme": "examples/v4/starter-skills/README.md",
+  "generated_at": "2026-05-26T00:00:00Z",
+  "hash_algo": "sha256",
+  "note": "Hashes are reproducible offline. sha256_file is over the raw bytes of the file as stored. sha256_canonical_json is over json.dumps(obj, sort_keys=True, separators=(',', ':'), ensure_ascii=False).encode('utf-8') and is stable across whitespace-only edits to the source file.",
+  "packs": [
+    {
+      "id": "x.klickd/user",
+      "file": "user.klickd",
+      "pack_version": "0.1.0-starter",
+      "bytes": 6020,
+      "sha256_file": "19121af045f6dd3537aa9bd4372edfaed5097b8436f026a8e9c585abbac6c80a",
+      "sha256_canonical_json": "09dfb1f9af44ac2e25d37ad87139388ea714f7b1d8ab79b5bc9ecf8f130cb1c6"
+    },
+    {
+      "id": "x.klickd/student",
+      "file": "student.klickd",
+      "pack_version": "0.1.0-starter",
+      "bytes": 6554,
+      "sha256_file": "ffea74552ecedc9076d6468cb10214586632163f073a8c7975642e272464dba4",
+      "sha256_canonical_json": "72c542ae92db5bf8ba76c8b5449eb99dfceb4ab6886c944414473ba8b99fcd0e"
+    },
+    {
+      "id": "x.klickd/research",
+      "file": "research.klickd",
+      "pack_version": "0.1.0-starter",
+      "bytes": 6274,
+      "sha256_file": "571bd07773caff23d08fe6857bbf696dd6e49f701aab750fa7b261345285ce63",
+      "sha256_canonical_json": "f668a1069b9bf85cbe190052f029ac7430910ca2bf0caf2cf28035542b1e2d9c"
+    },
+    {
+      "id": "x.klickd/coding",
+      "file": "coding.klickd",
+      "pack_version": "0.1.0-starter",
+      "bytes": 6305,
+      "sha256_file": "1aab06122d8b6c7ed45737aa3b6becad3ae33badb5ad893cc7788ad6dd1481f4",
+      "sha256_canonical_json": "b1ae3d57998c69ec41ad2fe88fa2b1920e31ab64cab71c38a7661edc3b14c38c"
+    }
+  ]
+}

package/starter-skills/research.klickd

@@ -0,0 +1,175 @@
+{
+  "klickd_version": "4.0",
+  "preview": "4.0.0-chimera-starter.1",
+  "payload_schema_version": "4.0.0-preview.1",
+  "domain_schema_version": "chimera-starter-1.0",
+  "created_at": "2026-05-26T00:00:00Z",
+  "encrypted": false,
+  "domain": "research",
+  "profile_kind": "researcher",
+  "_pack_metadata": {
+    "kind": "chimera_starter_pack",
+    "non_normative": true,
+    "claims_v41_ga": false,
+    "contains_real_pii": false,
+    "contains_secrets": false,
+    "see_readme": "examples/v4/starter-skills/README.md",
+    "spec_ref": "docs/rfcs/RFC-009-chimera-v4.1.md",
+    "note": "Real structured Chimera-aligned starter pack on the v4.0 envelope. Not a v4.1 GA pack."
+  },
+  "x_klickd_pack": {
+    "pack": "x.klickd/research",
+    "pack_version": "0.1.0-starter",
+    "spec_ref": "docs/rfcs/RFC-009-chimera-v4.1.md",
+    "publisher": {
+      "name": "klickd",
+      "ref": "https://klickd.app"
+    },
+    "frameworks": [
+      {
+        "scheme": "esco",
+        "version": "v1.1.1",
+        "iri_prefix": "http://data.europa.eu/esco/skill/",
+        "canonical_url": "https://esco.ec.europa.eu/en/classification/skill_main"
+      },
+      {
+        "scheme": "digcomp",
+        "version": "2.2",
+        "iri_prefix": "https://joint-research-centre.ec.europa.eu/digcomp/2.2/",
+        "canonical_url": "https://joint-research-centre.ec.europa.eu/digcomp_en"
+      },
+      {
+        "scheme": "lifecomp",
+        "version": "2020",
+        "iri_prefix": "https://joint-research-centre.ec.europa.eu/lifecomp/2020/",
+        "canonical_url": "https://joint-research-centre.ec.europa.eu/lifecomp_en"
+      },
+      {
+        "scheme": "eqf",
+        "version": "2017",
+        "iri_prefix": "https://europa.eu/europass/eqf/",
+        "canonical_url": "https://europa.eu/europass/en/europass-tools/european-qualifications-framework"
+      }
+    ],
+    "base_transversal_core": {
+      "frameworks": [
+        { "scheme": "esco", "version": "v1.1.1" },
+        { "scheme": "digcomp", "version": "2.2" },
+        { "scheme": "lifecomp", "version": "2020" },
+        { "scheme": "eqf", "version": "2017" }
+      ],
+      "transversal_refs": [
+        { "competency_ref": "esco:S2", "scheme": "esco", "prefLabel": "information skills" },
+        { "competency_ref": "digcomp:1.2", "scheme": "digcomp", "prefLabel": "Evaluating data, information and digital content" },
+        { "competency_ref": "lifecomp:L2", "scheme": "lifecomp", "prefLabel": "Critical thinking" }
+      ]
+    },
+    "competencies": [
+      { "competency_ref": "esco:S2", "scheme": "esco", "prefLabel": "information skills" },
+      { "competency_ref": "digcomp:1.2", "scheme": "digcomp", "prefLabel": "Evaluating data, information and digital content" },
+      { "competency_ref": "digcomp:1.3", "scheme": "digcomp", "prefLabel": "Managing data, information and digital content" },
+      { "competency_ref": "lifecomp:L2", "scheme": "lifecomp", "prefLabel": "Critical thinking" }
+    ],
+    "levels": [
+      {
+        "framework_ref": "https://europa.eu/europass/eqf/level/7",
+        "level_label": "EQF level 7",
+        "effective_at": "2026-05-26"
+      }
+    ],
+    "language_proficiency": [],
+    "mastery": [],
+    "claim_grounding": {
+      "policy": "every_factual_claim_with_date_or_attribution_requires_source",
+      "preferred_sources": ["peer_reviewed", "primary_source", "official_registry"],
+      "fallback_sources": ["tool:web_search"],
+      "forbidden_sources": ["unverified_social_media"],
+      "citation_shape_ref": "rfc-002#8b",
+      "replication_expected_when": "quantitative_result_or_dated_event"
+    },
+    "verification_artifacts_policy": {
+      "shape_ref": "rfc-003#verification_artifacts",
+      "required_for": ["empirical_claim", "quantitative_result", "policy_recommendation"],
+      "pointer_only": true
+    },
+    "gates": {
+      "verification_gates_default": {
+        "raise_only": true,
+        "claim_grounding_required": true,
+        "reversibility_threshold": "low"
+      },
+      "human_veto_policy": {
+        "owner": "human_carrier",
+        "scope": ["publication", "claim_attribution", "data_release"]
+      }
+    },
+    "human_authority": {
+      "final_decision_owner": "human_carrier",
+      "agent_role": "advisory",
+      "escalation": "human_carrier_only"
+    },
+    "memory_scope": "memory.x_klickd.research",
+    "structured_memory": {
+      "scope": "memory.x_klickd.research",
+      "policy": "pack_scoped_only",
+      "entries": []
+    },
+    "evidence_policy": {
+      "required_for_claims": true,
+      "pointer_only": true,
+      "attestation_shape_ref": "rfc-002#8b"
+    },
+    "source_policy": {
+      "frameworks_offline_bundle": "docs/rfcs/chimera/frameworks/base_transversal_core.bundle.json",
+      "allow_inline_definitions": false,
+      "language_tags": ["en", "fr"]
+    },
+    "verification_gates": {
+      "version": 1,
+      "user_default": "silent",
+      "gates": [
+        {
+          "id": "uncited-claim",
+          "action_class": "factual_claim_without_citation",
+          "level": "block",
+          "reason": "Research pack: every factual claim must carry a source pointer."
+        },
+        {
+          "id": "quantitative-result",
+          "action_class": "quantitative_result",
+          "level": "confirm",
+          "reason": "Quantitative results require verification artefact (RFC-003 §verification_artifacts)."
+        },
+        {
+          "id": "publication",
+          "action_class": "publication",
+          "level": "block",
+          "reason": "No publication step from the agent; human authority required."
+        },
+        {
+          "id": "data-release",
+          "action_class": "data_release",
+          "level": "block",
+          "reason": "Data release requires explicit human consent; reversibility threshold low."
+        }
+      ]
+    },
+    "router_cost": {
+      "tokens_estimate": 800,
+      "baseline": "base_plus_one",
+      "source_row": "docs/rfcs/chimera/packs/router_cost.md"
+    },
+    "forbidden_fields": [
+      "pedagogy",
+      "teaching_method",
+      "socratic_steps",
+      "prompt_strategy",
+      "scoring_rubric",
+      "intervention_policy",
+      "tone_rules",
+      "system_prompt_overrides",
+      "knowledge.mastered",
+      "mastered_topics"
+    ]
+  }
+}