agent-bios 0.3.0 → 0.5.0

package/scripts/check-learning.py

@@ -0,0 +1,231 @@
+#!/usr/bin/env python3
+"""Learning record gate + validator (collection loop, Phase 0).
+
+config/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
+checked here, not frozen in the schema, so vocabulary evolution never needs
+a schema_version bump.
+
+Modes:
+  (no args)     gate: schema validates against its 2020-12 metaschema;
+                every fixtures/valid-*.json passes; every fixtures/broken-*.json
+                fails AND the failure names the field the fixture breaks
+                (a broken fixture failing for an unrelated reason is a FAIL);
+                non-vacuity: >=1 valid fixture, >=1 broken fixture,
+                >=1 registered domain.
+  <file.json>…  validate the given record file(s); exit 0 iff all valid.
+                This is the client-side validation entry point for Phase 1.
+  --self-test   negative controls: in-memory mutations of a valid record
+                (each required field dropped, plus type/pattern/membership
+                mutations) must ALL be rejected; the unmutated record must
+                pass. Proves the gate can fail.
+
+Any violation exits 1 with all violations listed.
+"""
+import json
+import pathlib
+import sys
+
+try:
+    import jsonschema
+except ImportError:
+    sys.exit("check-learning: the 'jsonschema' package is required "
+             "(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"
+FIXTURES = REPO / "design" / "collection-loop" / "fixtures"
+
+# broken fixture -> field its single defect lives in; the reported errors
+# must mention it, so a fixture failing for an accidental other reason fails
+# the gate instead of silently passing as "broken as expected".
+BROKEN_EXPECT = {
+    "broken-missing-lesson.json": "lesson",
+    "broken-unknown-domain.json": "domain",
+    "broken-schema-version.json": "schema_version",
+    "broken-extra-field.json": "email",
+    "broken-empty-sessions.json": "supporting_sessions",
+    "broken-bad-created.json": "created",
+    "broken-proposed-domain-conflict.json": "domain",
+    "broken-bad-classification.json": "classification",
+}
+
+
+def load_json(path):
+    with open(path, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def valid_domain_values(path=DOMAINS):
+    """The set a record's `domain` may take, drawn from config/domains.json.
+
+    Ledger-compatible (design/session-distill/ledger.json): the ledger's
+    `domain` field uses BOTH domain keys (builder-base, …) for
+    domain-specific lessons AND tier names (core, infra, …) for cross-cutting
+    ones — 4 real entries carry core/infra. So the valid set is the union of
+    both registered vocabularies plus 'unclassified' (refinement B — the
+    not-yet-triaged escape; kept distinct from 'core', which means a genuinely
+    cross-cutting lesson). Reuses existing vocabulary; introduces none.
+    """
+    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)")
+    return values
+
+
+def validate_record(record, validator, domain_values):
+    """Full validity: schema conformance + domain membership. Returns error strings."""
+    errors = []
+    for e in validator.iter_errors(record):
+        where = "/".join(str(p) for p in e.path) or "<root>"
+        errors.append(f"{where}: {e.message}")
+    if isinstance(record, dict):
+        dom = record.get("domain")
+        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)")
+    return errors
+
+
+def build_validator():
+    schema = load_json(SCHEMA)
+    jsonschema.Draft202012Validator.check_schema(schema)
+    return jsonschema.Draft202012Validator(schema)
+
+
+def gate():
+    validator = build_validator()
+    domain_values = valid_domain_values()
+    failures = []
+
+    valid_fx = sorted(FIXTURES.glob("valid-*.json"))
+    broken_fx = sorted(FIXTURES.glob("broken-*.json"))
+    if not valid_fx:
+        failures.append(f"no valid-*.json fixtures in {FIXTURES} (vacuous)")
+    if not broken_fx:
+        failures.append(f"no broken-*.json fixtures in {FIXTURES} (vacuous)")
+
+    for fx in valid_fx:
+        errors = validate_record(load_json(fx), validator, domain_values)
+        if errors:
+            failures.append(f"{fx.name} must validate but failed: {'; '.join(errors)}")
+
+    for fx in broken_fx:
+        errors = validate_record(load_json(fx), validator, domain_values)
+        expect = BROKEN_EXPECT.get(fx.name)
+        if expect is None:
+            failures.append(f"{fx.name} has no BROKEN_EXPECT entry (unmapped negative control)")
+        elif not errors:
+            failures.append(f"{fx.name} must FAIL but validated (negative control broken)")
+        elif not any(expect in err for err in errors):
+            failures.append(
+                f"{fx.name} failed for the wrong reason (expected mention of "
+                f"{expect!r}): {'; '.join(errors)}")
+    for name in BROKEN_EXPECT:
+        if not (FIXTURES / name).is_file():
+            failures.append(f"BROKEN_EXPECT names a missing fixture: {name}")
+
+    if failures:
+        print("check-learning: FAIL")
+        for f in failures:
+            print(f"  - {f}")
+        return 1
+    print(f"check-learning: OK ({len(valid_fx)} valid, "
+          f"{len(broken_fx)} negative controls)")
+    return 0
+
+
+def self_test():
+    validator = build_validator()
+    domain_values = valid_domain_values()
+    base = load_json(FIXTURES / "valid-minimal.json")
+    schema = load_json(SCHEMA)
+
+    def drop(field):
+        r = dict(base)
+        del r[field]
+        return r
+
+    def swap(field, value):
+        return {**base, field: value}
+
+    mutations = [(f"drop required '{f}'", drop(f), f) for f in schema["required"]]
+    mutations += [
+        ("schema_version as string", swap("schema_version", "1"), "schema_version"),
+        ("uppercase learning_id", swap("learning_id", base["learning_id"].upper()), "learning_id"),
+        ("lesson below minLength", swap("lesson", "short"), "lesson"),
+        ("capitalized domain", swap("domain", "Builder-Base"), "domain"),
+        ("session id without tool prefix", swap("supporting_sessions", ["517fbcea"]), "supporting_sessions"),
+        ("created without T/zone", swap("created", "20260720T050000Z"), "created"),
+        ("unknown extra key", {**base, "user_email": "x@y"}, "user_email"),
+        ("classification type out of A-G enum", swap("classification", {"type": "Z"}), "classification"),
+        ("classification unknown sub-key", swap("classification", {"mechanism": "x"}), "classification"),
+        ("proposed_domain with a concrete domain", {**base, "proposed_domain": "data-pipeline", "domain": "builder-base"}, "domain"),
+    ]
+
+    failures = []
+    if validate_record(base, validator, domain_values):
+        failures.append("positive control (valid-minimal) does not validate")
+    # positive control: a tier-name domain (real ledger precedent) must pass.
+    if validate_record({**base, "domain": "core"}, validator, domain_values):
+        failures.append("positive control (domain='core' tier name) does not validate")
+    # positive control: the optional slim classification block must pass.
+    if validate_record({**base, "classification": {"type": "B", "layer": "hook", "meets_bar": True}}, validator, domain_values):
+        failures.append("positive control (valid classification block) does not validate")
+    # positive control: proposed_domain rides only with an unclassified domain (base is unclassified).
+    if validate_record({**base, "proposed_domain": "data-pipeline"}, validator, domain_values):
+        failures.append("positive control (proposed_domain + unclassified) does not validate")
+    for name, record, expect in mutations:
+        errors = validate_record(record, validator, domain_values)
+        if not errors:
+            failures.append(f"mutation NOT caught: {name}")
+        elif not any(expect in err for err in errors):
+            failures.append(f"mutation caught for the wrong reason: {name} -> {errors}")
+
+    if failures:
+        print("check-learning --self-test: FAIL")
+        for f in failures:
+            print(f"  - {f}")
+        return 1
+    print(f"check-learning --self-test: OK ({len(mutations)} mutations caught, "
+          f"4 positive controls)")
+    return 0
+
+
+def validate_files(paths):
+    validator = build_validator()
+    domain_values = valid_domain_values()
+    rc = 0
+    for p in paths:
+        # Client entry point (Phase 1): inputs are not hand-authored fixtures,
+        # so malformed JSON / unreadable files report cleanly, never a traceback.
+        try:
+            record = load_json(p)
+        except (json.JSONDecodeError, OSError) as e:
+            rc = 1
+            print(f"INVALID {p}")
+            print(f"  - not readable JSON: {e}")
+            continue
+        errors = validate_record(record, validator, domain_values)
+        if errors:
+            rc = 1
+            print(f"INVALID {p}")
+            for e in errors:
+                print(f"  - {e}")
+        else:
+            print(f"OK {p}")
+    return rc
+
+
+if __name__ == "__main__":
+    args = sys.argv[1:]
+    if args == ["--self-test"]:
+        sys.exit(self_test())
+    if args:
+        sys.exit(validate_files(args))
+    sys.exit(gate())

