chainaios 0.3.0__tar.gz

chainaios-0.3.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: chainaios
+Version: 0.3.0
+Summary: The Bandit AIOS application on the ChainCompiler stack: mint a domain's AC+CoR+SC and roll them up into persistent BanditChain-system AIOS dirs (GBA/HBA/COG).
+Requires-Python: >=3.11
+Requires-Dist: chaincompiler==0.3.0
+Requires-Dist: chaincompiler-accc==0.3.0
+Requires-Dist: corcc==0.3.0
+Requires-Dist: sccc==0.3.0
+Requires-Dist: agent-skilltree>=0.4.0
+Requires-Dist: click
+Requires-Dist: pyyaml
+Provides-Extra: legend
+Requires-Dist: glyphsteer==0.3.0; extra == "legend"

chainaios-0.3.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "chainaios"
+version = "0.3.0"
+description = "The Bandit AIOS application on the ChainCompiler stack: mint a domain's AC+CoR+SC and roll them up into persistent BanditChain-system AIOS dirs (GBA/HBA/COG)."
+requires-python = ">=3.11"
+# The AIOS tier sits ABOVE the cognition-chain stack: it imports the *CC + the CC base. (CC + the *CC
+# never import this — that is what keeps `chaincompiler` the compiler-compiler BASE, DESIGN.md §2.)
+dependencies = ["chaincompiler==0.3.0", "chaincompiler-accc==0.3.0", "corcc==0.3.0", "sccc==0.3.0", "agent-skilltree>=0.4.0", "click", "pyyaml"]
+
+# A lazy import is an optional extra (DESIGN.md §18): the roll-up writes each persona's GlyphSteer legend only when
+# glyphsteer is present (bandit.py, `_write_persona_aios`).
+[project.optional-dependencies]
+legend = ["glyphsteer==0.3.0"]
+
+# The `chaincompiler` CLI command now lives here (the AIOS commands are *CC-coupled); the command NAME is
+# unchanged so existing `chaincompiler gba/cog/hba/demo …` invocations keep working.
+[project.scripts]
+chaincompiler = "chainaios.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# the bandit-chain-system skill every GBA receives (DESIGN.md §8)
+[tool.setuptools.package-data]
+chainaios = ["data/bandit-chain-system/SKILL.md"]

chainaios-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

chainaios-0.3.0/src/chainaios/__init__.py

@@ -0,0 +1,30 @@
+"""chainaios — the Bandit AIOS application, ABOVE the cognition-chain stack.
+
+This is the AIOS/orchestration tier that sits ON TOP of ACCC/CORCC/SCCC (it mints a domain's AC + CoR + SC
+and rolls them up into persistent BanditChain-system AIOS dirs). It imports the *CC + the CC base; the CC
+base and the *CC never import it. (DESIGN.md §2 keeps `chaincompiler` the compiler-compiler BASE — the
+*CC are made FROM CC; this AIOS app is a separate top layer, extracted out of the CC package so CC no
+longer imports the *CC.)
+
+The `chaincompiler` console command lives here (entry `chainaios.cli:main`), so the CLI name is unchanged.
+"""
+from __future__ import annotations
+
+__version__ = "0.3.0"
+
+from .construct import construct_language, LanguageBundle
+from .bandit import (
+    domain_bandit, BanditChainSystem, roll_up_algebra, SelfView, hierarchicalize, COMPONENTS,
+)
+from .gba import GBA, make_gba, construct_into, search, load_gba, check_gba, default_rule_blocks
+from .hba import HBA, make_hba
+from .cog import COG, make_cog, load_cog, PATTERNS, SEATS
+
+__all__ = [
+    "construct_language", "LanguageBundle",
+    "domain_bandit", "BanditChainSystem", "roll_up_algebra", "SelfView", "hierarchicalize", "COMPONENTS",
+    "GBA", "make_gba", "construct_into", "search", "load_gba", "check_gba", "default_rule_blocks",
+    "HBA", "make_hba",
+    "COG", "make_cog", "load_cog", "PATTERNS", "SEATS",
+    "__version__",
+]

chainaios-0.3.0/src/chainaios/bandit.py

