Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,41 @@ Versions follow: `envelope_version (skill_revision)`.
> Production-recommended format remains **v3.5.1**. Preview track remains
> **v4.0.0-preview.1**.

### 2026-05-24 — RFC-001 / RFC-002 (v1 core) / RFC-004 promoted `Proposed → Accepted`

- **RFC-001 (`media_profile` v1)** — promoted to `Accepted`. The §4 decisions,
the §5 illustrative schema, the §6 V-001…V-012 validation checklist, and the
§9 error codes are approved for inclusion in the next normative `SPEC.md`
revision. Open questions (§11) are preserved verbatim and do not block
acceptance.
- **RFC-002 (`verification_gates` + `human_veto`)** — v1 core promoted to
`Accepted`: five gate levels (§6), `human_veto_policy`, `claim_sources`
(v1 fields only), `error_journal`, `risk_thresholds`, `preflight_checks`,
§4 decisions, §6 level semantics, and §9 G-001…G-006 conformance intent.
v2 §8b additions (`claim_status`, `contract_tests`, `success_criteria`,
`reversibility`, `blast_radius`, `verification_artifacts`,
`error_journal[].rule_created`, extended `claim_sources.records[]`) **stay
`Draft`** and may still iterate without affecting the v1 Accepted surface.
- **RFC-004 (Migration & Backward Compatibility — "Never break the soul")**
— promoted to `Accepted`. The §3 sub-principles, §4 decisions, §5.4 staged
pipeline (`v2.5 → v3.x → v3.5.1 → v4`), §6 reader-vs-writer matrix, §7
legacy / unknown / `x_*` rules, and §8 rollback model are approved.
Reference migrator (T-401 / T-402), `migration_report` schema (T-405), and
rollback CLI (T-406) remain future work, gated on `Implemented`.
- **Promotion gate.** Each RFC was assessed against
[`docs/rfcs/ACCEPTANCE_CHECKLIST_V4.md`](docs/rfcs/ACCEPTANCE_CHECKLIST_V4.md)
§3 C1–C16. The acceptance evidence table lives in the promotion PR body.
- **What does NOT change.** No SPEC, schema, SDK, vector, envelope, AAD, KDF,
or crypto change. No npm / PyPI / Zenodo / IANA publish. No tag, no release,
no announcement. v3.5.1 remains the production-recommended format;
v4.0.0-preview.1 remains the only preview release with permissive schemas.
- **What this unblocks.** The v4 GA P0 chantiers listed in
[`docs/roadmap/ROAD-TO-V4-GA.md`](docs/roadmap/ROAD-TO-V4-GA.md) §2.1 (P0-1
SPEC normative v4, P0-2 strict JSON Schema, P0-3 Python SDK, P0-4 JS/TS SDK,
P0-5 reference migrator, P0-6 strict vectors) may now begin against the
frozen v1 surface, per §4 step 3 ("SPEC normative v4") and §5 step 4
("PR « spec(v4): begin promoting §33 preview wording toward normative »").

### 2026-05-24 — V4 RFC acceptance checklist (`Proposed → Accepted` gate)

