@damiangilgonzalez/harness 1.3.7

package/skills/content-engine/references/brief-and-pipeline.md

@@ -0,0 +1,104 @@
+# Reference — Brief, pipeline stages, and calendar slot schema
+
+Offloaded detail for `content-engine`. The body states the rules; this is the full
+template, the stage gates, and the CSV column docs you fill in.
+
+## The canonical brief
+
+Every slot carries one brief in the same shape. A slot cannot leave the `idea` stage
+without it. Store briefs under `docs/wiki/content/briefs/<slug>.md`.
+
+These briefs live in the `docs/wiki/` OKF v0.1 bundle, so each brief `.md` carries YAML
+frontmatter with a non-empty `type: content-brief` (the OKF-recommended `title`/`description`/
+`tags`/`timestamp` are added where meaningful). The domain brief fields below are kept as-is —
+OKF allows any extra key. Cross-references in the body use **standard markdown links**, never
+wikilinks (e.g. `[brand voice](../brand-voice.md)`). See
+`../../harness/references/wiki-protocol.md` "## Conventions".
+
+| Field | Required | What goes here |
+|---|---|---|
+| `objective` | yes | the one outcome (e.g. "drive activation-checklist signups") |
+| `persona` | yes | which of the 2–4 personas |
+| `pillar` / `cluster` | yes | position in the architecture |
+| `angle` | yes | the specific take, not the topic ("the 3 setup steps most teams skip") |
+| `format` | yes | flagship-guide / linkedin-post / video-short / newsletter-issue / x-thread / … |
+| `owner` | yes | the human accountable |
+| `target_keyword` | flagship/article | handed off from `seo-geo`, never invented here |
+| `success_metric` | yes | how you'll know it worked (e.g. "100 checklist downloads in 30d") |
+| `atomization_intent` | flagship | derivative count + target channels |
+| `voice_ref` | yes | link to the `brand-voice` artifact the writer must follow |
+
+### Filled example
+
+```markdown
+---
+# OKF v0.1 standard surface — `type` is the only REQUIRED field (non-empty).
+type: content-brief
+title: "Onboarding activation guide — brief"
+description: "Brief of record for the flagship activation-checklist guide."
+tags: [content-brief, onboarding, flagship]
+timestamp: 2026-07-01T00:00:00Z
+# Domain brief fields (OKF allows any extra key; the pipeline + verify read these).
+slug: onboarding-activation-guide
+objective: drive activation-checklist signups from new-trial users
+persona: hands-on-ops-lead
+pillar: Onboarding
+cluster: activation-checklist
+angle: the 3 setup steps most teams skip in week one
+format: flagship-guide
+owner: ana
+target_keyword: "saas user activation checklist"
+success_metric: 100 checklist downloads in 30 days
+atomization_intent: 10 derivatives — 3 LinkedIn, 1 X thread, 2 shorts, 1 newsletter, 3 carousels
+voice_ref: ../brand-voice.md
+---
+```
+
+## Pipeline stages — entry/exit gates and WIP
+
+`idea → brief → draft → edit → atomize → publish-ready`
+
+| Stage | Entry gate | Exit gate | Typical WIP |
+|---|---|---|---|
+| `idea` | slot exists in calendar, pillar+cluster assigned | brief complete, owner set | unbounded (backlog) |
+| `brief` | brief written | target keyword present, voice_ref linked | small |
+| `draft` | brief complete | a draft exists, hits format+angle | cap per team-size table |
+| `edit` | draft exists | edited against brief + voice guide | cap per team-size table |
+| `atomize` | flagship passed edit (non-flagships skip) | atomization plan filled (≥ count) | 1–2 |
+| `publish-ready` | derivatives planned + routed | every asset has owner + destination | — |
+
+**WIP rule:** finish before you pull. Caps come from the cadence-by-team-size table in
+`../SKILL.md`. Exceeding the cap is how a calendar becomes a graveyard of half-done slots.
+
+**Station ownership:** `content-engine` owns the slot and its stage. Drafting/editing
+the words is routed out — long-form to `article-writing`, newsletter to `newsletter`,
+video to `video-shorts`, landing copy to `marketing`. The act of publishing is
+`social-publisher`. Automating the flow is `automation-flows`.
+
+## Calendar slot schema (CSV)
+
+One row per slot. This is the artifact `scripts/verify.sh` lints.
+
+| Column | Meaning | Notes |
+|---|---|---|
+| `date` | publish/target date | `YYYY-MM-DD` |
+| `pillar` | one of the 4–6 pillars | required |
+| `cluster` | sub-topic under the pillar | required |
+| `format` | the asset format | `flagship-*` rows trigger the brief+atomization checks |
+| `owner` | accountable human | empty allowed only on `reactive-open` slots |
+| `stage` | pipeline state | `idea\|brief\|draft\|edit\|atomize\|publish-ready` |
+| `brief_link` | path to the brief | required non-empty for flagship rows |
+| `atomization` | plan ref or `planned` | required non-empty for flagship rows |
+| `mix` | allocation bucket | `evergreen\|timely\|experimental\|reactive-open` |
+
+### Filled example
+
+```csv
+date,pillar,cluster,format,owner,stage,brief_link,atomization,mix
+2026-07-07,Onboarding,activation-checklist,flagship-guide,ana,brief,docs/wiki/content/briefs/onboarding-activation-guide.md,planned,evergreen
+2026-07-09,Onboarding,activation-checklist,linkedin-post,ana,idea,,,evergreen
+2026-07-11,Onboarding,activation-checklist,x-thread,leo,idea,,,evergreen
+2026-07-15,Trends,q3-benchmarks,reactive-open,,idea,,,reactive-open
+2026-07-21,Proof,customer-results,case-study,leo,brief,docs/wiki/content/briefs/acme-results.md,planned,evergreen
+2026-07-28,Seasonal,back-to-work,linkedin-post,ana,idea,,,timely
+```

