agent-bios 0.4.0 → 0.5.0

package/claude/CLAUDE.md

@@ -147,3 +147,7 @@
 
 - For the detailed `IMPLEMENTATION_MAP.html` construction rules and the SVG service-blueprint spec, read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/implementation-map.md` as a scoped extension of this section.
 - In repos with implementation code, when architecture, goals, or roadmap context would help future work, maintain `IMPLEMENTATION_MAP.html` as a current-state dashboard — not a changelog, handoff log, or project diary — and update it before committing, when writing a handoff, or after meaningful architecture, roadmap, risk, decision, or verification changes.
+
+## Session Learning
+
+- `learn!` — session learning: when the user enters `learn!` in ANY session, capture durable lessons from THIS session for their own next session and the org. Read `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/learning-flow.md` and run its flow (admission bar → type A–G → intended consumption layer → the user's explicit approval), submitting approved learnings ONLY through `scripts/collect-learning.py`, which owns the id/timestamp and writes both the prose and the JSON record. When a Session distill preset run (trigger `distill!`) is active, that mission owns capture — do not also run this; and never manufacture Type-G principles user-side (curator-only).

package/claude/guides/learning-flow.md

@@ -0,0 +1,106 @@
+---
+guide_id: learning-flow
+language: en
+status: active
+use_when:
+  - the user entered `learn!` in any session (this is the light capture flow)
+  - capturing a durable lesson from the current session for reuse + org curation
+  - deciding whether a candidate lesson is worth recording, and how it should apply
+core_rules:
+  - three gates BEFORE asking the user — admission bar, type, consumption layer
+  - the user approves every recorded learning; nothing is written without it
+  - submit ONLY through scripts/collect-learning.py; never hand-write the record
+---
+
+# Session learning flow (`learn!`)
+
+The **light**, per-user, single-session capture flow: turn a lesson from the
+current session into a **learning** (prose + a JSON record) that (a) applies to
+the user's own next session and (b) reaches the org for curation. This is the
+counterpart of the **heavy** session-distill pipeline (`distill!`), which mines
+many sessions and is curator/power-user only. Terms follow the agent-bios
+`LEXICON.md`; the full routing framework is
+`design/session-distill/PLACEMENT-FRAMEWORK.md` (agent-bios repo).
+
+Defer to the preset mission: if this session runs the **Session distill** preset
+(trigger `distill!`), that mission owns capture — do not also run this flow.
+
+## When it fires
+
+Only on the user's `learn!`. Runs in-conversation on the CURRENT session (no
+Workflow fleets, no subagent mining). **Multiple learnings per invocation are
+allowed** — walk each candidate through the gates independently.
+
+## Rigor: three gates BEFORE surfacing anything
+
+Establish all three for each candidate; drop candidates that fail. Only
+still-valid candidates are surfaced for the user's approval.
+
+1. **Admission bar** (promotion criteria — PLACEMENT-FRAMEWORK): the lesson
+   recurred across **≥2 independent sessions**, OR it is a **single event with
+   high materiality** (irreversible / verification-corrupting / security). A
+   one-off low-stakes observation does not meet the bar — say so and skip it.
+
+2. **Type** (typology A–G; classify by root cause, first match wins):
+   - **A. Own-tooling defect** — a flaw in a script/tool we own (a repair).
+   - **B. Tool gotcha** — counterintuitive external-tool behavior with a
+     machine-detectable trigger (command pattern).
+   - **C. Recognition principle** — a cross-domain semantic signal → suspicion/action.
+   - **D. Domain procedure** — a multi-step method within an already-routed kind of work.
+   - **E. Environment fact** — a non-generalizable, decaying specific fact.
+   - **F. Unproven** — evidence still below the bar (usually already dropped at gate 1).
+   - **G. Principle/direction** — a value ordering shaping many decisions.
+     **Not manufactured user-side in v1** (curator-only); record a principle-ish
+     observation as an ordinary learning and let curation promote it.
+   Prefer *leftward reformulation* when it holds (E→C generalize a fact into a
+   principle; B/C/D→A mechanize knowledge into structure) — cheaper and more reliable.
+
+3. **Intended consumption layer** (cheapest-that-still-fires wins):
+   **enforcement > gate > hook > guide > global > memory** (`incubator` = park
+   for later triage). This is recorded as **metadata only** — do NOT build the
+   hook/gate/enforcement here; mechanization is deferred to curation.
+
+## Domain tagging (the curation join key)
+
+Suggest a `domain` from the registered vocabulary in `config/domains.json`
+(domain keys for domain-specific lessons, or a tier name like `core`/`infra`
+for a genuinely cross-cutting lesson); the user **confirms**. If unsure, use
+`unclassified` (never blocks capture — the curator assigns later). If no
+registered domain fits, keep `domain: "unclassified"` and put the model's
+suggested new name in `proposed_domain` (domain creation stays curator authority).
+
+## User approval, then submit
+
+Surface each surviving candidate compactly — lesson, type, intended layer,
+admission-bar verdict, domain (+ proposed_domain) — and record ONLY what the
+user explicitly approves.
+
+Submit each approved learning through the deterministic submit tool. Pass your
+session's `--host` and pipe the **semantic payload only** as one JSON object on
+stdin (set the `supporting_sessions` tool prefix — `claude:` or `codex:` — to
+match your host):
+
+    echo '{"lesson":"…","domain":"builder-base","supporting_sessions":["<tool>:<session-short-id>"],
+           "criteria":["recurrent_error"],
+           "classification":{"type":"B","layer":"hook","meets_bar":true}}' \
+      | python3 scripts/collect-learning.py --host <claude|codex>
+
+The script (capability boundary) owns `learning_id` / `created` / `schema_version`,
+validates against `config/learning.schema.json`, logs the JSON record, and writes
+the lesson prose where THIS host loads it next session:
+- **Claude**: appended to the automation-owned personal learnings file, pulled in
+  by the entry file's `@personal/learnings.md` import.
+- **Codex**: appended into a managed `agent-bios:personal-learnings` region of
+  `AGENTS.md` (Codex has no import; AGENTS.md is always loaded), kept outside the
+  central markers so re-assembly preserves it.
+
+**Never** hand-author `learning_id` / `created` / `schema_version`, and never
+write those files directly. If the script REJECTS a record, fix the semantic
+payload — do not work around the validation.
+
+## Scope (v1)
+
+- Single-session capture only; cross-session mining is `distill!` (curator).
+- Mechanization (hook/gate/enforcement) is deferred to curation — record intent, don't build it.
+- Type-G principle manufacture is curator-only.
+- Transport (upload to the org) lands in Phase 2; Phase 1 writes locally.

package/codex/AGENTS.md

@@ -148,3 +148,7 @@
 
 - For the detailed `IMPLEMENTATION_MAP.html` construction rules and the SVG service-blueprint spec, read and use `${CODEX_HOME:-$HOME/.codex}/guides/implementation-map.md` as a scoped extension of this section.
 - In repos with implementation code, when architecture, goals, or roadmap context would help future work, maintain `IMPLEMENTATION_MAP.html` as a current-state dashboard — not a changelog, handoff log, or project diary — and update it before committing, when writing a handoff, or after meaningful architecture, roadmap, risk, decision, or verification changes.
+
+## Session Learning
+
+- `learn!` — session learning: when the user enters `learn!` in ANY session, capture durable lessons from THIS session for their own next session and the org. Read `${CODEX_HOME:-$HOME/.codex}/guides/learning-flow.md` and run its flow (admission bar → type A–G → intended consumption layer → the user's explicit approval), submitting approved learnings ONLY through `scripts/collect-learning.py`, which owns the id/timestamp and writes both the prose and the JSON record. When a Session distill preset run (trigger `distill!`) is active, that mission owns capture — do not also run this; and never manufacture Type-G principles user-side (curator-only).

package/codex/guides/learning-flow.md

@@ -0,0 +1,106 @@
+---
+guide_id: learning-flow
+language: en
+status: active
+use_when:
+  - the user entered `learn!` in any session (this is the light capture flow)
+  - capturing a durable lesson from the current session for reuse + org curation
+  - deciding whether a candidate lesson is worth recording, and how it should apply
+core_rules:
+  - three gates BEFORE asking the user — admission bar, type, consumption layer
+  - the user approves every recorded learning; nothing is written without it
+  - submit ONLY through scripts/collect-learning.py; never hand-write the record
+---
+
+# Session learning flow (`learn!`)
+
+The **light**, per-user, single-session capture flow: turn a lesson from the
+current session into a **learning** (prose + a JSON record) that (a) applies to
+the user's own next session and (b) reaches the org for curation. This is the
+counterpart of the **heavy** session-distill pipeline (`distill!`), which mines
+many sessions and is curator/power-user only. Terms follow the agent-bios
+`LEXICON.md`; the full routing framework is
+`design/session-distill/PLACEMENT-FRAMEWORK.md` (agent-bios repo).
+
+Defer to the preset mission: if this session runs the **Session distill** preset
+(trigger `distill!`), that mission owns capture — do not also run this flow.
+
+## When it fires
+
+Only on the user's `learn!`. Runs in-conversation on the CURRENT session (no
+Workflow fleets, no subagent mining). **Multiple learnings per invocation are
+allowed** — walk each candidate through the gates independently.
+
+## Rigor: three gates BEFORE surfacing anything
+
+Establish all three for each candidate; drop candidates that fail. Only
+still-valid candidates are surfaced for the user's approval.
+
+1. **Admission bar** (promotion criteria — PLACEMENT-FRAMEWORK): the lesson
+   recurred across **≥2 independent sessions**, OR it is a **single event with
+   high materiality** (irreversible / verification-corrupting / security). A
+   one-off low-stakes observation does not meet the bar — say so and skip it.
+
+2. **Type** (typology A–G; classify by root cause, first match wins):
+   - **A. Own-tooling defect** — a flaw in a script/tool we own (a repair).
+   - **B. Tool gotcha** — counterintuitive external-tool behavior with a
+     machine-detectable trigger (command pattern).
+   - **C. Recognition principle** — a cross-domain semantic signal → suspicion/action.
+   - **D. Domain procedure** — a multi-step method within an already-routed kind of work.
+   - **E. Environment fact** — a non-generalizable, decaying specific fact.
+   - **F. Unproven** — evidence still below the bar (usually already dropped at gate 1).
+   - **G. Principle/direction** — a value ordering shaping many decisions.
+     **Not manufactured user-side in v1** (curator-only); record a principle-ish
+     observation as an ordinary learning and let curation promote it.
+   Prefer *leftward reformulation* when it holds (E→C generalize a fact into a
+   principle; B/C/D→A mechanize knowledge into structure) — cheaper and more reliable.
+
+3. **Intended consumption layer** (cheapest-that-still-fires wins):
+   **enforcement > gate > hook > guide > global > memory** (`incubator` = park
+   for later triage). This is recorded as **metadata only** — do NOT build the
+   hook/gate/enforcement here; mechanization is deferred to curation.
+
+## Domain tagging (the curation join key)
+
+Suggest a `domain` from the registered vocabulary in `config/domains.json`
+(domain keys for domain-specific lessons, or a tier name like `core`/`infra`
+for a genuinely cross-cutting lesson); the user **confirms**. If unsure, use
+`unclassified` (never blocks capture — the curator assigns later). If no
+registered domain fits, keep `domain: "unclassified"` and put the model's
+suggested new name in `proposed_domain` (domain creation stays curator authority).
+
+## User approval, then submit
+
+Surface each surviving candidate compactly — lesson, type, intended layer,
+admission-bar verdict, domain (+ proposed_domain) — and record ONLY what the
+user explicitly approves.
+
+Submit each approved learning through the deterministic submit tool. Pass your
+session's `--host` and pipe the **semantic payload only** as one JSON object on
+stdin (set the `supporting_sessions` tool prefix — `claude:` or `codex:` — to
+match your host):
+
+    echo '{"lesson":"…","domain":"builder-base","supporting_sessions":["<tool>:<session-short-id>"],
+           "criteria":["recurrent_error"],
+           "classification":{"type":"B","layer":"hook","meets_bar":true}}' \
+      | python3 scripts/collect-learning.py --host <claude|codex>
+
+The script (capability boundary) owns `learning_id` / `created` / `schema_version`,
+validates against `config/learning.schema.json`, logs the JSON record, and writes
+the lesson prose where THIS host loads it next session:
+- **Claude**: appended to the automation-owned personal learnings file, pulled in
+  by the entry file's `@personal/learnings.md` import.
+- **Codex**: appended into a managed `agent-bios:personal-learnings` region of
+  `AGENTS.md` (Codex has no import; AGENTS.md is always loaded), kept outside the
+  central markers so re-assembly preserves it.
+
+**Never** hand-author `learning_id` / `created` / `schema_version`, and never
+write those files directly. If the script REJECTS a record, fix the semantic
+payload — do not work around the validation.
+
+## Scope (v1)
+
+- Single-session capture only; cross-session mining is `distill!` (curator).
+- Mechanization (hook/gate/enforcement) is deferred to curation — record intent, don't build it.
+- Type-G principle manufacture is curator-only.
+- Transport (upload to the org) lands in Phase 2; Phase 1 writes locally.

package/config/domains.json

@@ -0,0 +1,150 @@
+{
+  "version": 1,
+  "tiers": ["core", "domain", "env-personal", "infra"],
+  "domains": {
+    "builder-base": "Technical-common: coding, verification menus, documentation hygiene, tooling safety, concept economy",
+    "llm-pipeline-dev": "LLM pipeline development: capability boundary, structured output, runtime authority",
+    "multi-agent-orchestration": "Multi-model/CLI orchestration: spawn policy, prompting guides, cross-family review",
+    "visualization-docs": "Visual explanations: HTML/SVG diagrams, implementation map",
+    "office-work": "Office artifacts: spreadsheet processing"
+  },
+  "bullets": [
+    {"anchor": "Prefer concise Korean responses", "tier": "env-personal", "domains": []},
+    {"anchor": "Keep file changes within the requested scope", "tier": "core", "domains": []},
+    {"anchor": "First identify the goal, scope, ambiguities", "tier": "core", "domains": []},
+    {"anchor": "Resolve ambiguity from context when safe", "tier": "core", "domains": []},
+    {"anchor": "For simple requests, choose the most direct", "tier": "core", "domains": []},
+    {"anchor": "For non-trivial requests, compare 2-4 methods", "tier": "core", "domains": []},
+    {"anchor": "Mark one default method", "tier": "core", "domains": []},
+    {"anchor": "Execute the chosen method accurately", "tier": "core", "domains": []},
+    {"anchor": "Return to understanding if a discovery breaks", "tier": "core", "domains": []},
+    {"anchor": "Reconsider the method if the selected approach", "tier": "core", "domains": []},
+    {"anchor": "Log non-blocking discoveries and continue", "tier": "core", "domains": []},
+    {"anchor": "If the same loopback happens twice", "tier": "core", "domains": []},
+    {"anchor": "Compare the result with the selected", "tier": "core", "domains": []},
+    {"anchor": "Ask decision questions in outcome terms", "tier": "core", "domains": []},
+    {"anchor": "When the user may not know the domain", "tier": "core", "domains": []},
+    {"anchor": "Present 2-4 meaningful options", "tier": "core", "domains": []},
+    {"anchor": "For each option, state what changes", "tier": "core", "domains": []},
+    {"anchor": "Translate technical terms into plain consequences", "tier": "core", "domains": []},
+    {"anchor": "Ask for the user's goal or constraint", "tier": "core", "domains": []},
+    {"anchor": "Evaluate user suggestions for goal fit", "tier": "core", "domains": []},
+    {"anchor": "Distinguish implementation feasibility from recommendation", "tier": "core", "domains": []},
+    {"anchor": "Do not default to a restrictive lens", "tier": "core", "domains": []},
+    {"anchor": "Treat user suggestions, inherited premises, prior diagnoses", "tier": "core", "domains": []},
+    {"anchor": "For structured-output, runtime-authority, capability-surface", "tier": "domain", "domains": ["llm-pipeline-dev"]},
+    {"anchor": "Use instructions to describe intended work", "tier": "domain", "domains": ["llm-pipeline-dev"]},
+    {"anchor": "Use the LLM for semantic work", "tier": "domain", "domains": ["llm-pipeline-dev"]},
+    {"anchor": "Use the capability surface for structural constraints", "tier": "domain", "domains": ["llm-pipeline-dev"]},
+    {"anchor": "Enforce constraints through the capability surface", "tier": "domain", "domains": ["llm-pipeline-dev"]},
+    {"anchor": "Use tools/code for deterministic work", "tier": "domain", "domains": ["llm-pipeline-dev"]},
+    {"anchor": "When exactness, freshness, scale, repeatability", "tier": "domain", "domains": ["llm-pipeline-dev"]},
+    {"anchor": "Let the LLM design merge, projection", "tier": "domain", "domains": ["llm-pipeline-dev"]},
+    {"anchor": "For required structured or machine-consumed outputs", "tier": "domain", "domains": ["llm-pipeline-dev"]},
+    {"anchor": "Let tools/code own ids, paths, serialization", "tier": "domain", "domains": ["llm-pipeline-dev"]},
+    {"anchor": "Keep deterministic values out of LLM authority", "tier": "domain", "domains": ["llm-pipeline-dev"]},
+    {"anchor": "For simple stable explanations or planning", "tier": "domain", "domains": ["llm-pipeline-dev"]},
+    {"anchor": "Treat a produced field, flag, signal", "tier": "domain", "domains": ["llm-pipeline-dev"]},
+    {"anchor": "Hard-block only deterministically decidable structural", "tier": "domain", "domains": ["llm-pipeline-dev"]},
+    {"anchor": "Runtime/code may enforce the contract", "tier": "domain", "domains": ["llm-pipeline-dev"]},
+    {"anchor": "Keep the concept graph compact by reusing", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Treat lasting or shared names as concept", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Before adding or changing a concept", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Prefer broad, stable concepts with precise", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Before fixing a review finding or test failure", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Split or promote a concept when it changes", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Keep derived values as properties or projections", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Keep internal projections and helper outputs internal", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Distinguish authority from visibility", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Reuse existing enum values, failure kinds", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Use fallback paths, compatibility shims", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Keep comments and active docs aligned", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "When a split is necessary, name the parent", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "In ontology work, check existing entities", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "In code work, follow existing naming patterns", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Let the repository's shape mirror its concept graph", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "For `.xlsx` editing, generation, reconciliation", "tier": "domain", "domains": ["office-work"]},
+    {"anchor": "For meaningful development work, read and use", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "For mock, fixture, fake, stub, simulated-provider", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "When the user asks to", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Think before coding: state key assumptions", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Build the smallest viable functional path", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Treat viability as real behavior against", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Make surgical changes. Touch only what", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Clean up issues introduced by the current", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Own the full lifecycle of what you create", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Define success criteria before multi-step coding work", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "For bugs, prefer a reproducing test", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Every changed line should trace back", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Fix the root cause at its authority", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Land risky or behavior-changing work behind", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "For composing a review request, packet", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "After every meaningful code, ontology, config", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Use static checks broadly: typecheck, lint", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Add the narrowest reliable runtime or semantic test", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Pick each domain's verification mix", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Let the LLM derive scenarios from the diff", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Keep E2E stable with deterministic data", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Report the checks run, results", "tier": "core", "domains": []},
+    {"anchor": "Trust a green check only when it traversed", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Make completion criteria falsifiable", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Before comparing two of anything", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "For non-trivial designs or high-risk changes", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Proportion verification to cost, risk, and information gain", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Trust a green / zero-findings verdict only", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "For concrete shell/CLI traps", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Ambient state — the active shell", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Before relying on any model id", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Scope destructive actions (kill, rm, force-push", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Never accept secrets through transcript- or history-logged channels", "tier": "core", "domains": []},
+    {"anchor": "When a secret must be supplied", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Treat a coarse runtime signal", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Before reasoning about what a branch contains", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Standing spawn policy: check the spawn gates", "tier": "domain", "domains": ["multi-agent-orchestration"]},
+    {"anchor": "Down-spawns carry a machine-checkable done-when", "tier": "domain", "domains": ["multi-agent-orchestration"]},
+    {"anchor": "For work spanning multiple models or CLI agents", "tier": "domain", "domains": ["multi-agent-orchestration"]},
+    {"anchor": "For composing a prompt, packet, or tool description", "tier": "domain", "domains": ["multi-agent-orchestration"]},
+    {"anchor": "Allocate models by difficulty", "tier": "domain", "domains": ["multi-agent-orchestration"]},
+    {"anchor": "dual-provider frontier design drafts", "tier": "domain", "domains": ["multi-agent-orchestration"]},
+    {"anchor": "Never retry-storm a live rate limit", "tier": "domain", "domains": ["multi-agent-orchestration"]},
+    {"anchor": "On any resumed, cleared, or relocated session", "tier": "domain", "domains": ["multi-agent-orchestration"]},
+    {"anchor": "Keep runtime code, active docs, and execution-facing", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Use comments for non-obvious current behavior", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Put backward-compatibility notes, deprecated behavior", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Link from active docs or code to isolated notes", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Phrase guidelines as desired behavior", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "Prefer established docs such as", "tier": "domain", "domains": ["builder-base"]},
+    {"anchor": "For SVG diagrams, service blueprints", "tier": "domain", "domains": ["visualization-docs"]},
+    {"anchor": "When a concept is easier to understand visually", "tier": "domain", "domains": ["visualization-docs"]},
+    {"anchor": "Use HTML for comparisons, flows, state changes", "tier": "domain", "domains": ["visualization-docs"]},
+    {"anchor": "Keep HTML self-contained, accessible, and minimal", "tier": "domain", "domains": ["visualization-docs"]},
+    {"anchor": "Use plain text when it is clearer", "tier": "domain", "domains": ["visualization-docs"]},
+    {"anchor": "For the detailed `IMPLEMENTATION_MAP.html` construction rules", "tier": "domain", "domains": ["visualization-docs"]},
+    {"anchor": "In repos with implementation code", "tier": "domain", "domains": ["visualization-docs"]},
+    {"anchor": "`learn!` — session learning", "tier": "core", "domains": []}
+  ],
+  "guides": {
+    "claude-prompting.md": {"tier": "domain", "domains": ["multi-agent-orchestration"]},
+    "cli-multi-model-workflow.md": {"tier": "domain", "domains": ["multi-agent-orchestration"]},
+    "coding-staged-workflow.md": {"tier": "domain", "domains": ["builder-base"]},
+    "gpt-prompting.md": {"tier": "domain", "domains": ["multi-agent-orchestration"]},
+    "implementation-map.md": {"tier": "domain", "domains": ["visualization-docs"]},
+    "llm-capability-boundary-examples.md": {"tier": "domain", "domains": ["llm-pipeline-dev"]},
+    "llm-capability-boundary-patterns.md": {"tier": "domain", "domains": ["llm-pipeline-dev"]},
+    "llm-capability-boundary.md": {"tier": "domain", "domains": ["llm-pipeline-dev"]},
+    "mock-realization-boundary.md": {"tier": "domain", "domains": ["builder-base"]},
+    "review-request.md": {"tier": "domain", "domains": ["builder-base"]},
+    "session-distill-workflow.md": {"tier": "infra", "domains": []},
+    "learning-flow.md": {"tier": "infra", "domains": []},
+    "svg-visualization-guide.md": {"tier": "domain", "domains": ["visualization-docs"]},
+    "tooling-gotchas.md": {"tier": "domain", "domains": ["builder-base"]}
+  },
+  "hooks": {
+    "tooling-gotchas-hook.py": {"tier": "domain", "domains": ["builder-base"], "source_guide": "tooling-gotchas.md"}
+  },
+  "agents": {
+    "frontier.md": {"tier": "domain", "domains": ["multi-agent-orchestration"]},
+    "sweep.md": {"tier": "domain", "domains": ["multi-agent-orchestration"]},
+    "workhorse.md": {"tier": "domain", "domains": ["multi-agent-orchestration"]}
+  }
+}

package/config/learning.schema.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:agent-bios:schema:learning:v1",
+  "title": "Learning record",
+  "description": "Per-session learning artifact produced by the session learning flow (trigger `learn!`; design/collection-loop/DESIGN.md). This file is the SSOT for the upload payload of POST /api/ingest/learnings and for the curator export; the dashboard mirrors only minimal validation from it. Field names stay ledger-compatible (design/session-distill/ledger.json). Identity is NEVER carried in the payload — the server derives it from X-Hook-Token. `domain` membership (config/domains.json domains ∪ tier names ∪ 'unclassified') is enforced by scripts/check-learning.py, not frozen here, so vocabulary evolution never requires a schema_version bump.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "learning_id",
+    "lesson",
+    "domain",
+    "created",
+    "supporting_sessions"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 1,
+      "description": "Format version of this record (refinement A). v1 records carry exactly 1; the server accepts >=1 tolerantly and stores raw JSON verbatim (refinement C)."
+    },
+    "learning_id": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+      "description": "Client-generated UUID for this learning, lowercase canonical form (tooling must lowercase, e.g. macOS uuidgen emits uppercase). Owned by scripts/collect-learning.py, never hand-authored. Idempotency key for the pending-learnings.jsonl bounded retry in Phase 2. Distinct from the ledger's `id` (a curator-assigned short id like 'S3-07'); this is the light-flow record's own key.",
+      "$comment": "Ledger entries use `id`; the light-flow record's own key is `learning_id` (the artifact is a learning — LEXICON.md — so it is not `distill_id`, which would collide with the heavy session-distill pipeline)."
+    },
+    "lesson": {
+      "type": "string",
+      "minLength": 8,
+      "maxLength": 2000,
+      "description": "The learning as prose — the same text that landed in the user's ~/.claude/personal/learnings.md. Ledger-compatible with entries[].lesson."
+    },
+    "domain": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Curation join key, ledger-compatible: a D6 domain key from config/domains.json for a domain-specific lesson, OR a tier name (core, infra, …) for a cross-cutting lesson (4 real ledger entries carry core/infra), OR 'unclassified' (refinement B — users are never blocked at capture time; the curator assigns later; kept distinct from 'core', which asserts a genuinely cross-cutting lesson). Membership is validated by scripts/check-learning.py against config/domains.json (single source), not frozen in this pattern. When the model proposes a NOT-yet-registered domain, this stays 'unclassified' and the name goes in `proposed_domain`."
+    },
+    "created": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$",
+      "description": "Capture time (the moment the learning was recorded), ISO 8601 with explicit UTC 'Z' or numeric offset. Generated by tooling, not the LLM."
+    },
+    "supporting_sessions": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 16,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]*:[A-Za-z0-9-]{4,64}$"
+      },
+      "description": "Provenance in ledger format '<tool>:<session-short-id>' (e.g. 'claude:517fbcea'). The v1 slim flow is single-session, so capture-time records carry exactly one entry; the array shape is the ledger's."
+    },
+    "criteria": {
+      "type": "array",
+      "maxItems": 8,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9_]*$"
+      },
+      "description": "Optional why-worth-recording tags in ledger vocabulary (e.g. recurrent_error, quality_lever, rare_high_cost). The vocabulary is owned by design/session-distill/PLACEMENT-FRAMEWORK.md and deliberately not frozen here."
+    },
+    "classification": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional slim classification block set by the session learning flow (design/collection-loop/DESIGN.md Phase 1 step 2): the type, intended consumption layer, and admission-bar verdict — metadata ONLY (the hook/gate/enforcement is NOT built user-side; curation mechanizes later). Ledger-compatible with entries[].classification, which carries these plus curator-side detail.",
+      "properties": {
+        "type": {
+          "enum": ["A", "B", "C", "D", "E", "F", "G"],
+          "description": "Typology letter (design/session-distill/PLACEMENT-FRAMEWORK.md A–G); same vocabulary as the ledger's classification.type."
+        },
+        "layer": {
+          "enum": ["enforcement", "gate", "hook", "guide", "global", "memory", "incubator"],
+          "description": "Intended consumption layer (enforcement > gate > hook > guide > global > memory; 'incubator' = parked for later triage). Same vocabulary as the ledger's classification.layer; reuses the routing tree's fixed layers."
+        },
+        "meets_bar": {
+          "type": "boolean",
+          "description": "Whether the candidate passed the admission bar (independent-session recurrence ≥2 or single-event high materiality). Maps to the ledger's meets_promotion_bar."
+        }
+      }
+    },
+    "proposed_domain": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Optional: a NEW domain name the model proposes when no registered domain fits (design/collection-loop/DESIGN.md Phase 1 step 3). Domain creation stays curator authority, so `domain` remains 'unclassified' whenever this is set (enforced by the conditional below)."
+    },
+    "context": {
+      "type": "string",
+      "maxLength": 4000,
+      "description": "Optional one-paragraph evidence / when-it-applies note for the curator; the source session is gone by curation time."
+    }
+  },
+  "if": {
+    "required": ["proposed_domain"]
+  },
+  "then": {
+    "properties": {
+      "domain": {
+        "const": "unclassified"
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-bios",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A thin, low-level instruction layer for LLM CLI agents: one set of principles and behavior whichever model you run. Deploys into $HOME by copy via an explicit `agent-bios install`.",
   "bin": {
     "agent-bios": "scripts/install.sh"
@@ -15,10 +15,14 @@
     "codex/agents/",
     "codex/config-additions.toml",
     "config/agent-launch.toml",
+    "config/domains.json",
+    "config/learning.schema.json",
     "shell/agent-launch.zsh",
     "scripts/agent-launch.py",
     "scripts/check-parity.sh",
     "scripts/check-prompting-targets.sh",
+    "scripts/check-learning.py",
+    "scripts/collect-learning.py",
     "scripts/codex-run.sh",
     "scripts/codex-helm.sh",
     "scripts/install.sh",