- **New governance doc** [`docs/rfcs/ACCEPTANCE_CHECKLIST_V4.md`](docs/rfcs/ACCEPTANCE_CHECKLIST_V4.md).
Expand Down
8 changes: 4 additions & 4 deletions docs/rfcs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,16 +25,16 @@ Files follow `RFC-NNN-short-slug.md` with zero-padded sequential numbers (`RFC-0

| # | Title | Target | Status |
|---|---|---|---|
| 001 | [`media_profile` v1](./RFC-001-media-profile-v1.md) | `.klickd v4` | **Proposed** (2026-05-23) |
| 002 | [`verification_gates` + `human_veto`](./RFC-002-verification-gates.md) | `.klickd v4-A` (v1) · `v4-B` (v2 draft) | **Proposed** (v1 core, 2026-05-23) · Draft (v2 §8b additions) |
| 001 | [`media_profile` v1](./RFC-001-media-profile-v1.md) | `.klickd v4` | **Accepted** (2026-05-24) |
| 002 | [`verification_gates` + `human_veto`](./RFC-002-verification-gates.md) | `.klickd v4-A` (v1) · `v4-B` (v2 draft) | **Accepted** (v1 core, 2026-05-24) · Draft (v2 §8b additions) |
| 003 | [Context Cost Benchmark](../../benchmarks/context_cost/RFC.md) | `.klickd v4` (research / benchmark track) | Draft |
| 004 | [Migration & Backward Compatibility](./RFC-004-migration-backward-compatibility.md) | `.klickd v4` (migration policy for `v2.5 → v3.x → v3.5.1 → v4`) | **Proposed** (2026-05-23) |
| 004 | [Migration & Backward Compatibility](./RFC-004-migration-backward-compatibility.md) | `.klickd v4` (migration policy for `v2.5 → v3.x → v3.5.1 → v4`) | **Accepted** (2026-05-24) |
| 005 | *Claim-memory growth & deterministic compaction (planned — not yet drafted)* | `.klickd v4+` (post-preview) | Planned — placeholder in [`ROADMAP.md`](../../ROADMAP.md) |
| 006 | [`agent_core` / Agent Operating Context](./RFC-006-agent-core.md) | `.klickd v4+` (post-GA; first-party showcase `core.Kai.klickd`) | Draft |
| 007 | [`usage_profile` & in-session skill routing](./RFC-007-usage-profile-skill-routing.md) | `.klickd v4+` (post-GA; first-run purpose selection + progressive disclosure + skill routing) | Draft |
| 008 | [`core_update_watch` — domain core veille & update policy](./RFC-008-core-update-watch.md) | `.klickd v4+` (post-GA; core layer only — never touches user memory) | Draft (2026-05-24) |

> RFC-001, RFC-002 (v1 core), and RFC-004 were promoted from `Draft` to `Proposed` on 2026-05-23 (docs-only). This freezes the conceptual surface for community review and for the v4 GA schema / SDK work tracked in [`docs/roadmap/ROAD-TO-V4-GA.md`](../roadmap/ROAD-TO-V4-GA.md). No SDK, schema, or vector changes are part of this promotion. RFC-003 stays `Draft` pending the benchmark execution (P1-3). RFC-002 §8b additions (v2 — claim grounding, contract tests, verification artifacts) stay `Draft` and may still iterate without affecting the v1 Proposed surface.
> RFC-001, RFC-002 (v1 core), and RFC-004 were promoted from `Draft` to `Proposed` on 2026-05-23 (docs-only), and from `Proposed` to `Accepted` on 2026-05-24 (docs-only) per the [V4 Acceptance Checklist](./ACCEPTANCE_CHECKLIST_V4.md) §3. `Accepted` means "approved for inclusion in the next normative `SPEC.md` revision"; it triggers no SDK, schema, vector, npm / PyPI / Zenodo / IANA publish, and no tag. RFC-003 stays `Draft` pending the benchmark execution (P1-3). RFC-002 §8b additions (v2 — claim grounding, contract tests, verification artifacts) stay `Draft` and may still iterate without affecting the v1 Accepted surface. The v4 GA schema / SDK / vector work tracked in [`docs/roadmap/ROAD-TO-V4-GA.md`](../roadmap/ROAD-TO-V4-GA.md) (P0-1 SPEC normative, P0-2 strict schema, P0-3/4 SDKs, P0-5 migrator, P0-6 strict vectors) may now begin against the frozen v1 surface.

> **Promotion gate.** Moving an RFC from `Proposed` to `Accepted` (and later to `Implemented`) follows the explicit checklist in [`ACCEPTANCE_CHECKLIST_V4.md`](./ACCEPTANCE_CHECKLIST_V4.md). The checklist is **docs-only** and **non-normative**: it does not change any schema, SDK, or vector, and triggers no publish. It exists so that any contributor can audit an RFC against deterministic criteria before opening a promotion PR.

Expand Down
5 changes: 3 additions & 2 deletions docs/rfcs/RFC-001-media-profile-v1.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,16 @@
| **RFC** | 001 |
| **Title** | `media_profile` v1 — portable, encrypted, model-agnostic media context |
| **Target** | `.klickd v4` (envelope-v4 / payload extension) |
| **Status** | **Proposed** |
| **Status** | **Accepted** |
| **Author** | Vince C. (Klickd / Luxlearn, Luxembourg) |
| **Created** | 2026-05-22 |
| **Promoted to Proposed** | 2026-05-23 |
| **Promoted to Accepted** | 2026-05-24 |
| **Supersedes** | — |

> **This RFC is non-normative.** It targets a future `.klickd v4` release. No part of this document is binding on any current v3.x reader or writer. v3.x readers MUST ignore any `media_profile` field they encounter — see [Forward compatibility](#forward-compatibility).
>
> **Status note (Proposed).** The conceptual surface is frozen for community review and prototype implementations MAY rely on the §4 decisions and the §5 illustrative schema. The formal JSON Schema, error wiring, and SDK API land only at `Accepted` and `Implemented`. Open questions (§11) remain genuinely open and do not block this promotion.
> **Status note (Accepted).** The conceptual surface frozen at `Proposed` (the §4 decisions, the §5 illustrative schema, the §6 V-001…V-012 validation checklist, and the §9 error codes) is approved for inclusion in the next normative `SPEC.md` revision — see [`ACCEPTANCE_CHECKLIST_V4.md`](./ACCEPTANCE_CHECKLIST_V4.md) §3. Acceptance is **docs-only**: no SDK, schema, vector, or release is triggered. The formal JSON Schema, error wiring, and SDK API land only at `Implemented`. Open questions (§11) remain genuinely open and do not block acceptance.

---

Expand Down
5 changes: 3 additions & 2 deletions docs/rfcs/RFC-002-verification-gates.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,18 +5,19 @@
| **RFC** | 002 |
| **Title** | `verification_gates` + `human_veto` — UX-first guardrails for agent actions |
| **Target** | `.klickd v4-A` (v1 core) · `.klickd v4-B` (v2 claim grounding & contracts) |
| **Status** | **Proposed (v1 core) · Draft (v2 additions)** |
| **Status** | **Accepted (v1 core) · Draft (v2 additions)** |
| **Author** | Vince C. (Klickd / Luxlearn, Luxembourg) |
| **Created** | 2026-05-22 |
| **Revised** | 2026-05-22 (v2 draft: claim grounding + contract tests, additive) |
| **Promoted to Proposed** | 2026-05-23 (v1 core only; v2 §8b sections remain `Draft`) |
| **Promoted to Accepted** | 2026-05-24 (v1 core only; v2 §8b sections stay `Draft`) |
| **Supersedes** | — |

> **This RFC is non-normative.** It targets future `.klickd v4-A` and `v4-B` releases. No part of this document is binding on any current v3.x reader or writer. v3.x readers MUST ignore any `verification_gates`, `claim_sources`, `human_veto_policy`, `error_journal`, `risk_thresholds`, `preflight_checks`, `contract_tests`, `success_criteria`, `reversibility`, or `blast_radius` field they encounter — see [Forward compatibility](#forward-compatibility).
>
> **v2 additions are strictly additive over v1.** v2 introduces no new gate levels and no new UX surfaces. It refines *how* a gate decides — by grounding factual claims (`claim_status`, source provenance) and by attaching machine-checkable `contract_tests` and `success_criteria` to action classes — without changing the silent-by-default UX contract from v1 §4. A v4-A reader that does not understand v4-B fields MUST ignore them and behave exactly as the v1 resolution rules describe.
>
> **Status note (Proposed for v1; Draft for v2).** The v1 core — five gate levels, `human_veto_policy`, `claim_sources`, `error_journal`, `risk_thresholds`, `preflight_checks`, and the §4 decisions — is frozen for community review and prototype implementations. The v2 sections (§8b) — `claim_status`, `contract_tests`, `success_criteria`, `reversibility`, `blast_radius`, `verification_artifacts`, `error_journal[].rule_created` — remain `Draft` and MAY still change. Open questions (§10) remain open and do not block this promotion.
> **Status note (Accepted for v1 core; Draft for v2).** The v1 core surface frozen at `Proposed` — five gate levels (§6), `human_veto_policy`, `claim_sources` (v1 fields only), `error_journal`, `risk_thresholds`, `preflight_checks`, the §4 decisions, the §6 level semantics, and the §9 G-001…G-006 conformance intent — is approved for inclusion in the next normative `SPEC.md` revision per [`ACCEPTANCE_CHECKLIST_V4.md`](./ACCEPTANCE_CHECKLIST_V4.md) §3. Acceptance is **docs-only**: no SDK, schema, vector, or release is triggered. The v2 sections (§8b) — `claim_status`, `contract_tests`, `success_criteria`, `reversibility`, `blast_radius`, `verification_artifacts`, `error_journal[].rule_created`, and the extended `claim_sources.records[]` fields — remain `Draft` and MAY still change. Open questions (§10) remain open and do not block acceptance of the v1 core.

---

Expand Down
5 changes: 3 additions & 2 deletions docs/rfcs/RFC-004-migration-backward-compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,16 +5,17 @@
| **RFC** | 004 |
| **Title** | Migration & Backward Compatibility for older `.klickd` files |
| **Target** | `.klickd v4` (migration policy applies retroactively to `v2.5 → v3.x → v3.5.1 → v4`) |
| **Status** | **Proposed** |
| **Status** | **Accepted** |
| **Author** | Vince C. (Klickd / Luxlearn, Luxembourg) |
| **Created** | 2026-05-22 |
| **Revised** | 2026-05-22 |
| **Promoted to Proposed** | 2026-05-23 |
| **Promoted to Accepted** | 2026-05-24 |
| **Supersedes** | — |

> **This RFC is non-normative.** Nothing in this document binds any current SDK, schema, reader, or writer. It defines the *intended* migration model for older `.klickd` files at the moment a future v4 release lands. Until promoted into `SPEC.md` and the relevant schemas, the rules below MUST NOT be relied on for implementation.
>
> **Status note (Proposed).** The "Never break the soul" principle (§3), the staged pipeline (§5.4), the reader-vs-writer behaviour matrix (§6), the legacy/unknown/`x_*` handling (§7), and the rollback model (§8) are frozen for community review and for the reference migrator design work (T-401 / T-402). Open decisions (§12) remain open and do not block this promotion.
> **Status note (Accepted).** The surface frozen at `Proposed` — the §3 "Never break the soul" sub-principles, the §4 decisions, the §5.4 staged pipeline (`v2.5 → v3.x → v3.5.1 → v4`), the §6 reader-vs-writer behaviour matrix, the §7 legacy / unknown / `x_*` handling rules, and the §8 rollback model — is approved for inclusion in the next normative `SPEC.md` revision per [`ACCEPTANCE_CHECKLIST_V4.md`](./ACCEPTANCE_CHECKLIST_V4.md) §3. Acceptance is **docs-only**: no SDK, schema, vector, or release is triggered. The reference migrator implementation (T-401 / T-402) and `migration_report` schema (T-405) remain future work for `Implemented`. Open decisions (§12) remain open and do not block acceptance.

---

Expand Down
26 changes: 13 additions & 13 deletions docs/roadmap/ROAD-TO-V4-GA.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
- SPEC §33 (preview, non-normative)
- schémas permissifs (`additionalProperties: true`)
- SDKs round-trip-preserving (`klickd==4.0.0a1`, `@klickd/core@4.0.0-preview.1` — preview, jamais `latest`)
- RFC-001 / 002 (v1 core) / 004 en **Proposed** (promues 2026-05-23, docs-only). RFC-003 et RFC-002 §8b (v2 additions) restent **Draft**.
- RFC-001 / 002 (v1 core) / 004 en **Accepted** (promues `Proposed` 2026-05-23, puis `Accepted` 2026-05-24, docs-only, via le [V4 Acceptance Checklist](../rfcs/ACCEPTANCE_CHECKLIST_V4.md) §3 C1–C16). RFC-003 et RFC-002 §8b (v2 additions) restent **Draft**.
- RFC-006 (`agent_core` / Agent Operating Context, première itération, future-work) en **Draft** — voir [`docs/rfcs/RFC-006-agent-core.md`](../rfcs/RFC-006-agent-core.md). **Hors P0 GA** : post-GA / showcase first-party `core.Kai.klickd`.
- UX spec ([`docs/ux/V4-UX-SPEC.md`](../ux/V4-UX-SPEC.md))
- vectors `vectors_v40_preview.json`
Expand Down Expand Up @@ -264,21 +264,21 @@ L’ordre suivant minimise le re-travail :

> **Statut 2026-05-24 :**
>
> - La PR #30 « rfc(v4): promote RFC-001 / RFC-002 / RFC-004 from Draft to Proposed » a été mergée le 2026-05-23 (docs-only, aucun SDK / schéma / vector touché).
> - La PR suivante, également docs-only, introduit l'[**Acceptance Checklist V4**](../rfcs/ACCEPTANCE_CHECKLIST_V4.md) : critères explicites C1–C16 pour la promotion `Proposed → Accepted`, et I1–I9 pour `Accepted → Implemented`. Elle ne modifie aucun statut RFC. Elle ne touche aucun SDK, schéma, vector.
> - La PR #30 « rfc(v4): promote RFC-001 / RFC-002 / RFC-004 from Draft to Proposed » a été mergée le 2026-05-23 (docs-only).
> - La PR « docs(rfc): add V4 acceptance checklist » a introduit l'[**Acceptance Checklist V4**](../rfcs/ACCEPTANCE_CHECKLIST_V4.md) (critères C1–C16 pour `Proposed → Accepted`, I1–I9 pour `Accepted → Implemented`), docs-only.
> - La PR courante « rfc(v4): promote RFC-001 / RFC-002 (v1 core) / RFC-004 from Proposed to Accepted » applique ce checklist aux trois RFCs cibles. Acceptance = docs-only, aucun SDK / schéma / vector / publish / tag.

Justification : avant de promouvoir RFC-001 / RFC-002 (v1 core) / RFC-004 de
`Proposed` à `Accepted` (préalable explicite de P0-1 — SPEC normative v4), il
faut un gate déterministe. Sans ce gate, `Accepted` reste une décision implicite
d'un seul mainteneur. Le checklist garde l'autorité de décision côté mainteneur
mais rend l'évaluation auditable par n'importe quel contributeur.
Justification : promouvoir RFC-001 / RFC-002 (v1 core) / RFC-004 de `Proposed`
à `Accepted` est le préalable explicite de P0-1 (SPEC normative v4). Le
checklist C1–C16 garde l'autorité de décision côté mainteneur mais rend
l'évaluation auditable par n'importe quel contributeur.

La séquence attendue, après merge de cette PR docs-only, est :
La séquence après merge de la PR d'acceptance est :

1. **PR « rfc(v4): promote RFC-001 from Proposed to Accepted »** — coche le checklist §3, sans modifier SDK / schéma / vector.
2. **PR « rfc(v4): promote RFC-002 (v1 core) from Proposed to Accepted »** — idem.
3. **PR « rfc(v4): promote RFC-004 from Proposed to Accepted »** — idem.
4. **PR « spec(v4): begin promoting §33 preview wording toward normative (P0-1) »** — démarre la phase SPEC normative une fois les trois RFCs en `Accepted`.
1. ~~**PR « rfc(v4): promote RFC-001 from Proposed to Accepted »**~~incluse dans la PR groupée d'acceptance (2026-05-24).
2. ~~**PR « rfc(v4): promote RFC-002 (v1 core) from Proposed to Accepted »**~~ — idem.
3. ~~**PR « rfc(v4): promote RFC-004 from Proposed to Accepted »**~~ — idem.
4. **PR « spec(v4): begin promoting §33 preview wording toward normative (P0-1) »** — démarre la phase SPEC normative maintenant que les trois RFCs sont en `Accepted`.

Aucune de ces PR ne déclenche un publish (npm / PyPI / Zenodo), un tag, ni une
annonce externe. Elles restent docs-first conformément à la règle §3.10.
Expand Down
Loading