feat(learning): S9 — D7 læringssløyfe: verdict-inbox, fail-closed promoteringsgate, artefakt-sourced persona

- inbox.py (§4.2+§5): VerdictDocument med verbatim-id-regel; write_verdict
  authoring-primitiv (deterministisk JSON); load_inbox tolerant (skip, aldri
  raise; sortert på filnavn); merge_inbox_into_store first-write-wins,
  idempotent, skriver aldri (rolle-splitt §3 steg 7)
- promotion.py (§6): promote fail-closed mot {approved,
  approved_with_adjustment}; eksplisitt påkrevd timestamp; minimal frontmatter
  (rationale → description, aldri strukturerte læringsfelt); path-safe token
  med content-hash-fallback; idempotent index-lenking med fast nøytral label
- persona.py (§4.3): load_persona_example fail-fast (run-path-vokabular,
  marker ⊆ rationale); drop_persona_verdict artefakt-sourced ved kalltid mot
  delt shared/-artefakt
- experience.py (kirurgisk): seeding leser verdict_id VERBATIM fra frontmatter
  — re-minting ville kollidert distinkte promoterte kandidater
- 43 nye load-bearing tester (step7/step8/persona), 164/164 uten API-nøkkel;
  to-runs-bevis med fersk store + tom-inbox-kontroll; fire detach-bevis kjørt
  røde og revertert grønne

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QdSfQdND84oeq2mbjueLTS

src/portfolio_optimiser_claude/experience.py

@@ -124,7 +124,10 @@ def seed_store_from_bundle(store: VerdictStore, bundle_dir: Path) -> int:
     Entries are keyed on the bundle's candidate features, read from the IR
     projection (fail-fast, required input). The rationale is built from the
     ``description`` frontmatter plus, when present, the structured learning fields.
-    Returns the number of verdict files seeded.
+    A ``verdict_id`` in the frontmatter (promoted files, §6) is read VERBATIM
+    (§4.2) — re-minting from the bundle features would collide distinct
+    promoted candidates into one first-write-wins store slot. Returns the
+    number of verdict files seeded.
     """
     features = CandidateFeatures.from_proposal(load_validator_input(bundle_dir))
     seeded = 0
@@ -141,7 +144,7 @@ def seed_store_from_bundle(store: VerdictStore, bundle_dir: Path) -> int:
             rationale = f"{rationale} {learning}".strip()
         store.add(
             VerdictRecord(
-                verdict_id=mint_verdict_id(features),
+                verdict_id=concept.frontmatter.get("verdict_id") or mint_verdict_id(features),
                 decision=concept.frontmatter.get("decision", _DEFAULT_SEED_DECISION),
                 rationale=rationale,
                 features=features,

src/portfolio_optimiser_claude/inbox.py

@@ -0,0 +1,132 @@
+"""The verdict file and the inbox folder contract (method-spec §4.2, §5).
+
+The long feedback loop's folder interface: an expert (or, in simulation, the
+persona) drops one verdict per ``{id}.json`` file into an inbox folder; a
+separate, later run picks it up — fully resumable, no live-session assumption.
+Role split (§3 Step 7, unwaivable): the system READS the inbox (tolerant load,
+merge into the store); writing is the authoring primitive's job, used only by
+the expert/persona side — a run never persists its own captured verdict back.
+
+Decision vocabulary at this layer: the file carries the expert decision as a
+plain string — the run-path feedback contract (§4.1) and the promotion gate's
+accepted set (§6) are where the vocabulary is policed, not the raw file layer.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from pydantic import BaseModel, Field, ValidationError
+
+from portfolio_optimiser_claude.experience import (
+    CandidateFeatures,
+    VerdictRecord,
+    VerdictStore,
+    mint_verdict_id,
+)
+
+
+class ProposalFeatures(BaseModel):
+    """§4.2 ``proposal_features``: the structural features of the judged candidate.
+
+    ``description`` is surface text — deliberately excluded from both
+    similarity ranking and id minting.
+    """
+
+    affected_codes: list[str]
+    measure_type: str
+    claimed_saving_nok: float
+    description: str
+
+
+class VerdictDocument(BaseModel):
+    """One verdict file (§4.2). A LOADED ``id`` is kept verbatim — never re-minted."""
+
+    id: str = Field(min_length=1)
+    decision: str = Field(min_length=1)
+    rationale: str = Field(min_length=1)
+    proposal_features: ProposalFeatures
+
+    @classmethod
+    def from_candidate(
+        cls,
+        features: CandidateFeatures,
+        *,
+        decision: str,
+        rationale: str,
+        description: str,
+    ) -> VerdictDocument:
+        """Author a verdict for a candidate — the id is minted per §4.2."""
+        return cls(
+            id=mint_verdict_id(features),
+            decision=decision,
+            rationale=rationale,
+            proposal_features=ProposalFeatures(
+                affected_codes=sorted(features.affected_codes),
+                measure_type=features.measure_type,
+                claimed_saving_nok=features.claimed_saving_nok,
+                description=description,
+            ),
+        )
+
+    def features(self) -> CandidateFeatures:
+        return CandidateFeatures(
+            affected_codes=frozenset(self.proposal_features.affected_codes),
+            measure_type=self.proposal_features.measure_type,
+            claimed_saving_nok=self.proposal_features.claimed_saving_nok,
+        )
+
+    def to_record(self) -> VerdictRecord:
+        return VerdictRecord(
+            verdict_id=self.id,  # verbatim (§4.2) — raw number formatting could diverge
+            decision=self.decision,
+            rationale=self.rationale,
+            features=self.features(),
+        )
+
+
+def write_verdict(inbox_dir: Path, verdict: VerdictDocument) -> Path:
+    """The authoring primitive (§5): ``{id}.json``, written deterministically.
+
+    Creates the directory if needed; sorted keys, 2-space indent. The disk
+    layer is LAST-write-wins per file (§4.2).
+    """
+    inbox_dir.mkdir(parents=True, exist_ok=True)
+    path = inbox_dir / f"{verdict.id}.json"
+    payload = json.dumps(verdict.model_dump(), sort_keys=True, indent=2)
+    path.write_text(payload, encoding="utf-8")
+    return path
+
+
+def load_inbox(inbox_dir: Path) -> list[VerdictDocument]:
+    """Tolerant load (§5): the raw layer is written out of band — skip, never raise.
+
+    A missing folder yields zero verdicts; files that are not ``.json``, fail
+    to parse, or lack a required top-level key are SKIPPED. Deterministic
+    order: sorted by filename.
+    """
+    if not inbox_dir.is_dir():
+        return []
+    verdicts: list[VerdictDocument] = []
+    for path in sorted(inbox_dir.iterdir(), key=lambda p: p.name):
+        if path.suffix != ".json" or not path.is_file():
+            continue
+        try:
+            verdicts.append(VerdictDocument.model_validate(json.loads(path.read_text("utf-8"))))
+        except (OSError, ValueError, ValidationError):
+            continue
+    return verdicts
+
+
+def merge_inbox_into_store(store: VerdictStore, inbox_dir: Path) -> int:
+    """Merge, never replace (§5): per-verdict add, first-write-wins per id.
+
+    Runs BEFORE the Step-1 fold, so a passed-in store's existing verdicts
+    survive (cross-project threading) and repeated merges are idempotent.
+    Returns the number of inbox verdicts ingested; never writes anything.
+    """
+    verdicts = load_inbox(inbox_dir)
+    for verdict in verdicts:
+        store.add(verdict.to_record())
+    return len(verdicts)

