@ericrisco/rsc 0.1.33 → 0.1.35

package/skills/roast-me/tools/adapters/gemini.py

@@ -1,50 +1,58 @@
 """Gemini CLI adapter (@google/gemini-cli).
 
-Session files: ~/.gemini/tmp/<project_hash>/chats/*.jsonl
-Format: JSON Lines. Each line is a MessageRecord.
-
-CONFIRMED (2026-06, via official Gemini CLI docs at google-gemini.github.io
-and github.com/google-gemini/gemini-cli session-management.md):
-  - Base path: ~/.gemini/tmp/
-  - Subdirectory: <project_hash>/chats/
-  - File format: JSONL
-  - MessageRecord fields include: sessionId, projectHash, model, role,
-    content (array of {text: "..."}), and token usage fields.
-
-STUBBED (exact MessageRecord schema):
-  The exact JSONL schema per line has not been verified against a live Gemini
-  CLI installation. The role/content structure is inferred from the official
-  session-management docs. If the schema differs, parse() returns [] gracefully.
-
-Degradation: if ~/.gemini/ does not exist, discover() returns [].
+Session files: ~/.gemini/tmp/<project_hash>/chats/session-*.json
+Format: a SINGLE JSON object per file (not JSONL).
+
+CONFIRMED (2026-06, against live ~/.gemini/tmp on macOS):
+  - Base path / layout: ~/.gemini/tmp/<project_hash>/chats/*.json
+  - File shape: {"sessionId", "projectHash", "startTime", "lastUpdated",
+    "messages": [ {"id", "timestamp", "type", "content", ...} ]}
+  - messages[].type is "user" or "gemini"; content is a plain string.
+  - gemini (assistant) messages also carry "model", "thoughts", "tokens".
+  - The format does NOT persist tool calls/errors as messages, so tool-error
+    detection is not possible here — followed_by_error stays False (honest);
+    correction detection (next user message) still works.
+
+Degradation: if ~/.gemini/ does not exist, discover() returns []; a file that
+is not the expected object shape yields no records (parse never raises).
 """
 
 from __future__ import annotations
 
+import datetime
 import json
 from pathlib import Path
 from typing import Any
 
-from .base import BaseAdapter
+from .base import CORRECTION_RE, BaseAdapter
+
+
+def _ts(value: Any) -> float | None:
+    if isinstance(value, (int, float)):
+        return float(value)
+    if isinstance(value, str):
+        try:
+            return datetime.datetime.fromisoformat(value.replace("Z", "+00:00")).timestamp()
+        except (ValueError, AttributeError):
+            return None
+    return None
 
 
 class GeminiAdapter(BaseAdapter):
     RUNTIME_ID = "gemini"
 
-    # CONFIRMED: path from official gemini-cli session-management docs.
     GEMINI_TMP_DIR = Path.home() / ".gemini" / "tmp"
 
     def discover(self) -> list[Path]:
-        """Find all *.jsonl chat files under ~/.gemini/tmp/<hash>/chats/."""
+        """Find all session *.json chat files under ~/.gemini/tmp/<hash>/chats/."""
         if not self.GEMINI_TMP_DIR.exists():
             return []
         files: list[Path] = []
         try:
-            # Pattern: ~/.gemini/tmp/<project_hash>/chats/*.jsonl
-            for jsonl in self.GEMINI_TMP_DIR.rglob("chats/*.jsonl"):
+            for jf in self.GEMINI_TMP_DIR.rglob("chats/*.json"):
                 try:
-                    if jsonl.is_file():
-                        files.append(jsonl)
+                    if jf.is_file():
+                        files.append(jf)
                 except OSError:
                     continue
         except OSError:
@@ -52,70 +60,83 @@ class GeminiAdapter(BaseAdapter):
         return sorted(files, key=lambda f: f.stat().st_mtime, reverse=True)
 
     def parse(self, path: Path) -> list[dict[str, Any]]:
-        """Parse one Gemini CLI chat JSONL file.
-
-        STUBBED schema: expected MessageRecord with {role, content: [{text}], ...}.
-        Falls back silently if the schema differs.
-        """
-        records: list[dict[str, Any]] = []
+        """Parse one Gemini chat JSON file into user-prompt records with
+        correction context. Tool errors are not represented in this format."""
         try:
