integrate: cumulative x.klickd supply-chain (PRs #115-#120)

.internal-skills/supply-chain/ACTION_LOG.md

@@ -0,0 +1,81 @@
+# `.internal-skills/supply-chain/ACTION_LOG.md` — append-only internal action log
+
+> Internal · NON-NORMATIVE. Append-only. Records actions, validations, and
+> limitations for supply-chain runner/gate work. No external action is recorded
+> here because none was taken (no release, tag, DOI, publish, deploy, or
+> communication). The private repo `Davincc77/klickd-ai` was not touched.
+
+---
+
+## 2026-06-02 — candidate generator + promotion gate (v0.1)
+
+- **Branch:** `feat/supply-chain-runner-gate`, stacked on
+  `integration/supply-chain-cumulative` (PR #121).
+- **Base for PR:** `integration/supply-chain-cumulative` (NOT `main`).
+
+### Added
+- `scripts/generate_supply_chain_candidate.py` — internal candidate generator
+  (runner). Config-only `build_request` JSON → candidate skill in the internal
+  v4.2 target shape under `.internal-skills/supply-chain/candidates/` or
+  `--out`. Deterministic: `candidate_id` / `candidate_hash` / `run_id` derived
+  only from canonical build_request bytes (+ resolved source manifest hash).
+  No `generated_at` in the hashed core. Sources come only from the
+  build_request / referenced source_manifest; missing domain info →
+  `requires_human_premium_pass`, never hallucinated.
+- `scripts/run_supply_chain_promotion_gate.py` — combined promotion gate.
+  Orchestrates threat model (always), source/license (when `--source-manifest`),
+  logical diff (when `--before`), candidate shape checks, and forbidden-claim /
+  public-private boundary tripwires. Classifies ACCEPT / ACCEPT_WITH_REVIEW /
+  BLOCK. Exit 0 acceptable, 1 BLOCK, 2 usage. `deterministic_gate_id` excludes
+  the clock (`eval_date`). Reports — does not run — premium pass. `not_run`
+  checks recorded with a reason, never as `pass`.
+- `tests/test_supply_chain_candidate.py` (20 tests),
+  `tests/test_supply_chain_promotion_gate.py` (19 tests).
+- `tests/fixtures/supply_chain_candidate/` — `build_request_clean.json`,
+  `build_request_missing_domain.json`, `source_manifest_ok.json`.
+- Example artefacts: `candidates/xklickd-research-reader.json`,
+  `promotion-gate/xklickd-research-reader.gate.json` + `.gate.md`.
+- Updated `README.md` integration index: moved Candidate generation + Promotion
+  gate from "planned" to tool-backed, with literal scope notes.
+
+### Commands run (local, offline, stdlib-only)
+- `python scripts/generate_supply_chain_candidate.py --build-request <req> --out <path>`
+- `python scripts/run_supply_chain_promotion_gate.py --candidate <cand> [--source-manifest <m>] [--before <prev>] --out <path> --md <path> --eval-date 2026-06-02`
+- `python -m pytest tests/test_supply_chain_*.py` → 102 passed.
+- `python -m pytest tests/` → 283 passed, 1 unrelated DeprecationWarning
+  (jsonschema.__version__), 0 failures.
+- `python scripts/verify_xklickd_skill_packs.py verify` → rc 0.
+- `python scripts/validate_v4_schemas.py` → rc 0.
+- `python scripts/validate_v4_1_candidate_mapping.py` → rc 0.
+- Forbidden-claims / codename grep over committed `candidates/` and
+  `promotion-gate/` artefacts → CLEAN (no banned substring). Internal track name
+  `xklickd_internal_skill_v4_2` appears only inside the candidate's
+  `internal_target` block, as designed.
+
+### Validations / behaviour confirmed
+- Deterministic repeatability: identical build_request → identical
+  candidate_id/hash; identical candidate → identical gate_id, stable across
+  differing `--eval-date`.
+- Missing domain info → `requires_human_premium_pass=true` with named gaps;
+  no competencies/sources hallucinated.
+- Clean candidate → gate ACCEPT (exit 0).
+- Missing-domain candidate → gate ACCEPT_WITH_REVIEW (exit 0),
+  premium_pass_required=true.
+- Forbidden claim, internal codename, private→public leak, public v4.2
+  over-claim, missing v4.2 layer, completeness claim → gate BLOCK (exit 1).
+
+### Limitations (no mirage)
+- Emitting the v4.2 target shape is NOT a claim of supply-chain completeness; a
+  generated candidate is NOT a loaded executable skill (fails the loaded-skill
+  gate: requires artifact_loaded AND sha256_matches_manifest).
+- The gate's boundary tripwire is a coarse guard, not a full PII/secrets
+  scanner (still a planned stage). Runtime enforcement remains planned.
+- No legal/compliance, security-certification, or benchmark-superiority claim.
+- Premium pass is reported as required where applicable but is NOT executed.
+
+### Explicitly NOT done
+- No release, tag, DOI, npm/PyPI publish, GitHub Release, or deploy.
+- No merge to `main`.
+- No external communication.
+- No change to `Davincc77/klickd-ai`.
+- No public artefact promoted to v4.2 (public stays v4.1 candidates).

.internal-skills/supply-chain/README.md

@@ -0,0 +1,60 @@
+# `.internal-skills/supply-chain/` — internal supply-chain stages (integration index)
+
+| | |
+|---|---|
+| **Status** | **Internal · NON-NORMATIVE · no release / no publish / no merge to main** |
+| **Created** | 2026-06-02 |
+| **Companion spec** | [`docs/rfcs/chimera/SUPPLY_CHAIN.md`](../../docs/rfcs/chimera/SUPPLY_CHAIN.md) (process spec) |
+| **Rules of engagement** | [`MASTER_BRIEF.md`](../../MASTER_BRIEF.md) (anti-mirage rules, v4.1/v4.2 boundary) |
+
+> This directory holds **internal** supply-chain artefacts and the audit/diff/source-check records produced by the tool-backed stages. Nothing here is a public release, a normative spec, a schema, or an SDK contract. Read every stage label **literally** (`tool` / `planned`). A catalog entry or stub is **never** a loaded executable skill — see the loaded-skill gate in §"Loaded-skill gate".
+
+This README is the integration index that brings the supply-chain components together. It is the human-readable map of which stages are **real and tool-backed today** versus **planned**.
+
+---
+
+## Real, tool-backed stages (shipped + tested)
+
+| Stage | Tool | Internal artefacts | Tests |
+|---|---|---|---|
+| **Audit / determinism** | `scripts/generate_supply_chain_audit.py` | `audit/audit_trail_index.json`, `audit/determinism_record.json` | `tests/test_supply_chain_audit.py` |
+| **Logical diff** | `scripts/generate_supply_chain_diff.py` | `diff/` (report output) | `tests/test_supply_chain_diff.py` (+ `tests/fixtures/supply_chain_diff/`) |
+| **Source freshness + license** | `scripts/check_supply_chain_sources.py` | `source-check/example_source_manifest.json` | `tests/test_supply_chain_sources.py` (+ `tests/fixtures/supply_chain_sources/`) |
+| **Threat model** | `scripts/generate_supply_chain_threat_model.py` | (report output) · doc: `docs/supply-chain/THREAT_MODEL_GENERATOR.md` | `tests/test_supply_chain_threat_model.py` (+ `tests/fixtures/threat-model/`) |
+| **Candidate generation** | `scripts/generate_supply_chain_candidate.py` | `candidates/` (example: `candidates/xklickd-research-reader.json`) | `tests/test_supply_chain_candidate.py` (+ `tests/fixtures/supply_chain_candidate/`) |
+| **Promotion gate** | `scripts/run_supply_chain_promotion_gate.py` | `promotion-gate/` (example: `promotion-gate/xklickd-research-reader.gate.json` + `.md`) | `tests/test_supply_chain_promotion_gate.py` |
+
+Each of these is `tool`: a runnable script with a passing test module and deterministic output. "Tool-backed" means the bytes and behaviour exist and are tested — it does **not** imply the supply chain is complete, that any candidate is a loaded skill, or that a public release exists.
+
+### Candidate generator scope (read literally)
+
+`generate_supply_chain_candidate.py` emits the **internal v4.2 target shape** from a config-only `build_request`. Emitting the shape is **not** a claim that every lifecycle stage is implemented or verified — and a generated candidate is **not** a loaded executable skill (it fails the loaded-skill gate below). When domain information is missing, the runner marks `requires_human_premium_pass` rather than inventing competencies, risk, or sources. Sources come **only** from the `build_request` / referenced `source_manifest`.
+
+### Promotion gate scope (read literally)
+
+`run_supply_chain_promotion_gate.py` orchestrates the tool-backed checks (threat model always; source/license when a manifest is given; logical diff when a `--before` is given) plus candidate shape checks and forbidden-claim / public-private boundary tripwires. It classifies **ACCEPT / ACCEPT_WITH_REVIEW / BLOCK** and **reports** whether a human premium pass is required — it does **not** run that pass, and makes no compliance/security/benchmark claim. A check that could not run is recorded `not_run` with a reason, never as `pass`.
+
+## Planned stages (specified, not built)
+
+| Stage | What it will do | Why it is not claimed yet |
+|---|---|---|
+| **Full PII / secrets scanner** | Scan candidate inputs/outputs for PII and secrets beyond the engineering source/license checks. | Current `source-check` is an engineering license/freshness check, **not** a compliance attestation or a PII scanner. The gate's boundary tripwire is a coarse guard, not a full scanner. |
+| **Runtime enforcement** | Enforce guardrails in-loop at execution time, not just at build/audit time. | Build-time checks + the promotion gate exist; runtime enforcement does not. |
+
+---
+
+## Loaded-skill gate
+
+A pack/skill is "loaded" or "used" **only** when:
+
+```
+artifact_loaded == true  AND  sha256_matches_manifest == true
+```
+
+per [`docs/integrations/skill-loader-protocol.md`](../../docs/integrations/skill-loader-protocol.md). Anything short of that — a manifest row, a stub, a routing placeholder — is **not** a loaded skill and must not be described as one.
+
+## Boundary reminder
+
+- Public artefacts remain **v4.1**. **No public v4.2 claim.** v4.2 is an internal target only (`docs/internal/`).
+- No release, publish, tag, DOI, external communication, merge to main, or PR approval from supply-chain work.
+- Do not touch `Davincc77/klickd-ai`.

.internal-skills/supply-chain/audit/README.md

@@ -0,0 +1,70 @@
+# x.klickd supply-chain — audit-trail index + determinism record
+
+**Status:** NON-NORMATIVE. Not a v4.1 GA release artefact. No publish / deploy /
+merge / tag / release performed by this stage.
+
+This directory holds the **first tool-backed automation stage** of the x.klickd
+supply-chain protocol. It does **not** automate the full pipeline. It turns two
+traceability elements from spec into artefacts that are actually generated,
+hashed, and re-checkable by a script:
+
+| File | What it is |
+|---|---|
+| `audit_trail_index.json` | A consultable index of the verifiable artifacts the supply chain operates on, the declared validation commands, an append-style event list, and a per-stage automation map. |
+| `determinism_record.json` | Input file hashes, output file hashes, and a `deterministic_run_id` derived **only** from inputs, so identical inputs yield an identical id across runs and hosts. |
+
+## Generate / re-check
+
+```bash
+# Write (or refresh) both artefacts:
+python scripts/generate_supply_chain_audit.py
+
+# Verify the on-disk artefacts are still in sync with current inputs (no write):
+python scripts/generate_supply_chain_audit.py check
+```
+
+`generate` exits non-zero if a critical invariant fails (missing or changed
+input, hash mismatch against the manifest, banned public-claim string, or an
+obvious secret/PII pattern in the generated output). `check` exits non-zero on
+any drift in the deterministic core.
+
+## Determinism
+
+- The inputs are the 42 NON-NORMATIVE x.klickd v4.1 candidate skill packs plus
+  their manifest under `examples/v4.1/x-klickd-skills/` (43 inputs total).
+- An input is counted **only** when its bytes exist on disk **and** hash-match
+  the manifest — the same `artifact_loaded` + `sha256_matches_manifest` gate
+  enforced by `scripts/verify_xklickd_skill_packs.py`. A catalogue entry alone
+  is not a loaded skill.
+- `deterministic_run_id` and `checked_artifacts_hash_summary` are computed over
+  `(relative_path, sha256)` pairs only. They do **not** depend on timestamps,
+  host, or run order.
+- The only non-deterministic field, `generated_at`, is quarantined under
+  `non_deterministic_zone` and is **excluded** from every hash.
+
+## What is real vs. planned
+
+`stage_automation` in `audit_trail_index.json` labels each pipeline stage:
+
+- `tool` — backed by shipped, runnable automation (audit-trail index,
+  determinism record, reproducibility check, pack hash verification, candidate
+  mapping validation).
+- `partial` — a tripwire, not a full implementation (the PII/secrets scan here
+  guards only this stage's own generated output).
+- `planned` — spec-only; no automation yet (diff report, threat model, license
+  check, source-freshness check, private/public boundary check, context-graph
+  generation, candidate-skill generation).
+- `manual` — human/agent premium pass.
+
+`validation_results` is intentionally **empty**: this generator records the
+declared validation commands but does not run them, so it does not assert their
+outcomes. Pre-filled "pass" values would be a mirage. The operator runs the
+commands; the audit / CI captures the outcomes.
+
+## Relation to the supply-chain spec
+
+The full 18-stage build-process specification is documented separately in the
+supply-chain RFC under `docs/rfcs/` (the docs-only spec PR; not merged here).
+This stage is the narrow, executable slice of stage **15 (determinism /
+reproducibility)** and the **audit-trail index** from that spec. Everything else
+in the pipeline remains `planned` until separately implemented.

.internal-skills/supply-chain/audit/audit_trail_index.json

@@ -0,0 +1,52 @@
+{
+  "build_or_audit_events": [
+    {
+      "automation": "tool",
+      "event": "audit_trail_index_generated",
+      "inputs_hash_summary": "10fa77ec74ebfa2b7daa51a5787607b1dc9eb654608477f478c7850ab5a09b85",
+      "source_commit_sha": "b73858cb2d9c6915195361e9ed34ed1b02a39ea4",
+      "stage": "audit_trail_index"
+    }
+  ],
+  "checked_artifacts_count": 43,
+  "checked_artifacts_hash_summary": "10fa77ec74ebfa2b7daa51a5787607b1dc9eb654608477f478c7850ab5a09b85",
+  "deterministic_run_id": "sha256:10fa77ec74ebfa2b7daa51a5787607b1dc9eb654608477f478c7850ab5a09b85",
+  "kind": "x_klickd_supply_chain_audit_trail_index",
+  "non_deterministic_zone": {
+    "comment": "Fields here are excluded from deterministic_run_id and checked_artifacts_hash_summary.",
+    "generated_at": "2026-06-02T11:20:28Z"
+  },
+  "non_normative": true,
+  "notes": [
+    "NON-NORMATIVE. Not a v4.1 GA release artefact.",
+    "Only the stages marked 'tool' are backed by shipped automation; 'planned' stages are spec-only; 'partial' is a tripwire, not a full scanner; 'manual' is human/agent premium work.",
+    "An artifact is counted only when its bytes exist on disk and hash-match the manifest (loaded + sha256_matches_manifest).",
+    "validation_results is empty by design: this generator does not run the validation commands, so it does not assert their outcomes.",
+    "Timestamps are excluded from deterministic_run_id; see determinism_record.json non_deterministic_zone."
+  ],
+  "repo": "Davincc77/klickdskill",
+  "schema_version": "0.1.0",
+  "source_commit_sha": "b73858cb2d9c6915195361e9ed34ed1b02a39ea4",
+  "stage_automation": {
+    "audit_trail_index": "tool",
+    "candidate_mapping_validation": "tool",
+    "candidate_skill_generation": "planned",
+    "context_graph_generation": "planned",
+    "determinism_record": "tool",
+    "diff_report": "planned",
+    "license_check": "planned",
+    "pack_hash_verification": "tool",
+    "pii_secrets_scan": "partial",
+    "premium_pass": "manual",
+    "private_public_boundary_check": "planned",
+    "reproducibility_check": "tool",
+    "source_freshness_check": "planned",
+    "threat_model": "planned"
+  },
+  "validation_commands": [
+    "python scripts/verify_xklickd_skill_packs.py verify",
+    "python scripts/validate_v4_1_candidate_mapping.py",
+    "pytest tests/test_supply_chain_audit.py"
+  ],
+  "validation_results": []
+}