@@ -0,0 +1,312 @@
+"""bandit.py — the bandit's headline capability.
+
+The default persona (`corcc.BANDIT`, the ChainSelector) does ONE big move: given a
+domain, **roll up the AC→CoR→SC algebra and CLOSE it** into a self-contained
+*bandit chain system* — a domain-specific persona (an AIOS dir) whose CoR is the
+bandit, carrying instructions to (a) build its own KB and (b) walk that KB with
+GlyphSteer chains to improve itself.
+
+Then `hierarchicalize` applies the SAME move over everything the bandit is *made
+of* (accc · corcc · sccc · glyphsteer · skilltree · si · honeyc ·
+rulecatcher) — the homoicon: the bandit views its own composition as a domain and
+mints a closed chain system for each part, organized into one granular self-view.
+
+    roll_up_algebra(domain, atoms, ...) -> BanditChainSystem     (closed: bool)
+    hierarchicalize(workdir, ...)        -> SelfView             (a tree of systems)
+
+Exported from `chainaios` (the agent tier above the chain compilers — DESIGN.md §7);
+the chaincompiler base never imports it.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import accc
+import corcc
+import sccc
+from corcc.notation import BANDIT, Move, PersonaSpec
+
+from chaincompiler import slugify, write_skill   # the CC base (chainaios is ABOVE CC + the *CC)
+
+
+# ── the domain-specialized bandit (the selector, given a domain flavor) ──────
+def domain_bandit(domain: str, blurb: str = "") -> PersonaSpec:
+    """The BANDIT (ChainSelector) specialized to a domain. Same explore/exploit
+    moves (Task→Recall→Decide→Execute→Reward); the domain rides in the name, the
+    blurb, and an added Task cue. A *flavor* is a single proven chain; this is the
+    selector itself, pointed at one domain — so it still chooses select-vs-construct."""
+    b = blurb or (f"in the {domain} domain: frame the task, recall a proven {domain} "
+                  f"chain, choose exploit (select a golden chain) vs explore "
+                  f"(construct a new one), execute it, record the reward")
+    moves = list(BANDIT.moves)
+    moves[0] = Move("Task", BANDIT.moves[0].cues + (f"the {domain} task", f"in {domain}"))
+    return PersonaSpec(name=f"{domain.capitalize()}Bandit", moves=tuple(moves), blurb=b)
+
+
+# ── the two self-improvement instruction blocks the persona carries ──────────
+def kb_instructions(domain: str) -> str:
+    """How this persona builds its OWN knowledge base (the first self-instruction)."""
+    return "\n".join([
+        f"## Build your own KB ({domain})",
+        "",
+        "You maintain a knowledge base under `kb/`. It is yours — grow it as you work:",
+        "",
+        f"1. **Record** — every time you run a {domain} chain, write what happened to a",
+        f"   `kb/<topic>.md` note: the task, the chain you chose (select vs construct),",
+        "   the reward, and what you'd do differently. One note per topic; append, don't overwrite.",
+        "2. **Tag** — head each note with a `glyphs:` line (a GlyphSteer legend facet, e.g.",
+        "   `🏆`/`✅`/`⚠️`/`❌`) recording how well the chain worked. The grade is the reward signal.",
+        "3. **Index** — the KB is a corpus; treat each note as a chunk. The legend in",
+        "   `legend.json` is the controlled glyph vocabulary you annotate with.",
+    ])
+
+
+def glyphsteer_improve_instructions(domain: str) -> str:
+    """How this persona walks its KB with GlyphSteer chains to improve ITSELF."""
+    return "\n".join([
+        f"## Improve yourself via GlyphSteer chains ({domain})",
+        "",
+        "Your KB is not static — you read it back through GlyphSteer to get better:",
+        "",
+        "1. **Annotate** the KB with the legend (`glyphsteer.annotate_chunk`) so each note",
+        "   carries its grade facet lexically (the ASCII tag) and densely (the emoji direction).",
+        "2. **Steer** retrieval: when a new task arrives, `glyphsteer.search(con, task, facet=🏆)`",
+        "   surfaces your *best-graded* prior chains first — that is the `Recall` move made real.",
+        "   The markers steer the match and are stripped before you read (the HIDE invariant).",
+        "3. **Promote** — when a constructed chain earns 🏆 twice, FILE A GOLDENIZATION REQUEST",
+        "   (goldenreq) with the graded notes as evidence — never self-fold to golden; promotion",
+        "   happens only on an accepted verdict. Demote ❌ chains out of `Recall`.",
+        "4. **Loop** — this is your reward update: the KB + the legend ARE your bandit policy,",
+        "   improved by reading yourself. Re-run after every batch of tasks.",
+    ])
+
+
+@dataclass
+class BanditChainSystem:
+    """A rolled-up, CLOSED chain system for one domain — the bandit's output type.
+    Every field is (a path to) the one type, a skill dir, except `closed`/`report`."""
+    domain: str
+    ac: list[Path]
+    cor: Path
+    sc: Path
+    persona_dir: Path
+    tree_root: Path
+    closed: bool
+    report: dict = field(default_factory=dict)
+
+
+def _write_persona_aios(domain: str, persona: PersonaSpec, ac: list[Path], cor: Path,
+                        sc: Path, root: Path, *, selector: bool = True) -> Path:
+    """Write the domain-specific persona as an AIOS dir: CLAUDE.md (the persona) +
+    legend.json (the glyph vocab) + kb/ (its own knowledge base) + a skills/ pointer.
+    A persona IS a CLAUDE.md inside a dir — not a single SKILL.md.
+
+    `selector=True` = the default bandit (the ChainSelector); False = a custom
+    PersonaSpec CoR — same AIOS shape (KB + glyphsteer self-improvement), but the
+    role text and loop render from the persona's own moves."""
+    pdir = root / slugify(f"{domain}-bandit-persona" if selector
+                          else f"{domain}-{persona.name}-persona")
+    pdir.mkdir(parents=True, exist_ok=True)
+    (pdir / "kb").mkdir(exist_ok=True)
+
+    # the GlyphSteer legend this persona annotates its KB with (built-in GRADE vocab)
+    try:
+        from glyphsteer import GRADE
+        from glyphsteer.legend import save_legend
+        save_legend(GRADE, pdir / "legend.json")
+        legend_line = "Legend: `legend.json` (GlyphSteer GRADE vocabulary: 🏆 ✅ ⚠️ ❌)."
+    except Exception:  # glyphsteer not installed — the persona still stands
+        legend_line = "Legend: install `glyphsteer` to enable the grade vocabulary."
+
+    moves = " → ".join(m.name for m in persona.moves)
+    who = "the ChainSelector" if selector else "a chain-of-reasoning persona"
+    kind = "a bandit chain system" if selector else "a rolled-up chain system"
+    claude_md = "\n".join([
+        f"# {persona.name} — {kind} for `{domain}`",
+        "",
+        f"You are the **{persona.name}**: {who} ({moves}), specialized to the "
+        f"`{domain}` domain. {persona.blurb}.",
+        "",
+        "## Your closed algebra (the chains you were rolled up from)",
+        "",
+        "These three skill dirs are your minted, closed AC→CoR→SC algebra:",
+        "",
+        *[f"- **AC** (how to think): `{p.parent.name}`" for p in ac],
+        f"- **CoR** ({'the bandit, spoken' if selector else 'spoken — the melt-gauge'}): `{cor.parent.name}`",
+        f"- **SC** (the rollup): `{sc.parent.name}`",
+        "",
+        legend_line,
+        "",
+        kb_instructions(domain),
+        "",
+        glyphsteer_improve_instructions(domain),
+        "",
+        "## The loop",
+        "",
+        ("`Task → Recall (search your KB, 🏆-faceted) → Decide (select golden vs construct new) "
+         "→ Execute → Reward (grade it, write the KB note)` — then improve yourself by reading the KB back."
+         if selector else
+         f"`{moves}` — perform the moves in order on every task (the last move is your held "
+         "convergence; skipping or scrambling them = the persona is melting). Grade each run in "
+         "the KB, then improve yourself by reading the KB back."),
+    ])
+    (pdir / "CLAUDE.md").write_text(claude_md)
+    (pdir / "kb" / "README.md").write_text(
+        f"# {domain} KB\n\nThis persona's knowledge base. One note per topic, each headed "
+        f"with a `glyphs:` grade line. See `../CLAUDE.md` for the protocol.\n")
+    return pdir
+
+
+def roll_up_algebra(domain: str, atoms: list[str] | dict[str, str | tuple[str, str]],
+                    *, db: str, skills_dir: str,
+                    out_dir: str, blurb: str = "", persona_root: str | None = None,
+                    sequence: str | None = None,
+                    persona: PersonaSpec | None = None) -> BanditChainSystem:
+    """Mint a domain's AC(s) + CoR + SC, build its persona AIOS, and CLOSE it.
+
+    `atoms` = the attention-chain strings (the inner templates): a list (auto-named
+    `{domain}-attention[-N]`) or a dict `name -> atom` / `name -> (atom, description)`
+    to control the minted AC package names. The CoR defaults to the domain-specialized
+    BANDIT (not a flavor — the selector itself); pass `persona=` a custom `PersonaSpec`
+    to seat a domain CoR instead (e.g. an SDNA v2 profile's melt-gauge chain) — same
+    AIOS + KB + glyphsteer self-improvement, role text rendered from its moves.
+    Closure = every minted artifact is the one type AND the organizing SkillTree
+    validates.
+    """
+    from skilltree import SkillTree, TreeNode, materialize, validate
+
+    skills_dir = str(skills_dir)
+    # 1. AC(s) — accc forges + packages each atom into a skill dir
+    if isinstance(atoms, dict):
+        normalized = [(name, *(val if isinstance(val, tuple) else (val, None)))
+                      for name, val in atoms.items()]
+    else:
+        normalized = [((f"{domain}-attention" if len(atoms) == 1
+                        else f"{domain}-attention-{i+1}"), atom, None)
+                      for i, atom in enumerate(atoms)]
+    ac_paths: list[Path] = []
+    for name, atom, desc in normalized:
+        accc.forge(name, [atom], db=db)
+        ac_paths.append(Path(accc.package(name, atom, out_dir=skills_dir, description=desc)))
+
+    # 2. CoR — the domain-specialized bandit by default, or the supplied persona
+    selector = persona is None
+    persona = persona or domain_bandit(domain, blurb)
+    forged = corcc.forge_persona(persona, db=db)
+    cor = Path(corcc.package(forged, out_dir=skills_dir))
+
+    # 3. SC — roll the AC(s) + the bandit CoR up into one sequence (the closure op)
+    seq = sequence or (
+        " ⇒ ".join(f"[ac:{p.parent.name}]" for p in ac_paths)
+        + f" ⇒ [cor:{cor.parent.name}] ⇒ |{domain.capitalize()}|")
+    sccc.forge(domain, [seq], db=db)
+    sc = Path(sccc.package(domain, seq, out_dir=out_dir, skills_dir=skills_dir))
+
+    # 4. the domain-specific persona AIOS (CLAUDE.md + legend + KB + glyphsteer self-improve)
+    persona_dir = _write_persona_aios(
+        domain, persona, ac_paths, cor, sc, Path(persona_root or out_dir), selector=selector)
+
+    # 5. CLOSE — organize into a SkillTree and validate (the algebra closes ⇔ no violations)
+    tree = SkillTree(TreeNode(slugify(domain), "sc", description=f"{domain} — {persona.blurb}",
+        children=[TreeNode(slugify(persona.name), "cor", description=persona.blurb, children=[
+            TreeNode(slugify(p.parent.name), "ac", description=f"attend ({domain})") for p in ac_paths
+        ])]))
+    tree_root = Path(out_dir) / f"{slugify(domain)}-tree"
+    materialize(tree, tree_root)
+    violations = validate(tree_root)
+    minted_ok = all(p.exists() and p.name == "SKILL.md" for p in [*ac_paths, cor, sc])
+    closed = minted_ok and len(violations) == 0
+
+    return BanditChainSystem(
+        domain=domain, ac=ac_paths, cor=cor, sc=sc, persona_dir=persona_dir,
+        tree_root=tree_root, closed=closed,
+        report={"sequence": seq, "minted_ok": minted_ok, "violations": len(violations),
+                "moves": [m.name for m in persona.moves]})
+
+
+# ── the bandit's own composition (what it is MADE OF) ───────────────────────
+# Each entry: name -> (what that part IS, [its REAL operations as attention chains]).
+# The atoms decompose each component into its actual public moves, so the self-view
+# is genuinely granular: root → component → that component's operations.
+COMPONENTS: dict[str, tuple[str, list[str]]] = {
+    "accc":        ("attention chains — how to think; inner, silent templates", [
+                    "[Examples] ⇒ [Grammar] ⇒ |Forge|",
+                    "[AC] ⇒ [Grammar] ⇒ |Gate|",
+                    "[Language] ⇒ [Foci] ⇒ |Package|"]),
+    "corcc":       ("chains of reasoning — spoken, end in a decision", [
+                    "[PersonaSpec] ⇒ [InnerAC] ⇒ |ForgePersona|",
+                    "[CoRText] ⇒ [Moves] ⇒ |Lint|",
+                    "[Persona] ⇒ [Chain] ⇒ |Package|"]),
+    "sccc":        ("skill chains — sequence AC+CoR+skills into the closed composite", [
+                    "[Sequence] ⇒ [StepRefs] ⇒ |Parse|",
+                    "[Steps] ⇒ [Packages] ⇒ |Resolve|",
+                    "[Sequence] ⇒ [Rollup] ⇒ |Package|"]),
+    "glyphsteer":  ("dual-regime retrieval steering — glyph facets, hidden on return", [
+                    "[Chunk] ⇒ [Glyph] ⇒ |Annotate|",
+                    "[Chunks] ⇒ [FTS5] ⇒ |Index|",
+                    "[Query] ⇒ [Facet] ⇒ |Search|",
+                    "[Indexed] ⇒ [Clean] ⇒ |Hide|"]),
+    "skilltree":   ("progressive-disclosure tree of skill dirs (Read-breadcrumbs)", [
+                    "[Tree] ⇒ [Dirs] ⇒ |Materialize|",
+                    "[Root] ⇒ [Breadcrumbs] ⇒ |Validate|",
+                    "[Corpus] ⇒ [BM25] ⇒ |Search|"]),
+    "si":          ("self-interpreter — walk + execute the tree", [
+                    "[Root] ⇒ [Reachable] ⇒ |Walk|",
+                    "[Name] ⇒ [SkillMd] ⇒ |Read|",
+                    "[Source] ⇒ [Env] ⇒ |Interpret|"]),
+    "honeyc":      ("the compiler — a dense-rune chain rendered many ways", [
+                    "[Rune] ⇒ [AST] ⇒ |Parse|",
+                    "[AST] ⇒ [Statements] ⇒ |Normalize|",
+                    "[Statements] ⇒ [Lens] ⇒ |Render|"]),
+    "rulecatcher": ("the gate — learn a grammar, lint to ok/orthogonal/syntax_break", [
+                    "[Examples] ⇒ [Rules] ⇒ |Learn|",
+                    "[Text] ⇒ [Rules] ⇒ |Lint|",
+                    "[Violations] ⇒ [Verdict] ⇒ |Classify|"]),
+}
+
+
+@dataclass
+class SelfView:
+    """The bandit's granular view of itself: a closed chain system per component,
+    organized into one master SkillTree."""
+    systems: list[BanditChainSystem]
+    tree_root: Path
+    closed: bool
+    report: dict = field(default_factory=dict)
+
+
+def hierarchicalize(*, workdir: str | Path, components: dict | None = None) -> SelfView:
+    """Apply `roll_up_algebra` over everything the bandit is composed of — a closed
+    chain system per part — and assemble them into ONE master SkillTree: the bandit's
+    more-granular view of itself (the homoicon, the self-application)."""
+    from skilltree import SkillTree, TreeNode, materialize, validate
+
+    components = components or COMPONENTS
+    work = Path(workdir); work.mkdir(parents=True, exist_ok=True)
+    db = str(work / "self.db")
+    skills = work / "skills"; skills.mkdir(exist_ok=True)
+    dist = work / "dist"; dist.mkdir(exist_ok=True)
+    personas = work / "personas"; personas.mkdir(exist_ok=True)
+
+    systems: list[BanditChainSystem] = []
+    for name, (blurb, atoms) in components.items():
+        systems.append(roll_up_algebra(
+            name, atoms, db=db, skills_dir=str(skills), out_dir=str(dist),
+            blurb=blurb, persona_root=str(personas)))
+
+    # the master self-view: root "bandit-self" over each component's rolled-up system
+    master = SkillTree(TreeNode("bandit-self", "sc",
+        description="the bandit's granular view of its own composition", children=[
+            TreeNode(slugify(s.domain), "cor", description=components[s.domain][0],
+                     children=[TreeNode(slugify(p.parent.name), "ac",
+                                        description=f"attend ({s.domain})") for p in s.ac])
+            for s in systems]))
+    tree_root = work / "bandit-self-tree"
+    materialize(master, tree_root)
+    violations = validate(tree_root)
+    closed = all(s.closed for s in systems) and len(violations) == 0
+
+    return SelfView(systems=systems, tree_root=tree_root, closed=closed,
+                    report={"components": list(components), "violations": len(violations),
+                            "all_closed": all(s.closed for s in systems)})