src/portfolio_optimiser_claude/persona.py

@@ -0,0 +1,70 @@
+"""The persona example artifact loader (method-spec §4.3).
+
+The expert-reviewer persona is a shared skill artifact: one canonical example
+verdict JSON (``decision``, ``marker``, ``rationale``). The persona judgement
+is sourced from that artifact AT CALL TIME — never from an inlined copy — and
+loading is fail-fast: the artifact is required input (contrast the tolerant
+inbox, §5). In simulation the persona plays the human on the WRITE side of the
+inbox role split: ``drop_persona_verdict`` authors a §4.2 verdict file through
+the same folder interface a production expert uses.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+from portfolio_optimiser_claude.experience import CandidateFeatures
+from portfolio_optimiser_claude.inbox import VerdictDocument, write_verdict
+
+
+class PersonaVerdict(BaseModel):
+    """The canonical persona example (§4.3): a run-path decision + traceable payload."""
+
+    # §4.3: MUST be a run-path value (§4.1) — the seed-only vocabulary is rejected.
+    decision: Literal["approved", "rejected"]
+    marker: str = Field(min_length=1)
+    rationale: str = Field(min_length=1)
+
+    @model_validator(mode="after")
+    def _marker_is_traceable(self) -> PersonaVerdict:
+        # The marker is the payload a simulation follows from the persona's
+        # judgement into a later run's prompt — it must live in the rationale.
+        if self.marker not in self.rationale:
+            raise ValueError(
+                f"persona example: marker {self.marker!r} is not a substring of the rationale"
+            )
+        return self
+
+
+def load_persona_example(artifact_path: Path) -> PersonaVerdict:
+    """Load the shared artifact — FAIL-FAST on a missing or malformed file (§4.3)."""
+    return PersonaVerdict.model_validate(json.loads(artifact_path.read_text(encoding="utf-8")))
+
+
+def drop_persona_verdict(
+    inbox_dir: Path,
+    artifact_path: Path,
+    features: CandidateFeatures,
+    *,
+    description: str,
+) -> VerdictDocument:
+    """The persona judges a candidate and drops a verdict file into the inbox.
+
+    The judgement (decision + rationale) is read from the artifact at call
+    time; the id is minted from the candidate features (§4.2); the file is
+    written through the authoring primitive (§5) — the same interface a
+    production expert uses.
+    """
+    persona = load_persona_example(artifact_path)
+    verdict = VerdictDocument.from_candidate(
+        features,
+        decision=persona.decision,
+        rationale=persona.rationale,
+        description=description,
+    )
+    write_verdict(inbox_dir, verdict)
+    return verdict

src/portfolio_optimiser_claude/promotion.py

@@ -0,0 +1,103 @@
+"""The promotion gate (method-spec §3 Step 8, §6) — an opt-in PUBLIC primitive.
+
+``promote`` lifts one APPROVED verdict from the raw output layer into the OKF
+context layer as a navigable ``type: verdict`` concept file. It is NEVER wired
+into the run itself: the system reads context; the gate/persona promotes.
+Fail-closed — only human/persona-approved knowledge enters the wiki, never raw
+agent output (self-contamination). The index link label is FIXED and neutral:
+the index body flows verbatim into the rendered read-context, so a descriptive
+label would leak the learning signal around the gated fold.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from pathlib import Path
+
+from portfolio_optimiser_claude.inbox import VerdictDocument
+
+# §6: the gate's accepted set — approved_with_adjustment exists ONLY here and
+# in bundle-seed frontmatter, never on the run path (§4).
+_ACCEPTED_DECISIONS = frozenset({"approved", "approved_with_adjustment"})
+_PROMOTED_PREFIX = "promoted-verdict-"
+# §6: FIXED neutral label — carries NO verdict signal.
+_NEUTRAL_LABEL = "Promotert ekspert-dom"
+_TOKEN_UNSAFE = re.compile(r"[^A-Za-z0-9._-]")
+_INDEX_FILENAME = "index.md"
+
+
+class PromotionError(ValueError):
+    """A verdict was refused at the gate (§6) — nothing written, nothing linked."""
+
+
+def _filename_token(verdict_id: str) -> str:
+    # Path-safe, fail-closed against escaping names: sanitise to the safe
+    # alphabet; a degenerate token falls back to a content hash.
+    token = _TOKEN_UNSAFE.sub("", verdict_id)
+    if not token.strip("."):
+        token = hashlib.sha256(verdict_id.encode("utf-8")).hexdigest()[:16]
+    return token
+
+
+def _frontmatter_text(value: str) -> str:
+    # The frontmatter parser is line-oriented — prose must stay on one line.
+    return " ".join(value.split())
+
+
+def promote(
+    verdict: VerdictDocument,
+    bundle_dir: Path,
+    *,
+    approved_by: str,
+    experiment: str,
+    timestamp: str,
+) -> Path:
+    """Promote one approved verdict into the bundle — fail-closed, idempotent link.
+
+    ``timestamp`` is an explicit REQUIRED argument (no wall-clock default), so
+    promotion is deterministic and reproducible. The promoted file is minimal:
+    the rationale becomes ``description`` (the learning signal as prose) — the
+    structured learning fields of hand-authored seeds are never reproduced.
+    Ids key on candidate features (§4.2), so re-approving the same candidate
+    overwrites the same file (last-write-wins): one curated verdict file per
+    distinct candidate, not one per verdict event.
+    """
+    if verdict.decision not in _ACCEPTED_DECISIONS:
+        raise PromotionError(
+            f"promotion refused: decision {verdict.decision!r} is not in the "
+            f"gate's accepted set {sorted(_ACCEPTED_DECISIONS)} (§6 fail-closed)"
+        )
+    filename = f"{_PROMOTED_PREFIX}{_filename_token(verdict.id)}.md"
+    path = (bundle_dir / filename).resolve()
+    if path.parent != bundle_dir.resolve():
+        raise PromotionError(f"promotion refused: {filename!r} escapes the bundle")
+    path.write_text(
+        "---\n"
+        "type: verdict\n"
+        f"title: {_NEUTRAL_LABEL}\n"
+        f"decision: {verdict.decision}\n"
+        f"description: {_frontmatter_text(verdict.rationale)}\n"
+        f"verdict_id: {verdict.id}\n"
+        f"provenance: approved_by={approved_by}; experiment={experiment}; "
+        f"timestamp={timestamp}\n"
+        "tags: [verdict, promoted]\n"
+        "---\n",
+        encoding="utf-8",
+    )
+    _link_from_index(bundle_dir, filename)
+    return path
+
+
+def _link_from_index(bundle_dir: Path, filename: str) -> None:
+    # §6: navigation follows only index cross-links — an unlinked file is
+    # unreachable. Idempotent: re-promotion never double-links. (reference
+    # limitation: the read-modify-write is not atomic — single-process MVP.)
+    index_path = bundle_dir / _INDEX_FILENAME
+    index_text = index_path.read_text(encoding="utf-8")
+    if f"({filename})" in index_text:
+        return
+    link_line = f"- [{_NEUTRAL_LABEL}]({filename})\n"
+    if not index_text.endswith("\n"):
+        index_text += "\n"
+    index_path.write_text(index_text + link_line, encoding="utf-8")