-            lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
-        except OSError:
+            obj = json.loads(path.read_text(encoding="utf-8", errors="replace"))
+        except (OSError, json.JSONDecodeError):
+            return []
+        if not isinstance(obj, dict):
             return []
 
-        for line in lines:
-            line = line.strip()
-            if not line:
-                continue
-            try:
-                obj = json.loads(line)
-            except json.JSONDecodeError:
-                continue
+        messages = obj.get("messages")
+        if not isinstance(messages, list):
+            return []
 
-            # STUBBED: inferred from gemini-cli session-management docs.
-            role = obj.get("role", "")
-            if role not in ("user", "USER"):
+        # Normalise into an ordered timeline of {kind, text, model, ts}.
+        timeline: list[dict[str, Any]] = []
+        for m in messages:
+            if not isinstance(m, dict):
                 continue
-
-            content = obj.get("content", [])
-            if isinstance(content, list):
-                parts = []
-                for block in content:
-                    if isinstance(block, dict):
-                        text = block.get("text", "")
-                        if text:
-                            parts.append(text)
-                text = "\n".join(parts)
-            elif isinstance(content, str):
-                text = content
-            else:
-                text = ""
-
-            if not text.strip():
+            mtype = m.get("type")
+            content = m.get("content", "")
+            if not isinstance(content, str) or not content.strip():
                 continue
-
-            # Gemini MessageRecord may carry token counts and model name.
-            model = obj.get("model") or obj.get("modelVersion")
-            ts = obj.get("timestamp") or obj.get("createTime")
-            if isinstance(ts, str):
-                try:
-                    import datetime
-                    dt = datetime.datetime.fromisoformat(ts.replace("Z", "+00:00"))
-                    ts = dt.timestamp()
-                except (ValueError, AttributeError):
-                    ts = None
-            elif not isinstance(ts, (int, float)):
-                ts = None
-
-            record: dict[str, Any] = {
+            ts = _ts(m.get("timestamp"))
+            if mtype == "user":
+                timeline.append({"kind": "user", "text": content, "ts": ts})
+            elif mtype == "gemini":
+                model = m.get("model")
+                timeline.append({
+                    "kind": "assistant",
+                    "text": content,
+                    "ts": ts,
+                    "model": str(model) if model else "",
+                })
+
+        user_indices = [i for i, t in enumerate(timeline) if t["kind"] == "user"]
+        records: list[dict[str, Any]] = []
+        for n, idx in enumerate(user_indices):
+            turn = timeline[idx]
+            next_user = user_indices[n + 1] if n + 1 < len(user_indices) else len(timeline)
+
+            # Model that answered this prompt: the first assistant reply after it.
+            model = ""
+            context_after_assistant = ""
+            for j in range(idx + 1, next_user):
+                if timeline[j]["kind"] == "assistant":
+                    model = timeline[j].get("model", "") or model
+                    if not context_after_assistant:
+                        context_after_assistant = timeline[j]["text"]
+            # context_before: last assistant text strictly before this prompt.
+            context_before = ""
+            for j in range(idx - 1, -1, -1):
+                if timeline[j]["kind"] == "assistant":
+                    context_before = timeline[j]["text"]
+                    break
+
+            followed_by_correction = False
+            correction_text = ""
+            if next_user < len(timeline):
+                nxt = timeline[next_user]["text"]
+                if CORRECTION_RE.search(nxt):
+                    followed_by_correction = True
+                    correction_text = nxt
+
+            records.append({
                 "runtime": self.RUNTIME_ID,
                 "session_file": str(path),
-                "prompt_text": text,
-                "timestamp": ts,
-            }
-            if model:
-                record["model"] = str(model)
-
-            records.append(record)
+                "prompt_text": turn["text"],
+                "timestamp": turn.get("ts"),
+                "model": model,
+                "context_before": context_before,
+                # This format does not record tool errors — be honest, not invent.
+                "followed_by_error": False,
+                "error_was_recovered": False,
+                "followed_by_correction": followed_by_correction,
+                "correction_text": correction_text,
+                "error_tool": "",
+                "error_text": "",
+            })
 
         return records

