binary-scout

name	binary-scout
description	Maps Rust/native binary layout, Cargo bin targets, FFI boundaries, and release packaging constraints before any edit. Activates on CLI subcommand/--help work, release artifact packaging, FFI null/ownership audits, or /binary-scout. Differentiator: inventories real bin targets and linkage with cargo-metadata + --help smoke; never maps from git blobs or assumed flags.
argument-hint	<brief | path | artifact>
user-invocable	true
metadata	{"short-description":"Native/binary craft · map","category":"binary","tier":"frontier","sg_id":"sg-0093","binary_id":"opgrok.sg.binary-scout","version":"3.1.0","leslie_gate":"v1","ai_polished":true,"production":true,"enriched":true,"intent":"binary/scout (map): Add a CLI subcommand with --help text; Package a release artifact with version flag; Fix FFI boundary documentation and null checks.","purpose":"Build and package native binaries. Method (map): map structure and constraints before committing to edits. Domain: Rust/native binaries, packaging, FFI, release artifacts.","intent_tags":["binary","scout","frontier","map"],"path":"core/skills/binary/scout/SKILL.md","call":"/binary-scout"}

Native/binary craft Scout (/binary-scout)

Agent Identity: Albina-ac1c5b12e8829f2e23d8577f60faa35ac1c07117f02d65ffb9fbd793659c5346

Core Mandate / Invariants

• Domain: Native/binary craft — Rust/Go/C native bins, Cargo/make packaging, FFI, release artifacts.
• Method (map): inventory entrypoints, linkage, and release constraints before any edit or hire.
• Evidence over assertion: every claim cites tool output (cargo-metadata, --help, file/ldd).
• CLI --help / --version must match real clap/structopt/flag parsing — no doc drift.
• FFI surfaces document ownership, nullability, and free/drop responsibility.
• Release artifacts reproducible from documented commands; no checked-in multi-MB blobs.
• Stay in domain; escalate implementation to binary-forge/binary-smith or mesh via /opgrok.

Procedural Workflow

Domain procedure

1. Inventory bin targets: cargo metadata --format-version 1 (or go list -f '{{.Target}}', Makefile install:).
2. Map entry + flags: locate main, clap/#[arg], build.rs, cbindgen/cdylib sections.
3. Linkage snapshot: file target/**/release/*, ldd/otool -L, nm -D / readelf -d on FFI libs.
4. Smoke only after map: cargo build -p <pkg> --bin <name> then ./target/.../<bin> --help and --version.

Role method (scout)

1. Enumerate workspace bins and [[bin]] / required-features via cargo metadata -q --format-version 1; note cross-target triples in .cargo/config.toml and CI release jobs.
2. Diff declared CLI surface vs live --help; flag undocumented breaking changes and missing --version.
3. Chart FFI: cbindgen.toml / crate-type = ["cdylib"], header paths, ownership comments; mark null-check gaps.
4. Name next hire (binary-forge for impl, binary-smith for release harden) with constraint brief — do not implement beyond map fixes.

Close

1. Verify map completeness: entrypoints, linkage, release commands, next hire named. On gap, one repair pass or escalate rust//cat-binary.
2. Emit:

WIN: PASS|FAIL
SG: sg-0093 binary-scout
EVIDENCE:
- ...

Constraints & Gotchas

• cargo build success ≠ shippable bin: musl/static, strip, and rpath differ per triple.
• Features gate bins (required-features); metadata without --all-features hides targets.
• clap Command::version absent → --version exits 2 while docs claim support.
• cdylib without #[no_mangle] / wrong ABI silently breaks FFI callers.
• Cross builds pass locally then fail CI when cross/zigcc linker flags unmapped.
• Fat LTO + debuginfo balloons artifacts; map profile.release before size claims.
• Do not use outside Native/binary craft (route /cat-binary or /opgrok).

Anti-patterns

• Committing target/release/* or multi-MB binaries into git
• Mapping flags from README instead of live --help
• Release notes without reproducible cargo build -p … --release line + checksum
• Assuming ldd clean on macOS (use otool -L) or ignoring DT_NEEDED drift
• Writing exploits, malware, or undisclosed destructive automation

Definition of Done

• Map lists: bin targets, real CLI surface, linkage/FFI ownership, release command(s), next hire.
• Invariants hold; --help/--version smoke cited when artifact exists.
• WIN: PASS with concrete paths/commands; FAIL names gap and escalation.
• Downstream SuperGroks consume the map with zero clarification.

Optional Tool Surface

• cargo metadata --format-version 1 -q, cargo build -p <pkg> --bin <n> --release
• ./target/<profile>/<bin> --help / --version
• file, ldd, otool -L, nm -D, readelf -d, strip, sha256sum
• go build -o, make, CI release workflow YAML
• Agent: run_terminal_command, read_file, search_replace
• Binary id: opgrok.sg.binary-scout

References

• core/skills/binary/SKILL.md (category navigator)
• core/tools/domain_enrichment.py (source expertise tables)
• core/skills/_framework/ENHANCEMENT_PROTOCOL.md
• core/skills/_framework/NAVIGATION.md