agent-bios 0.9.8 → 0.9.9

package/launch/agent-launch.toml

@@ -0,0 +1,376 @@
+schema_version = 1
+
+[backends.codex]
+command = "codex"
+passthrough_args = []
+
+[backends.claude]
+command = "claude"
+passthrough_args = ["--dangerously-skip-permissions"]
+
+# Optional dependencies. `command` gates the route: unresolvable means the route
+# is unavailable and the review setup degrades without it. `install` is the single
+# source for both the one-line hint shown when it is missing and what
+# `agent-bios install --with <name>` runs.
+[capabilities.onto]
+command = "onto"
+install = "npm i -g onto-mcp"
+# How this tool exposes an operation. The adapter is a protocol codec owned by core,
+# never a method identity, so a second method reusing the tag is data-only.
+# `evidence` names what this tool reports back about the dispatch it performed, and a
+# receipt missing any of it is not credited. These three are what onto's override already
+# returns on its warning channel. They are here because of a measured incident, not a
+# guess: an override that reached no seat resolved to a default provider with a null model
+# and did NOT fail, so a reporter with nothing to check would have called it a success.
+offers = [{ operation = "structured-review", adapter = "mcp-stdio-v1", hosts = ["codex", "claude"], evidence = ["reached_seat", "billing_mode", "auth_defaulted"] }]
+
+# ── dynamic workflow, one concept and two host-bound tools ─────────────────
+# `ultracode` runs ON CLAUDE and `ultracode-for-codex` runs ON CODEX — the names say which,
+# and getting them the wrong way round is the mistake to avoid: the package name is
+# "ultracode, ported for codex", not "the codex one is the real one".
+#
+# What they are FOR, which is what a reader choosing between reviewers actually needs:
+# both drive a dynamic workflow, used here as a flexible many-perspective check on an
+# IMPLEMENTATION — does it function, does it survive an adversary, does the logic hold,
+# does it hold under a real scenario, does it hold under stress. That makes them
+# COMPLEMENTARY to onto rather than competing with it: onto looks hardest at whether
+# authority, gates and harness are consistent with each other. The two are independently
+# selectable, and both single-sided choices are legitimate — a thing whose whole point is
+# that it WORKS can be reviewed by the workflow alone, and a logic-bearing document,
+# ontology, harness or gate can be reviewed by onto alone.
+
+[capabilities.ultracode]
+# Not a separate tool: the Claude Code CLI's own dynamic workflow, opened by putting the
+# keyword in the prompt (read in the installed 2.1.220 bundle —
+# `workflowKeywordTriggerEnabled`: "including the keyword in a prompt opts that turn into
+# the Workflow tool", default true). So the command IS the claude backend, and there is
+# nothing extra to install.
+# `${backend}` and not the literal token: this tool IS the configured claude CLI, so a
+# duplicated default broke it for anyone whose backend is a wrapper or an absolute path —
+# dispatch worked, the reviewer reported NOT INSTALLED, and the review went on without it.
+# No `install`: that field is EXECUTED by `agent-bios install --with`, so prose there would
+# be run as a shell command, and a missing claude CLI is a missing host, not a missing
+# reviewer.
+command = "${backend}"
+# claude only: the keyword trigger is a Claude Code feature, so a codex seat cannot run it.
+offers = [{ operation = "workflow-review", adapter = "host-workflow-v1", hosts = ["claude"] }]
+
+[capabilities.ultracode-for-codex]
+command = "ultracode-for-codex"
+install = "npm i -g ultracode-for-codex"
+# codex only, and this is the tool's nature rather than a policy: it drives the Codex
+# app-server and takes its model catalog from there, so a reviewer seated on the
+# claude host is a seat it cannot fill. Declaring both hosts made a codex-main launch
+# emit "run ultracode-for-codex on claude-fable-5", which cannot work.
+#
+# Between the two, this review is available CROSS-FAMILY from either main — which the
+# codex arm previously had no way to express, and so silently went without.
+offers = [{ operation = "workflow-review", adapter = "host-workflow-v1", hosts = ["codex"] }]
+
+# ── review methods (DESIGN.md §1) ───────────────────────────────────────────
+# Data only. Adding a method here — including one this repo has never seen — must
+# need no code change; gates/check_parity.py proves that with a runtime-named canary.
+# `instructions` may use only the core slot vocabulary: command, model, effort,
+# provider, host, service_tier, perspectives, trials, severities. An unknown slot is
+# rejected at load, so this list going stale is an over-restriction with a real cost — a
+# reviewer that needs one of them cannot be authored from what the config says. The
+# launcher's own rejection message enumerates INSTRUCTION_SLOTS, which is the list to
+# trust if the two ever differ.
+
+[review_methods.panel]
+label = "Isolated panel"
+description = "The always-present base: an isolated multi-perspective panel, no install required."
+instructions = "dispatch {command} as a fresh read-only process for {trials} isolated passes over the perspectives {perspectives}, each pinned to {model}/{effort}, and aggregate"
+output = "review-v1"
+perspectives = ["correctness", "security", "reproduction"]
+trials = 3
+order = "randomized"
+swap_augmentation = true
+aggregation = "majority"
+# Our own subagents report on the canonical ladder itself. Stated rather than left
+# implicit, because an identity map is exactly what a wrongly copied one looks like.
+severity_emits = ["blocker", "high", "medium", "low", "info"]
+severity_map = { blocker = "blocker", high = "high", medium = "medium", low = "low", info = "info" }
+
+[review_methods.onto]
+label = "onto structured lens review"
+description = "Audits any target — code, a design doc, a whole repo — against the intent you state, looking hardest at whether authority, gates and harness are consistent with one another; complementary to the ultracode workflows rather than an alternative, and enough on its own for a logic-bearing document, ontology, harness or gate. Six lenses, cited issues, dissent kept as an artifact. Needs no diff. Returns a handle, not a result: poll 10+ min, and read record_status before believing a clean report."
+capability = "onto"
+operation = "structured-review"
+# `effort` is sent and `auth` is deliberately NOT. onto's per-call override REPLACES
+# a seat whose route differs, so what it omits is dropped rather than inherited —
+# which is why effort must be stated: this binding IS the reviewer's pinned rigour.
+# auth is the opposite case. onto selects the metered route only when a seat says so in
+# writing — `auth = "api_key"` or an `api_key_env` naming the variable to call — and
+# defaults to the subscription worker otherwise, so an omitted auth cannot land on
+# metered and stating one buys nothing. It does cost something: switching a seat to
+# oauth is a route change, so a user who deliberately chose metered loses both their
+# auth and the api_key_env that carried it. Omitting it lets onto's default protect the
+# unconfigured seat and its overlay preserve the configured one.
+instructions = 'call onto_review/onto_prepare_review with llmOverride={{"provider":"{provider}","model":"{model}","effort":"{effort}"}} so onto runs on {provider} at {effort}'
+output = "review-v1"
+perspectives = ["axiology", "coverage", "evolution", "logic", "semantics", "structure"]
+trials = 1
+order = "fixed"
+swap_augmentation = false
+aggregation = "union"
+# onto's own REVIEW_SEVERITY_ORDER is this same ladder — read in its source, not
+# assumed. Identity is correct here for a different reason than the panel below.
+severity_emits = ["blocker", "high", "medium", "low", "info"]
+severity_map = { blocker = "blocker", high = "high", medium = "medium", low = "low", info = "info" }
+
+[review_methods.ultracode-for-codex]
+label = "Ultracode workflow review (Codex)"
+# Named for the tool, not for the legacy layer. The legacy route token `ultracode` used to
+# BE this capability's key, so naming the Claude tool `ultracode` silently repointed the
+# legacy route at it — the golden caught that, and the fix was to bind the legacy token to
+# a capability explicitly (`LEGACY_ULTRACODE_CAPABILITY`) rather than let a setup name and
+# a tool id be the same string.
+description = "The same dynamic workflow, ported to Codex — same use: things that have to WORK, checked from many angles rather than one. Fans dozens of Codex agents over your UNCOMMITTED working-tree changes for file:line defects, each candidate verified by its own agent. Its built-in code-review fails before spawning anything when the tree holds no reviewable change — clean, or only types it excludes such as .java, Dockerfile or dist/. Passing that gate is not the same as your files being reviewed. Detached: launching exits 0 even when the run dies."
+capability = "ultracode-for-codex"
+operation = "workflow-review"
+instructions = "run {command} against a self-contained review packet on {model}/{effort}"
+output = "review-v1"
+perspectives = ["orchestration"]
+trials = 1
+order = "fixed"
+swap_augmentation = false
+aggregation = "union"
+# P0..P3 plus a null severity, taken from the tool's own result contract. The mapping
+# is the owner's call: the tool documents the vocabulary but not what each level
+# means, so it cannot be derived. "null" keys a finding the tool reports with none.
+severity_emits = ["P0", "P1", "P2", "P3", "null"]
+severity_map = { P0 = "blocker", P1 = "high", P2 = "medium", P3 = "low", null = "info" }
+
+[review_methods.ultracode]
+label = "Ultracode workflow review (Claude)"
+description = "Claude Code's own dynamic workflow, on Claude. Decomposes the request across many agents and adversarially verifies each candidate finding before it survives. Use it on things that have to WORK — functional, adversarial, logic, scenario and stress passes — where onto is the one to reach for when the question is whether authority, gates and harness agree. Reviews whatever packet you hand it, so it needs no working-tree state. The keyword in the prompt is what opens the workflow: without it the turn is an ordinary session that will answer, plausibly, alone. PRECONDITION this launcher cannot establish: the keyword trigger must be enabled (`workflowKeywordTriggerEnabled`, default true, verified in claude 2.1.220). A resolvable claude CLI proves the command exists, not that the workflow opens — with that setting off the review runs as an ordinary session and would report as though it were orchestrated."
+capability = "ultracode"
+operation = "workflow-review"
+# The keyword is the whole mechanism, so it is stated as a literal rather than left to the
+# dispatcher's memory. The severity ladder is stated too, and that is what makes the
+# identity map below TRUE rather than copied: this reviewer has no vocabulary of its own —
+# it reports on the ladder because the request tells it to. A gate asserts the instruction
+# still names every value the descriptor claims, so the two cannot drift apart.
+instructions = "dispatch {command} as a fresh read-only process whose prompt carries the keyword ultracode, so the turn runs as an orchestrated workflow over a self-contained review packet on {model}/{effort} (confirm the workflow actually opened — a disabled keyword trigger yields an ordinary session), and require every finding to carry one of {severities}"
+output = "review-v1"
+perspectives = ["orchestration"]
+trials = 1
+order = "fixed"
+swap_augmentation = false
+aggregation = "union"
+severity_emits = ["blocker", "high", "medium", "low", "info"]
+severity_map = { blocker = "blocker", high = "high", medium = "medium", low = "low", info = "info" }
+
+[hosts.codex]
+# The model family this host speaks for. A review binding names a provider, and
+# the reverse map must be unique so it resolves to exactly one validatable seat.
+provider = "openai"
+models = ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"]
+# onto review seat used when a CROSS-family main (Claude) routes onto review to
+# this (gpt/codex) family; must be an onto review-role registered (provider, model).
+onto_review = { provider = "openai", model = "gpt-5.6-sol" }
+
+[hosts.codex.tiers.frontier]
+model = "gpt-5.6-sol"
+effort = "max"
+
+[hosts.codex.tiers.helm]
+model = "gpt-5.6-sol"
+effort = "xhigh"
+
+[hosts.codex.tiers.workhorse]
+model = "gpt-5.6-terra"
+effort = "high"
+
+[hosts.codex.tiers.sweep]
+model = "gpt-5.6-luna"
+effort = "low"
+
+[hosts.codex.agent_templates]
+frontier = "${CODEX_HOME}/agents/frontier.toml"
+workhorse = "${CODEX_HOME}/agents/workhorse.toml"
+sweep = "${CODEX_HOME}/agents/sweep.toml"
+
+# Model id -> the name the human-readable guides write. The guides' Environment Binding tables
+# restate these bindings in prose that also carries policy the profile does not hold ("main Ultra
+# requires explicit selection"), so those tables are not generatable — but the MODEL IDENTITY in
+# them is this file's, and until this map existed the parity gate compared each table to display
+# names written inside the gate. That made the gate a third author of the binding. With the map
+# here, the gate compares two real surfaces and holds no copy of its own.
+[model_display]
+"claude-fable-5" = "Claude Fable 5"
+"claude-opus-5" = "Claude Opus 5"
+"claude-haiku-4-5" = "Claude Haiku 4.5"
+"gpt-5.6-sol" = "GPT-5.6 Sol"
+"gpt-5.6-terra" = "GPT-5.6 Terra"
+"gpt-5.6-luna" = "GPT-5.6 Luna"
+
+[hosts.claude]
+provider = "anthropic"
+models = ["claude-fable-5", "claude-opus-5", "claude-sonnet-5", "claude-haiku-4-5"]
+# onto review seat used when a CROSS-family main (Codex) routes onto review to
+# this (anthropic/claude) family; must be an onto review-role registered (provider, model).
+onto_review = { provider = "anthropic", model = "claude-fable-5" }
+
+[hosts.claude.tiers.frontier]
+model = "claude-fable-5"
+effort = "max"
+
+[hosts.claude.tiers.helm]
+model = "claude-opus-5"
+effort = "xhigh"
+
+[hosts.claude.tiers.workhorse]
+model = "claude-opus-5"
+effort = "medium"
+
+[hosts.claude.tiers.sweep]
+model = "claude-haiku-4-5"
+effort = "low"
+
+[presets.balanced]
+label = "Balanced"
+description = "HELM default for everyday work with native multi-perspective review."
+mode = "builder"
+main_tier = "helm"
+frontier_effort = "max"
+delegation = true
+codex_execution_policy = "bypass"
+claude_permission_mode = "bypassPermissions"
+
+[presets.deep-review]
+label = "Deep review"
+description = "HELM with hybrid onto, native, and Ultracode review at deep FRONTIER effort."
+mode = "builder"
+main_tier = "helm"
+frontier_effort = { codex = "ultra", claude = "max" }
+delegation = true
+codex_execution_policy = "bypass"
+claude_permission_mode = "bypassPermissions"
+
+[presets.fast-batch]
+label = "Fast batch"
+description = "WORKHORSE default for high-volume, cost-conscious execution."
+mode = "builder"
+main_tier = "workhorse"
+frontier_effort = "max"
+delegation = true
+codex_execution_policy = "bypass"
+claude_permission_mode = "bypassPermissions"
+
+[presets.solo]
+label = "Solo"
+description = "Single-model session: delegation off (no tier fan-out; the standing spawn policy is lifted), review via the host's own command only."
+mode = "builder"
+main_tier = "helm"
+frontier_effort = "max"
+review_setup = "none"
+delegation = false
+codex_execution_policy = "bypass"
+claude_permission_mode = "bypassPermissions"
+
+[presets.vanilla]
+label = "Vanilla"
+description = "Plain CLI session: no launch contract, no tier bindings, standard permissions — exactly what the bare backend gives you."
+mode = "software-engineer"
+main_tier = "helm"
+frontier_effort = "max"
+review_setup = "none"
+delegation = false
+codex_execution_policy = "standard"
+claude_permission_mode = "standard"
+
+[presets.session-distill]
+# Author-only: the workflow edits the agent-bios corpus and needs a checkout, so
+# its mission names repo paths a packaged user does not have. Declaring it lets
+# gates/check-package.sh judge the mission text. NOTE: this declaration is read by
+# the gate, not yet by the launcher — the preset is still offered on a packaged
+# install. Closing that route belongs with the package-based distill work.
+audience = "author"
+label = "Session distill"
+description = "Dedicated session-distill run: mine recent sessions, verify, place, and apply per the session-distill workflow. Requires an agent-bios checkout."
+mode = "distill"
+main_tier = "helm"
+frontier_effort = "max"
+delegation = true
+codex_execution_policy = "bypass"
+claude_permission_mode = "bypassPermissions"
+mission = "This is a session-distill initiative session, gated on a trigger. When the user enters the trigger command '{trigger}': read claude/guides/session-distill-workflow.md in the agent-bios checkout, then the initiative state in design/session-distill/ledger.json in that same checkout, and run the next mining window per that guide. Until the trigger arrives, respond normally and do not start the workflow. Every promotion passes through explicit user approval; nothing is applied to the corpus without it."
+trigger = "distill!"
+
+
+# ── review, per host (DESIGN.md Corrections C7) ─────────────────────────────
+# A binding names a provider, which maps to one host, so cross-family review has to
+# be stated per launch host. Both answers live here rather than being inferred, and
+# the reviewer's tier now tracks the preset's intent instead of exposing the whole
+# opposite tier table for the reader to pick from.
+
+[presets.balanced.review.hosts.claude.base]
+provider = "openai"
+tier = "helm"
+
+[presets.balanced.review.hosts.codex.base]
+provider = "anthropic"
+tier = "helm"
+
+[presets.deep-review.review.hosts.claude.base]
+provider = "openai"
+tier = "frontier"
+
+[presets.deep-review.review.hosts.claude.methods."onto"]
+provider = "openai"
+tier = "frontier"
+
+[presets.deep-review.review.hosts.claude.methods."ultracode-for-codex"]
+provider = "openai"
+tier = "frontier"
+
+[presets.deep-review.review.hosts.codex.base]
+provider = "anthropic"
+tier = "frontier"
+
+[presets.deep-review.review.hosts.codex.methods."onto"]
+provider = "anthropic"
+tier = "frontier"
+
+[presets.deep-review.review.hosts.codex.methods."ultracode"]
+provider = "anthropic"
+tier = "frontier"
+
+[presets.fast-batch.review.hosts.claude.base]
+provider = "openai"
+tier = "workhorse"
+
+[presets.fast-batch.review.hosts.codex.base]
+provider = "anthropic"
+tier = "workhorse"
+
+[presets.session-distill.review.hosts.claude.base]
+provider = "openai"
+tier = "frontier"
+
+[presets.session-distill.review.hosts.claude.methods."onto"]
+provider = "openai"
+tier = "frontier"
+
+[presets.session-distill.review.hosts.claude.methods."ultracode-for-codex"]
+provider = "openai"
+tier = "frontier"
+
+[presets.session-distill.review.hosts.codex.base]
+provider = "anthropic"
+tier = "frontier"
+
+[presets.session-distill.review.hosts.codex.methods."onto"]
+provider = "anthropic"
+tier = "frontier"
+
+[presets.session-distill.review.hosts.codex.methods."ultracode"]
+provider = "anthropic"
+tier = "frontier"
+
+# Nudge baseline lives in ~/.local/share/agent-bios/session-distill-state.json,
+# written by session-distill/update-state.py at window close.
+[session_distill]
+nudge_after = 250

