super-skill-cli 0.9.2__py3-none-any.whl

super_skill/__init__.py

@@ -0,0 +1,9 @@
+"""super-skill: personal Agent-Skill package manager (M0+WS scope).
+
+v1 is the package-manager form the GATE-1 measurement supports: a git-backed,
+versioned skill registry with seed import, explain, and rollback. The
+self-learning loop (M2-M5) is deferred to a research track until candidate
+opportunity flow is proven real. See docs/03-development-plan.md.
+"""
+
+__version__ = "0.1.0"

super_skill/candidate.py

@@ -0,0 +1,213 @@
+"""Candidate approval loop (WS second half, docs/03: mine -> draft -> approve).
+
+A *candidate* is a proposed skill drafted from a mined OpportunityFamily. It is
+pre-promotion scratch: it lives under ``candidates/`` (git-ignored by the
+registry) and is human-editable. Nothing reaches the production skill set until
+``approve`` — the single write path that runs ``registry.add_version`` +
+``materialize`` (git commit + copy to host). This preserves the One Writer Rule:
+candidate -> gate (human approve) -> promote, never bypassed.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from . import config
+from .evallite import EvalError, eval_lite
+from .gate import InstructionGateError, scan_skill_md
+from .mine import OpportunityFamily
+from .registry import Registry
+from .schemas import (
+    CandidateType,
+    Provenance,
+    ProvenanceKind,
+    SkillStatus,
+    SkillVersion,
+    utcnow,
+)
+from .skillmd import parse
+
+_SLUG_RE = re.compile(r"[^a-z0-9]+")
+
+
+def slugify(label: str) -> str:
+    """Reduce a family label to an agentskills.io-legal skill name (may be empty;
+    callers skip empties). Matches NAME_RE: lowercase alnum + single hyphens."""
+    return _SLUG_RE.sub("-", label.lower()).strip("-")[:64].strip("-")
+
+
+class CandidateError(RuntimeError):
+    pass
+
+
+class Candidate(BaseModel):
+    """Persisted metadata for one drafted candidate (SKILL.md stored alongside)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    candidate_id: str
+    family_label: str
+    session_count: int
+    event_count: int
+    projects: list[str] = Field(default_factory=list)
+    status: str = "pending"  # pending | approved | rejected
+    skill_id: str | None = None
+    version: str | None = None
+    created_at: datetime = Field(default_factory=utcnow)
+
+
+def _draft_md(cand_id: str, fam: OpportunityFamily) -> str:
+    """A stub SKILL.md the human is expected to edit before approving. WS coarse
+    mining can name a recurring family, not write its procedure — so we scaffold
+    honestly and leave TODOs rather than fabricate steps."""
+    return (
+        f"---\n"
+        f"name: {cand_id}\n"
+        f'description: Recurring workflow around "{fam.label}" '
+        f"(seen in {fam.session_count} sessions). EDIT before approving.\n"
+        f"---\n"
+        f"# {fam.label}\n\n"
+        f"<!-- WS draft mined from {fam.session_count} sessions"
+        f"{f', {len(fam.projects)} projects' if fam.projects else ''}. "
+        f"Replace the TODOs with the real reusable procedure, then `candidate approve`. -->\n\n"
+        f"## When to use\n\n"
+        f"TODO: the trigger you hit repeatedly.\n\n"
+        f"## Steps\n\n"
+        f"TODO: the procedure you re-derived each time.\n"
+    )
+
+
+class CandidateStore:
+    """Filesystem store for draft candidates under ``<root>/candidates/<id>/``."""
+
+    def __init__(self, root: Path | None = None) -> None:
+        self.root = root or config.state_root()
+        self.dir = self.root / "candidates"
+
+    def _cdir(self, cand_id: str) -> Path:
+        return self.dir / cand_id
+
+    def get(self, cand_id: str) -> Candidate | None:
+        meta = self._cdir(cand_id) / "candidate.json"
+        if not meta.exists():
+            return None
+        return Candidate.model_validate_json(meta.read_text(encoding="utf-8"))
+
+    def list(self) -> list[Candidate]:
+        if not self.dir.exists():
+            return []
+        out = [self.get(d.name) for d in sorted(self.dir.iterdir()) if d.is_dir()]
+        return [c for c in out if c is not None]
+
+    def skill_md(self, cand_id: str) -> str:
+        md = self._cdir(cand_id) / "SKILL.md"
+        if not md.exists():
+            raise CandidateError(f"candidate {cand_id!r} has no SKILL.md")
+        return md.read_text(encoding="utf-8")
+
+    def write_skill_md(self, cand_id: str, raw: str) -> None:
+        self._cdir(cand_id).mkdir(parents=True, exist_ok=True)
+        (self._cdir(cand_id) / "SKILL.md").write_text(raw, encoding="utf-8")
+
+    def save(self, cand: Candidate) -> None:
+        cdir = self._cdir(cand.candidate_id)
+        cdir.mkdir(parents=True, exist_ok=True)
+        (cdir / "candidate.json").write_text(
+            cand.model_dump_json(indent=2), encoding="utf-8"
+        )
+
+
+def draft_from_families(
+    store: CandidateStore, families: list[OpportunityFamily]
+) -> list[Candidate]:
+    """Create one pending candidate per new family (idempotent by slug). Families
+    whose label yields no legal slug are skipped."""
+    created: list[Candidate] = []
+    for fam in families:
+        cand_id = slugify(fam.label)
+        if not cand_id or store.get(cand_id) is not None:
+            continue
+        cand = Candidate(
+            candidate_id=cand_id,
+            family_label=fam.label,
+            session_count=fam.session_count,
+            event_count=fam.event_count,
+            projects=sorted(fam.projects),
+        )
+        store.write_skill_md(cand_id, _draft_md(cand_id, fam))
+        store.save(cand)
+        created.append(cand)
+    return created
+
+
+def approve(
+    store: CandidateStore,
+    reg: Registry,
+    cand_id: str,
+    host_dir: Path,
+    *,
+    actor: str = "user",
+    reason: str | None = None,
+) -> SkillVersion:
+    """Promote a candidate into the registry and materialize it to the host.
+
+    The single write path (One Writer Rule): parses the current — possibly
+    human-edited — SKILL.md, registers an immutable ACTIVE version, copies it to
+    the host skills dir, and marks the candidate approved. Raises before any
+    write if the candidate is unknown or already approved."""
+    cand = store.get(cand_id)
+    if cand is None:
+        raise CandidateError(f"unknown candidate: {cand_id}")
+    if cand.status == "approved":
+        raise CandidateError(f"candidate {cand_id!r} already approved")
+
+    raw = store.skill_md(cand_id)
+    # Instruction-layer adversarial gate (docs/04 §2.4bis): v1's only mandatory
+    # security gate. Runs BEFORE any write — a blocked candidate never reaches
+    # the registry or the host. Captured content is untrusted; auto-approval
+    # never bypasses this (there is no auto-approval, but the invariant holds).
+    findings = scan_skill_md(raw)
+    if findings:
+        raise InstructionGateError(findings)
+    # Deterministic eval-lite hard gate (docs/04 §1.6): schema, zero secret leak,
+    # token budget. The No Skill/Skill two-arm is Insufficient Evidence at WS.
+    report = eval_lite(raw)
+    if not report.passed:
+        raise EvalError(report)
+    skill_id = parse(raw).frontmatter.name  # frontmatter name is authoritative
+    reg.init()
+    prov = [
+        Provenance(
+            kind=ProvenanceKind.CAPTURED_SESSION,
+            origin=f"mined:{cand.family_label} ({cand.session_count} sessions)",
+        )
+    ]
+    sv = reg.add_version(
+        skill_id,
+        raw,
+        CandidateType.CAPTURED,
+        prov,
+        status=SkillStatus.ACTIVE,
+        actor=actor,
+        reason=reason or f"approve candidate {cand_id}",
+    )
+    reg.materialize(skill_id, host_dir)
+
+    cand.status = "approved"
+    cand.skill_id = skill_id
+    cand.version = sv.version
+    store.save(cand)
+    return sv
+
+
+def reject(store: CandidateStore, cand_id: str) -> Candidate:
+    cand = store.get(cand_id)
+    if cand is None:
+        raise CandidateError(f"unknown candidate: {cand_id}")
+    cand.status = "rejected"
+    store.save(cand)
+    return cand

