linc-crucible

Quality gates for mobile apps, answering one question: is this app ready to ship? crucible builds an Android (Gradle) or iOS (xcodebuild) app and deploys it to devices through linc-nerve, runs your lint and tests and folds them into a 7-dimension quality score with a ship gate at 85, checks app-store readiness (5 dimensions, threshold 80%), runs YAML build-verification tests (BVT) against visual and accessibility-tree baselines, and pulls ranked marketing screenshots out of a screen recording. It is one layer of a 4-layer stack: linc-device-kit (shared models) → linc-nerve (device I/O) → linc-crucible (quality). crucible itself contains no device code; everything that touches a device goes through the nerve daemon's HTTP API.

8 MCP tools | Python 3.13+ | Android + iOS

Install

Requires Python 3.13+ (python3 --version); with pipx/uv, --python 3.13.

• pipx install linc-crucible (or pipx install --python 3.13 linc-crucible)
• uv tool install linc-crucible (or uv tool install --python 3.13 linc-crucible)
• pip install linc-crucible (inside a virtual environment)

AI-ranked frame picks need the unpublished linc-ai package; without it crucible_extract_assets uses evenly-spaced frames and reports fallback_used: true.

Project setup

crucible discovers projects by scanning $LINC_PROJECTS_DIR/*/linc-manifest.yaml (default ~/projects/*/linc-manifest.yaml). Two files live in the project root:

• linc-manifest.yaml — identity. identity.name is the project name every command takes; identity.package is the Android applicationId / iOS bundle ID.
• .forge.yaml — holds the build/test/lint commands; the name is historical. Commands in .forge.yaml run from the project root, so the ./gradlew example below requires a Gradle wrapper (./gradlew) in that directory. When neither lint_command nor test_command runs to a measurement (nothing measured), crucible assay reports "status": "unmeasured" and exits 1.

# ~/projects/myapp/linc-manifest.yaml
schema_version: 1
identity:
  name: myapp
  package: com.example.myapp

# ~/projects/myapp/.forge.yaml
forge:
  build_command: "./gradlew :app:assembleDebug"
  test_command: "./gradlew test"
  lint_command: "./gradlew lint"

For crucible preflight --project myapp, place store metadata in <project>/store/:

• <project>/store/store-listing.md — markdown with headings # Title, # Short Description, # Full Description, # Keywords, # Category.
• <project>/store/brand-brief.json — JSON object with required fields app_name, tagline, emotion, primary_color, accent_color, background_color, icon_concept, style, platforms.

Apps with a phone and a watch module sharing one package ID can declare modules: in .forge.yaml (name, device_types, build_command, apk_pattern) so each artifact is routed to the right device type: crucible pour --project myapp --module watchApp --device-type watch.

Quickstart

After Project setup above (myapp has linc-manifest.yaml and .forge.yaml in $LINC_PROJECTS_DIR/myapp), the first four commands need no daemon, device or Docker:

crucible fuelcheck
crucible assay --project myapp
crucible score myapp
crucible preflight --project myapp
# pour, bvt and baseline capture reach devices through the nerve daemon:
pipx install "linc-nerve>=0.1,<0.2" && nerve daemon &
claude mcp add linc-crucible -- crucible bellows

crucible fuelcheck reports which build tools, projects and services it can see and exits 0 on a fresh machine. Seven of the 8 MCP tools map directly to CLI commands (crucible_extract_assets → crucible extract-assets), while crucible_baseline is served by crucible baseline (capture, list, prune; see MCP Tools); options are flags, not positionals (crucible pour --project myapp), except crucible score PROJECT [--history] [--limit N] and crucible baseline. Output is JSON on stdout; for text, put --human before the command (crucible --human score myapp). Exit 0 success (status: "partial" stays exit 0 with ship_gate: false in the payload), 1 tool error (a run that measured nothing, or a BVT that did not run, exits 1), 2 usage error. crucible schema --json prints every command and option.

MCP Tools (8)

Seven of the 8 MCP tools are reflected directly as CLI commands (crucible_pour → crucible pour). crucible_baseline is served on the CLI by the hand-written crucible baseline group (capture, list, prune for screenshot baselines); its a11y mode and latest / promote actions are MCP-only.

Configuration

Generated from linc_crucible.config_contract.ENV_VARS (crucible fuelcheck --env-table); pinned to the variables read under src/ by tests/test_config_contract.py.

State crucible writes between runs:

Troubleshooting

Trust

• Your project's commands run as you. assay and pour run the build_command, test_command and lint_command from the project's .forge.yaml with your user's permissions. crucible never spawns a shell itself (argv list, shell=False, shlex.split) and refuses |, ;, &, $( and backticks, but a project command that is itself a shell (sh -c '…', bash script.sh) runs a shell because the project asked for it: the trust boundary is the project. Only point crucible at projects you trust. Details: SECURITY.md.
• No telemetry, no phone-home. Nothing leaves the machine: crucible talks to your local nerve daemon, and to MobSF only if you run a full assay against one you started. The nerve daemon on loopback is a trusted peer: crucible acts on the device list, element trees and file paths (e.g. the screenshot path) nerve returns.
• A local usage log, under your control. Each MCP tool call is appended to $LINC_HOME/mcp-calls.jsonl (default ~/.linc/mcp-calls.jsonl) with the tool name, timing and success. Set CRUCIBLE_USAGE_LOG=off|redacted|full:
  • redacted (default) — keeps allowlisted parameter values (such as project, mode, action and boolean/numeric flags), replaces every other parameter value length-only (<redacted len=N>) and scrubs redacted values, host roots and absolute paths (<path>) from error; new state directories are created 0700 and the log file is created owner-only (0600).
  • off — nothing is written.
  • full — raw parameter values. Opt in only on a machine you trust.

How this repo works

This is a release mirror of LINC's private repository. The code is built by LINC's AI software factory under human review; each release lands as one commit. Issues are welcome; pull requests by arrangement — see CONTRIBUTING.md.

Built by LINC Innovations — we diagnose flaky device test suites.

Licensed under the Apache License 2.0.