package/scripts/check-parity.sh

@@ -113,8 +113,43 @@ real Microsoft Excel engine|claude/CLAUDE.md|claude/guides/coding-staged-workflo
 severity contract|README.md|claude/guides/coding-staged-workflow.md
 Ambient state|claude/CLAUDE.md|claude/guides/tooling-gotchas.md
 the full lifecycle of what you create|claude/CLAUDE.md|claude/guides/tooling-gotchas.md
+dual-provider frontier design drafts|claude/CLAUDE.md|claude/guides/cli-multi-model-workflow.md
 ANCHORS
 
+# Domain-manifest gate: bullet<->anchor bijection, file coverage, router
+# co-packaging (config/domains.json vs the monolith); its --self-test proves
+# every negative control still fails, so a green gate is falsifiable.
+if [ -f config/domains.json ]; then
+  python3 scripts/check-domains.py >/dev/null \
+    || { echo "FAIL: domains manifest gate (run scripts/check-domains.py)"; fail=1; }
+  python3 scripts/check-domains.py --self-test >/dev/null \
+    || { echo "FAIL: domains gate self-test missed a negative control"; fail=1; }
+  bash scripts/test-assemble.sh >/dev/null \
+    || { echo "FAIL: assembler scenario suite (run scripts/test-assemble.sh)"; fail=1; }
+fi
+
+# Learning record gate: config/learning.schema.json (collection-loop
+# SSOT) vs its fixtures; --self-test proves every mutation is still caught.
+if [ -f config/learning.schema.json ]; then
+  python3 scripts/check-learning.py >/dev/null \
+    || { echo "FAIL: learning record gate (run scripts/check-learning.py)"; fail=1; }
+  python3 scripts/check-learning.py --self-test >/dev/null \
+    || { echo "FAIL: learning gate self-test missed a negative control"; fail=1; }
+  # collect-learning Phase 2 transport: the watermark upload-drain logic
+  # (status classification, watermark advance, transient-stop, poison-skip).
+  python3 scripts/collect-learning.py --self-test >/dev/null \
+    || { echo "FAIL: collect-learning upload-drain self-test"; fail=1; }
+fi
+
+# Lexicon gate: forbid deprecated terminology tokens in live files
+# (LEXICON.md is the SSOT); --self-test proves the detector can fire.
+if [ -f LEXICON.md ]; then
+  python3 scripts/check-lexicon.py >/dev/null \
+    || { echo "FAIL: lexicon gate (run scripts/check-lexicon.py)"; fail=1; }
+  python3 scripts/check-lexicon.py --self-test >/dev/null \
+    || { echo "FAIL: lexicon gate self-test failed"; fail=1; }
+fi
+
 # The launcher's Textual preflight UI tests need the managed venv (textual).
 # Provision it if missing; every non-UI check above runs under system python.
 VENV="${AGENT_LAUNCH_VENV:-$HOME/.local/share/agent-launch/venv}"