chainaios-0.3.0/src/chainaios/cli.py

@@ -0,0 +1,214 @@
+"""cc — ChainCompiler. Construct a whole cognition-language for a domain."""
+from __future__ import annotations
+
+from pathlib import Path
+import tempfile
+
+import click
+
+from corcc.notation import Move, PersonaSpec
+
+from .construct import construct_language
+
+# A sample domain persona: triage an incident → decide severity.
+TRIAGE = PersonaSpec(
+    name="TriageIncident",
+    blurb="scope the blast radius, find the trigger, decide severity",
+    moves=(
+        Move("BlastRadius", ("who is affected", "scope", "how many")),
+        Move("Trigger", ("what changed", "trigger", "first seen")),
+        Move("Severity", ("severity", "sev", "decide", "priority")),
+    ),
+)
+
+
+@click.group()
+@click.version_option(message="cc %(version)s")
+def main() -> None:
+    """ChainCompiler — the umbrella over ACCC / CORCC / SCCC."""
+
+
+@main.command()
+def layers() -> None:
+    """Print the stack."""
+    click.echo("CC (ChainCompiler)")
+    click.echo("  ACCC  — attention template (how to think)        → SKILL.md")
+    click.echo("  CORCC — spoken reasoning that makes a decision    → SKILL.md  (HAS AC)")
+    click.echo("  SCCC  — chains AC + CoR + regular skills          → SKILL.md  (HAS CoR, AC, skills)")
+    click.echo("  each: catch grammar → LINT (syntax only) → compile .md → package <name>/SKILL.md")
+
+
+@main.command()
+def demo() -> None:
+    """Construct a brand-new domain language (AC + CoR + SC) in one call."""
+    with tempfile.TemporaryDirectory() as tmp:
+        bundle = construct_language(
+            "triage",
+            ac_chain="[Symptom] ⇒ [Scope] ⇒ [Change] ⇒ |Severity|",
+            cor_persona=TRIAGE,
+            db=str(Path(tmp) / "cc.db"),
+            skills_dir=str(Path(tmp) / "skills"),
+            out_dir=str(Path(tmp) / "dist"),
+        )
+        click.echo("══ CC.construct_language('triage') — minted a new cognition-language ══")
+        click.echo(f"  AC  → {bundle.ac.parent.name}/SKILL.md   (how to think)")
+        click.echo(f"  CoR → {bundle.cor.parent.name}/SKILL.md   (spoken reasoning → decision)")
+        click.echo(f"  SC  → {bundle.sc.parent.name}/SKILL.md   (chains AC + CoR)")
+        click.echo(f"\n  default sequence: {bundle.sequence}")
+        click.echo("\n  ── the SC rollup (publishable, auto-loadable by any agent) ──")
+        head = bundle.sc.read_text().splitlines()
+        click.echo("\n".join("  " + ln for ln in head[:14]))
+        click.echo("\n  A new domain language, pre-powered with AC + CoR by default. "
+                   "That is the bandit's 'construct-chain-language' move.")
+
+
+@main.command()
+@click.argument("prompt_file", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option("--out", "out_dir", default="dist", type=click.Path(path_type=Path),
+              help="output dir for the compiled <cogid>/ skill")
+def persona(prompt_file: Path, out_dir: Path) -> None:
+    """Compile a glyph-persona-program (e.g. BizziBee) → <cogid>/SKILL.md + legend.json.
+
+    Parses the three layers — [VarDefs] legend, ⚙️ workflow, [ROLE] wrapper — into the
+    artifacts the rest of ChainCompiler eats. Gates a legend chain via rulecatcher.
+    """
+    from chaincompiler.persona import compile_persona
+    res = compile_persona(prompt_file.read_text(encoding="utf-8"), out_dir)
+    click.echo(f"══ compiled persona '{res['name']}' ══")
+    click.echo(f"  legend : {res['axes']} glyph axes → {res['legend']}")
+    click.echo(f"  workflow: {res['steps']} ⚙️ steps")
+    click.echo(f"  skill  : {res['skill']}")
+    if res["gate"]:
+        click.echo(f"  gate   : chain {res['gate']['chain']} → {res['gate']['verdict']} (rulecatcher)")
+
+
+@main.group()
+def gba() -> None:
+    """General BanditAgent — a persistent AIOS dir an agent goes to and BECOMES."""
+
+
+@gba.command("new")
+@click.argument("domain")
+@click.argument("root", type=click.Path(path_type=Path))
+@click.option("--atom", "-a", "atoms", multiple=True, required=True,
+              help="an attention chain, e.g. -a '[Symptom] ⇒ [Scope] ⇒ |Severity|'")
+def gba_new(domain: str, root: Path, atoms: tuple[str, ...]) -> None:
+    """Emit a persistent GBA AIOS at ROOT (CLAUDE.md + live tree + index + kb)."""
+    from .gba import make_gba
+    g = make_gba(domain, root, atoms=list(atoms))
+    click.echo(f"══ GBA '{domain}' → {g.root} ══")
+    click.echo(f"  closed={g.closed}  ·  {g.report['indexed_skills']} skills indexed  ·  persona: CLAUDE.md")
+    click.echo(f"  become it: cd {g.root} and run an agent there.")
+
+
+@gba.command("construct")
+@click.argument("root", type=click.Path(exists=True, path_type=Path))
+@click.argument("name")
+@click.argument("atoms", nargs=-1, required=True)
+@click.option("--persona-json", type=click.Path(exists=True, path_type=Path), default=None,
+              help="JSON {name, blurb, moves:[{name, cues:[...]}]} — seat a bespoke CoR "
+                   "(the melt-gauge) instead of the default bandit. This is how a walked "
+                   "SDNA_Synth places a character with its OWN persona, not the selector.")
+def gba_construct(root: Path, name: str, atoms: tuple[str, ...],
+                  persona_json: Path | None) -> None:
+    """Mint a new chain system NAME into the GBA at ROOT (persists into the tree + re-indexes).
+
+    With --persona-json, the placed character gets a bespoke chain-of-reasoning seat (its own
+    melt-gauge) rather than the generic ChainSelector — the operational half of SDNA_Synth."""
+    import json as _json
+    from .gba import load_gba, construct_into
+    from corcc.notation import Move, PersonaSpec
+    persona = None
+    if persona_json is not None:
+        spec = _json.loads(Path(persona_json).read_text())
+        persona = PersonaSpec(name=spec["name"], blurb=spec.get("blurb", ""),
+                              moves=tuple(Move(m["name"], tuple(m.get("cues", [])))
+                                          for m in spec["moves"]))
+    g = load_gba(root)
+    sysd = construct_into(g, name, list(atoms), persona=persona)
+    seat = persona.name if persona else "bandit (default selector)"
+    click.echo(f"constructed '{name}' → {sysd.sc.parent.name}  (CoR seat: {seat}; "
+               f"{g.report['indexed_skills']} skills now)")
+
+
+@gba.command("search")
+@click.argument("root", type=click.Path(exists=True, path_type=Path))
+@click.argument("query")
+@click.option("--scope", "scope_coord", default=None,
+              help="restrict to a coordinate subtree, e.g. --scope 0.1 (where you are = what you see)")
+@click.option("--newest", "newest_only", is_flag=True, default=False,
+              help="forward only the newest version per logical skill (the self-expansion routing)")
+def gba_search(root: Path, query: str, scope_coord: str | None, newest_only: bool) -> None:
+    """Select's search half: BM25 over the GBA's live tree, optionally scoped + newest-version-routed."""
+    from .gba import load_gba, search
+    g = load_gba(root)
+    hits = search(g, query, scope_coord=scope_coord, newest_only=newest_only)
+    if not hits:
+        click.echo("  (no hits)")
+    for h in hits:
+        click.echo(f"  [{h.get('coord','') or '–'}] {h['name']:28s} — {h.get('description','')}")
+
+
+@gba.command("check")
+@click.argument("root", type=click.Path(exists=True, path_type=Path))
+def gba_check(root: Path) -> None:
+    """Re-check the GBA at ROOT is closed: its bodies present, its tree the manifest's and valid, no skill outside the
+    tree, its frontmatter parsing (exit 1 if not)."""
+    from .gba import check_gba
+    r = check_gba(root)
+    click.echo(f"closed={r['closed']}  ·  {r['skills']} skills  ·  {len(r['violations'])} violations  ·  "
+               f"{len(r['missing_sources'])} missing sources  ·  tree matches manifest={r['tree_matches_manifest']}  ·  "
+               f"{len(r['unlisted_skills'])} unlisted skills  ·  {len(r['unparsed_frontmatter'])} unparsed frontmatter")
+    for kind in ("violations", "missing_sources", "unlisted_skills", "unparsed_frontmatter"):
+        for item in r[kind]:
+            click.echo(f"  {kind}: {item}")
+    raise SystemExit(0 if r["closed"] else 1)
+
+
+@gba.command("hba")
+@click.argument("domain")
+@click.argument("root", type=click.Path(path_type=Path))
+@click.option("--atom", "-a", "atoms", multiple=True, required=True,
+              help="an attention chain for the HBA's tree")
+def gba_hba(domain: str, root: Path, atoms: tuple[str, ...]) -> None:
+    """Emit an HBA AIOS at ROOT: a GBA + select/construct seat subagents + the dispatch protocol."""
+    from .hba import make_hba
+    h = make_hba(domain, root, atoms=list(atoms))
+    click.echo(f"══ HBA '{domain}' → {h.root} ══")
+    click.echo(f"  seats (subagents): {', '.join(p.name for p in sorted(h.agents_dir.glob('*.md')))}")
+    click.echo(f"  dispatch protocol: .claude/rules/01-hba-dispatch.md  ·  base GBA tree + index")
+
+
+@main.group()
+def cog() -> None:
+    """COG — a Challenger·Observer·Generator whose three seats are each a GBA."""
+
+
+@cog.command("new")
+@click.argument("domain")
+@click.argument("root", type=click.Path(path_type=Path))
+@click.option("--atom", "-a", "atoms", multiple=True, required=True,
+              help="an attention chain for the Generator seat")
+def cog_new(domain: str, root: Path, atoms: tuple[str, ...]) -> None:
+    """Emit a COG AIOS at ROOT: the C→G→O flow skill + three role-AIOS seats (C/O/G) + a workspace."""
+    from .cog import make_cog
+    c = make_cog(domain, root, atoms=list(atoms))
+    click.echo(f"══ COG '{domain}' → {c.root}  (flow valid: {c.closed}) ══")
+    click.echo(f"  seats: ./C ./G ./O (each an AIOS you go to)  ·  shared: ./workspace")
+    click.echo(f"  flow : cat {c.flow.relative_to(c.root) if c.flow else '—'}  (the C→G→O workflow you walk)")
+
+
+@cog.command("flow")
+@click.argument("root", type=click.Path(exists=True, path_type=Path))
+def cog_flow(root: Path) -> None:
+    """Print the COG's default-workflow flow skill — the C→G→O flow you walk (it's a prompt, not a run)."""
+    from .cog import load_cog
+    c = load_cog(root)
+    if c.flow and c.flow.exists():
+        click.echo(c.flow.read_text())
+    else:
+        click.echo("(no flow skill found — re-run `cog new`)")
+
+
+if __name__ == "__main__":
+    main()