package/skills/content-engine/scripts/verify.sh

@@ -0,0 +1,146 @@
+#!/usr/bin/env bash
+#
+# verify.sh — structural lint for a `content-engine` editorial calendar CSV.
+#
+# WHAT IT DOES (read-only; never edits a file)
+#   Static, network-free checks on one calendar CSV emitted by the skill.
+#     1. A calendar artifact exists at the given path and has a header row.
+#     2. Required columns present:
+#        date,pillar,cluster,format,owner,stage,brief_link,atomization,mix
+#     3. Every row's `stage` is an allowed pipeline state
+#        (idea|brief|draft|edit|atomize|publish-ready).
+#     4. Every flagship-format row (format starts with "flagship") has a non-empty
+#        `brief_link` AND a non-empty `atomization` — the two hard rules (no flagship
+#        slot without a brief or an atomization plan).
+#     5. Mix sanity (warn only): warns if >80% of slots are evergreen, or if 0 slots
+#        are left open/reactive (catches the over-planned / no-slack anti-pattern).
+#
+#   Hard failures (missing artifact, missing column, bad stage, flagship missing
+#   brief/atomization) exit 1. Mix issues are warnings, not failures. A missing or
+#   empty target is reported and exits 0 (no false failure on a clean/empty target).
+#   Pure bash + awk, no dependencies. It is a lint, not a strategy oracle.
+#
+# HOW TO RUN
+#   ./verify.sh path/to/calendar.csv     # lint one calendar
+#   ./verify.sh                          # no target -> nothing to check, exit 0
+#
+# EXIT CODES
+#   0  clean, or nothing to check
+#   1  a hard structural failure
+#   2  bad usage
+#
+# Runs on stock macOS bash 3.2.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+ok_count=0; warn_count=0; fail_count=0
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; ok_count=$((ok_count + 1)); }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+usage() { sed -n '2,33p' "$0" | sed 's/^# \{0,1\}//'; }
+
+summary_exit() {
+  printf '\nok=%d warn=%d fail=%d\n' "$ok_count" "$warn_count" "$fail_count"
+  [ "$fail_count" -gt 0 ] && exit 1
+  exit 0
+}
+
+# --- arg parse --------------------------------------------------------------
+TARGET=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help) usage; exit 0 ;;
+    -*) printf 'unknown flag: %s\n' "$1" >&2; usage >&2; exit 2 ;;
+    *) TARGET="$1"; shift ;;
+  esac
+done
+
+# No target, or empty/missing file -> nothing to check, clean exit (no false fail).
+if [ -z "$TARGET" ]; then
+  ok "no calendar path given — nothing to lint"
+  summary_exit
+fi
+if [ ! -f "$TARGET" ]; then
+  warn "file not found: $TARGET — nothing to lint"
+  summary_exit
+fi
+if [ ! -s "$TARGET" ]; then
+  warn "file is empty: $TARGET — nothing to lint"
+  summary_exit
+fi
+
+# --- header / required columns ---------------------------------------------
+REQUIRED="date pillar cluster format owner stage brief_link atomization mix"
+
+# Map column name -> 1-based index from the header.
+get_idx() {
+  awk -v want="$1" -F',' 'NR==1{for(i=1;i<=NF;i++){g=$i; gsub(/^[ \t]+|[ \t]+$/,"",g); if(g==want){print i; exit}}}' "$TARGET"
+}
+
+missing_cols=""
+for col in $REQUIRED; do
+  idx="$(get_idx "$col")"
+  if [ -z "$idx" ]; then
+    missing_cols="$missing_cols $col"
+  fi
+done
+
+if [ -n "$missing_cols" ]; then
+  fail "missing required column(s):$missing_cols"
+  summary_exit
+fi
+ok "all required columns present"
+
+STAGE_IDX="$(get_idx stage)"
+FORMAT_IDX="$(get_idx format)"
+BRIEF_IDX="$(get_idx brief_link)"
+ATOM_IDX="$(get_idx atomization)"
+MIX_IDX="$(get_idx mix)"
+
+# --- per-row checks (awk emits FAIL:/WARN:/STAT: lines we count below) ------
+RESULT="$(awk -F',' \
+  -v si="$STAGE_IDX" -v fi="$FORMAT_IDX" -v bi="$BRIEF_IDX" -v ai="$ATOM_IDX" -v mi="$MIX_IDX" '
+  function trim(s){ gsub(/^[ \t\r]+|[ \t\r]+$/,"",s); return s }
+  NR==1 { next }
+  trim($0)=="" { next }
+  {
+    total++
+    stage=trim($si); fmt=trim($fi); brief=trim($bi); atom=trim($ai); mix=trim($mi)
+    if (stage !~ /^(idea|brief|draft|edit|atomize|publish-ready)$/)
+      print "FAIL:row " NR ": stage \"" stage "\" not an allowed pipeline state"
+    if (fmt ~ /^flagship/) {
+      flagship++
+      if (brief == "") print "FAIL:row " NR ": flagship \"" fmt "\" has empty brief_link"
+      if (atom  == "") print "FAIL:row " NR ": flagship \"" fmt "\" has empty atomization plan"
+    }
+    if (mix == "evergreen") evergreen++
+    if (mix == "reactive-open" || fmt ~ /reactive/) reactive++
+  }
+  END {
+    if (total > 0) {
+      ev_pct = (evergreen*100)/total
+      if (ev_pct > 80) printf "WARN:%d%% of slots are evergreen (>80%%) — thin on timely/experimental mix\n", ev_pct
+      if (reactive == 0) print "WARN:0 slots left open/reactive — calendar has no slack to react"
+    }
+    printf "STAT:total=%d flagship=%d evergreen=%d reactive=%d\n", total, flagship+0, evergreen+0, reactive+0
+  }
+' "$TARGET")"
+
+while IFS= read -r line; do
+  case "$line" in
+    FAIL:*) fail "${line#FAIL:}" ;;
+    WARN:*) warn "${line#WARN:}" ;;
+    STAT:*) ok  "rows checked — ${line#STAT:}" ;;
+  esac
+done <<EOF
+$RESULT
+EOF
+
+summary_exit