package/{scripts → launch}/check-prompting-targets.sh

@@ -11,7 +11,7 @@ cd "$(dirname "$0")/.." || exit 2
 python3 - "$@" <<'PY'
 import pathlib, re, sys, tomllib
 
-config = pathlib.Path("config/agent-launch.toml")
+config = pathlib.Path("launch/agent-launch.toml")
 hosts = tomllib.loads(config.read_text())["hosts"]
 
 # host -> the guide that owns prompting guidance for that host's model family

package/{scripts → launch}/provision-venv.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Provision the managed virtualenv that backs the agent-launch Textual preflight.
 #
-# The interactive launcher re-execs into this venv (scripts/agent-launch.py ->
+# The interactive launcher re-execs into this venv (launch/agent-launch.py ->
 # maybe_reexec_into_venv). It is an enhancement, not a hard dependency: when the
 # venv is missing or broken, the launcher falls back to numbered prompts, and
 # every direct / non-TTY / --no-tui path keeps running under the system

package/{scripts → learn}/check-learning.py

@@ -1,10 +1,10 @@
 #!/usr/bin/env python3
 """Learning record gate + validator (collection loop, Phase 0).
 
-config/learning.schema.json is the SSOT for the learning record
+learn/learning.schema.json is the SSOT for the learning record
 (design/collection-loop/DESIGN.md); the dashboard mirrors only minimal
 validation. Full client-side validity = JSON Schema conformance PLUS domain
-membership in config/domains.json domains ∪ 'unclassified' — membership is
+membership in compose/domains.json domains ∪ 'unclassified' — membership is
 checked here, not frozen in the schema, so vocabulary evolution never needs
 a schema_version bump.
 
@@ -35,8 +35,8 @@ except ImportError:
              "(pip install jsonschema; verified 4.26.0 in DEPENDENCIES.md)")
 
 REPO = pathlib.Path(__file__).resolve().parent.parent
-SCHEMA = REPO / "config" / "learning.schema.json"
-DOMAINS = REPO / "config" / "domains.json"
+SCHEMA = REPO / "learn" / "learning.schema.json"
+DOMAINS = REPO / "compose" / "domains.json"
 FIXTURES = REPO / "design" / "collection-loop" / "fixtures"
 
 # broken fixture -> field its single defect lives in; the reported errors
@@ -60,7 +60,7 @@ def load_json(path):
 
 
 def valid_domain_values(path=DOMAINS):
-    """The set a record's `domain` may take, drawn from config/domains.json.
+    """The set a record's `domain` may take, drawn from compose/domains.json.
 
     Ledger-compatible (design/session-distill/ledger.json): the ledger's
     `domain` field uses BOTH domain keys (builder-base, …) for
@@ -73,7 +73,7 @@ def valid_domain_values(path=DOMAINS):
     manifest = load_json(path)
     values = set(manifest["domains"]) | set(manifest["tiers"]) | {"unclassified"}
     if len(values) <= 1:
-        sys.exit("FAIL: config/domains.json registers no domains/tiers (vacuous gate)")
+        sys.exit("FAIL: compose/domains.json registers no domains/tiers (vacuous gate)")
     return values
 
 
@@ -88,7 +88,7 @@ def validate_record(record, validator, domain_values):
         if isinstance(dom, str) and dom not in domain_values:
             errors.append(
                 f"domain: {dom!r} is not a registered domain key, tier name, "
-                f"or 'unclassified' (config/domains.json)")
+                f"or 'unclassified' (compose/domains.json)")
     return errors
 
 

package/{scripts → learn}/collect-learning.py

@@ -7,8 +7,8 @@ optional criteria / classification / proposed_domain / context) plus its session
 `--host`; THIS script owns every deterministic value and side effect:
 
   * mints learning_id (a lowercase UUID) + created (ISO-8601) + schema_version;
-  * validates the full record against config/learning.schema.json — the single
-    validation source, reused from scripts/check-learning.py (no second schema);
+  * validates the full record against learn/learning.schema.json — the single
+    validation source, reused from learn/check-learning.py (no second schema);
   * logs the JSON record to <home>/personal/learnings.jsonl — the durable,
     append-only upload source that the Phase 2 watermark drain re-sends from;
   * writes the lesson prose where THIS host loads it next session, and wires it:
@@ -16,7 +16,7 @@ optional criteria / classification / proposed_domain / context) plus its session
         `@personal/learnings.md` import once in the entry CLAUDE.md;
       - codex: appends into a preserved `agent-bios:personal-learnings` region
         of <home>/AGENTS.md (Codex has no @import; AGENTS.md is always loaded).
-        The region lives OUTSIDE the central markers so scripts/assemble.py —
+        The region lives OUTSIDE the central markers so compose/assemble.py —
         which only rewrites the central region — preserves it across re-assembly.
 
 It REFUSES any script-owned field in the payload (deterministic values are never
@@ -61,7 +61,7 @@ HOSTS = {
 CLAUDE_IMPORT_LINE = "@personal/learnings.md"
 CLAUDE_CENTRAL_IMPORT = "@central/bundle.md"
 
-# Codex AGENTS.md markers. The central pair is owned by scripts/assemble.py
+# Codex AGENTS.md markers. The central pair is owned by compose/assemble.py
 # (kept in sync here); the personal-learnings pair is this tool's own region,
 # placed outside the central pair so re-assembly preserves it.
 CENTRAL_START = "<!-- agent-bios:central:start -->"
@@ -72,7 +72,7 @@ PERSONAL_END = "<!-- agent-bios:personal-learnings:end -->"
 CLAUDE_LEARNINGS_HEADER = """# Personal learnings
 
 <!-- Automation-owned: written by the session learning flow (`learn!`,
-     scripts/collect-learning.py). Do NOT hand-edit — promote→migrate clears
+     learn/collect-learning.py). Do NOT hand-edit — promote→migrate clears
      applied items by learning_id when the org redistributes them. Your own
      personal rules belong in the entry CLAUDE.md '## Personal' section, never
      here. This file is pulled into context by the entry file's
