# semantic-scala

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/DmytroMitin/scala-semantic-harness  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/semantic-scala

## Description
Bounded Scala compiler, build, test, type, effect, symbol, and SemanticDB evidence for agents.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "semantic-scala": {
    "command": "npx",
    "args": ["-y","semantic-scala"]
  }
}
```

## Documentation & README

# scala-semantic-harness

Experimental semantic tooling for Scala and functional-programming projects
used by coding agents.

The harness is a bounded semantic evidence layer, not a replacement for the
Scala compiler, sbt, tests, Metals, or other IDE/LSP tooling. Compiler, build,
and test results remain the final correctness oracle. See
[`docs/project-status.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/docs/project-status.md) for current evidence and
readiness limits and
[`docs/semantic-tooling-positioning.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/docs/semantic-tooling-positioning.md)
for the product boundary. Technical evaluators can use
[`docs/early-feedback.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/docs/early-feedback.md) to report a concrete
real-project comparison.

The current tree is the standalone experimental public-alpha source product
under the [Apache-2.0 license](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/LICENSE). It was published from an independently
constructed, audited clean root followed only by reviewed public-product
commits. The earlier mixed development history is retained separately in a
private archive and is not part of this public repository.

Mutable source `main` reports `0.1.0-alpha.4-SNAPSHOT` for source development
only. No Alpha 4 Central artifact, supported channel, tag, GitHub Release, or
release-readiness claim is established.
The exact eight-module `0.1.0-alpha.3` release is published on Maven Central,
and the public `main` two-application Coursier channel selects it. Fresh
outsider-like JDK 21 install/runtime/update/uninstall through the actual public
raw-GitHub URL and Maven Central passed, as did commit-pinned reproduction.
Both exact Alpha 2 and Alpha 3 application routes now have bounded supported-
distribution READY evidence. The immutable `0.1.0-alpha.3` lightweight tag
identifies commit `075a60bfb7d7677d7fdfcc2369c9ffe41c8b32a8`, whose two clean
builds reproduced all 32 public Maven primaries. Its
[GitHub prerelease](https://github.com/DmytroMitin/scala-semantic-harness/releases/tag/0.1.0-alpha.3)
has normal generated source archives plus the exact Linux x86_64 MCPB used by
the active official Registry record. The immutable
`0.1.0-alpha.2` tag and prerelease retain the independently qualified supported
route and source identity for its 32 Central primaries.

## Agent quick start

The current supported packaged route is exact `0.1.0-alpha.3` on JDK 21. Install the
CLI and generic stdio MCP server first:

```bash
cs install --default-channels=false \
  --channel https://raw.githubusercontent.com/DmytroMitin/scala-semantic-harness/main/distribution/coursier/channel.json \
  semantic-scala semantic-scala-mcp
semantic-scala version
```

Then choose the integration that the agent client supports: the complete CLI,
the curated exact-eight MCP projection, and/or the immutable alpha-2 agent
skill. Copying this repository's thin skill wrappers into another project is
not supported; install the canonical skill from the `0.1.0-alpha.2` tag.

[`docs/agent-onboarding.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/docs/agent-onboarding.md) gives copy-ready Codex,
Claude Code, Cursor, and VS Code/Copilot recipes, exact local qualification
statuses, skill installation, the CLI/MCP surface matrix, and troubleshooting.
Alpha-3 project and target-JDK selectors are explicitly excluded from the
alpha-2 packaged contract. The qualified mutable `main` channel selects Alpha 3;
Alpha 2 remains reproducible through its immutable tag-pinned channel.

## What is included

- structured compile, test, and diagnostic reports;
- SemanticDB inventory, coverage, symbol, and exact-symbol usage evidence;
- bounded Presentation Compiler symbol and type queries;
- reconciliation of dynamic compiler evidence with an explicit SemanticDB
  artifact;
- a public point-evidence composition that preserves source-artifact discovery,
  safe selection, live symbol evidence, and conditional reconciliation;
- Alpha 3 opt-in build-target-aware SemanticDB source mapping v4 with
  a validated optional Scala axis and root-only receipt, alongside target-aware
  point-evidence v4 with a non-compiling partial existing-output context and
  explicit v5 existing-internal-Compile-output opt-in, plus strict v6
  content-fresh internal-output gating;
- an Alpha 3 CLI-only, same-request post-compile TASTy point-evidence
  operation with exact stable Scala 3 child-inspector provenance;
- bounded Alpha 3 sbt-backed command, classpath, and TASTy-receipt
  compatibility proven on sbt 1.12.15 and 2.0.6 fixtures;
- conservative syntax-first FP effect summaries;
- a stdio MCP server exposing exactly eight public tools;
- small external example projects and benchmark infrastructure; and
- a client-neutral `semantic-scala` agent skill with thin Codex and Claude Code
  wrappers;
- source templates and a deterministic assembler for a self-contained Agent
  Plugins 1.0 package containing that skill and the exact-eight MCP server; and
- a supported, independently qualified exact-eight Maven/Coursier application
  route for exact versions `0.1.0-alpha.2` and `0.1.0-alpha.3`, with Alpha 3
  current on the public `main` channel and Alpha 2 retained at its release tag.

## Modules

- `modules/core`: shared JSON models and codecs.
- `modules/cli`: the `semantic-scala` command entry point.
- `modules/sbt-runner`: sbt compile/test subprocess integration.
- `modules/semanticdb-reader`: SemanticDB inventory and usage evidence.
- `modules/presentation-compiler`: bounded dynamic semantic queries.
- `modules/semantic-reconciliation`: static/dynamic symbol comparison and the
  point-evidence composition and reconciliation contracts.
- `modules/fp-analyzers`: syntax-first effect summaries.
- `modules/mcp-server`: CLI-backed MCP stdio adapter.
- `modules/benchmark`: benchmark models and fixtures.

## Build and test

The project uses Scala 3 and sbt. A fresh source setup requires JDK 21, sbt,
Git, and Python 3; CI uses Temurin JDK 21. A newer local JDK may work, but it is
not the documented baseline.

Scala 3 describes the harness implementation, not a blanket target-language
promise. A bounded JDK 21 matrix has verified build/test/error delegation,
SemanticDB discovery/symbol/usages, and syntax-first effect summaries on Scala
2.13.18 and Scala 3.3.8 fixtures. The harness is built with Scala 3.9.0 and its
dynamic point operations use the linked Scala 3.9.0 Presentation Compiler.
That host compiler resolved the matrix's shared-syntax Scala 2 points, but this
is not general Scala 2 dialect or compiler support. Target builds still use
their selected target compiler; static SemanticDB and post-compile TASTy
evidence remain target-artifact evidence. Reconciliation and point evidence
inherit the dynamic-source limitation. See
[`docs/project-status.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/docs/project-status.md) and
[`docs/semantic-api.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/docs/semantic-api.md) for the exact boundary.

Two maintained real-project Stage-A checks now cover frozen Scala 2.13.18
revisions without source or build changes. `scala/scala-java8-compat` produced
no SemanticDB, so its otherwise-passing alpha-2 matrix preserved truthful
degraded point evidence. A bounded production row of `scalacenter/scalafix`
produced target-owned SemanticDB; static symbol discovery, bounded dynamic
lookup, exact static/dynamic reconciliation, complete point evidence, and the
ordered exact-eight MCP projection passed. Scalafix's aggregated sbt build also
exposed that the alpha-2 build oracle cannot select one project row. The
Alpha 3 release closes that routing gap with an optional validated
project selector; the immutable alpha-2 distribution remains unchanged. These
two projects are complementary bounded evidence, not general Scala 2 support or
semantic superiority.

The Alpha 3 release sbt subprocess boundary sends project selection plus
one product-owned task as a single fixed command sequence. Its injected
classpath/receipt adapters use sbt's `fileConverter` for sbt 2 virtual
references and preserve sbt 1 file-backed entries. Readable extensionless sbt 2
CAS JARs are copied directly, without cache scanning, into an owner-only
content-addressed area under the selected workspace's generated `target` tree.
A disposable sbt 2.0.6 fixture, a disposable sbt 2.0.7 multi-project fixture,
frozen sbt 1.12.15 and sbt 2.0.6 plugin projects, and a frozen Chimney sbt
2.0.7 / Scala 3.8.4 selected row pass their bounded gates. The shared runner
uses a request-owned foreground sbt server lifecycle, and structured sbt suite
counters preserve ignored/skipped tests in the existing Test JSON fields. This
is version-specific evidence, not universal sbt 2 or compiler-plugin
compatibility. Chimney's macro-heavy PC points remain neutrally unresolved
because target compiler options and plugins are not replayed.

```bash
sbt -batch test
sbt cli/stage
sbt mcpServer/stage
```

The source-checkout wrapper runs the CLI through sbt:

```bash
./semantic-scala --help
./semantic-scala version
./semantic-scala compile --json
./semantic-scala compile --sbt-project core2_13 --json
./semantic-scala compile --sbt-project plugin --sbt-java-home /absolute/path/to/installed-jdk --json
./semantic-scala test --json
./semantic-scala errors --json
```

`compile`, `errors`, `test`, `semanticdb-for-source`, and `point-evidence`
accept an optional `--sbt-project <id>` where
the ID matches `[A-Za-z][A-Za-z0-9_-]*`. Without it they preserve ordinary root
behavior. With it, compile/errors run that project's fixed `Compile` scope and
test runs its fixed `Test` scope. The selector is not arbitrary sbt syntax, and
a successful selected invocation proves only that bounded project operation,
not whole-workspace correctness.

All eight sbt-backed forms (`compile`, `errors`, `test`, target-aware
`semanticdb-for-source`, target-aware `point-evidence`, sbt-backed `infer-type`,
`infer-type-batch`, and `tasty-point-evidence`) also accept an
optional `--sbt-java-home <absolute-directory>`. The harness itself remains on the
supported JDK 21 runtime; only the target sbt child receives the selected
canonical `JAVA_HOME` and a matching `PATH` prefix. The home must already be
installed and pass bounded validation and a fixed version probe. The harness
does not discover, download, install, or globally select JDKs. Omitting the
flag preserves inherited-Java behavior. Selected-JDK classpath acquisition is
isolated from no-selector cache reuse, and public result schemas do not expose
the home or probe evidence.

Target-aware `semanticdb-for-source` and `point-evidence` also accept
`--sbt-scala-version <version>`. The option requires `--sbt-project`, uses a
strict version-only grammar, and selects that cross-Scala axis in a fresh sbt
lifecycle. Source mapping then runs its fixed root-only receipt task; point
evidence runs its distinct partial existing-output point-context receipt.
Omission means the checked-in build default, never inherited `++` state.

For repeated use, prefer the staged launcher at
`modules/cli/target/stage/bin/semantic-scala`.

## Maven/Coursier distribution

The source-build route above remains supported and externally verified. Exact
eight-module Alpha 2 and Alpha 3 runtimes are published under final group
`com.github.dmytromitin` on Maven Central, with their complete public repository
shapes verified against reviewed bytes. Both exact versions passed fresh
outsider-like public raw-GitHub install/runtime/update/uninstall against Maven
Central only. Alpha 3 is current on `main` and also passed commit-pinned
reproduction; Alpha 2 retains its immutable, qualified release-tag route.

The Central publication contains exactly the eight implementation modules,
never the root aggregate or benchmark, and the public channel uses
exact-version descriptors for the
distinct `semantic-scala` CLI and `semantic-scala-mcp` server applications.
JDK 21 and Coursier are runtime/install prerequisites. Target-workspace sbt is
needed by build-oracle commands such as `compile`, `errors`, and `test`; it is
not required merely to install the applications or for every read-only
semantic command. The Maven modules are application implementation artifacts,
not a supported embeddable-library API or binary-compatibility promise.

Install only the CLI:

```bash
cs install --default-channels=false \
  --channel https://raw.githubusercontent.com/DmytroMitin/scala-semantic-harness/main/distribution/coursier/channel.json \
  semantic-scala
```

Or install the CLI and stdio MCP server together:

```bash
cs install --default-channels=false \
  --channel https://raw.githubusercontent.com/DmytroMitin/scala-semantic-harness/main/distribution/coursier/channel.json \
  semantic-scala semantic-scala-mcp
```

Use `semantic-scala-mcp` as the generic stdio MCP command with the target
workspace as its working directory. See
[`docs/distribution.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/docs/distribution.md) for Coursier setup, updates,
uninstall, commit-pinned channel reproduction, and the current qualification
boundary.

## Semantic commands

```bash
./semantic-scala semanticdb-status --workspace . --json
./semantic-scala semanticdb-coverage --workspace . --json
./semantic-scala semanticdb-for-source --file src/main/scala/example/Main.scala --workspace . --json
./semantic-scala point-evidence --file src/main/scala/example/Main.scala --workspace . --line 6 --col 16 --json
./semantic-scala semanticdb-for-source --file src/main/scala/example/Main.scala --workspace . --sbt-project app [--sbt-scala-version 3.3.7] --json
./semantic-scala point-evidence --file src/main/scala/example/Main.scala --workspace . --line 6 --col 16 --sbt-project app [--sbt-scala-version 3.3.7] [--include-existing-internal-outputs [--require-fresh-internal-outputs]] --json
./semantic-scala tasty-point-evidence --workspace . --sbt-project app --file src/main/scala/example/Main.scala --line 6 --col 16 [--sbt-java-home /absolute/path/to/installed-jdk] --json
./semantic-scala symbols --semanticdb path/to/Main.scala.semanticdb --json
./semantic-scala usages --workspace . --manifest semantic-usages.json --symbol 'example/Foo#bar().' --json
./semantic-scala symbol-at --file path/to/Main.scala --line 6 --col 16 --json
./semantic-scala infer-type --file path/to/Main.scala --line 6 --col 16 --json
./semantic-scala infer-type-batch --requests batch-request.json --workspace . --sbt-project core --sbt-configuration Compile [--sbt-java-home /absolute/path/to/installed-jdk] --json
./semantic-scala reconcile-symbol --file path/to/Main.scala --line 6 --col 16 --semanticdb path/to/Main.scala.semanticdb --json
./semantic-scala effect-summary --file path/to/UserRepo.scala --json
```

Target-aware source mapping and point evidence are explicit Alpha 3
options. Omitting target options preserves the v2 workspace-wide behavior,
including truthful ambiguity. With `--sbt-project`, source mapping emits v4 and
uses a fixed root-only Compile receipt containing target identity,
`classDirectory`, `semanticdbTargetRoot`, requested/effective Scala-axis
provenance, and bounded JDK provenance. It does not request target compilation,
`fullClasspath`, products, or exported products; sbt build/plugin loading,
resolution, and ordinary metadata/cache writes remain possible. Candidate
ownership is checked canonically beneath the reported SemanticDB root while
workspace discovery remains unchanged. Optional `--sbt-scala-version` selects
one validated axis and must exactly match the effective receipt axis; omission
uses the fresh lifecycle's build default.

Target-aware point evidence emits v4 by default. It acquires exactly one fixed Compile
receipt containing the selected existing class directory when present plus the
selected target's external dependencies. It never requests target compilation,
`fullClasspath`, products, or exported products, and has no build fallback.
The report always marks this context `PartialExistingOutputs`; a missing class
directory is omitted rather than built. Checked-in sbt build/plugin loading,
dependency resolution, and metadata/cache writes remain possible. The harness
Presentation Compiler does not replay target compiler flags, plugins, or
lifecycle, and the context is not a complete arbitrary multi-project classpath.
An explicit `--include-existing-internal-outputs` presence flag emits v5 and
adds only already-present same-axis internal Compile class directories found by
a bounded settings-only dependency traversal. Missing outputs remain typed and
are never built. V5 stays `PartialExistingCompileOutputs`, does not request
`fullClasspath`, products, or `internalDependencyClasspath`, and still does not
replay target compiler flags/plugins. The existing eighth MCP tool exposes the
same opt-in as optional boolean `includeExistingInternalOutputs`; the registry
remains exactly eight.
Adding `--require-fresh-internal-outputs` requires the v5 flag and emits v6.
It reads only existing same-axis `Compile / compileAnalysisFile` archives and
uses supported Zinc persistence APIs in one on-demand bounded JDK 21 worker
plus content stamps and source/product relations. The worker is not resolved
or launched by v2/v4/v5 or ordinary MCP initialization. Its exact pinned Zinc
1.12.1/Scala 2.13.18/JNA 5.14.0 graph is cache-first; first uncached strict-v6
use may contact Maven Central and populate the Coursier cache, while a warm
cache can run offline. Cold offline unavailability fails closed as
`Unverifiable`, with no compile or linked-runtime fallback. The same settings-only receipt captures exact configured source
roots and generator-list cardinality; configured generators, managed source
residue, unavailable provenance, unsafe roots, or exceeded file/archive bounds
fail closed as Unverifiable. Only internal directories proven `Fresh`
contribute; `Stale` and all `Unverifiable` states remain visible but excluded.
This does not compile, run generators, use mtimes or Git state as freshness
authority, or establish whole-target/build freshness. The matching MCP boolean is
`requireFreshInternalOutputs` on the same eighth tool.
Moving the graph off normal process classpaths reduces the ordinary staged and
shipped dependency surface; it does not claim lower total disk use after the
on-demand cache has been populated.
`semanticdb-for-source` remains CLI-only, direct `reconcile-symbol` remains an
explicit-artifact target-independent operation, and the MCP registry remains
exactly eight tools.

All machine-facing commands have JSON output. Build-oracle command exit code
`0` means the CLI operation completed; inspect the JSON `success` field for the
compile or test domain result. Semantic results preserve their scope and
uncertainty: rendered hover text is not canonical identity, artifact presence
is not complete source coverage, and only `ExactMatch` is exact reconciliation.

Detailed contracts:

- [`docs/semantic-api.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/docs/semantic-api.md)
- [`docs/usages.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/docs/usages.md)
- [`docs/point-evidence.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/docs/point-evidence.md)
- [`docs/tasty-point-evidence.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/docs/tasty-point-evidence.md)
- [`docs/architecture.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/docs/architecture.md)

## MCP server

The stdio server exposes exactly these tools:

```text
semantic_compile
semantic_errors
semantic_test
semantic_effect_summary
semantic_symbol_at
semantic_symbols
semantic_reconcile_symbol
semantic_point_evidence
```

Build and validate it with:

```bash
sbt cli/stage
sbt mcpServer/stage
scripts/mcp/smoke-mcp-tools.py
```

Copy [`.mcp.example.json`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/.mcp.example.json) and replace its placeholder
checkout path for source-development client configuration. Installed alpha-2
users should configure `semantic-scala-mcp` directly. See
[`docs/mcp-client-validation.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/docs/mcp-client-validation.md) for the public
configuration and protocol checks and
[`docs/agent-onboarding.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/docs/agent-onboarding.md) for client recipes.

## Agent skill

The canonical client-neutral policy is
[`skills/semantic-scala/SKILL.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/skills/semantic-scala/SKILL.md). Thin
repository wrappers live at:

- [`.agents/skills/semantic-scala/SKILL.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/.agents/skills/semantic-scala/SKILL.md)
- [`.claude/skills/semantic-scala/SKILL.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/.claude/skills/semantic-scala/SKILL.md)

These files are source-tree wrappers, not standalone external installations.
The skill is policy and documentation. It does not add commands, background
services, or automatic invocation. External alpha-2 installation plus client
qualification is in
[`docs/agent-onboarding.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/docs/agent-onboarding.md); packaging and
maintenance guidance is in
[`docs/agent-skill-semantic-scala.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/docs/agent-skill-semantic-scala.md).

For a current repository-sourced installation, select the single canonical
skill explicitly:

```bash
npx skills add https://github.com/DmytroMitin/scala-semantic-harness --skill semantic-scala
```

This installs guidance only; install the supported runtime separately. The
qualified command, stable catalog metadata, registry boundaries, and native
plugin follow-ups are documented in
[`docs/discoverability.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/docs/discoverability.md).

## Official MCP Registry package

The repository includes a deterministic MCPB packaging surface for the exact
`0.1.0-alpha.3` CLI and MCP server. The published Linux x86_64 package carries a
package-local Corretto 21 runtime and static entry points, so it does not call
an undeclared host `java`. It preserves ordinary host access to the target
Scala workspace and its build tools. Qualification is limited to Linux x86_64
with a compatible GNU-libc environment and system zlib; it is not a claim for
every Linux libc or distribution.

The exact bundle is a public Alpha-3 release asset and its active official MCP
Registry record is `io.github.DmytroMitin/semantic-scala`. The maintained
manifest and final record are under `packaging/mcpb/semantic-scala/` and
`distribution/mcp-registry/`. See
[`docs/mcpb-package.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/docs/mcpb-package.md) for the immutable URL and digest,
exact-tag build, determinism, validation, and platform boundary.

## Agent Plugin package

After staging the CLI and MCP server, generate a fresh relocatable package:

```bash
sbt cli/stage mcpServer/stage
python3 scripts/package-agent-plugin.py assemble \
  --output target/agent-plugin/semantic-scala
python3 scripts/package-agent-plugin.py validate \
  --plugin-root target/agent-plugin/semantic-scala
```

The output is ignored build material, not a checked-in binary distribution or
release. It targets the Agent Plugins 1.0.0 working draft and bundles the
canonical skill, complete staged CLI, and complete staged exact-eight MCP
server. See [`docs/agent-plugin.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/docs/agent-plugin.md) for the package
contract, validation level, relocation smoke, and current client-support
limits.

## Native plugin candidates

The repository also contains deterministic OpenAI/Codex and Claude Code source
templates plus an assembler that transforms the exact published Alpha-3 MCPB
into native candidates with a package-local Java runtime. Both candidates
passed native manifest validation, canonical-skill byte checks, two-build
inventory equality, and a relocated no-host-Java exact-eight runtime smoke.
Codex CLI `0.154.0` additionally passed a disposable local-marketplace install,
skill load, bundled-MCP registration, and one read-only semantic call. Claude
Code `2.1.220` passed a disposable local-marketplace install, packaged-skill
load, plugin-local MCP connection, and one read-only client-mediated semantic
call after an explicit owner login checkpoint. The historical full Claude candidate remains preserved at commit
`c05aac9f38e7755a51f511078ff555a587f97ccf` in
[`DmytroMitin/semantic-scala-claude-plugin`](https://github.com/DmytroMitin/semantic-scala-claude-plugin).
The repository's current `main` instead contains the directory-compatible thin
wrapper, qualified at commit `05d4f0de35a02916504bf29156bc42270cf77a23`.
An anonymous clone reproduced its six-file identity, and its 17,129-byte public
GitHub archive passes the current hard limits. Claude Code `2.1.283` passed
strict plugin and marketplace validation; prior public-source cold/warm client
evidence remains applicable because runtime and bootstrap bytes are unchanged.
The existing draft was submitted for Claude Directory review exactly once on
2026-09-28. Its security scan completed and sent the qualified `05d4f0d`
version to content-policy review because the scan could not automatically read
shipped executable, bytecode, WebAssembly, or packed code. The current status
is In review, and no public listing is verified. Versions history retains an
earlier `fc3a6c8` detection event, but a scheduled check added `05d4f0d` as the
version now in review. No duplicate submission, update check, or corrective
portal action was attempted.
The owner packet under
[`distribution/claude-community/`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/distribution/claude-community/) records the
immutable qualification commit and expected human review hold. The
owner-approved [semantic-scala Privacy Policy](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/PRIVACY.md) is public and
exposed from the qualified plugin README. The submitted answers are `Reads
only`, `No`, `Not retained`, and `No`; all four compliance acknowledgements
were owner-approved. The private contact value is not retained in this
repository.

A separate OpenAI skills-only candidate now lives under
[`packaging/openai-skills-plugin/`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/packaging/openai-skills-plugin/) without
reusing or changing the local-MCP candidate. It packages one narrow read-only
`effect-summary` workflow, an exact canonical-policy reference, and a
standard-library-only Python helper. The helper fetches and verifies the fixed
Alpha-3 runtime on first approved use, then invokes `bin/semantic-scala`
directly; it contains no MCP configuration and starts no MCP process. Codex CLI
`0.157.1` passed disposable marketplace installation, installed-skill loading,
packaged-helper invocation, and interpretation of `Fixture.value: Option[Int]`.
Cold acquisition and warm cache-only reuse passed with unchanged fixture bytes.
This is local technical qualification, not an OpenAI submission or public
listing. Current OpenAI guidance requires partner contact before submitting
the local-execution/local-file/offline workflow; production-ready original logo
and composer-icon assets also remain human prerequisites. The prepared
owner-approved privacy amendment covers the OpenAI/Codex path, first-use
download, and separate cache; the public URL will reflect it after separately
authorized publication. See
[`docs/openai-skills-only-plugin.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/docs/openai-skills-only-plugin.md).

The repository now also contains a separate directory-compatible thin Claude
candidate. It retains the canonical skill and local exact-eight MCP interface,
but replaces the bundled runtime with a Python 3.11 bootstrap that downloads
the fixed Alpha-3 MCPB on first start, verifies its exact byte count and
SHA-256 before safe extraction, and atomically installs it in an owner-only
semantic-scala cache. Warm starts reuse that verified cache and require no
network fetch. The deterministic 6-file candidate is 40,205 unpacked bytes,
its largest file is 21,188 bytes, and its ZIP is 14,843 bytes. Claude Code
`2.1.283` passed strict validation for the privacy-link source. The cold session
retains one pre-semantic invalid-path rejection followed by one successful
read-only call; the warm session made one successful read-only call. This is
public-source technical readiness and a submitted review request, not directory
acceptance. The next gate is monitoring the existing content-policy review and handling
reviewer feedback without a duplicate submission; publication, if approved, remains a
separate portal state/action. See
[`docs/claude-directory-thin-plugin.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/docs/claude-directory-thin-plugin.md).
See [`docs/native-plugin-packages.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/docs/native-plugin-packages.md) for the
build commands, current vendor contracts, public-submission boundary, and
platform limits.

## Examples and benchmarks

Projects under `examples/` are external CLI fixtures rather than members of
the root sbt build. The normal test suite exercises the compile-success and
compile-failure examples through the CLI.

The repository contains a standalone public benchmark subset with methodology,
portable prompts, test-coupled fixtures, deterministic validation, and a
bounded aggregate. Start at [`benchmarks/README.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/benchmarks/README.md).
Historical raw transcripts and controller automation are not part of that
subset. The admitted evidence does not establish broad superiority or general
benchmark reproducibility beyond its stated small-sample gate.

## Current limitations

- The official MCPB package is validated only for Linux x86_64. Other operating
  systems and architectures require separately built and tested assets. The
  tested bundle requires a compatible GNU-libc environment and system zlib even
  though it requires no host Java.
- A generated self-contained Agent Plugins package has bounded structural,
  official-schema, determinism, and relocated-runtime evidence, but no
  supported release channel or conformant installed-client adoption proof.
- The OpenAI/Codex and Claude Code native packages are locally validated
  Linux x86_64 candidates assembled from the exact Alpha-3 MCPB. Both have
  bounded disposable installed-client skill and MCP-use qualification. They
  are not public listings or supported public install channels. OpenAI public
  MCP submission still requires a separately authorized public HTTPS service.
  The exact Claude candidate is present at a qualified public Git commit, but
  current directory submission follows a branch or tag and rejects a GitHub
  archive of 50 MiB or more, an unpacked plugin of 256 MiB or more, or an
  individual file of 5 MiB or more. The candidate is 339,741,892 unpacked bytes
  and contains a 54,008,260-byte runtime image file, so that historical full
  candidate is not eligible. The separately generated 40,205-byte thin candidate
  fits those limits and is now published on public `main`, byte-qualified at
  commit `05d4f0de35a02916504bf29156bc42270cf77a23`; the unchanged runtime remains
  cold/warm client qualified. Its first start requires network access and Python 3.11 or newer to
  fetch and verify the fixed Alpha-3 MCPB. Human portal acceptance and review
  remain distinct from local qualification.
- The separate seven-file OpenAI skills-only candidate is locally validated on
  Codex CLI `0.157.1` for one direct-CLI `effect-summary` workflow with no MCP
  dependency. It is not submitted. OpenAI partner review, production logo and
  composer-icon assets, verified publisher identity, country selection, and
  policy attestations remain prerequisites. The OpenAI-specific privacy
  amendment is approved in the prepared product diff and awaits repository
  publication.
- The MCP surface remains the documented eight-tool stdio adapter.
- Source-paired `semanticdb-for-source`, `point-evidence`, and
  `reconcile-symbol` requests now report snapshot-consistent content freshness.
  Fresh means the captured source content agrees with the captured SemanticDB
  document; it does not mean a build ran or that the whole project compiles.
- Stale SemanticDB remains visible but cannot produce completed reconciliation.
  Unverifiable evidence stays explicit and can complete only as qualified
  evidence. SemanticDB inventory and coverage still do not establish that every
  source is covered or fresh.
- Presentation Compiler renderings are bounded evidence, not whole-project
  compile proof.
- The canonical skill selects `symbol-at` for one exact Presentation Compiler
  declaration question and reserves `point-evidence` for questions where
  artifact discovery/selection and reconciliation are themselves relevant.
  Source-sufficient questions still require no semantic query.
- Public-alpha source readiness is separate from binary distribution,
  installation usability, semantic utility, and skill-adoption evidence.
- The exact `0.1.0-alpha.2` Maven/Coursier application route is independently
  qualified from the actual project-owned public channel URL and Maven
  Central under JDK 21. This does not establish Coursier contrib, MCP Registry,
  MCPB, native/container/npm/PyPI packaging, a stable embeddable-library API,
  broad Scala compatibility, skill adoption, semantic superiority, or 1.0
  stability. The exact alpha-2 source identity is published as a lightweight
  tag and GitHub prerelease with normal generated source archives and zero
  uploaded project assets.
  All 16 formerly flagged license/NOTICE rows are technically dispositioned;
  the owner selected Apache-2.0 for resolver-fetched JNA 5.14.0. This is not
  legal advice or authority for another publication action.
- The public repository contains only the audited clean source history. The
  separate mixed development history remains private and is not a release or
  installation channel.

See [`ROADMAP.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/ROADMAP.md) for product-oriented next steps.

Current development is validation-first: test real Scala projects, preserve
compatibility boundaries, and admit features only from concrete gaps. Real
project reports are welcome using the bounded comparison packet in
[`docs/early-feedback.md`](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/docs/early-feedback.md), especially missing
decision-relevant evidence or materially useful composition of compiler,
build/test, IDE/LSP, and artifact facts. Both exact Alpha 2 and Alpha 3 packaged
routes are independently qualified and retain immutable source-release identity.
External early-user feedback is the primary next input for semantic-value
admission; the Alpha 4 SNAPSHOT source identity adds no packaged route.

## Project policies

- [Contributing](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/CONTRIBUTING.md)
- [Security reporting](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/SECURITY.md)
- [Changelog](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/CHANGELOG.md)
- [Release and versioning](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/RELEASE.md)
- [Apache-2.0 license](https://github.com/DmytroMitin/scala-semantic-harness/blob/HEAD/LICENSE)