super_skill/capture.py

@@ -0,0 +1,76 @@
+"""Append-only JSONL event WAL (docs/01 FR-CAP-1, WS form).
+
+Every event is redacted before it is written (capture.append never persists a raw
+payload), then appended as one JSON line under events/<date>/events.jsonl. Raw
+events are TTL-bounded (FR-CAP-6); structured products live elsewhere.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Iterator
+from pathlib import Path
+
+from . import config
+from .redact import redact_payload, redact_text
+from .schemas import CaptureEvent, EventType
+
+
+class EventLog:
+    def __init__(self, root: Path | None = None) -> None:
+        self.root = root or config.state_root()
+        self.events_dir = self.root / "events"
+
+    def _new_id(self) -> str:
+        return uuid.uuid4().hex
+
+    def append(
+        self,
+        event_type: EventType,
+        session_id: str,
+        payload: dict[str, object],
+        *,
+        project_id: str | None = None,
+        event_id: str | None = None,
+        consent_scope: str = "default",
+    ) -> CaptureEvent:
+        """Redact then append. Returns the persisted (redacted) event.
+
+        Every field that can carry private content — the payload AND the
+        project_id (derived from cwd, often a home path) — is redacted here so
+        nothing raw reaches disk (FR-CAP-2, §8 SAFETY)."""
+        red_payload, marks = redact_payload(payload)
+        red_project = redact_text(project_id)[0] if project_id else None
+        event = CaptureEvent(
+            event_id=event_id or self._new_id(),
+            session_id=session_id,
+            event_type=event_type,
+            project_id=red_project,
+            payload=red_payload,
+            redactions=marks,
+            consent_scope=consent_scope,
+        )
+        day = event.timestamp.strftime("%Y-%m-%d")
+        out = self.events_dir / day / "events.jsonl"
+        out.parent.mkdir(parents=True, exist_ok=True)
+        with out.open("a", encoding="utf-8") as f:
+            f.write(event.model_dump_json() + "\n")
+        return event
+
+    def iter_events(self) -> Iterator[CaptureEvent]:
+        if not self.events_dir.exists():
+            return
+        for day in sorted(self.events_dir.iterdir()):
+            wal = day / "events.jsonl"
+            if not wal.exists():
+                continue
+            for line in wal.read_text(encoding="utf-8").splitlines():
+                line = line.strip()
+                if line:
+                    yield CaptureEvent.model_validate_json(line)
+
+    def count(self) -> int:
+        return sum(1 for _ in self.iter_events())
+
+    def distinct_sessions(self) -> int:
+        return len({ev.session_id for ev in self.iter_events()})

super_skill/cli.py

@@ -0,0 +1,381 @@
+"""super-skill CLI (WS P0 subset, docs/01 FR-IF-1): seed / status / list / show /
+explain / rollback. The self-learning commands (sleep, distill, candidate-eval)
+arrive only if the GATE opens the M2-M5 research track."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import typer
+
+from . import config, minestate
+from .candidate import CandidateError, CandidateStore, approve, draft_from_families, reject
+from .capture import EventLog
+from .doctor import check_registry, repair
+from .evallite import EvalError, eval_lite
+from .gate import InstructionGateError, scan_skill_md
+from .hooks import hooks_settings
+from .mine import mine_families
+from .registry import Registry, RegistryError
+from .schemas import EventType, OperationType
+from .seed import seed_from_host
+from .skillmd import SkillMdError
+
+app = typer.Typer(add_completion=False, help="Personal Agent-Skill package manager.")
+candidate_app = typer.Typer(help="Draft / review / approve skill candidates (mine -> approve).")
+app.add_typer(candidate_app, name="candidate")
+
+
+def _registry() -> Registry:
+    return Registry(root=config.state_root())
+
+
+def _short(text: str, n: int = 60) -> str:
+    text = " ".join(text.split())
+    return text if len(text) <= n else text[: n - 1] + "…"
+
+
+@app.command()
+def seed() -> None:
+    """Import existing host skills into the registry (idempotent, read-only on host)."""
+    reg = _registry()
+    report = seed_from_host(reg, config.host_skills_dir())
+    typer.echo(
+        f"seed: {len(report.imported)} imported, {len(report.updated)} updated, "
+        f"{len(report.unchanged)} unchanged, {len(report.skipped)} skipped "
+        f"(host={config.host_skills_dir()})"
+    )
+    for name, reason in report.skipped:
+        typer.echo(f"  skipped {name}: {reason}")
+
+
+@app.command()
+def capture(
+    event_type: str = typer.Option("", "--event-type", help="override hook_event_name"),
+) -> None:
+    """Append a host hook event (JSON on stdin) to the WAL, redacted.
+
+    Designed to be called from a Claude Code hook. Never fails the session
+    (NFR-3): malformed input or an unknown event type exits 0 without writing.
+    """
+    try:
+        raw = sys.stdin.read()
+        data = json.loads(raw) if raw.strip() else {}
+    except (json.JSONDecodeError, OSError):
+        raise typer.Exit(0) from None
+    name = event_type or str(data.get("hook_event_name", ""))
+    try:
+        etype = EventType(name)
+    except ValueError:
+        raise typer.Exit(0) from None
+    session_id = str(data.get("session_id", "unknown"))
+    project_id = data.get("cwd")
+    EventLog().append(
+        etype, session_id, data, project_id=str(project_id) if project_id else None
+    )
+
+
+@app.command()
+def mine(min_sessions: int = typer.Option(3, "--min-sessions")) -> None:
+    """Surface recurring task families from captured events (FR-GEN-1 signal)."""
+    log = EventLog()
+    families = mine_families(log.iter_events(), min_sessions=min_sessions)
+    distinct = log.distinct_sessions()
+    if not families:
+        typer.echo(
+            f"no families recurring across >={min_sessions} sessions yet "
+            f"({distinct} distinct sessions captured)"
+        )
+    else:
+        typer.echo(f"{'sessions':>8}  {'events':>6}  family")
+        for fam in families:
+            typer.echo(f"{fam.session_count:>8}  {fam.event_count:>6}  {fam.label}")
+    # Mining acknowledges the accumulated sessions: reset the reminder watermark.
+    minestate.record_mined(log.root, distinct)
+
+
+@app.command()
+def status() -> None:
+    """Registry summary: location, git head, skill/version/candidate counts."""
+    reg = _registry()
+    records = reg.list_skills()
+    active = sum(1 for r in records if r.skill.active_version)
+    versions = sum(len(r.versions) for r in records)
+    cands = CandidateStore(reg.root).list()
+    by_status: dict[str, int] = {}
+    for c in cands:
+        by_status[c.status] = by_status.get(c.status, 0) + 1
+    breakdown = ", ".join(f"{n} {s}" for s, n in sorted(by_status.items())) or "none"
+    typer.echo(f"state root : {reg.root}")
+    typer.echo(f"git head   : {reg.head()}")
+    typer.echo(f"skills     : {len(records)} ({active} active)")
+    typer.echo(f"versions   : {versions}")
+    log = EventLog(reg.root)
+    typer.echo(f"events     : {log.count()}")
+    typer.echo(f"candidates : {len(cands)} ({breakdown})")
+    unmined = minestate.unmined(reg.root, log.distinct_sessions())
+    if unmined >= minestate.reminder_threshold():
+        typer.echo(f"reminder   : {unmined} distinct sessions unmined "
+                   f"— run `super-skill mine`")
+
+
+@app.command("list")
+def list_() -> None:
+    """List registered skills plus any pending candidates awaiting approval."""
+    reg = _registry()
+    records = reg.list_skills()
+    if not records:
+        typer.echo("no skills registered — run `super-skill seed`")
+    for r in records:
+        av = r.active
+        ver = r.skill.active_version or "-"
+        desc = _short(av.frontmatter.description) if av else ""
+        typer.echo(f"{r.skill.skill_id:<32} {ver:<5} {desc}")
+
+    pending = [c for c in CandidateStore(reg.root).list() if c.status == "pending"]
+    if pending:
+        typer.echo(f"\npending candidates ({len(pending)}) — review with `candidate show <id>`:")
+        for c in pending:
+            typer.echo(f"  {c.candidate_id:<30} {c.session_count} sessions  {c.family_label}")
+
+
+@app.command()
+def show(skill_id: str) -> None:
+    """Show a skill's frontmatter, version history and provenance."""
+    reg = _registry()
+    rec = reg.get(skill_id)
+    if rec is None:
+        typer.echo(f"unknown skill: {skill_id}", err=True)
+        raise typer.Exit(1)
+    av = rec.active
+    typer.echo(f"skill      : {rec.skill.skill_id} (scope={rec.skill.scope})")
+    typer.echo(f"active     : {rec.skill.active_version}")
+    if av:
+        typer.echo(f"description: {av.frontmatter.description}")
+        typer.echo(f"hash       : {av.artifact_hash}")
+    typer.echo("versions   :")
+    for ver, sv in rec.versions.items():
+        mark = "*" if ver == rec.skill.active_version else " "
+        typer.echo(f"  {mark} {ver:<5} {sv.candidate_type:<11} {sv.status}")
+
+
+@app.command()
+def explain(skill_id: str) -> None:
+    """FR-IF-5: why this skill exists, where it came from, and how to roll it back."""
+    reg = _registry()
+    rec = reg.get(skill_id)
+    if rec is None:
+        typer.echo(f"unknown skill: {skill_id}", err=True)
+        raise typer.Exit(1)
+    typer.echo(f"# {rec.skill.skill_id}")
+    for sv in rec.versions.values():
+        origins = ", ".join(f"{p.kind}:{p.origin}" for p in sv.provenance) or "(none)"
+        typer.echo(f"{sv.version} [{sv.candidate_type}] from {origins}")
+    typer.echo("\naudit:")
+    for ev in rec.audit:
+        detail = f" ({ev.reason})" if ev.reason else ""
+        typer.echo(f"  {ev.created_at:%Y-%m-%d %H:%M} {ev.op} {ev.from_version}->{ev.to_version}"
+                   f" by {ev.actor}{detail}")
+    versions = list(rec.versions)
+    active = rec.skill.active_version
+    if active and versions.index(active) > 0:
+        prev = versions[versions.index(active) - 1]
+        typer.echo(f"\nrollback : super-skill rollback {skill_id} --to {prev}")
+
+
+@app.command()
+def rollback(
+    skill_id: str,
+    to: str = typer.Option("", "--to", help="target version; default = previous"),
+    reason: str = typer.Option("", "--reason"),
+) -> None:
+    """Switch the active pointer to an older version and re-materialize to the host."""
+    reg = _registry()
+    rec = reg.get(skill_id)
+    if rec is None:
+        typer.echo(f"unknown skill: {skill_id}", err=True)
+        raise typer.Exit(1)
+    versions = list(rec.versions)
+    if not to:
+        idx = versions.index(rec.skill.active_version) if rec.skill.active_version else 0
+        if idx <= 0:
+            typer.echo("no previous version to roll back to", err=True)
+            raise typer.Exit(1)
+        to = versions[idx - 1]
+    try:
+        reg.set_active(skill_id, to, op=OperationType.ROLLBACK, reason=reason or None)
+        dest = reg.materialize(skill_id, config.host_skills_dir())
+    except RegistryError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(1) from e
+    typer.echo(f"rolled back {skill_id} -> {to}; materialized {dest}")
+
+
+@app.command()
+def doctor(
+    fix: bool = typer.Option(False, "--fix", help="restore tampered/missing versions from git "
+                             "and re-materialize host drift, then re-verify"),
+) -> None:
+    """Check registry integrity: hashes, pointers, host sync.
+
+    Read-only by default; exits 1 if any integrity error is found. With --fix it
+    restores git-recoverable versions and re-materializes host drift, then
+    re-verifies — exit status reflects what remains, not what was attempted.
+    Dangling pointers / name mismatches need judgment and are left to you."""
+    reg = _registry()
+    host = config.host_skills_dir()
+
+    if fix:
+        actions, remaining = repair(reg, host)
+        for a in actions:
+            mark = "✓" if a.ok else "✗"
+            typer.echo(f"  {mark} {a.issue.skill_id}: {a.action}")
+        if not actions:
+            typer.echo("doctor --fix: nothing mechanically fixable")
+        errors = [i for i in remaining if i.severity == "error"]
+        for i in remaining:
+            m = "✗" if i.severity == "error" else "!"
+            typer.echo(f"  {m} [{i.severity}] {i.skill_id}: {i.message} (needs manual fix)")
+        typer.echo(
+            f"doctor --fix: {len(actions)} action(s); "
+            f"{len(errors)} error(s) remain, {len(remaining) - len(errors)} warning(s)"
+        )
+        if errors:
+            raise typer.Exit(1)
+        return
+
+    issues = check_registry(reg, host)
+    if not issues:
+        typer.echo("doctor: OK — registry consistent, host in sync")
+        return
+    errors = [i for i in issues if i.severity == "error"]
+    for i in issues:
+        mark = "✗" if i.severity == "error" else "!"
+        typer.echo(f"  {mark} [{i.severity}] {i.skill_id}: {i.message}")
+    typer.echo(f"doctor: {len(errors)} error(s), {len(issues) - len(errors)} warning(s)")
+    if errors:
+        raise typer.Exit(1)
+
+
+@app.command("hooks-config")
+def hooks_config(
+    command: str = typer.Option("super-skill capture", "--command", help="capture invocation"),
+) -> None:
+    """Print the settings.json hooks block that feeds real sessions to capture.
+
+    Prints only — merge it into ~/.claude/settings.json yourself (editing
+    user-global config is your call, not the tool's)."""
+    typer.echo(json.dumps(hooks_settings(command), indent=2))
+    typer.echo(
+        "\n# merge the above into ~/.claude/settings.json (or a project .claude/settings.json)",
+        err=True,
+    )
+
+
+@candidate_app.command("draft")
+def candidate_draft(min_sessions: int = typer.Option(3, "--min-sessions")) -> None:
+    """Draft skill candidates from mined families (idempotent, pre-promotion)."""
+    log = EventLog()
+    families = mine_families(log.iter_events(), min_sessions=min_sessions)
+    store = CandidateStore(config.state_root())
+    created = draft_from_families(store, families)
+    # Drafting acts on the mining, so it too clears the status reminder.
+    minestate.record_mined(log.root, log.distinct_sessions())
+    if not created:
+        typer.echo("no new candidates (nothing mined, or all already drafted)")
+        return
+    typer.echo(f"drafted {len(created)} candidate(s):")
+    for c in created:
+        typer.echo(f"  {c.candidate_id:<32} {c.session_count} sessions — edit then approve")
+
+
+@candidate_app.command("list")
+def candidate_list() -> None:
+    """List drafted candidates and their status."""
+    cands = CandidateStore(config.state_root()).list()
+    if not cands:
+        typer.echo("no candidates — run `super-skill candidate draft`")
+        return
+    for c in cands:
+        typer.echo(
+            f"{c.candidate_id:<32} {c.status:<9} "
+            f"{c.session_count} sessions  {c.family_label}"
+        )
+
+
+@candidate_app.command("show")
+def candidate_show(candidate_id: str) -> None:
+    """Show a candidate's metadata and drafted SKILL.md."""
+    store = CandidateStore(config.state_root())
+    cand = store.get(candidate_id)
+    if cand is None:
+        typer.echo(f"unknown candidate: {candidate_id}", err=True)
+        raise typer.Exit(1)
+    typer.echo(f"candidate  : {cand.candidate_id} ({cand.status})")
+    typer.echo(f"family     : {cand.family_label}")
+    typer.echo(f"recurrence : {cand.session_count} sessions, {cand.event_count} events")
+    if cand.version:
+        typer.echo(f"promoted   : {cand.skill_id}@{cand.version}")
+    raw = store.skill_md(candidate_id)
+    findings = scan_skill_md(raw)
+    if findings:
+        typer.echo(f"gate       : {len(findings)} finding(s) — approve will be BLOCKED:")
+        for f in findings:
+            typer.echo(f"  ! {f.category} in {f.location}: {f.snippet}")
+    else:
+        typer.echo("gate       : clean (no injection patterns)")
+    report = eval_lite(raw)
+    ev = "pass" if report.passed else "FAIL"
+    typer.echo(f"eval-lite  : {ev} ({'; '.join(f'{c.name}={c.detail}' for c in report.checks)})")
+    if report.insufficient_evidence:
+        typer.echo("           : two-arm (No Skill/Skill) = Insufficient Evidence — human accept")
+    typer.echo("--- SKILL.md ---")
+    typer.echo(raw)
+
+
+@candidate_app.command("approve")
+def candidate_approve(
+    candidate_id: str,
+    reason: str = typer.Option("", "--reason"),
+) -> None:
+    """Approve a candidate: promote to the registry and materialize to the host."""
+    store = CandidateStore(config.state_root())
+    reg = _registry()
+    try:
+        sv = approve(store, reg, candidate_id, config.host_skills_dir(), reason=reason or None)
+    except InstructionGateError as e:
+        typer.echo(str(e), err=True)
+        for f in e.findings:
+            typer.echo(f"  ! {f.category} in {f.location}: {f.snippet}", err=True)
+        typer.echo("edit the candidate's SKILL.md to remove the flagged text, then re-approve.",
+                   err=True)
+        raise typer.Exit(1) from e
+    except EvalError as e:
+        typer.echo(str(e), err=True)
+        for c in e.report.failures():
+            typer.echo(f"  ! {c.name}: {c.detail}", err=True)
+        raise typer.Exit(1) from e
+    except (CandidateError, RegistryError, SkillMdError) as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(1) from e
+    typer.echo(
+        f"approved {candidate_id} -> {sv.skill_id}@{sv.version}; "
+        f"materialized to {config.host_skills_dir() / sv.skill_id}"
+    )
+
+
+@candidate_app.command("reject")
+def candidate_reject(candidate_id: str) -> None:
+    """Mark a candidate rejected (leaves it on disk for the record)."""
+    store = CandidateStore(config.state_root())
+    try:
+        reject(store, candidate_id)
+    except CandidateError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(1) from e
+    typer.echo(f"rejected {candidate_id}")
+
+
+if __name__ == "__main__":
+    app()