package/skills/roast-me/tools/extract_prompts.py

@@ -33,6 +33,7 @@ from typing import Any
 # ---------------------------------------------------------------------------
 _TOOLS_DIR = Path(__file__).parent
 sys.path.insert(0, str(_TOOLS_DIR))
+from adapters.base import CORRECTION_RE
 from adapters.registry import get_adapters, list_runtime_ids
 
 # ---------------------------------------------------------------------------
@@ -42,15 +43,11 @@ from adapters.registry import get_adapters, list_runtime_ids
 MAX_PROMPTS = 300
 PROMPT_TEXT_LIMIT = 1500
 CORRECTION_TEXT_LIMIT = 500
+ERROR_TEXT_LIMIT = 500
 CONTEXT_BEFORE_LIMIT = 500
 
-CORRECTION_PATTERNS = re.compile(
-    r"\b(no[,.]?\s|wrong|instead|actually|don'?t|shouldn'?t|stop|not that|"
-    r"I said|I meant|I asked|that'?s not|please don'?t|why did you|"
-    r"you should have|that was wrong|incorrect|try again|redo|"
-    r"that broke|you broke|revert|undo)\b",
-    re.IGNORECASE,
-)
+# Single source of truth for the correction heuristic — shared with every adapter.
+CORRECTION_PATTERNS = CORRECTION_RE
 
 # Model tier classification (provider-neutral labels).
 # Maps substrings found in model IDs to tier names.
