@adia-ai/adia-ui-factory 0.2.2 → 0.2.4

package/skills/adia-ui-kit/references/response-authoring.md

@@ -0,0 +1,398 @@
+# Reference: Response Authoring — Defensible Upstream Reviews (vendored from color-app)
+
+**Vendored:** 2026-05-20, from `/Users/kimba/Projects/adia/color-app/.agents/team/skills/response-authoring.md`.
+**Original upstream:** `~/.pi/agent/memory/skills/review-and-respond-to-feedback-ticket.md`.
+**Why vendored:** Companion to `feedback-authoring.md`. When upstream
+sends a RESPONSE to a FEEDBACK ticket (filed in `.agents/team/tickets/inbox/`),
+or when self-reviewing a draft FEEDBACK before submission, this is the canonical
+procedure. Verdict taxonomy (✅ confirmed / ⚠️ partial / ⏳ deferred / ❌ dismissed /
+🔍 needs-clarification / 🔀 out-of-scope) is normative.
+
+**Used by:** `adia-ui-kit` skill, when:
+- Triaging an incoming RESPONSE-NN in `.agents/team/tickets/inbox/`
+- Self-reviewing a draft FEEDBACK before submission (sniff-test #2: write the
+  RESPONSE you'd expect upstream to write, see if it rejects any claims)
+
+**Companion:** `feedback-authoring.md` (the author half of the dyad).
+
+---
+
+## When to Use
+
+- Responding to incoming `FEEDBACK-NN` from upstream (AdiaUI, partner teams)
+- Writing `RESPONSE-NN` files in `.agents/team/tickets/inbox/`
+- Self-review before filing your own FEEDBACK — write the RESPONSE you'd *expect* upstream to write, and see if it rejects any of your claims
+- Triaging whether upstream fixes actually work in our installed runtime
+
+**Trigger phrases:** "respond to FEEDBACK", "review this ticket", "write the RESPONSE doc", "audit these claims", "self-review this before sending"
+
+---
+
+## Core Principles
+
+1. **Verdict-per-claim, not per-ticket.** A ticket with 7 items may land at 3 confirmed / 2 dismissed / 1 deferred / 1 clarification. Single overall verdicts are wrong.
+
+2. **Quote original claims verbatim.** No paraphrasing. The author must recognize their own words.
+
+3. **Verify against runtime, not docs.** Open `node_modules/@adia-ai/web-components/` and read `.js`/`.ts` source. Cite `file.js:LINE`.
+
+4. **Dismissals carry same burden as confirmations.** "We don't think this is a problem" without a runtime cite is opinion, not verdict.
+
+5. **"Fixed in vX.Y" must cite commit + runtime line.** CHANGELOGs lie. Verify the actual code.
+
+6. **Distinguish "won't fix" from "can't reproduce" from "disagree."** Different next steps.
+
+---
+
+## Verdict Taxonomy
+
+| Marker | Verdict | Meaning |
+|---|---|---|
+| ✅ | **Confirmed — already shipped** | Fixed in vX.Y; cite runtime line |
+| ✅ | **Confirmed — accepting** | True; will fix; cite planned milestone |
+| ⚠️ | **Confirmed — partial** | Real problem but framed wrong, or fix differs from proposal |
+| ⏳ | **Deferred** | True but not scheduled; give cut horizon |
+| ❌ | **Dismissed — not reproducible** | Repro failed; show attempt, ask for missing input |
+| ❌ | **Dismissed — by design** | Intentional behavior; cite ADR / design doc |
+| ❌ | **Dismissed — incorrect claim** | Author's premise wrong; cite runtime line proving it |
+| 🔍 | **Needs clarification** | Cannot triage; list exact questions |
+| 🔀 | **Out of scope — redirected** | Wrong package/team; name correct destination |
+
+Every verdict MUST have a marker. Verdicts without markers are invalid.
+
+---
+
+## Procedure
+
+### Step 0 — Locate and stage the ticket
+
+```bash
+# Find the FEEDBACK being responded to
+ls .agents/team/tickets/outbox/ | grep "FEEDBACK-NN"
+
+# Read it end-to-end BEFORE opening code
+cat .agents/team/tickets/outbox/FEEDBACK-NN--<author>--<date>.md
+```
+
+Note front-matter: `version`, `references`, `priority`. Verdict must address the version the author measured against.
+
+**Optional: Write placeholder RESPONSE early** so parallel agents know the ticket is being worked:
+
+```yaml
+---
+id: "NN"
+type: response
+recipient: color-app
+date: "YYYY-MM-DD"
+author: "Adia UI maintainers"
+project: "chat-ui"
+references:
+  - "FEEDBACK-NN--color-app--YYYY-MM-DD"
+version: "@adia-ai/web-components@0.7.13"
+status: in-progress
+---
+
+# RESPONSE-NN — receipt acknowledged, full triage in flight
+
+Will follow up with claim-by-claim verdict within 24h.
+```
+
+### Step 1 — Build claim inventory
+
+```bash
+# Extract every distinct claim
+grep -n '^## [0-9]+\.' .agents/team/tickets/outbox/FEEDBACK-NN-*.md
+grep -n 'Ask:|Request:|Proposed' .agents/team/tickets/outbox/FEEDBACK-NN-*.md
+```
+
+Also check the "Related observations / not full items" block — they still need verdicts.
+
+### Step 2 — Verify each claim against installed source
+
+For each claim:
+
+1. **Reproduce symptom** (if repro provided):
+   ```bash
+   # Run exact commands from ticket
+   # If succeeds → confirms symptom
+   # If fails → check version skew first before dismissing
+   ```
+
+2. **Read cited runtime path**:
+   ```bash
+   sed -n 'L1,L2p' node_modules/@adia-ai/web-components/components/<name>/class.js
+   # Cite exact line range in response — no paraphrasing
+   ```
+
+3. **Cross-check shipped artefacts**:
+   - `.d.ts` matches runtime?
+   - YAML sidecar `events:` / `props:` matches `dispatchEvent` / property definitions?
+   - CHANGELOG entry for "fixed in vX.Y" claim?
+
+4. **For "already shipped" verdicts**, verify from clean tree:
+   ```bash
+   npm i @adia-ai/web-components@<claimed-fix-version>
+   # Re-run ticket's repro
+   # If still broken → fix didn't fully land
+   ```
+
+5. **Record every verification step** — author must be able to re-run.
+
+### Step 3 — Distinguish symptom from root cause
+
+Common failure: verdict-on-symptom without root cause. If author reported a symptom with two causes and only one was fixed → `⚠️ Confirmed — partial`, not `✅ Already shipped`. Spell out which sub-symptom remains.
+
+### Step 4 — Draft response, claim-by-claim
+
+Match ticket's numbering. For each item:
+
+```markdown
+### {marker} #{N} — {Author's heading verbatim} ({priority}) — **Audit verdict: {conclusion}**
+
+**Author claim (verbatim):**
+> {quote exact text from ticket}
+
+**Verification:**
+- {what you ran / read}
+- {file:line citations}
+- {repro outcome}
+
+**Verdict:** {Confirmed | Dismissed | Deferred | …}
+
+**Disposition:**
+{What's happening / when}
+
+**Next action for author (if any):**
+{Specific thing author needs to provide or change}
+```
+
+Six conventional parts:
+1. Header with marker + verdict summary
+2. Verbatim quote of consumer's framing
+3. Evidence with cited `file:line` ranges
+4. Verdict statement
+5. Disposition (what's happening)
+6. Optional: next action required from author
+
+Every ⚠️ confirmed bug needs all six. A clean ✅ already-shipped may need only 1, 2, 3, 5.
+
+### Step 5 — Address omissions and "Known omissions" section
+
+If author wrote a §"Items deliberately NOT included" block, **honor it explicitly**:
+
+```markdown
+## Confirming the consumer's exclusions
+
+- **<excluded item>** — ✅ Agreed. Verified at `<file:line>`.
+- **<excluded item>** — ⚠️ Flipped. Verification anchor incomplete — symbol exists at
+  `<file:line>` but with different shape than assumed. Reopened as #N+1 below.
+- **<excluded item>** — 🔀 Wrong scope. This is our problem, not consumer's.
+  Bringing back as new line item.
+```
+
+If author did NOT include omissions but you see adjacent bugs they missed, add a §"Reviewer-identified additions" section.
+
+### Step 6 — Aggregate meta-patterns
+
+After 3+ rounds with same consumer:
+
+```markdown
+## Meta-observation (round N closes the <pattern> pattern)
+
+Across rounds 01–NN:
+
+| Round | Claims | Real bugs | Real gaps | Already-shipped | Already-documented |
+|---|---|---|---|---|---|
+| 01 | 8 | 0 | 4 | 0 | 4 |
+| 02 | 10 | 0 | 3 | 4 | 3 |
+| … |
+| **Total** | **N** | **N (X%)** | **N (X%)** | **N (X%)** | **N (X%)** |
+
+**<Pattern statement>** — e.g. "More than half trace to functionality that exists
+but isn't discoverable."
+
+<Structural fix addressing pattern> — e.g. "Per-component reference generator in
+v<X.Y.Z> closes discoverability lag."
+```
+
+Tally tables compound: by round 4, predict next round's distribution. Structural fix is more valuable than any individual verdict.
+
+### Step 7 — Write release-planning section
+
+```markdown
+## What's in v0.5.18 vs v0.5.19
+
+### Shipped (already on main, lands at v0.5.18 tag)
+| # | Item | Where |
+|---|---|---|
+| 1 | <fix> | §<journal>, this response |
+
+### Already-shipped (closes on upgrade)
+| # | Item | Where |
+|---|---|---|
+| 4 | <thing> | v<earlier> §<journal> |
+
+### Deferred to v0.5.19
+| # | Item | Why deferred |
+|---|---|---|
+| 2 | <thing> | API design call / scope / cost |
+```
+
+Pair with TL;DR for upgrading:
+```markdown
+## TL;DR for upgrading
+```bash
+npm install @adia-ai/web-components@^0.5.18
+```
+After upgrade:
+1. <consumer-visible win 1>
+2. <consumer-visible win 2>
+```
+
+### Step 8 — Set front-matter and ownership
+
+```yaml
+---
+id: "NN"
+type: response
+recipient: color-app
+date: "YYYY-MM-DD"
+author: "Adia UI maintainers"
+project: "chat-ui"
+status: draft        # → acknowledged → resolved
+references:
+  - "FEEDBACK-NN--color-app--YYYY-MM-DD"
+version: "@adia-ai/web-components@0.7.13"
+verdicts:
+  confirmed: [1, 4]
+  partial: [3]
+  dismissed: [2]
+  deferred: [5, 6]
+  needs-clarification: [7]
+---
+```
+
+Close with §Pointers:
+```markdown
+## Pointers
+
+- **§331 journal:** `packages/web-components/CHANGELOG.md`
+- **§314 (prior FEEDBACK):** `.agents/team/tickets/outbox/FEEDBACK-34.md` §314
+- **Component reference:** `node_modules/@adia-ai/web-components/components/swatch/class.js`
+- **For round 40+ feedback** — drop `FEEDBACK-40--chat-ui--YYYY-MM-DD.md` in this directory.
+```
+
+### Step 9 — Self-audit before committing
+
+- [ ] Every claim has exactly one verdict marker
+- [ ] Every "already shipped" cites commit/version AND runtime line
+- [ ] Every "dismissed" cites runtime line OR ADR OR failed-repro log
+- [ ] Every "deferred" names cut horizon and gating concern
+- [ ] Author's verbatim claim text appears before each verdict
+- [ ] No paraphrase drift — `diff` quoted claims against original
+- [ ] `version:` field matches verified runtime
+- [ ] `references:` includes original FEEDBACK
+- [ ] Controversial dismissals have §"Anticipated disputes" subsection
+- [ ] 3+ rounds with same consumer → meta-pattern tally present
+- [ ] Registry (`REGISTRY.md`) updated
+- [ ] Reproducibility: every cited command runs on clean checkout
+
+### Step 10 — Commit and cross-link
+
+```bash
+git add .agents/team/tickets/inbox/RESPONSE-NN--{author}--{date}.md
+git add .agents/team/tickets/REGISTRY.md
+git commit -m "docs(tickets): RESPONSE-NN to {author} — {verdict summary}
+
+Verdict rollup:
+  ⚠️ Confirmed bugs (now fixed):  N
+  🐛 Confirmed bugs (deferred):   M
+  ✅ Already-shipped:              K
+  📚 Already-documented:           J
+  🟡 Partial accept:               I
+  ❌ Declined-with-reason:         H
+
+Excluded — peer-agent in-flight: <none>"
+```
+
+---
+
+## Self-Review Variant (Critical for This Project)
+
+**Same agent writes FEEDBACK then self-RESPONSE as steelman audit.**
+
+1. **Switch mental context.** RESPONSE front-matter `project:` is maintainer's (chat-ui), not consumer's (color-app). `author:` is maintainer role.
+2. **Read ticket cold.** Pretend you didn't write it. Look for weak asks.
+3. **Try to dismiss each claim first.** Apply verdict taxonomy strictly.
+4. **Cite recipient's runtime.** Open `node_modules/@adia-ai/web-components/` and quote actual code.
+5. **Output indistinguishable from real maintainer.** Same structure, same burden, same front-matter.
+
+**If self-RESPONSE downgrades any P0 to P2 or dismisses any claim → GO BACK AND REVISE FEEDBACK before submitting.** Don't ship a ticket your own steelman rejects.
+
+---
+
+## Pitfalls
+
+### "We don't see it" reflex
+"Can't reproduce" is not a verdict — it's a state. Show failed-repro log AND ask for missing input.
+
+### "Fixed in v0.5.2" trap
+Don't claim without verifying runtime. `CHANGELOG.md` and `.d.ts` are downstream of code.
+
+### Paraphrase drift
+If response says "author reported X" but author said "Y", you've lost the conversation.
+
+### Verdict mixing
+Don't bundle "fixed in 0.5.2" + "won't fix rest" into one ✅. Split into multiple numbered items.
+
+### Ignoring omissions
+If author defended exclusions and you silently disagree, you must call it out.
+
+### Symptom-only verdicts
+"Can't reproduce crash" may be true while "root cause still present" is also true. Address both.
+
+### Asymmetric rigor
+Confirmations get evidence; dismissals get hand-waving. This is the #1 reviewer failure mode.
+
+### Stale `version:` field
+If reviewed against v0.5.18 but ticket measured against v0.5.16, say so explicitly.
+
+### Forgetting registry update
+Every RESPONSE needs a row in `REGISTRY.md`.
+
+### Pre-emptive defensiveness
+Don't write anticipating a fight. State verdicts factually, cite evidence, let evidence carry argument. "I think" / "we believe" more than once per response = insufficient evidence.
+
+---
+
+## Verification
+
+Before merging response:
+1. **Independent re-verification:** Second engineer reads ticket + response, decides if they'd reach same verdict from cited evidence.
+2. **Author-perspective read-back:** Imagine hostile author. Which verdicts would they push back on hardest? Pre-empt in §"Anticipated disputes".
+3. **Registry consistency:** `REGISTRY.md` has new row, related FEEDBACK status updated.
+4. **Reproducibility audit:** Every cited command runs on clean checkout.
+5. **Front-matter completeness:** `id`, `type=response`, `references`, `version`, `status` all populated.
+6. **No paraphrase drift:** `diff` quoted claims against original ticket — byte-identical.
+
+---
+
+## Meta: Round Tallying
+
+Across 43 rounds (R7–R43) in this project:
+
+| Stat | Value |
+|---|---|
+| Total rounds | 43 |
+| Real bugs confirmed | 28 (65%) |
+| Real gaps confirmed | 5 (12%) |
+| Already-shipped | 7 (16%) |
+| Clarifications | 2 (5%) |
+| Dismissals | 1 (2%) |
+| Zero dismissals across entire run | — |
+
+This tally validates the "consumer dogfooding surfaces bugs faster than maintainer test matrices" pattern. The meta-observation is structural: maintainer test matrices miss lifecycle-timing axes that consumer adoption discovers.
+
+---
+
+*Companion: `.agents/team/skills/feedback-authoring.md` — the author half. Both skills enforce the same evidentiary contract from both sides.*

package/skills/adia-ui-kit/references/session-log-schema.md

@@ -0,0 +1,203 @@
+# Session Log Schema — adia-ui-kit v3.1.0+
+
+**Purpose.** Define a structured emission format for agent session events so consumers, operators, and future audits have a tractable audit trail. Per REFACTOR-SPEC P5(a).
+
+**Status.** v3.1.0 ships the schema + a validator (`scripts/validate-session-log.mjs`). Emission is **optional but recommended** in v3.1.0; the schema is documented so consumers can opt in. v3.2.0 may promote emission to required for the senior-skill harness once a stable cadence is observed.
+
+**File location.** JSONL (one event per line). Per-session file at `.agents/team/session-logs/YYYY-MM-DD/<session-id>.jsonl` (under each kit's own `team/` dir, or a substrate-wide path when running from a substrate).
+
+**Why JSONL not JSON?** Append-only — agents can flush an event after each tool-call without re-reading + re-writing the file. Tail-friendly. Per-line atomic — partial writes don't corrupt the whole log.
+
+---
+
+## Event Schema (v1)
+
+Every line in a session log is a JSON object with these fields:
+
+```json
+{
+  "schema_version": "1",
+  "session_id": "string",
+  "timestamp": "ISO 8601 (UTC)",
+  "skill": "string",
+  "skill_version": "string",
+  "event_type": "string",
+  "payload": {}
+}
+```
+
+### Required fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `schema_version` | string | Always `"1"` for this version. Increment on breaking changes. |
+| `session_id` | string | Unique per agent run. Format: `<ISO-date>-<short-uuid>` (e.g. `2026-05-22-a1b2c3d4`). |
+| `timestamp` | string | ISO 8601 UTC. Must include `Z` suffix. |
+| `skill` | string | Skill name (e.g. `adia-ui-kit`, `adia-ui-release`). |
+| `skill_version` | string | Skill version at emission time (e.g. `3.1.0`). |
+| `event_type` | enum | One of: `skill_loaded`, `mode_entered`, `decision_made`, `component_named`, `verify_target_run`, `correction_applied`, `teach_landing`, `session_closed`. |
+| `payload` | object | Event-specific fields (see below). |
+
+### Optional fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `parent_session_id` | string | If this session was spawned by another (delegate-task, cron, etc.). |
+| `mode` | string | Which mode (1-12) the skill is operating in. |
+| `gate_result` | object | If a verify-target ran, the gate name + result + duration. |
+
+---
+
+## Event Payloads (per event_type)
+
+### `skill_loaded`
+```json
+{
+  "event_type": "skill_loaded",
+  "payload": {
+    "trigger": "user_request | auto_load | cron",
+    "trigger_phrase": "string (optional)",
+    "loaded_references": ["references/foo.md", "..."]
+  }
+}
+```
+
+### `mode_entered`
+```json
+{
+  "event_type": "mode_entered",
+  "mode": "mode-3-screen-composition",
+  "payload": {
+    "mode_id": 3,
+    "mode_name": "screen-composition",
+    "verify_target": "node scripts/audit-shell-composition.mjs"
+  }
+}
+```
+
+### `decision_made`
+**This is the load-bearing event for P5(b) DecisionModel.** A `decision_made` event records (a) the named decision, (b) the signal that resolved it, (c) the action taken.
+```json
+{
+  "event_type": "decision_made",
+  "payload": {
+    "decision": "string — what was being decided",
+    "required_signal": "string — what input the decision depended on",
+    "signal_value": "string — the actual input observed",
+    "possible_actions": ["action-a", "action-b", "action-c"],
+    "chosen_action": "string",
+    "rationale": "string"
+  }
+}
+```
+
+### `component_named`
+```json
+{
+  "event_type": "component_named",
+  "payload": {
+    "tag": "button-ui",
+    "context": "kit-compose | recipe-application | direct-mention",
+    "traced_to_decision_id": "string (optional but recommended for P5(b))"
+  }
+}
+```
+
+### `verify_target_run`
+```json
+{
+  "event_type": "verify_target_run",
+  "payload": {
+    "verify_target": "node scripts/audit-shell-composition.mjs --root=...",
+    "exit_code": 0,
+    "duration_ms": 1234,
+    "findings_count": 0
+  }
+}
+```
+
+### `correction_applied`
+```json
+{
+  "event_type": "correction_applied",
+  "payload": {
+    "feedback_ticket": "FB-42",
+    "skill_section": "§CorrectionLoop",
+    "what_skill_said_before": "string",
+    "what_corrected_to": "string",
+    "bug_shape_class": "string"
+  }
+}
+```
+
+### `teach_landing`
+Emitted whenever `scripts/teach-route.mjs` is invoked to classify a knowledge payload (advisory; helps build the eval corpus over time).
+```json
+{
+  "event_type": "teach_landing",
+  "payload": {
+    "input_payload": "string",
+    "branch": "A | B | C | D | E | F | G",
+    "landing_target": "string (file path or 'journal-only')",
+    "confidence": "high | medium | low",
+    "human_overrode": false
+  }
+}
+```
+
+### `session_closed`
+```json
+{
+  "event_type": "session_closed",
+  "payload": {
+    "duration_ms": 12345678,
+    "total_events": 47,
+    "outcome": "completed | interrupted | error",
+    "summary": "string (≤ 500 chars)"
+  }
+}
+```
+
+---
+
+## Worked Example A — minimal session
+
+A 6-event session: skill loaded, mode entered, one decision, one component named, one verify run, session closed.
+
+```jsonl
+{"schema_version":"1","session_id":"2026-05-22-a1b2c3d4","timestamp":"2026-05-22T14:00:00.000Z","skill":"adia-ui-kit","skill_version":"3.1.0","event_type":"skill_loaded","payload":{"trigger":"user_request","trigger_phrase":"compose me a login page"}}
+{"schema_version":"1","session_id":"2026-05-22-a1b2c3d4","timestamp":"2026-05-22T14:00:01.234Z","skill":"adia-ui-kit","skill_version":"3.1.0","event_type":"mode_entered","mode":"mode-3-screen-composition","payload":{"mode_id":3,"mode_name":"screen-composition","verify_target":"node scripts/audit-shell-composition.mjs"}}
+{"schema_version":"1","session_id":"2026-05-22-a1b2c3d4","timestamp":"2026-05-22T14:00:02.500Z","skill":"adia-ui-kit","skill_version":"3.1.0","event_type":"decision_made","payload":{"decision":"which shell wraps the login page","required_signal":"page has no chrome/nav requirements","signal_value":"login is a marketing-style standalone page","possible_actions":["admin-shell","simple-shell","editor-shell","none (raw)"],"chosen_action":"simple-shell","rationale":"login pages are standalone without admin chrome"}}
+{"schema_version":"1","session_id":"2026-05-22-a1b2c3d4","timestamp":"2026-05-22T14:00:03.100Z","skill":"adia-ui-kit","skill_version":"3.1.0","event_type":"component_named","payload":{"tag":"simple-shell","context":"recipe-application","traced_to_decision_id":"decision-1"}}
+{"schema_version":"1","session_id":"2026-05-22-a1b2c3d4","timestamp":"2026-05-22T14:00:09.876Z","skill":"adia-ui-kit","skill_version":"3.1.0","event_type":"verify_target_run","payload":{"verify_target":"node scripts/audit-shell-composition.mjs","exit_code":0,"duration_ms":2345,"findings_count":0}}
+{"schema_version":"1","session_id":"2026-05-22-a1b2c3d4","timestamp":"2026-05-22T14:01:00.000Z","skill":"adia-ui-kit","skill_version":"3.1.0","event_type":"session_closed","payload":{"duration_ms":60000,"total_events":6,"outcome":"completed","summary":"Composed login page with simple-shell + simple-hero + form-field. All gates green."}}
+```
+
+## Worked Example B — session with feedback resolution
+
+```jsonl
+{"schema_version":"1","session_id":"2026-05-22-e5f6g7h8","timestamp":"2026-05-22T16:00:00.000Z","skill":"adia-ui-kit","skill_version":"3.1.0","event_type":"skill_loaded","payload":{"trigger":"user_request","trigger_phrase":"resolve FB-42"}}
+{"schema_version":"1","session_id":"2026-05-22-e5f6g7h8","timestamp":"2026-05-22T16:00:01.000Z","skill":"adia-ui-kit","skill_version":"3.1.0","event_type":"teach_landing","payload":{"input_payload":"FB-42 resolved upstream; skill said admin-statusbar defaults slot=footer but was wrong","branch":"F","landing_target":"SKILL.md §CorrectionLoop + reference correction-loop.md","confidence":"high","human_overrode":false}}
+{"schema_version":"1","session_id":"2026-05-22-e5f6g7h8","timestamp":"2026-05-22T16:00:30.000Z","skill":"adia-ui-kit","skill_version":"3.1.0","event_type":"correction_applied","payload":{"feedback_ticket":"FB-42","skill_section":"§CorrectionLoop","what_skill_said_before":"admin-statusbar defaults to slot=footer","what_corrected_to":"admin-statusbar has no default slot; explicit slot=trailing on host","bug_shape_class":"misdiagnosed-default-slot"}}
+{"schema_version":"1","session_id":"2026-05-22-e5f6g7h8","timestamp":"2026-05-22T16:01:00.000Z","skill":"adia-ui-kit","skill_version":"3.1.0","event_type":"session_closed","payload":{"duration_ms":60000,"total_events":4,"outcome":"completed","summary":"FB-42 correction applied to §CorrectionLoop. Bug-shape taxonomy updated."}}
+```
+
+---
+
+## Operational notes
+
+- **Append-only** — never rewrite past events. Bugs in past entries are corrected by emitting a `correction_applied` event referencing them.
+- **Retention** — operator-owned. The skill does NOT prescribe a retention policy (don't be opinionated about ops). Recommend rotating per-month or per-quarter for long-running deployments.
+- **Privacy** — payloads may contain user-facing content. Treat as user-confidential at the same level as the agent's tool-call transcripts.
+- **Validation** — `scripts/validate-session-log.mjs <path>` lints a JSONL file against this schema. Fails on missing required fields, unknown event types, or invalid timestamps.
+- **Not a billing log** — this is for audit/QA/eval-corpus-growth, not metering.
+
+---
+
+## Cross-references
+
+- `scripts/validate-session-log.mjs` — runtime validator
+- `scripts/teach-route.mjs` — emits `teach_landing` event candidates
+- `decision-model.md` — DecisionModel contract that produces `decision_made` events (v3.1.0 advisory, v3.2.0+ may become required)
+- REFACTOR-SPEC P5(a) — origin of this schema
+- AGENTS.md journal discipline — orthogonal to session logs (journals = human prose, session logs = structured event stream)