@@ -551,7 +586,9 @@ if launcher.is_file() and launch_profile:
             def set_plan(self, plan):
                 self.plan = plan
 
-            def choose(self, title, options, default, allow_back, preview=None, learning_lines=None):
+            def choose(self, title, options, default, allow_back, preview=None, corpus_lines=None):
+                if title == "Mode":
+                    return "builder"
                 if title == "Preset":
                     if preview is not None:
                         balanced = launcher_module.setup_summary_lines(preview("balanced"))
@@ -772,12 +809,17 @@ if launcher.is_file() and launch_profile:
                 os.close(master)
             return bytes(transcript), picker_status
 
+        # Root menu is now a Mode picker (General user / Builder / Session
+        # distill); Builder is the default highlight and lists Custom. Reaching
+        # Custom means: Enter the root to open Builder's preset submenu, then
+        # step down through its fixed presets (Balanced default-highlighted).
         open_custom_steps = (
+            (b"Esc cancel | q cancel", b"\r"),
             (b"native multi-perspective review", b""),
-            (b"Esc cancel | q cancel", b"\x1b[B"),
+            (b"Esc back | q cancel", b"\x1b[B"),
             (b"hybrid onto", b"\x1b[B"),
             (b"high-volume", b"\x1b[B"),
-            (b"learning-refinement", b"\x1b[B"),
+            (b"the standing spawn policy is lifted", b"\x1b[B"),
             (b"Open a settings hub", b"\r"),
         )
         down = b"\x1b[B"