@@ -144,13 +141,15 @@ def normalise_record(raw: dict[str, Any], position: int, total: int) -> dict[str
         "has_xml_tags": has_xml_tags,
         "has_file_paths": has_file_paths,
         "has_code_blocks": has_code_blocks,
-        # These will be populated by post-processing when session context is available.
-        "followed_by_error": False,
-        "error_was_recovered": False,
-        "followed_by_correction": False,
-        "correction_text": "",
-        "error_tool": "",
-        "error_text": "",
+        # Error/correction context: honored from the adapter when it does its own
+        # session-aware detection (codex, gemini); defaults to False for adapters
+        # that only surface raw prompts. Claude uses process_claude_sessions instead.
+        "followed_by_error": bool(raw.get("followed_by_error", False)),
+        "error_was_recovered": bool(raw.get("error_was_recovered", False)),
+        "followed_by_correction": bool(raw.get("followed_by_correction", False)),
+        "correction_text": truncate(raw.get("correction_text", ""), CORRECTION_TEXT_LIMIT),
+        "error_tool": raw.get("error_tool", "") or "",
+        "error_text": truncate(raw.get("error_text", ""), ERROR_TEXT_LIMIT),
         "context_before": truncate(raw.get("context_before", ""), CONTEXT_BEFORE_LIMIT),
         # Compute fields (best-effort from adapter)
         "model": model_id,

package/skills/shortform-packaging/SKILL.md

@@ -63,8 +63,13 @@ stranger's voice that contradicts what already won.
 4. **No script or no settled angle? Route OUT** (see Handoffs). Never invent here.
 
 Persist the package under `02-DOCS/wiki/shortform/` and raw test results under
-`02-DOCS/raw/shortform/`. Pattern depth lives in
-[references/package-templates.md](references/package-templates.md).
+`02-DOCS/raw/shortform/`. The `shortform/` wiki tree is an **OKF v0.1 bundle** shared
+with the `tiktok-api` and `shortform-strategy` siblings: each persisted package `.md`
+leads with YAML frontmatter carrying a non-empty `type: shortform-package` (plus the
+recommended `title`/`tags`/`timestamp`), and any cross-references use standard markdown
+links, never `[[wikilinks]]`. The raw feedback log under `02-DOCS/raw/shortform/` is
+`raw/`, not `wiki/` — no frontmatter required. The full frontmatter + pattern depth
+lives in [references/package-templates.md](references/package-templates.md).
 
 ## The two-second decision
 

package/skills/shortform-packaging/references/package-templates.md

@@ -6,10 +6,21 @@ filled `02-DOCS` feedback-log schema.
 
 ## The package file format
 
-Emit one plain-text/markdown block per short. `scripts/verify.sh` lints exactly these
-labels (English or ES/CA, one per line, content following):
+Emit one markdown file per short under `02-DOCS/wiki/shortform/`. The `shortform/`
+wiki tree is an **OKF v0.1 bundle** shared with the `tiktok-api` and
+`shortform-strategy` siblings, so the file leads with YAML frontmatter (a non-empty
+`type` is the only OKF hard requirement; `title`/`tags`/`timestamp` are the recommended
+surface). The labeled body below is unchanged — `scripts/verify.sh` lints exactly these
+labels (English or ES/CA, one per line, content following) and ignores the frontmatter:
 
 ```text
+---
+type: shortform-package
+title: faceless productivity TikTok — package
+tags: [shortform, packaging, tiktok]
+timestamp: 2026-06-02T12:00:00Z
+platform: tiktok
+---
 Hook:
   - I deleted my to-do app. Here's why.
   - The app that runs my whole week (it's free)

package/skills/shortform-strategy/SKILL.md

@@ -113,9 +113,21 @@ Every decision must end up in the ledger so next month's call is grounded.
 
 ### Decision record format
 
-Append every call to `02-DOCS/wiki/shortform/decisions.md` as a dated block:
+`02-DOCS/wiki/shortform/decisions.md` is an OKF append-log: write the frontmatter
+header once (a non-empty `type` is the only OKF hard requirement; `title`/`tags`/`timestamp`
+are the recommended surface), then **prepend each new dated block newest-first** so the
+latest call is on top. Use ISO 8601 dates; never edit a past block. Bump the header
+`timestamp` on each append. Header + one block:
 
 ```markdown
+---
+type: shortform-decision-log
+title: Shortform strategy decisions
+tags: [shortform, strategy, decisions]
+timestamp: 2026-06-02T10:00:00Z
+---
+# Shortform strategy decisions
+
 ## 2026-06-02 — Drop daily posting to 4 Reels/week
 **Decision:** Cut from ~7 thin posts/week to 4 strong Reels/week, fixed Tue/Fri.
 **Rationale:** Reach fell as volume rose; consistency > velocity past the ceiling.
@@ -140,10 +152,22 @@ Append every call to `02-DOCS/wiki/shortform/decisions.md` as a dated block:
 
 ## Persist it
 
-Write the account's brain back so it compounds (mirrors the harness Karpathy-wiki convention):
+Write the account's brain back so it compounds (mirrors the harness Karpathy-wiki convention). The `shortform/` wiki tree is an **OKF v0.1 bundle** shared with the `tiktok-api` and `shortform-packaging` siblings: every `.md` written here carries YAML frontmatter with a non-empty `type`, cross-references are standard markdown links (never `[[wikilinks]]`), and `decisions.md` follows the OKF newest-first append-log rule.
+
+- `02-DOCS/wiki/shortform/strategy.md` — positioning, cadence/mix, KPI, length bands, current series. Lead with frontmatter; the body keeps the H1 + sections the linter checks:
+
+  ```markdown
+  ---
+  type: shortform-strategy
+  title: Shortform account strategy
+  tags: [shortform, strategy, positioning, cadence]
+  timestamp: 2026-06-02T10:00:00Z
+  ---
+  # Shortform account strategy
+  ...
+  ```
 
-- `02-DOCS/wiki/shortform/strategy.md` — positioning, cadence/mix, KPI, length bands, current series.
-- `02-DOCS/wiki/shortform/decisions.md` — the dated decision log (format above).
-- `02-DOCS/raw/shortform/metrics.csv` — the per-post ledger (schema in `references/learning-loop-template.md`).
+- `02-DOCS/wiki/shortform/decisions.md` — the dated decision log, OKF append-log (`type: shortform-decision-log`, newest block on top; format above).
+- `02-DOCS/raw/shortform/metrics.csv` — the per-post ledger (schema in `references/learning-loop-template.md`). This is `raw/`, not `wiki/` — a CSV, no frontmatter.
 
-Verify a produced strategy doc with `scripts/verify.sh 02-DOCS/wiki/shortform/strategy.md` — a read-only structural lint (positioning, cadence, completion KPI, ride-or-skip rule, ≥1 dated decision, sends/saves logged).
+Verify a produced strategy doc with `scripts/verify.sh 02-DOCS/wiki/shortform/strategy.md` — a read-only structural lint (positioning, cadence, completion KPI, ride-or-skip rule, ≥1 dated decision, sends/saves logged). The lint reads body content, so the added frontmatter does not affect it.

package/skills/shortform-strategy/references/learning-loop-template.md

@@ -38,9 +38,17 @@ Run once a month, reading `02-DOCS/raw/shortform/metrics.csv`:
 
 ## Decision-record template
 
-Append to `02-DOCS/wiki/shortform/decisions.md`. Every block is dated, rests on a named metric, and carries a revisit date so it is an experiment, not folklore.
+`02-DOCS/wiki/shortform/decisions.md` is an OKF v0.1 append-log: the frontmatter header (a non-empty `type` is the only OKF hard requirement; `title`/`tags`/`timestamp` are recommended) is written once, then each new block is **prepended newest-first** under the H1. Every block is dated (ISO 8601), rests on a named metric, and carries a revisit date so it is an experiment, not folklore. Past blocks are immutable; bump the header `timestamp` on each append.
 
 ```markdown
+---
+type: shortform-decision-log
+title: Shortform strategy decisions
+tags: [shortform, strategy, decisions]
+timestamp: YYYY-MM-DDTHH:MM:SSZ
+---
+# Shortform strategy decisions
+
 ## YYYY-MM-DD — <short decision title>
 **Decision:** <what changes, concretely — cadence/positioning/series/trend rule>
 **Rationale:** <the one-line why>

package/skills/specify/references/spec-template.md

@@ -6,10 +6,21 @@ endpoint, library, file path, or algorithm. If you can't phrase it without
 naming the tech, it's a *point to clarify*, not a requirement.
 
 ```markdown
+---
+type: spec
+title: Spec — <Feature name>
+description: WHAT and WHY for <feature> — problem, goals, behaviour, acceptance criteria.
+tags: [sdd, spec]
+timestamp: YYYY-MM-DDTHH:MM:SSZ
+topic: sdd
+slug: <slug>
+status: draft
+---
+
 # Spec — <Feature name>
 
 > Slug: `<slug>` · Status: draft · Created: <YYYY-MM-DD>
-> Inherits: 02-DOCS/wiki/sdd/constitution.md
+> Inherits: [constitution](../constitution.md)
 
 ## Problem & why
 <The pain, who feels it, and the cost of leaving it unsolved. One short

package/skills/tiktok-api/SKILL.md

@@ -251,10 +251,14 @@ A pull that prints to stdout and vanishes is wasted. **Every pull appends a date
 
 Filenames carry the `tiktok-` prefix because the same `shortform/` wiki may also hold Instagram and YouTube pulls — namespacing keeps platforms from colliding.
 
-Per-pull entry template:
+Per-pull entry template. The frontmatter is **OKF v0.1 conformant** — a non-empty `type` is the only hard requirement; `title`/`tags`/`timestamp` are the recommended OKF surface; the domain `date`/`range`/`account`/`platform`/`source` keys the siblings parse are preserved additively (OKF tolerates extra keys). `date` is the reporting day; `timestamp` is the ISO 8601 write moment:
 
 ```markdown
 ---
+type: shortform-metrics
+title: TikTok account snapshot — 2026-06-02
+tags: [tiktok, metrics, snapshot]
+timestamp: 2026-06-02T09:00:00Z
 date: 2026-06-02
 range: 2026-05-26..2026-06-01
 account: <open_id>
@@ -274,7 +278,7 @@ For You 71% · Personal profile 14% · Search 7%
 completion +3.1pts after the tighter cold-open; FYP share up 5pts.
 ```
 
-Rule: **append, never overwrite.** The feedback log *is* the value — overwriting yesterday's snapshot destroys the trend the siblings need, and erases the 24–48h settling you only see across pulls. Exact file tree, naming, and how siblings read the log: `references/wiki-schema.md`.
+Rule: **append, never overwrite.** The feedback log *is* the value — overwriting yesterday's snapshot destroys the trend the siblings need, and erases the 24–48h settling you only see across pulls. The per-video log (`videos/tiktok-<id>.md`) is an OKF append-log: write its frontmatter header once, prepend each new dated block newest-first, never edit a past block. `index.md` is the OKF reserved file — no frontmatter, standard markdown links only. Exact file tree, frontmatter, naming, and how siblings read the log: `references/wiki-schema.md`.
 
 ## 6. Rate & failure math
 

package/skills/tiktok-api/references/wiki-schema.md

@@ -24,8 +24,19 @@ from colliding and lets a sibling grep `tiktok-*` for just this account.
 
 ## Account snapshot entry (one file per pull)
 
+Frontmatter is **OKF v0.1 conformant**: a non-empty `type` is the only hard
+requirement; `title`/`tags`/`timestamp` are the recommended OKF surface. The
+domain keys (`date`, `range`, `account`, `platform`, `source`, `provisional`) are
+preserved verbatim — siblings parse them, and OKF tolerates arbitrary extra keys.
+`date` is the snapshot's reporting day; `timestamp` is the ISO 8601 moment the file
+was written. Keep both.
+
 ```markdown
 ---
+type: shortform-metrics
+title: TikTok account snapshot — 2026-06-02
+tags: [tiktok, metrics, snapshot]
+timestamp: 2026-06-02T09:00:00Z
 date: 2026-06-02
 range: 2026-05-26..2026-06-01
 account: <open_id>
@@ -50,11 +61,23 @@ completion +3.1pts after the tighter cold-open; FYP share up 5pts.
 
 Newest entry on top, so a glance shows the latest. Each pull **prepends** a block —
 this is where the 24–48h settling becomes visible (the same video's
-`full_video_watched_rate` will drift between pulls).
+`full_video_watched_rate` will drift between pulls). This is an OKF append-log:
+the frontmatter header is written once and stays immutable; new dated blocks are
+prepended **above** older ones (newest-first), past blocks are never edited, and
+dates are ISO 8601.
 
 ```markdown
+---
+type: shortform-record
+title: tiktok-7399 — "cold open hook test"
+tags: [tiktok, video-log]
+timestamp: 2026-06-02T09:00:00Z
+video_id: "7399..."
+platform: tiktok
+posted: 2026-05-28
+duration: 21s
+---
 # tiktok-7399... — "cold open hook test"
-posted: 2026-05-28 | duration: 21s
 
 ## 2026-06-02 (final-ish)
 views 52,140 | completion 28.4% | avg_watched 6.1s | FYP 71%
@@ -63,13 +86,18 @@ views 52,140 | completion 28.4% | avg_watched 6.1s | FYP 71%
 views 18,900 | completion 24.1% | avg_watched 5.3s | FYP 64%
 ```
 
+On each prepend, bump the header `timestamp` to the new pull's ISO moment; never
+edit a past dated block.
+
 ## index.md
 
-A thin pointer, not a data dump:
+A thin pointer, not a data dump. As an OKF **reserved** file it carries **no
+frontmatter**, and its cross-references are standard markdown links (never
+wikilinks), so an OKF consumer can follow them straight to the snapshot files:
 
 ```markdown
 # shortform wiki — index
-- tiktok: latest snapshot → tiktok-account-2026-06-02.md
+- tiktok: latest snapshot → [tiktok-account-2026-06-02.md](./tiktok-account-2026-06-02.md)
 - open questions:
   - is the cold-open change holding completion above 27%? (watch next 2 pulls)
 ```
@@ -83,3 +111,9 @@ A thin pointer, not a data dump:
 - **Namespace by platform.** `tiktok-` prefix on every file so IG/YouTube pulls coexist.
 - **Numbers only, no interpretation.** "What changed" is a factual delta line, not a
   recommendation — what to *do* about it belongs to `shortform-strategy`.
+- **OKF v0.1 conformant.** Every snapshot and per-video file carries YAML frontmatter
+  with a non-empty `type` (`shortform-metrics` / `shortform-record`) plus the OKF
+  `title`/`tags`/`timestamp` surface; domain keys like `date` are kept additively. The
+  reserved `index.md` carries no frontmatter. All cross-references are standard markdown
+  links — never `[[wikilinks]]` — so the `shortform/` tree is a portable OKF bundle the
+  siblings (and any OKF consumer) read without translation.

package/skills/verify/SKILL.md

@@ -113,9 +113,19 @@ A criterion you "reviewed by reading the code" is not verified. Reading is `revi
 
 ### 4 — RECORD
 
-Write a dated verification record to `02-DOCS/wiki/sdd/verifications/<slug>-YYYY-MM-DD.md` so the project's living knowledge carries the proof, then index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer) under the `sdd/` topic. Keep it short and factual:
+Write a dated verification record to `02-DOCS/wiki/sdd/verifications/<slug>-YYYY-MM-DD.md` so the project's living knowledge carries the proof, then index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer) under the `sdd/` topic. It is an OKF v0.1 wiki article: open it with YAML frontmatter carrying a non-empty `type:`. Keep it short and factual:
 
 ```markdown
+---
+type: verification
+title: Verification — <slug> — YYYY-MM-DD
+description: Evidence-backed verdict for <slug> — stack gate, task done-checks, acceptance criteria.
+tags: [sdd, verification]
+timestamp: YYYY-MM-DDTHH:MM:SSZ
+topic: sdd
+slug: <slug>
+---
+
 # Verification — <slug> — YYYY-MM-DD
 
 ## Stack gate

package/skills/youtube-api/SKILL.md

@@ -215,10 +215,15 @@ A pull that prints to stdout and vanishes is wasted. **Every pull appends a date
   videos/<VIDEO_ID>.md      # per-video running log, newest entry on top
 ```
 
-Per-pull entry template:
+Per-pull entry template (OKF v0.1: non-empty `type` + the domain keys siblings parse):
 
 ```markdown
 ---
+type: youtube-metrics
+title: Channel snapshot 2026-05-31
+description: Channel KPIs, traffic and retention for 2026-05-01..2026-05-31.
+tags: [youtube, channel-snapshot]
+timestamp: 2026-05-31T00:00:00Z
 date: 2026-05-31
 range: 2026-05-01..2026-05-31
 channel: MINE
@@ -237,7 +242,7 @@ Sharp drop 0.00→0.06 (intro), recovers, second dip ~0.55.
 avg_view_pct +2.1pts; SUGGESTED share up 6pts after the Ep.13 packaging change.
 ```
 
-Rule: **append, never overwrite.** The feedback log *is* the value — overwriting yesterday's snapshot destroys the trend the siblings need. Exact file tree, naming, and how siblings read the log: `references/wiki-schema.md`.
+Rule: **append, never overwrite.** The feedback log *is* the value — overwriting yesterday's snapshot destroys the trend the siblings need. `02-DOCS/wiki/` is an OKF v0.1 bundle: keep the domain keys (`date`, `range`, `channel`, `source`) the siblings parse, add `type`/`timestamp` alongside them, use standard markdown links (never `[[wikilinks]]`), and leave the reserved `index.md` frontmatter-free. Exact file tree, naming, per-video log shape, and how siblings read the log: `references/wiki-schema.md`.
 
 ## 7. Quota & failure math
 

package/skills/youtube-api/references/wiki-schema.md

@@ -2,6 +2,8 @@
 
 The point of this skill is not to print stats once; it is to grow a **feedback log** the strategy/packaging siblings can read. The log lives under `02-DOCS/wiki/youtube/` and every pull **appends** to it.
 
+`02-DOCS/wiki/` is an **OKF v0.1** bundle, so every non-reserved `.md` file written here carries YAML frontmatter with a non-empty `type`. This skill writes `type: youtube-metrics` on its snapshots/logs and keeps the domain keys (`date`, `range`, `channel`, `source`) that the strategy/packaging siblings parse literally — `type` and `timestamp` are added *alongside* them, never replacing them. OKF allows arbitrary extra keys, so the shared keys stay stable. Links between wiki files are standard markdown links (`[text](./file.md)`), never Obsidian wikilinks.
+
 ## File tree
 
 ```text
@@ -24,6 +26,11 @@ Naming:
 
 ```markdown
 ---
+type: youtube-metrics
+title: Channel snapshot 2026-05-31
+description: Channel KPIs and traffic for 2026-05-01..2026-05-31.
+tags: [youtube, channel-snapshot]
+timestamp: 2026-05-31T00:00:00Z
 date: 2026-05-31
 range: 2026-05-01..2026-05-31
 channel: MINE
@@ -40,9 +47,20 @@ BROWSE 44% · SUGGESTED 31% · YT_SEARCH 12%
 avg_view_pct +2.1pts; SUGGESTED share +6pts after the Ep.13 packaging change.
 ```
 
-## Per-video entry template (prepended to `videos/<id>.md`)
+## Per-video log file — `videos/<VIDEO_ID>.md`
+
+The file carries frontmatter once (at the top); each new dated block is **prepended directly under the frontmatter** (newest entry first — this is an append-log, past entries are immutable). On the first write, create the frontmatter; on every later pull, refresh `timestamp` and insert the new block above the previous newest one. Keep the domain key `channel` so siblings can parse it.
 
 ```markdown
+---
+type: youtube-metrics
+title: Video log — dQw4w9WgXcQ
+description: Per-pull KPI/traffic/retention log for video dQw4w9WgXcQ, newest entry first.
+tags: [youtube, video-log]
+timestamp: 2026-05-31T00:00:00Z
+channel: MINE
+source: youtube-analytics-api-v2
+---
 ## 2026-05-31  (range 2026-05-01..2026-05-31)
 views: 8,902 | avg_view_pct: 41.0% | ctr(studio): 6.2%
 traffic: SUGGESTED 52% · BROWSE 23% · YT_SEARCH 9%
@@ -52,10 +70,12 @@ note: held suggested-traffic share week over week.
 
 ## index.md
 
+OKF **reserved file**: a directory listing, so it carries **no frontmatter**. Point at the latest snapshot and tracked videos with standard markdown links (never wikilinks).
+
 ```markdown
 # YouTube channel feedback log
-latest snapshot: channel-2026-05-31.md
-videos tracked: dQw4w9WgXcQ, abc123XYZ
+latest snapshot: [channel-2026-05-31.md](./channel-2026-05-31.md)
+videos tracked: [dQw4w9WgXcQ](./videos/dQw4w9WgXcQ.md), [abc123XYZ](./videos/abc123XYZ.md)
 
 ## Open questions for strategy/packaging
 - Intro drop-off at 0.06 recurs across last 3 uploads — packaging or pacing?
@@ -67,4 +87,5 @@ videos tracked: dQw4w9WgXcQ, abc123XYZ
 1. **Append, never overwrite.** A snapshot is a point in time; deleting it erases the trend. The history is the deliverable.
 2. **One source of truth for derived numbers.** Store what the API returned. Mark Studio-sourced values explicitly (`ctr(studio)`) so a reader knows it was not API-derived.
 3. **No interpretation in the log beyond a one-line "what changed."** Deeper reading ("we should change the hook") is the strategy/packaging sibling's job — this skill records, it does not prescribe.
-4. **Siblings read this tree.** Keep frontmatter keys stable (`date`, `range`, `channel`, `source`) so a sibling can parse the latest snapshot without guessing.
+4. **Siblings read this tree.** Keep the domain frontmatter keys stable (`date`, `range`, `channel`, `source`) so a sibling can parse the latest snapshot without guessing. The OKF keys (`type`, `title`, `description`, `tags`, `timestamp`) are added alongside them, never instead of them — all four youtube skills share this same key set and the same markdown-link style.
+5. **OKF-conformant wiki content.** Every non-reserved `.md` here has a non-empty `type` (`youtube-metrics`). `index.md` is the lone reserved file (no frontmatter, a directory listing). Per-video logs are newest-first append-logs with ISO 8601 dates; past dated blocks are never edited. Cross-references use standard markdown links (`[text](./file.md)`), never `[[wikilinks]]`.