package/skills/context-budget/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: context-budget
+description: "Use when a long-horizon task is filling the context window and you must decide what to keep, offload, drop, or hand off to a fresh window — when to compact, what the summary must preserve, and whether to isolate a read-heavy subtask in a subagent. NOT dollar spend or caps (that is cost-tracking), NOT finding context via embeddings (that is rag)."
+tags: ["context-window", "token-budget", "compaction", "context-rot", "long-running-agents", "handoff", "subagents"]
+recommends: ["cost-tracking", "rag", "building-agents", "harness"]
+origin: risco
+---
+
+# Context budget
+
+The context window is RAM, not a hard drive. Full ≠ free: a window stuffed to 95% does not just cost more money, it *reasons worse*. Model performance degrades as input tokens grow — even well inside the stated limit, every token added depletes a finite attention budget (Chroma "Context Rot" research, accessed 2026-06-02). Your job on a long task is to keep the *live* window lean and externalise everything else, so the work can run for hours across many fresh windows without losing the thread.
+
+> **The one rule:** if you can reconstruct a thing from a file or from git, it does not belong resident in the window. Keep load-bearing-right-now; evict the rest. The cost of forgetting is one re-read; the cost of hoarding is silent quality rot on every turn that follows.
+
+Neighbours, so you don't do their job here: pricing tokens, spend ledgers and hard `$` caps are `../cost-tracking/SKILL.md` — same words ("token budget"), different unit, dollars vs. attention. Finding the *right* context via embeddings/chunking is `../rag/SKILL.md`; RAG is *how you find* context, this is *how much* you let live and *when to evict*. Prompt text, few-shot and output format are `../prompt-engineering/SKILL.md`; the agent loop, tool schemas and provider adapters are `../building-agents/SKILL.md`; partition-then-gather fan-out of independent work is `../parallel/SKILL.md` (this skill *uses* subagents as a context-isolation tactic but does not own that discipline); the 01-TOOLS / docs control plane is `../harness/SKILL.md`.
+
+## Read the gauge first
+
+Before you do anything, estimate utilisation: live input tokens ÷ the model's window limit. You cannot manage a budget you are not watching.
+
+- **Compact early — around ~60% utilisation, not 80–95%.** Most people only act when quality already broke at 80–95%; by then the rot already happened. Treat 60% as the line where you start reducing, not panicking (practitioner guidance on Claude Code `/compact`, accessed 2026-06-02).
+- **Trust the symptoms as an *earlier* trigger than the number.** You can feel rot before the gauge confirms it:
+  - You re-read a file you already read this session.
+  - You restate the plan or a decision you already made.
+  - You contradict an earlier choice.
+  - Tool results from ten turns ago are still sitting verbatim in the window.
+
+Any one of those is a signal to act now, regardless of the percentage.
+
+## The four moves
+
+Every context-engineering action is one of four moves (context-engineering surveys, accessed 2026-06-02). Pick by *what is eating the window*.
+
+**1. Offload** — summarise a tool output or large read; store the full thing in a file or reference, keep only the distilled fact + a path. *Why: raw bytes you might need later don't have to be resident now.*
+
+```text
+Bad:  <pastes the entire 4,000-line config file into the window to "have it">
+Good: read it, keep the 30 relevant lines, leave a note:
+      "full config at src/app/config.ts:1-4012; the load-bearing keys are X, Y, Z (lines 88-120)"
+```
+
+**2. Reduce** — compact or summarise stale history so the window carries the *conclusions*, not the journey. *Why: the dead-end exploration that got you to a decision is not the decision.*
+
+```text
+Bad:  carry 2,000 lines of trial-and-error debugging transcript forward unchanged.
+Good: compact to "tried A (failed: race condition), B (failed: types); C works — see commit a1b2c3d."
+```
+
+**3. Retrieve** — fetch a fact at runtime instead of pre-loading it. *Why: most of what you might need, you won't; pull it when you actually need it.* This is RAG's job — see `../rag/SKILL.md`.
+
+```text
+Bad:  load all 40 design-doc sections up front in case one is relevant.
+Good: keep an index; fetch section 7 the moment the task touches auth.
+```
+
+**4. Isolate** — hand a read-heavy or independent subtask to a subagent with its own fresh window; take back only the answer. *Why: a big read in a child window never pollutes the parent's.* Subagents are the single most effective anti-rot pattern (Anthropic context-engineering guidance, accessed 2026-06-02).
+
+```text
+Bad:  read 12 files into the main window to answer "which module owns retries?"
+Good: spawn a subagent to scan them; it returns "retries live in lib/http/retry.ts:44" — that one line lands in the parent.
+```
+
+## Decision table: the window is filling — what do I do?
+
+| What is eating the window | Move | Concrete action |
+|---|---|---|
+| Bloated tool output / a giant pasted file or log | **Offload** | Distil to the load-bearing lines, write the full thing to a file, keep a `path:line` note. |
+| Stale early history, dead-end exploration | **Reduce** | `/compact` now (you're at ~60%, not 95%) with preserve instructions; keep decisions, drop the journey. |
+| A fact you need is simply not in the window | **Retrieve** | Fetch it on demand via `../rag/SKILL.md`; don't pre-load "just in case". |
+| A read-heavy or independent subtask | **Isolate** | Spawn a subagent (fresh window) via `../parallel/SKILL.md`; take back only the answer, never the transcript. |
+| The whole task won't fit any single window | **Hand off** | Write a progress file (below) so a fresh window resumes in one read. |
+
+## Compaction, concretely
+
+**Manual (`/compact`).** Do it early and tell it what to keep. A bare `/compact` will happily drop the file paths and decisions you needed.
+
+```text
+/compact keep: the migration plan, every file path touched, the three decisions
+(use Drizzle, keep the legacy table read-only, cut over Friday), and the open TODOs.
+drop: the exploratory diffs and the debugging transcript.
+```
+
+**Server-side (beta).** The API can compact for you: beta header `compact-2026-01-12`, edit type `compact_20260112`, default trigger at `input_tokens` = **150,000** (min 50,000), `pause_after_compaction` defaults `false`. The API drops all blocks before the compaction block and continues from the `<summary>` — and you must append the *whole* response (including the compaction block) to subsequent requests (Claude API "Compaction" docs, accessed 2026-06-02). The exact contract and the append rule are version-specific and rot fastest, so they live in `references/handoff-and-compaction.md` — read it before you wire this up.
+
+**A good summary preserves** decisions, file paths, open TODOs, and gotchas/constraints. **A good summary drops** raw logs, dead-end exploration, and redundant restatements. If the summary can't resume the task, it failed.
+
+## Surviving a fresh window (handoff discipline)
+
+When the task is bigger than one window, the win is making a *fresh* window resume the work in a single read. The long-running harness pattern (Anthropic, "Effective harnesses for long-running agents", published 2025-11-26, accessed 2026-06-02) is: an initializer session sets up the work, then each coding session works **one unit at a time** and leaves a structured update — a progress log (e.g. `claude-progress.txt`) plus git history plus a structured feature list — so the next window reconstructs state without you re-explaining it.
+
+Write the handoff *before* you run out of room, not after quality already cratered. The template (Goal / Done / In-progress / Next / Gotchas / Key paths) and a good-vs-bad summary checklist are in `references/handoff-and-compaction.md`.
+
+## Budget allocation heuristic
+
+A starting split for a production agent's window — a **heuristic, not a law** (context-engineering production guidance, accessed 2026-06-02). Tune to your task; the point is to leave headroom and trigger reduction well before 100%.
+
+| Slice | Rough share |
+|---|---|
+| System / instructions | ~10–15% |
+| Tool definitions & results | ~15–20% |
+| Knowledge / RAG injections | ~30–40% |
+| Working headroom (kept clear) | the rest — defend it |
+
+## Anti-patterns
+
+| Anti-pattern | Why it rots | Do instead |
+|---|---|---|
+| Read the whole repo into context "to be safe" | Thousands of irrelevant tokens degrade every later turn | Read the files the task touches; leave path notes for the rest |
+| Compact only at 95% when things break | The rot already happened; you're summarising damaged reasoning | Compact at ~60%, before quality drops |
+| Let tool results pile up verbatim | Stale outputs from 10 turns ago still taxing attention | Offload to a file, keep the distilled fact + path |
+| Re-explain the plan every turn | Burns the same tokens repeatedly and invites drift | State it once; keep it in the progress file, reference it |
+| Paste a subagent's full transcript back into the parent | Defeats the entire point of isolation — the child's bloat lands in the parent | Take back only the answer/artifact, never the transcript |
+| Treat the window as infinite because the model "has 1M" | Context rot scales with tokens regardless of the limit | Budget against attention, not the advertised ceiling |
+| Carry dead-end exploration forward | The journey isn't the decision; it's pure noise | Reduce to the conclusion + the commit that proves it |

package/skills/context-budget/evals/README.md

@@ -0,0 +1,11 @@
+# Evals: context-budget
+
+`cases.yaml` is read by the repo's eval runner. The `should_trigger` and `should_not_trigger`
+sets check routing: each `should_trigger` prompt should select this skill, and each
+`should_not_trigger` near-miss should route to the named sibling (`route_to`) instead — those
+boundaries against `cost-tracking`, `rag`, `parallel`, and `prompt-engineering` are the ones
+that actually get confused. The single `capability` case is a rubric-graded scenario: an agent
+facing an ~85%-full window must pick the right moves (offload + compact early), write a resumable
+handoff, and isolate the read-heavy step to a subagent; grade its response against `must_include`
+with an LLM judge or a human. This is a process skill, so there is no `verify.sh` to run — the
+rigor lives in the capability rubric, not a script.

package/skills/context-budget/evals/cases.yaml

@@ -0,0 +1,40 @@
+skill: context-budget
+
+should_trigger:
+  - prompt: "We're 80% through context, compact before it breaks."
+    why: Explicit utilisation trigger — the core ask is when/how to reduce a filling window.
+  - prompt: "This refactor will span days — make it survive across fresh sessions."
+    why: Harness/handoff trigger; the task is bigger than one window and needs resumable state.
+  - prompt: "The agent keeps re-reading the same files and forgetting decisions it made earlier."
+    why: Non-obvious symptom phrasing — context rot described with zero token vocabulary.
+  - prompt: "Se está llenando el contexto, ¿qué guardo y qué tiro?"
+    why: Spanish, what-to-keep-vs-drop framing — the keep/offload/drop decision is exactly this skill.
+  - prompt: "Should I spawn a subagent for this huge log read or just inline it?"
+    why: Isolation decision — whether to keep a read-heavy subtask out of the live window.
+
+should_not_trigger:
+  - prompt: "Cap our Claude API spend at $200/month and alert me at 80%."
+    route_to: cost-tracking
+    why: This is money — pricing and budget caps in dollars, not working-memory quality.
+  - prompt: "Pull the right design-doc sections into context with embeddings."
+    route_to: rag
+    why: Retrieval is how you find context to inject, not how much you let live or when to evict.
+  - prompt: "Split these 4 independent modules across agents and reconcile the results."
+    route_to: none
+    why: Fan-out/partition-then-gather discipline has no dedicated destination in this catalog, not single-window budgeting.
+  - prompt: "Rewrite this prompt so the model returns cleaner JSON."
+    route_to: prompt-engineering
+    why: Prompt text and output format, not the context budget.
+
+capability:
+  - scenario: >
+      Mid-task in a long refactor. The window is ~85% full, someone pasted a 3,000-line build
+      log into the conversation, and the plan has visibly drifted (you've restated it twice and
+      contradicted an earlier decision). The next step is to read 8 more files to find where
+      retries are configured. Decide what to do.
+    must_include:
+      - Names the right moves explicitly — offload the build log to a file/summary and compact early.
+      - Writes a resumable handoff note covering goal, decisions, current state, next step, and key paths.
+      - Isolates the next read-heavy step (the 8-file scan) to a subagent instead of inlining it into the live window.
+      - Does NOT advise "the window is big, just keep going."
+      - References the ~60% compact-early discipline rather than waiting for 95%.

package/skills/context-budget/references/handoff-and-compaction.md

@@ -0,0 +1,96 @@
+# Handoff and compaction (the version-specific detail)
+
+This file holds the material that rots fastest — the exact server-side compaction API
+contract and the concrete templates. Re-verify the numbers against the live docs before you
+quote them; they are dated, not eternal.
+
+## Server-side compaction API contract
+
+Source: Claude API "Compaction" docs, accessed 2026-06-02.
+
+- **Beta header:** `compact-2026-01-12`
+- **Edit type:** `compact_20260112`
+- **Default trigger:** `trigger.type = "input_tokens"`, `trigger.value = 150000` (minimum allowed: `50000`)
+- **`pause_after_compaction`:** defaults `false` (the model continues straight from the summary)
+
+### Behaviour you must account for
+
+1. When the trigger fires, the API emits a **compaction block** and **drops all blocks before it**, continuing from the `<summary>` it produced.
+2. You must **append the whole response — including the compaction block — to subsequent requests.** If you strip the compaction block, the next request loses the summarised state. This is the easiest thing to get wrong.
+3. The summary is generated by a default prompt that distils the prior turns into a `<summary>`; you can steer what it preserves the same way you steer a manual `/compact` (keep decisions, paths, TODOs).
+
+### Minimal request shape (illustrative)
+
+```json
+{
+  "betas": ["compact-2026-01-12"],
+  "context_management": {
+    "edits": [
+      {
+        "type": "compact_20260112",
+        "trigger": { "type": "input_tokens", "value": 150000 },
+        "pause_after_compaction": false
+      }
+    ]
+  }
+}
+```
+
+Treat the field names as version-stamped: the `compact_20260112` suffix *is* the version. When
+the beta graduates or revs, this block changes — do not assume it.
+
+## Progress-file template
+
+Drop this in the workspace (e.g. `claude-progress.txt` or `PROGRESS.md`) and rewrite it before
+you run low on window. A fresh session should resume from this in a single read.
+
+```markdown
+# Progress: <task name>
+
+## Goal
+<one or two sentences — what "done" looks like>
+
+## Done
+- <unit completed> — proof: <commit hash / file path / test name>
+- ...
+
+## In progress
+- <the one unit currently open> — current state: <where it stands>
+
+## Next
+1. <the very next concrete step>
+2. <then this>
+
+## Gotchas / constraints
+- <non-obvious thing that will bite a fresh window>
+- <decision that must not be relitigated, and why>
+
+## Key paths
+- <path:line> — <what lives there>
+- ...
+```
+
+Rules:
+
+- **One unit at a time.** Close a unit, record its proof (a commit hash beats a paragraph), then open the next.
+- **Proof over prose.** "Done: auth migration — commit a1b2c3d, tests in auth/migrate.test.ts" beats three paragraphs describing it.
+- **Write it before you need it.** A handoff written at 60% is calm and complete; one scrambled at 97% is missing the gotchas.
+
+## Good vs. bad summary checklist
+
+A summary (manual `/compact`, server-side, or a handoff note) is judged by one question:
+**can a fresh window resume the task from it alone?**
+
+**Keep (load-bearing):**
+
+- Decisions made, and the one-line reason for each.
+- Every file path touched, with `path:line` where it matters.
+- Open TODOs and the next concrete step.
+- Constraints and gotchas a fresh window can't re-derive.
+
+**Drop (noise):**
+
+- Raw tool logs and full command output.
+- Dead-end exploration ("tried X, didn't work" collapses to one line, not the transcript).
+- Redundant restatements of things already captured.
+- Pleasantries and meta-commentary about the process.

package/skills/continuous-learning/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: continuous-learning
+description: "Use when a mistake, correction, or surprise taught the workspace something that must stick — a retro or postmortem, the same agent error corrected twice, a resolved bug's root cause, scattered notes-to-self — and route that lesson to the durable surface that fires next time. NOT a forward choice with alternatives (that is `decision-records`)."
+tags: [learning, retro, postmortem, feedback-loop, knowledge, meta]
+recommends: [write-adr, author-skill, harness, knowledge-ops]
+origin: risco
+---
+
+# Continuous learning — the feedback loop of the harness
+
+This is the engine that makes the system get better every time it is wrong. When something broke, got corrected, surprised you, or simply taught the workspace something, your job is to **catch that lesson and route it back into the durable apparatus so the same mistake cannot recur**.
+
+One premise is load-bearing: **a lesson that lives only in chat is gone at the next compaction.** Verbal reflection only changes future behaviour when it is persisted to memory the agent actually reads next time (this is the Reflexion mechanism — self-reflection written to durable memory, not held in the conversation). In this harness, "memory" is a concrete set of surfaces: a `SKILL.md` body, `docs/wiki/harness/decisions.md`, `docs/wiki/harness/user-profile.md`, a root `CLAUDE.md` rule, or a `verify.sh` check. **Chat is not memory.** A lesson is "captured" only when it has landed in one of those.
+
+Read `docs/wiki/harness/user-profile.md` for the accompaniment dial before you narrate. It governs narration only — the capture loop runs identically at every level.
+
+## Boundaries
+
+| Situation | Owner | Why |
+|---|---|---|
+| "We chose Postgres over Mongo, here's the why + the rejected options" | `../decision-records/SKILL.md` | forward choice with alternatives; a choice is not a lesson from a mistake |
+| "The migration failed because Postgres rejects NULL on the PK — never assume that again" | `continuous-learning` | backward lesson from a mistake |
+| "Find the bug causing the 500" | `../debug/SKILL.md` | in-the-moment diagnosis; you run after it resolves |
+| "Now that debug found it, make sure we never ship that pattern again" | `continuous-learning` | post-resolution capture |
+| "Write the SKILL.md and evals for pr-describe" | `../author-skill/SKILL.md` | skill craft — body, description, evals |
+| "This lesson means the deploy skill needs a new guardrail" | `continuous-learning` decides the home → `../author-skill/SKILL.md` makes the edit | you route, it writes |
+| "Consolidate these docs / sweep the inbox" | `../harness/SKILL.md` | generic docs filing; your trigger is "we learned something the hard way" |
+| "What do I know about X" | `../knowledge-ops/SKILL.md` | reference knowledge, as opposed to mistake-derived experiential knowledge |
+| "Run this sweep every week" | `loop` / `schedule` harness CLI | you may recommend a cadence; you are not a scheduler |
+
+## The capture loop
+
+Five steps. Run them in order; do not stop before step 5.
+
+1. **Harvest** — pull the lesson out of chat *now*, while it is still in context. *Why:* the next compaction deletes it for free.
+2. **Root-cause, blameless** — name the *system* gap: a missing rule, a wrong assumption, an under-specified skill, an absent guardrail. Never "the agent is careless" or "the user keeps forgetting". *Why:* blame indicts a person and the loop stops running; blameless framing focuses on contributing causes and keeps the retro honest (Google SRE / Atlassian blameless postmortem practice).
+3. **Route to a durable home** — pick the *cheapest surface that will fire next time* (table below). Prefer the **preventative** write that kills the whole class of failure over a one-off note that just records it. *Why:* good postmortems split mitigative-vs-preventative action items, and the preventative one is what stops recurrence.
+4. **Write it** — land the entry in that surface in the lesson format below. If the home is a skill body, a description, or an eval, **delegate the edit to `author-skill`** — you decide the home, it does the craft.
+5. **Verify it fires** — prove the lesson is live (see "Verify it fires next time"). *Why:* learning loops do not fail at the retro, they fail *after* it — at action-tracking and trend analysis (incident.io / Rootly 2025 SRE best-practice consensus). If you cannot point to where it fires, you have not captured it.
+
+## Routing decision table
+
+The single most important artifact in this skill. Pick the row, write to that exact home, hand off to that writer.
+
+| Lesson type | Durable home (exact path) | Who writes it |
+|---|---|---|
+| About the user (prefers X, hates Y, works this way) | `docs/wiki/harness/user-profile.md` | this skill |
+| A rule we keep breaking | root `CLAUDE.md` rule, or the relevant `SKILL.md` body | `author-skill` for the skill body; this skill for `CLAUDE.md` |
+| A pattern to ban | a `verify.sh` banlist/check on the owning skill | `author-skill` |
+| A missed-trigger insight (skill fired wrong / didn't fire) | a `should_not_trigger` (or `should_trigger`) eval case | `author-skill` |
+| A surprising fact / how a provider actually behaves | wiki article via the harness ingest protocol | `harness` |
+| A forward choice that surfaced mid-retro | punt to `decisions.md` | `decision-records` |
+| A one-off, low-stakes note | `docs/wiki/harness/decisions.md` append, or a topic note | this skill |
+
+Full catalogue with hand-off recipes and a worked end-to-end example is in `references/lesson-routing.md`. The body table is enough for routine cases; read the reference when the home or the hand-off is unobvious.
+
+## The "2+ recurrences ⇒ structural fix" rule
+
+First sighting of a lesson: a note is fine. **Second sighting of the same class: stop noting and build a guardrail** — a `CLAUDE.md` rule, a `verify.sh` check, or a `should_not_trigger` eval. A third note proves the second note did nothing.
+
+*Why:* this is exactly where learning loops die. Teams nail the postmortem and then fumble trend analysis — the recurring class never gets a structural fix, so it keeps recurring. The recurrence is the signal that prose has failed; answer it with a check, not another apology.
+
+## Lesson entry format
+
+Copy-pasteable and **situation-tagged**, so it retrieves on the trigger that matters — not as a vague blob nobody can act on (experiential memory works when entries are actionable and situation-tagged, not when they are similarity soup):
+
+```md
+## <date> — <short lesson title>
+- **Situation:** <when this fires / the trigger phrasing>
+- **We believed:** <the wrong assumption>
+- **Actually:** <what is true>
+- **Durable home:** <path + surface that now holds it>
+- **Fires next time via:** <rule / eval / verify.sh / index entry in `docs/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer)>
+```
+
+The last two lines are not optional. An entry with no durable home and no "fires next time" is a chat message with a date on it.
+
+## Verify it fires next time
+
+This is the rigor of this process skill, and it stands in for a `verify.sh` (this skill emits no checkable artifact of its own — see below). **Acceptance: you can point to a concrete place where the lesson now changes behaviour:**
+
+- a rule the agent reads on its next pass (`CLAUDE.md` or a skill body), or
+- an eval case (`should_not_trigger` / `should_trigger`) that would have caught the miss, or
+- a `verify.sh` check on the owning skill that fails on the banned pattern, or
+- a `docs/wiki/index.md` entry (the Knowledge map; root `CLAUDE.md` keeps only a short pointer) pointing at the new wiki article.
+
+If you cannot name one of those, the lesson is not captured — keep going. Prefer a surface a human can review (a rule, an eval, a profile line) over an opaque store: a single agent reflecting alone can talk itself into a local optimum, so the durable write should be legible enough for a human to sanity-check.
+
+**This skill has no `scripts/verify.sh`.** Its output is a *routing decision plus a durable write into another surface*. The check that the lesson fires lives in *that target surface* — a `verify.sh` on the deploy skill, a `should_not_trigger` eval, a `CLAUDE.md` rule — not here. Its rigor is the capability eval, same as `decision-records`, `author-skill`, and `harness`.
+
+## Periodic retro sweep
+
+To harvest scattered corrections and notes-to-self on a cadence, do not reimplement a scheduler — recommend the `loop` / `schedule` harness CLI to run the sweep weekly. For pulling raw notes through `docs/inbox/` into the wiki, route the consolidation itself through `../harness/SKILL.md`; you only own the lessons that came from a mistake, not the general filing.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+|---|---|---|
+| Lesson captured only in chat | lost at the next compaction | write it to a durable surface from the table |
+| "The agent/user is bad at X" | blame indicts a person; the loop stops running | name the *system* gap (missing rule, wrong assumption) |
+| Note added but it never fires | prose nobody reads next time is not a capture | attach a rule / eval / check, then verify it fires |
+| Re-noting the same class a 3rd time | the 2nd note already proved prose failed | build a guardrail on the 2nd sighting |
+| Hand-editing the SKILL.md yourself | you do not own skill craft | hand the edit to `author-skill` |
+| Capturing a forward choice here | that is a decision, not a lesson | route to `decision-records` |
+| A vague vector-blob note | won't retrieve, can't be acted on | situation-tag it in the entry format |
+| Starting to diagnose the bug | that is `debug`'s job | come here *after* it resolves, with the root cause |

package/skills/continuous-learning/evals/README.md

@@ -0,0 +1,16 @@
+# Evals — continuous-learning
+
+These cases are eyeballed against the SKILL.md description and body, not run by a
+harness. Two axes. **Triggering:** read each `should_trigger` prompt and confirm
+the description's "Use when …" / "Triggers:" clauses would route it here, and
+read each `should_not_trigger` prompt and confirm it routes to its `route_to`
+sibling instead (the `NOT … (that is decision-records)` boundary plus the
+when-NOT list should make every one of those a clean miss). **Capability:** walk
+the scenario through the body and check every `must_include` rubric item is
+satisfied — the blameless root cause, the 2+-recurrences structural fix, the
+routing to an exact durable path, the hand-off to `author-skill` for craft, the
+situation-tagged entry, and the "prove it fires next time" surface.
+
+There is no `scripts/verify.sh`: this is a process skill whose only output is a
+durable write into *another* surface, which is checked there (a rule, an eval, a
+verify.sh on the owning skill). Its rigor is the capability eval above.