@@ -798,7 +840,7 @@ if launcher.is_file() and launch_profile:
             b"WORKHORSE",
             b"SWEEP",
             b"About highlighted option",
-            b"HELM default for everyday work",
+            b"Tune tiers, review routes, and permissions",
             b"Options (",
         )
         positions = {token: transcript.find(token) for token in layout_tokens}
@@ -809,7 +851,7 @@ if launcher.is_file() and launch_profile:
             positions[b"Current setup"]
             < min(positions[token] for token in (b"FRONTIER", b"HELM", b"WORKHORSE", b"SWEEP"))
             < positions[b"About highlighted option"]
-            < positions[b"HELM default for everyday work"]
+            < positions[b"Tune tiers, review routes, and permissions"]
             < positions[b"Options ("]
         ):
             mark_fail("agent-launch layout is not setup then description then options")
@@ -821,12 +863,27 @@ if launcher.is_file() and launch_profile:
         if picker_status != 130:
             mark_fail(f"agent-launch root Esc returned {picker_status}, want 130")
 
+        # Root Mode picker navigation: Esc from the Builder preset submenu
+        # returns to a freshly re-rendered Mode picker (Builder's own
+        # description reappears) rather than cancelling the launcher outright.
+        _, picker_status = run_picker_scenario(
+            "mode picker navigation",
+            (
+                (b"Esc cancel | q cancel", b"\r"),
+                (b"native multi-perspective review", b"\x1b"),
+                (b"Tune tiers, review routes, and permissions", b"q"),
+            ),
+        )
+        if picker_status != 130:
+            mark_fail(f"agent-launch mode picker Esc-back returned {picker_status}, want 130")
+
         if argv_log.exists():
             argv_log.unlink()
         _, picker_status = run_picker_scenario(
             "launch confirmation q cancellation",
             (
                 (b"Esc cancel | q cancel", b"\r"),
+                (b"HELM default for everyday work", b"\r"),
                 (b"Launch? [Y/n/q]:", b"q\r"),
             ),
             dry_run=False,
@@ -1128,10 +1185,19 @@ if launcher.is_file() and launch_profile:
         # TERM=dumb routes to numbered prompts (textual renders on any usable
         # terminal, so the numbered fallback is gated on TERM/non-TTY/textual
         # availability, not a terminfo probe). 'b' is the numbered back command.
-        custom_number = str(len(fake_data["presets"]) + 1).encode()
+        # The root Mode menu is fixed (General=1, Builder=2, Session distill=3)
+        # regardless of preset count; only Custom's position within Builder's
+        # own preset submenu depends on how many builder-mode presets exist.
+        builder_preset_count = sum(
+            1
+            for data in fake_data["presets"].values()
+            if data.get("mode", "builder") == "builder"
+        )
+        custom_number = str(builder_preset_count + 1).encode()
         transcript, picker_status = run_picker_scenario(
             "numbered fallback (TERM=dumb)",
             (
+                (b"Tune tiers, review routes, and permissions", b"2\n"),
                 (b"Open a settings hub", custom_number + b"\n"),
                 (b"Custom settings", b"b\n"),
                 (b"HELM default for everyday work", b"1\n"),
@@ -1145,27 +1211,27 @@ if launcher.is_file() and launch_profile:
         ):
             mark_fail("agent-launch numbered fallback (TERM=dumb) did not preserve numbered back")
 
-        # Session Learning hub: enter, render status, back out, launch balanced.
-        learning_number = str(len(fake_data["presets"]) + 2).encode()
+        # Session Distill hub: enter, render status, back out, launch balanced.
         transcript, picker_status = run_picker_scenario(
-            "numbered learning hub (TERM=dumb)",
+            "numbered distill hub (TERM=dumb)",
             (
-                (b"Session Learning", learning_number + b"\n"),
+                (b"Session distill", b"3\n"),
                 (b"Versions & rollback", b"4\n"),
+                (b"Tune tiers, review routes, and permissions", b"2\n"),
                 (b"HELM default for everyday work", b"1\n"),
             ),
             term="dumb",
         )
-        learning_panel_rendered = (
+        corpus_panel_rendered = (
             b"Applied version" in transcript or b"not projected yet" in transcript
         )
         if (
             picker_status != 0
             or b"Traceback" in transcript
-            or not learning_panel_rendered
+            or not corpus_panel_rendered
             or b"Preset         Balanced" not in transcript
         ):
-            mark_fail("agent-launch numbered learning hub did not render or return")
+            mark_fail("agent-launch numbered distill hub did not render or return")
 
         passed = invoke([
             sys.executable, str(launcher), "--no-tui", "codex", "--", "exec", "--json", "probe"
@@ -1492,6 +1558,29 @@ if launcher.is_file() and launch_profile:
                         "agent-launch Claude expert overrides were not appended last"
                     )
 
+        # Vanilla (mode=general): the raw backend with nothing applied — no
+        # launch contract, no agents, no permission-bypass flag.
+        vanilla_configured = invoke([
+            sys.executable, str(launcher), "--preset", "vanilla", "--yes", "--dry-run",
+            "claude",
+        ], env=env)
+        if vanilla_configured.returncode != 0:
+            mark_fail(
+                f"agent-launch vanilla dry-run failed: {vanilla_configured.stderr.strip()}"
+            )
+        else:
+            vanilla_argv = json.loads(vanilla_configured.stdout.splitlines()[-1])
+            for forbidden in (
+                "--append-system-prompt", "--agents", "--dangerously-skip-permissions",
+            ):
+                if forbidden in vanilla_argv:
+                    mark_fail(f"agent-launch vanilla preset unexpectedly carried {forbidden}")
+            if vanilla_argv != [str(backend)]:
+                mark_fail(
+                    "agent-launch vanilla preset must project the bare backend with "
+                    f"nothing applied: {vanilla_argv!r}"
+                )
+
         # Cross-family default: each main routes every review route to the OPPOSITE
         # model family, with concrete tools/paths/bindings named in the contract.
         # The cross CODEX_HOME needs the reviewer wrappers (bin) and the same-family
@@ -1766,5 +1855,5 @@ then
   fail=1
 fi
 
-[ "$fail" -eq 0 ] && echo "PARITY OK: mirrors, globals, guides, launch profile, bypass paths, role bindings, and wrapper defaults aligned"
+[ "$fail" -eq 0 ] && echo "PARITY OK: mirrors, globals, guides, domain manifest, assembler, launch profile, bypass paths, role bindings, and wrapper defaults aligned"
 exit "$fail"