@@ -81,15 +81,15 @@ CLAUDE_LEARNINGS_HEADER = """# Personal learnings
 
 CODEX_REGION_HEADER = """## Personal learnings
 <!-- Automation-owned: written by the session learning flow (`learn!`,
-     scripts/collect-learning.py). Codex loads this via AGENTS.md (no @import).
+     learn/collect-learning.py). Codex loads this via AGENTS.md (no @import).
      Do NOT hand-edit — promote→migrate clears applied items by learning_id.
      Kept outside the agent-bios central markers so re-assembly preserves it. -->
 """
 
 
 def load_checker():
-    """Reuse scripts/check-learning.py as the single validation source."""
-    path = REPO / "scripts" / "check-learning.py"
+    """Reuse learn/check-learning.py as the single validation source."""
+    path = REPO / "learn" / "check-learning.py"
     spec = importlib.util.spec_from_file_location("check_learning", path)
     module = importlib.util.module_from_spec(spec)
     spec.loader.exec_module(module)
@@ -97,9 +97,9 @@ def load_checker():
 
 
 def load_redactor():
-    """Reuse scripts/redact.py as the single secret-redaction floor (loaded by
+    """Reuse learn/redact.py as the single secret-redaction floor (loaded by
     path so it works from the npm bin regardless of cwd, like load_checker)."""
-    path = REPO / "scripts" / "redact.py"
+    path = REPO / "learn" / "redact.py"
     spec = importlib.util.spec_from_file_location("redact", path)
     module = importlib.util.module_from_spec(spec)
     spec.loader.exec_module(module)

package/{config → learn}/learning.schema.json

@@ -2,7 +2,7 @@
   "$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.",
+  "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 (compose/domains.json domains ∪ tier names ∪ 'unclassified') is enforced by learn/check-learning.py, not frozen here, so vocabulary evolution never requires a schema_version bump.",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -21,7 +21,7 @@
     "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.",
+      "description": "Client-generated UUID for this learning, lowercase canonical form (tooling must lowercase, e.g. macOS uuidgen emits uppercase). Owned by learn/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": {
@@ -33,7 +33,7 @@
     "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`."
+      "description": "Curation join key, ledger-compatible: a D6 domain key from compose/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 learn/check-learning.py against compose/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",