@klickd/core 4.0.0 → 4.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klickd/core",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "description": "Official JavaScript/TypeScript library for reading and writing .klickd portable AI context files",
   "keywords": [
     "klickd",
@@ -29,12 +29,14 @@
   },
   "files": [
     "dist",
+    "starter-skills",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts --external argon2 --external argon2-browser --external ajv --loader .json=copy",
+    "build": "tsup src/index.ts --format esm,cjs --dts --external argon2 --external argon2-browser --external ajv",
     "test": "node --experimental-vm-modules node_modules/.bin/jest",
+    "verify:tarball": "node scripts/verify-tarball.mjs",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {

package/starter-skills/README.md

@@ -0,0 +1,98 @@
+# `examples/v4/starter-skills/` — Starter `.klickd` skills
+
+> **Status:** Starter / sample artefacts. **Non-normative.** **Pre-release.**
+>
+> **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 and not host-side skills.
+
+## 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
+
+- **Stable v4.0 envelope.** `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`) by
+default expects the structured 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
+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 sit on top of the **v4.0 envelope** and are non-normative starter artefacts for reviewers and integrators. Any future schema promotion and 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,226 @@
+{
+  "klickd_version": "4.0",
+  "payload_schema_version": "4.0.0-preview.1",
+  "domain_schema_version": "v4-starter-1.0",
+  "created_at": "2026-05-26T00:00:00Z",
+  "encrypted": false,
+  "domain": "software_engineering",
+  "profile_kind": "developer",
+  "_pack_metadata": {
+    "kind": "starter_skill_pack",
+    "non_normative": true,
+    "claims_v41_ga": false,
+    "contains_real_pii": false,
+    "contains_secrets": false,
+    "see_readme": "examples/v4/starter-skills/README.md",
+    "note": "Non-normative starter skill pack on the v4.0 envelope."
+  },
+  "x_klickd_pack": {
+    "pack": "x.klickd/coding",
+    "pack_version": "0.1.0-starter",
+    "spec_ref": "examples/v4/starter-skills/README.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": {
+      "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"
+    },
+    "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,44 @@
+{
+  "manifest_version": "1.0",
+  "kind": "klickd_starter_skill_manifest",
+  "non_normative": true,
+  "claims_v41_ga": false,
+  "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": 6294,
+      "sha256_file": "514e68223066e05a1b3af8f1d42c9d81c3e30f685259f7cf45c8aa2d50052036",
+      "sha256_canonical_json": "f61d52924d34acccf47cf4e8d5f7b6c9d791fad9f5a4f963e062c2230f11a4c9"
+    },
+    {
+      "id": "x.klickd/student",
+      "file": "student.klickd",
+      "pack_version": "0.1.0-starter",
+      "bytes": 6685,
+      "sha256_file": "26d4bed5172a67397af201ca6ff6d96b716ff994f359acf68e29e7fc4a0865ec",
+      "sha256_canonical_json": "1a1c783442bc3dccd8ad2fac8e72785d746016fd3a34d0976656efdf9dfda69a"
+    },
+    {
+      "id": "x.klickd/research",
+      "file": "research.klickd",
+      "pack_version": "0.1.0-starter",
+      "bytes": 6488,
+      "sha256_file": "e0da88dbb5c1d0768ca7a05422c4831e0751462ce399c9109ac2a5de61fba2a9",
+      "sha256_canonical_json": "f6f7d613ce640421b1902cb93af750ff1c057971c7c05872b7643fe34ca74e16"
+    },
+    {
+      "id": "x.klickd/coding",
+      "file": "coding.klickd",
+      "pack_version": "0.1.0-starter",
+      "bytes": 6465,
+      "sha256_file": "ae022d357ee9b3445afca761c76cf74e47f4ba85fb8ae9470a3ddf8e3cafa07b",
+      "sha256_canonical_json": "a872a0bf1abf829d87ca05b73f47dbb3f817aca4152688cf00d2dd0ea24f9a7e"
+    }
+  ]
+}

package/starter-skills/research.klickd

@@ -0,0 +1,230 @@
+{
+  "klickd_version": "4.0",
+  "payload_schema_version": "4.0.0-preview.1",
+  "domain_schema_version": "v4-starter-1.0",
+  "created_at": "2026-05-26T00:00:00Z",
+  "encrypted": false,
+  "domain": "research",
+  "profile_kind": "researcher",
+  "_pack_metadata": {
+    "kind": "starter_skill_pack",
+    "non_normative": true,
+    "claims_v41_ga": false,
+    "contains_real_pii": false,
+    "contains_secrets": false,
+    "see_readme": "examples/v4/starter-skills/README.md",
+    "note": "Non-normative starter skill pack on the v4.0 envelope."
+  },
+  "x_klickd_pack": {
+    "pack": "x.klickd/research",
+    "pack_version": "0.1.0-starter",
+    "spec_ref": "examples/v4/starter-skills/README.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": {
+      "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"
+    },
+    "forbidden_fields": [
+      "pedagogy",
+      "teaching_method",
+      "socratic_steps",
+      "prompt_strategy",
+      "scoring_rubric",
+      "intervention_policy",
+      "tone_rules",
+      "system_prompt_overrides",
+      "knowledge.mastered",
+      "mastered_topics"
+    ]
+  }
+}