Engineering operating manual / edition 1.1

From requirements
to reviewed evidence.

A practical user guide to FormalSpecGen for new systems, existing codebases, and supervised agent-assisted verification.

38 CLI commands205 argument declarations2 strict MCP tools
Pinned to public revision 91c6790 · 24 September 2026 · Edition 1.1 adds request-level permissions and policy-bound evidence. Formal example runs are not pre-certified.
Read workflows first; use the reference for exact flags and defaults.

Operating guide

Greenfield development · Brownfield adoption · Verification · Review · Evidence

Documentation baseline: public revision 91c6790. Guide edition: 1.1, 24 September 2026.

This guide explains how to operate FormalSpecGen, choose an appropriate workflow, interpret its results, and retain the evidence needed to review a change. It covers all 38 commands registered by the default CLI, the interactive shell, and the two tools in the default strict MCP catalogue. It is a versioned operating manual, not a claim that every supported command proves an entire application correct.

Edition 1.1 updates the earlier complete guide through the two direct admission-policy commits. The CLI parser is unchanged; admission, evidence fields, profile restrictions, templates, and helper checks were reviewed against 91c6790. The included Java teaching fixtures were syntax-compiled; the formal backends and the complete example workflows were not executed during preparation. Expected outcomes in examples are acceptance targets, not pre-generated proof results. Do not substitute this guide for a new validation run in your environment. S01 S02 S03 S04 S60 S61

New in edition 1.1: invocation-specific permission profiles; requested versus granted effects; policy-bound evidence; per-command strict-MCP availability; and a pinned-policy receipt check. See the admission field guide and edition changelog.

Contents

  1. Choose your workflow
  2. Understand contracts, claims, and review
  3. Install and configure the tool
  4. First run: inspect, prove, and reject a bad candidate
  5. Greenfield: requirements to implementation
  6. Greenfield: reviewed V2 domain to source
  7. Brownfield: understand and specify an existing project
  8. Brownfield: refactor and optimize without changing the contract
  9. Architecture, composition, and system workflows
  10. Security assessment, remediation, and intentional correction
  11. Specialized verification workflows
  12. Use MCP with AiderDesk and Qwen
  13. Publish, validate, and review evidence
  14. Automate safely in development and CI
  15. Use the interactive shell
  16. Troubleshooting and recovery
  17. Coverage, maintenance, and extension boundaries
  18. Source register

The companion command reference gives the syntax, every declared positional argument and option, defaults, allowed values, examples, outcomes, and limitations for each command. The machine-readable inventory supports documentation-drift checks.

1. Choose your workflow

What the tool does

FormalSpecGen coordinates specification drafting, deterministic transformations, implementation generation, native verification, bounded model checking, and evidence collection. Some operations propose artifacts; some inspect them; some invoke formal tools. Human review decides what the intended contract and assumptions should be. A successful model response is never itself a verification result. S05 S06 S07 S08

Start from the object you actually have, not the strongest-sounding command name.

Starting point Recommended path Review checkpoint
A new feature described in prose draft → review contract → implement → verify Confirm preconditions, outcomes, frames, and assumptions before generating bodies.
A finite stateful component to reuse across languages domain --schema-version 2 → validate-domain → review → promote-domain → canonical draft → implement Accept an exact candidate hash, then retain matching evidence.
An existing repository with little formal documentation analyze-codebase → document-code → review extracted candidates → validate selected models Extraction is incomplete discovery, not approval or proof of the source.
An existing source file with reviewed contracts verify → inspect → approved edit → verify-refactor Keep an immutable baseline and inspect the full semantic diff.
A slow verified algorithm optimize-algorithm or discover-algorithms → preservation/proof gates → separate benchmarks Verification does not establish a performance improvement.
A suspected vulnerability security-inspect / assess-security → review → remediate or correct-behavior Decide whether behavior must remain unchanged or intentionally change.
Several reviewed components compose, then reverify; use system for component workflows Review dependency contracts, bindings, and composition assumptions.
Agent-assisted editing Strict MCP inspect_code and Java verify_code Approve edits; keep the verifier installation and evidence outside agent control.

For a first adoption, choose a small sequential component with explicit boundaries. Do not begin by treating a whole distributed application as one proof obligation. The specialist workflows in chapter 11 have deliberately limited input profiles. S01 S08 S09 S10

CLI availability is not agent permission

Workflow Operator-facing CLI Default strict MCP Approval boundary
Inspect existing Java inspect inspect_code, read-only Java profile Review findings before editing
Check a submitted Java/JML artifact verify verify_code; OpenJML parse, check, esc only Review the specification; parsing/checking is not proof
Greenfield drafting, implementation, and V2 generation Supported commands in chapters 5–6 Not admitted Operator manages providers and generated outputs
Brownfield extraction, documentation, preservation, optimization Supported commands in chapters 7–8 Not admitted Operator reviews baseline, writes, and backend scope
Native, architecture, security, and system workflows Supported within their documented input profiles Not admitted Operator manages the whole execution chain
Environment diagnosis doctor Not admitted; it launches probes Operator-run environment check
Promotion, signing, and trust policy promote-domain, sign-artifact, manage-trust Human-only; no MCP profile permitted Reviewer retains authority and keys

This table describes the baseline, not a promise that every CLI workflow has strict isolation. No generation provider or ordinary workspace-write permission is granted by either current MCP profile. A CLI recipe in this guide is not permission for an agent to execute it through a shell. S01 S48 S56

project/
├── src/                         Application source
├── baseline/                    Reviewed snapshots for preservation checks
├── refactored/                  Candidate revisions, same public class filenames
├── requirements.txt             Requirements with REQ-### identifiers
├── domains/
│   ├── candidates/              Unreviewed V2 YAML and validation evidence
│   └── v2/                      Promoted reviewed JSON
├── plans/                       Composition and system plans
├── generated/                   Deterministic scaffolds / candidate source
├── evidence/                    Explicit CLI verdict files and review reports
└── .formalspecgen/
    ├── session.json             Interactive-shell session state
    └── mcp-evidence/            Strict MCP run directories

This is a recommended application layout, not a requirement that FormalSpecGen itself be installed inside the application. A separate pinned installation is preferable for an agent-facing verifier. Application evidence/*.json files are ordinary outputs unless the workflow explicitly publishes a ledger and receipt. S03 S11

2. Understand contracts, claims, and review

The main artifacts

A contract describes allowed inputs, promised results, exceptional behavior, and permitted state changes. A frame condition identifies the state a method may modify. A domain model describes state variables and transitions. An implementation supplies executable bodies. Evidence records what a tool checked, with which inputs, assumptions, configuration, and result.

Preservation checks compare the supported semantic surface rather than treating unchanged method names as sufficient. In the pinned Java and native front ends, unsupported or incompletely represented syntax can be rejected. That is a supported boundary, not an instruction to strip annotations or weaken the contract. S12

Read claims in context

Result category What it can establish What it does not establish by itself
Inspection, extraction, documentation, or transformation A report or artifact was produced under a defined procedure Correctness of the application
Parsing or static checking Accepted syntax/types for the requested checker A postcondition proof
RUNTIME_SAMPLE The recorded tests ran with their observed outcome All possible inputs or executions
BOUNDED_ARCHITECTURE_EVIDENCE Properties of the recorded model within its checked bounds Unbounded behavior or source/model correspondence
DEDUCTIVE_PROOF The supported obligations were discharged under the tool's assumptions That the specification captures every intended requirement
Source/model refinement evidence A supported relation between the checked source and model Unmodeled I/O, arbitrary language features, or external service behavior
NO_PROOF The requested proof is not established by this result Necessarily that the program is incorrect

Result labels differ between workflows. Read status or final_status, claim or claims, request_satisfied where supplied, and the stage evidence. Do not write an integration that searches a log for the word “VERIFIED.” The centralized verification policy distinguishes successful process execution from satisfaction of the requested assurance. S04 S05 S06 S07 S08

Human review is a separate gate

Before accepting a contract or model, check that it admits the intended inputs, describes failure behavior, preserves the required class invariants, and does not hide contradictions or unreviewed assumptions. Review nullness, arithmetic bounds, literal values, imported constants, trusted declarations, and verification-suppression controls where relevant.

For a counter bounded by five, “increment requires value < 5” means callers must establish that condition. It does not mean increment has been specified to throw an exception or return false at five. The example requirements explicitly choose the former semantics. A different product requirement needs a different reviewed contract.

Keep these decisions distinct: approve intended semantics; prove a candidate against them; verify preservation when comparing revisions. verify_code through MCP performs the middle task, not all three. S03 S12 S13

3. Install and configure the tool

3.1 Create a pinned installation

The package requires Python 3.10 or later. The following shell example uses a separate installation directory; do not run it inside an existing checkout with uncommitted changes. S02

# Shell setup, not FormalSpecGen subcommands.
git clone https://github.com/sheelmorjaria/formalspecgen.git formalspecgen-tool
cd formalspecgen-tool
git checkout --detach 91c6790
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[mcp]'
formalspecgen --version
formalspecgen --help

Omit [mcp] for a CLI-only installation. Installing the Python package does not install OpenJML, TLC, Frama-C, Prusti, or every other judge. Install only the backends required for your intended workflows, then verify their readiness. Use the source-controlled CI workflow as the pinned acceptance-environment reference, not as a universal workstation-provisioning script. S02 S04 S14

The examples use a POSIX shell. Strict execution needs Linux facilities. A Windows or macOS desktop therefore needs a suitable Linux execution host or environment for these strict paths; a Python virtual environment alone is insufficient. Do not silently replace strict execution with unrestricted local commands. S15

3.2 Check readiness

formalspecgen doctor
formalspecgen doctor --judges
formalspecgen doctor --json
formalspecgen doctor --require OpenJML --require TLC --json evidence/doctor.json

Create the output directory first and use the judge names reported by your installed version. doctor --json without a value prints JSON; most other commands require a filename after --json. --require is repeatable. --strict fails when the aggregate report is not ready, which can be too broad for a deliberately minimal installation. A successful readiness report remains environmental metadata, not an application proof. S01 S16

3.3 Configure formal tools

Set configuration in the environment inherited by the CLI or MCP process. The built-in .env reader uses the configured tool home and simple KEY=VALUE lines; it is not a general shell interpreter. Existing environment variables take precedence. Restart a long-running MCP server after changing its configuration. S14

Variable Purpose / relevant default
FORMALSPECGEN_HOME Tool resource/configuration root; do not point it at an unrelated application merely to change the workspace.
OPENJML_BIN, OPENJML_HOME OpenJML launcher and bundle; preserve their matching specifications and bundled runtime.
OPENJML_SPECS, OPENJML_JAVA, JMLRUNTIME Optional explicit paths for the bundle's specifications, Java runtime, and runtime library.
JAVAC, JAVA_BIN Java compiler and Java launcher used by relevant adapters.
TLC_JAR, TLC_TIMEOUT TLA+ tools JAR and bounded-check timeout; timeout defaults to 60 seconds.
CHECK_TIMEOUT, ESC_TIMEOUT Java checking / ESC limits; defaults are 60 / 180 seconds.
PRUSTI_BIN, RUSTC_BIN, PRUSTI_TIMEOUT Native Rust verifier, compiler, and timeout.
KANI_BIN, KANI_TIMEOUT Kani launcher and timeout; the configured launcher defaults to cargo.
FRAMAC_BIN, FRAMAC_PROVERS, FRAMAC_TIMEOUT Frama-C WP launcher, prover selection, and timeout; prover default is z3.
CC_BIN C compiler, default gcc.
FORMALSPECGEN_CGROUP_ROOT Administrator-delegated cgroup parent for strict executions.
FORMALSPECGEN_MCP_STRICT_JAVA_ONLY Keep unset at its strict default, or explicitly set 1.

Paths and secondary specialist tools are detailed in pipeline/config.py and the doctor report. Do not assume a verifier installed under a different path will be discovered automatically. S14 S16

3.4 Provision the strict Linux execution boundary

The strict executor needs Bubblewrap (bwrap), prlimit, usable Linux namespaces, and a cgroup v2 hierarchy with delegated memory/process controls. The administrator must arrange the parent/child cgroup membership correctly; setting a path in an environment variable does not create delegation. Writable /work and /tmp are separately bounded tmpfs mounts. Source inputs and the selected tool resources are read-only. S15

The executor's default policy object uses a 60-second wall limit, 512 MiB memory, 32 processes, 1 MiB output, 64 MiB per-file limit, 128 MiB workspace, and 64 MiB temporary storage. Adapters can override these defaults. These are not universal CLI flags and are not promises that every workflow uses the same values. S15

Provision this on a dedicated runner or service account. Keep the authoritative evidence location outside the sandbox's writable mounts. Do not disable host security policy globally as a routine installation step; resolve namespace and delegation requirements with the administrator. A missing sandbox, inaccessible cgroup, resource failure, or failed cleanup is an execution failure, not a request to retry without isolation.

Scope: the strict Java and generated native runtime paths are not a guarantee that every full CLI workflow and native formal backend has the same boundary. Default MCP deliberately limits execution to isolated Java verification. S03 S15

3.5 Configure generation separately from verification

Pure verification and deterministic inspection do not require an LLM endpoint. Generation, narrative, repair, and some invariant-proposal workflows do. Most generation commands accept --provider and --model; consult the reference because these are not global options. S01 S17

# Example for an already working local Ollama endpoint.
export OLLAMA_BASE_URL=http://127.0.0.1:11434/v1
export OLLAMA_MODEL=YOUR_EXACT_SERVED_MODEL_ID

# Alternative: use --provider openai with a local compatible endpoint.
export OPENAI_BASE_URL=http://127.0.0.1:8000/v1
export OPENAI_MODEL=YOUR_EXACT_SERVED_MODEL_ID
export OPENAI_API_KEY=YOUR_ENDPOINT_AUTH_VALUE

Use a harmless placeholder only when the local endpoint genuinely needs no authentication. Never paste production secrets into project documentation. Supported provider names are glm, openai, and ollama; unknown names fail rather than selecting an unrelated provider. Relevant limits include LLM_TIMEOUT, LLM_MAX_TOKENS, and the Ollama context/prediction settings. S14 S17

Selecting Qwen in AiderDesk configures the outer agent. It does not configure FormalSpecGen's own generation provider. The default strict MCP tools do not run those generation loops, so the first pilot needs only AiderDesk's existing tool-capable endpoint. S03 S17

4. First run: inspect, prove, and reject a bad candidate

Use the bundled project at examples/guide_demo/. Activate the pinned tool environment, then change to that directory. All paths below are relative to it.

mkdir -p evidence
formalspecgen inspect src/BoundedCounter.java --json evidence/inspection.json
formalspecgen verify src/BoundedCounter.java --mode esc --json evidence/valid.json

The first command performs deterministic Java inspection. The second requests deductive checking of the submitted Java contract and implementation. With a correctly provisioned backend, the intended-correct fixture should satisfy the request. Read the actual verdict rather than assuming success from this document. S01 S18

Now exercise the negative path:

formalspecgen verify negative/BoundedCounter.java --mode esc --json evidence/invalid.json

The negative fixture adds two instead of one. It is expected to fail the postcondition check, potentially also the invariant at the upper boundary. A nonzero exit is the desired result for this negative test. Do not weaken the specification to make the test pass.

Finally check a body-only revision:

formalspecgen verify-refactor baseline/BoundedCounter.java refactored/BoundedCounter.java --json evidence/refactor.json

The candidate changes only assignment syntax. The expected result is a preserved supported contract plus successful backend checks. Both revisions keep the public class name and filename BoundedCounter.java; compile or verify them as separate revisions, not simultaneously in one class output directory. S12 S19

Completion check: you have a genuine successful verification, a genuine failed verification, and a separately checked preservation result. You have not yet demonstrated architecture refinement, thread safety, performance, or an MCP transport round trip.

5. Greenfield: requirements to implementation

Interface: operator-facing CLI workflow. The complete workflow is not admitted to default strict MCP. Java inspection or verification can be used separately under their own profiles; that does not authorize the surrounding steps. S48 S56

This route suits a new component whose method contracts are the immediate goal.

Step 1 — Write requirements and clarify behavior

State valid inputs, initial state, failure outcomes, state changes, arithmetic bounds, external dependencies, and concurrency assumptions. Assign identifiers such as REQ-001 for later traceability. Avoid requirements that say only “safe,” “correct,” or “secure” without defining observable behavior.

formalspecgen draft "A sequential counter starts at zero, stays between zero and five, increments only below five, and decrements only above zero." --provider ollama --lang java --out runs/counter-draft-001

draft takes the requirement text, not a path to a requirements file. Answer its clarification questions and inspect the generated file location in the result. For Java generative drafting, use the reported run output; --out-file is primarily for native/canonical paths. Use a fresh run root for each evidence-bearing attempt. S01 S05

Step 2 — Review and freeze the contract

Read every precondition, postcondition, invariant, frame, assumption, and semantic annotation. A draft accepted by OpenJML's checking stage is not an implementation proof. Preserve the reviewed file as the trusted input. Use --no-clarify only when clarification has already happened; it does not approve missing semantics.

Step 3 — Generate an implementation at an explicit scope

For a method-contract-only starting point:

formalspecgen implement reviewed/Counter.java --provider ollama --method-proof-only --max-attempts 5 --out runs/counter-implementation-001 --json evidence/implementation.json

reviewed/Counter.java is the contract file you actually approved, not a bundled filename. This explicit mode skips architecture/TLC and source-refinement claims. It is often preferable to requesting critical architecture assurance for an unsupported domain and then weakening gates when it fails. S06

For a supported architecture and reviewed V2 binding, use the stronger route in chapter 6 instead. The general profile behavior is:

Profile / mode Java route Native route
lightweight Specification lint and compilation-oriented implementation path Static checking without the standard runtime sample
standard Static contract checking plus required RAC/JUnit sample Static checking plus required instrumented runtime sample
critical ESC, required bounded architecture evidence, and supported refinement gates Native formal checking, with refinement only where supported and evidenced
--method-proof-only Explicit ESC against method contracts without architecture/refinement Narrows the stated scope; it does not add missing backend capabilities

The returned stage evidence is authoritative. Profile names do not make evidence interchangeable across languages. Java standard assurance is not Java critical assurance; a passing runtime sample is not deductive proof. S06 S07 S08

Step 4 — Review, verify, and integrate

Inspect the complete candidate diff, not just the method body visible in a chat message. Verify the exact file you intend to merge. Retain the approved contract, output source hash, final verdict, actual execution observations when supplied, and any published receipt. Run your ordinary application tests as a separate check of integration requirements.

Do not automatically approve --accept-pass entries. Postprocessing can alter proof-relevant semantics; accepted transformations need explicit review, and the final artifact is checked against the supported trusted surface. S07 S12

6. Greenfield: reviewed V2 domain to source

Interface: operator-facing CLI workflow. The complete workflow is not admitted to default strict MCP. Java inspection or verification can be used separately under their own profiles; that does not authorize the surrounding steps. S48 S56

This route is for a bounded state machine whose semantics should drive multiple deterministic outputs. V2 uses typed integer/boolean state, guards, effects, frames, and invariants. The supported scope is smaller than an arbitrary programming language and rejects malformed or unsupported models. S13

Step 1 — Create a candidate

Interactive generation:

formalspecgen domain "A sequential bounded counter from zero through five" --schema-version 2 --provider ollama --project-root .

The default domain schema is 1, so explicitly choose 2 for this workflow. V1 is the older plugin/scaffold path; do not confuse its scaffold with a reviewed V2 artifact. The V2 workflow may already emit validation evidence. Revalidate after every candidate edit. S01 S20

The bundled alternative is domains/candidates/bounded_counter.v2.yaml. It is explicitly unreviewed and includes no fabricated promotion digest or signature. Its operations use void / unavailable: an operation is enabled only when its guard holds.

Step 2 — Validate by module name

formalspecgen validate-domain bounded_counter --project-root . --emit-tla evidence/BoundedCounter.tla

Pass the module name, not an arbitrary YAML path. This command has no --json option. Inspect the reported validation file, emitted model, reachable-state/bounds information, and counterexample or failure details. Validation checks the candidate; it does not supply human approval or prove correspondence to separately written source. S20 S21

Step 3 — Review the model and exact candidate identity

For the example, confirm the range [0, 5], initial value 0, one actor, increment/decrement guards, one-state-variable frame, and the absence of an implied “return false” or exception at the boundary. Review all changed bytes after the last validation. Read candidate_sha256 from that validation and verify it identifies the candidate you actually reviewed.

Promotion is deliberately a human checkpoint:

formalspecgen promote-domain bounded_counter --project-root . --schema-version 2 --accept-candidate-sha256 REVIEWED_64_HEX_DIGEST

Replace the placeholder manually with the reviewed digest. Do not automate “read latest hash and approve it” in an agent workflow. Use --replace-reviewed-domain only for an intentional reviewed replacement. --force during candidate work is not the same as authorization to replace a reviewed domain. S22

The promoted JSON is written under domains/v2/. Keep the candidate, its validation evidence, and promotion provenance together. An edit after validation invalidates the old evidence; an edit after promotion requires a new reviewed revision.

Step 4 — Deterministically render a reviewed domain

Run from the project containing domains/v2/:

formalspecgen draft "Render the reviewed bounded counter" --canonical-domain bounded_counter --lang java --out-file generated/BoundedCounter.java --no-clarify

The canonical route consumes the reviewed domain rather than asking an LLM to reinterpret it. The prose is still a required positional argument. Java, Rust, C, and C++ are selectable on this route; C++ drafting requires a canonical domain at this revision. S01 S23

Step 5 — Check implementation and source/model linkage

formalspecgen implement generated/BoundedCounter.java --provider ollama --assurance-level critical --v2-reviewed-domain domains/v2/bounded_counter.json --v2-validation-evidence domains/candidates/bounded_counter.v2.validation.json --out runs/counter-v2-001 --json evidence/counter-v2.json

Use the actual validation path reported locally. The two V2 arguments form a pair. They are not interchangeable with a generic architecture report. Native deterministic V2 outputs take a different verification path from free-form native synthesis; read the actual claim and unsupported-boundary reports. S06 S07 S08

Step 6 — Add traceability

formalspecgen generate-traceability-matrix domains/candidates/bounded_counter.v2.yaml src --reqs requirements.txt --out evidence/traceability.md --json evidence/traceability.json

Review unmatched or ambiguous rows. A matrix connecting REQ-### identifiers, invariants, and source locations is a review artifact, not a certificate that every requirement was implemented. S24

7. Brownfield: understand and specify an existing project

Interface: operator-facing CLI workflow. The complete workflow is not admitted to default strict MCP. Java inspection or verification can be used separately under their own profiles; that does not authorize the surrounding steps. S48 S56

The starting point is executable code and existing behavior, not a clean specification. Preserve the repository baseline and its tests before extracting or editing contracts.

Step 1 — Record the baseline and select a component

Use a branch or worktree and keep the original source revision. Identify externally visible behavior, error handling, persistent state, dependencies, and concurrency. Start with a component small enough to review rather than treating extraction output as a complete architecture.

Step 2 — Extract an inventory and candidate models

formalspecgen analyze-codebase src --out-dir extracted --project-root . --json evidence/extraction.json

This command can create unreviewed domain candidates and architecture/extraction reports. “EXTRACTED” is not “VERIFIED.” Read its limitations, skipped constructs, and source associations. Bounds, initial values, reset transitions, omitted calls, and approximated operations are review obligations. Do not overwrite your understanding of the production system with whatever subset the extractor recognizes. S25

Step 3 — Produce deterministic documentation first

formalspecgen document-code src/BoundedCounter.java --no-llm --out evidence/counter-documentation.md --project-root . --json evidence/documentation.json

This documents the application's extracted model. It does not generate this tool manual, establish extraction completeness, or prove the original source. Remove --no-llm and select a provider only when you also want an explanatory narrative; that narrative adds no formal evidence. S26

Step 4 — Reconcile the extracted model with reality

For each chosen candidate, review what is represented and what is not. Reconcile existing tests and requirements with the extracted guards/effects. Add or revise contracts deliberately, retaining a record of whether you are documenting established behavior or changing it.

Validate the candidate by its generated module name. Promotion can follow chapter 6 after review. Separately verify the original source against its reviewed contracts. A checked model and a checked source do not establish correspondence unless the supported refinement path also runs successfully. S20 S21 S22 S25

Step 5 — Decide between preservation and correction

Choose a preserving refactor when callers must retain the same contract. Choose a behavior-correction workflow when you intentionally change accepted inputs, limits, error handling, or side effects. Record the distinction before generating patches. Do not call stronger preconditions a harmless optimization: they can exclude calls that were previously allowed.

Adoption completion check: the component has a reviewed baseline, documented assumptions, a known supported proof scope, negative tests, a verification result for the source, and a separate record for any model validation/refinement. Proceed component by component. S12 S19 S27

8. Brownfield: refactor and optimize without changing the contract

Interface: operator-facing CLI workflow. The complete workflow is not admitted to default strict MCP. Java inspection or verification can be used separately under their own profiles; that does not authorize the surrounding steps. S48 S56

Inspection and targeted transformation

formalspecgen inspect src/Service.java --json evidence/service-inspection.json
formalspecgen apply-refactor src/Service.java --inspection evidence/service-inspection.json --pattern extract-method --method process --out refactored/Service.java --json evidence/refactor-action.json
formalspecgen verify-refactor baseline/Service.java refactored/Service.java --json evidence/preservation.json

These are application-specific templates: the bundled counter is intentionally too small to demonstrate a long-method extraction. Use a method the inspection actually identifies. The Java transformation consumes a source-hash-bound inspection; rerun inspection when the source changes. Candidate generation is not the preservation verdict. S18 S19 S28

The parser lists extract-method, factory-method, state, decorator, facade, null-object, and strategy. Their availability depends on the recognized source shape and language. Native transformation support is narrower: extract-method and a supported Rust strategy path. Do not assume every inspection finding has an automatic transformation.

For supported Java helper extraction, the candidate may be a directory of collaborating .java files. Keep the baseline's primary class filename and include the exact files to be checked. Private helpers are allowed within the supported boundary; new assumptions, skipped verification, or changed public contracts are not ordinary helper extraction. S12 S19

Optimization and multi-strategy discovery

formalspecgen optimize-algorithm baseline/TwoSum.java --strategy hashmap --out optimized/TwoSum.java --provider ollama --json evidence/optimization.json
formalspecgen discover-algorithms baseline/TwoSum.java --strategies hashmap,two_pointer --max-workers 1 --provider ollama --out-dir discovered --json evidence/discovery.json

Use a reviewed Java algorithm matching the lane's supported shape. The optimizer accepts nested_loop in its argument choices but rejects it as a potential regression; it is not a usable optimization recommendation. Discovery supports its own wider strategy registry, listed in the command reference. A verified candidate still needs separate performance measurements and integration testing. S29 S30

Two different meanings of “equivalence”

verify-bisimulation is only an input and public-surface preflight. Its mapping connects state labels to source class names. Its successful result remains NO_PROOF and explicitly reports that behavior/heap equivalence was not proved. The bundled mappings/preflight.json demonstrates that schema. S31

formalspecgen verify-bisimulation baseline/BoundedCounter.java refactored/BoundedCounter.java mappings/preflight.json --json evidence/preflight.json

prove-equivalence checks finite V2 transition systems against an explicit relation. Its mapping schema is different: an object with a states list of baseline_state / refactored_state pairs. S32

formalspecgen prove-equivalence domains/candidates/bounded_counter.v2.yaml models/equivalent_counter.v2.yaml --mapping mappings/states.json --json evidence/model-equivalence.json

The bundled example uses the identity relation on values zero through five. A successful bounded-model result does not prove Java heap equivalence, timing, external I/O behavior, or arbitrary program equivalence.

9. Architecture, composition, and system workflows

Interface: operator-facing CLI workflow. The complete workflow is not admitted to default strict MCP. Java inspection or verification can be used separately under their own profiles; that does not authorize the surrounding steps. S48 S56

There are several architecture-related artifact types. They are not aliases for the same JSON schema.

Artifact Producer / consumer Main purpose
Source-derived behavioral model architecture SOURCE Supported source abstraction and bounded checking
Design architecture design-system Generated component/dependency proposal
Staged UnifiedArchitecture design-system --staged → validate-architecture Typed staged architecture and validation
CompositionSpec Hand-reviewed plan → compose / reverify Bind reviewed domains and sequence their operations
System implementation/refactor/correction plan system --mode ... Coordinate per-component work

These paths have distinct validation and evidence ceilings. S09 S33 S34 S35

9.1 Source-level architecture checking

formalspecgen architecture src/Component.java --clarifications "Two actors; each modeled operation is atomic." --abstraction atomic_operations --emit-tla evidence/Component.tla --json evidence/architecture.json

The source must match a supported domain adapter. --clarifications is text, not a path to a file. lock_protocol is an alternative abstraction only when the input and assumptions support it. The model's bounds and operation-level atomicity are part of the evidence. Failure to find an adapter is not permission to silently invent one. S33

9.2 Design and staged lowering

formalspecgen design-system "A small counter service with explicit component boundaries" --provider ollama --staged --lang java --out-file plans/architecture.json --json evidence/design.json
formalspecgen validate-architecture plans/architecture.json --json evidence/architecture-validation.json
formalspecgen unified-system plans/architecture.json --evidence evidence/architecture-validation.json --lang java --out-dir generated/system --json evidence/unified.json

These commands require the actual generated typed artifact and its matching validation. design-system has a provider option but no --model option at this revision. A lowerer's successful LOWERED result is not synonymous with implementation verification. S01 S34 S35

Native-language distinction: unified-system --lang rust|c|cpp currently routes to the native composition checker, expects a composition-shaped artifact, and does not consume --evidence even though the parser requires it. Use compose --lang ... for native composition rather than assuming Java's staged-evidence workflow applies unchanged. S01

9.3 Compose reviewed domains

After the example domain has been validated, reviewed, and promoted:

formalspecgen compose plans/composition.json --v2-dir domains/v2 --lang java --out-dir generated/composition --json evidence/composition.json

A composition plan has system_name, architecture, bindings, and use_cases. Each binding connects a declared component ID to a promoted module. Each use case names ordered steps. The bundled plan uses one reviewed counter component with separate increment and decrement use cases. It is not a pre-proved composition. S09

The core Java boundary is sequential atomic composition with at most one operation from a component in each use case and supported void/unavailable semantics. External ports need explicit contracts; proof of the caller is not proof of a remote payment provider or device. --no-esc intentionally stops short of the deductive composition gate. S09 S36

After a reviewed module changes:

formalspecgen reverify plans/composition.json --changed-module bounded_counter --v2-dir domains/v2 --json evidence/reverification.json

This is dependency-aware impact and rechecking, not permission to reuse stale evidence. The command has no --lang flag. S01 S36

9.4 Coordinate implementation workers

The bundled plans/system-implement.json embeds the composition and identifies each component's contract source, reviewed domain, and matching validation file. Render the canonical source first.

formalspecgen system plans/system-implement.json --mode implement --max-workers 1 --out-dir runs/system-001 --json evidence/system-001.json

Implementation plans must cover the composition's component bindings. Start with one worker when sharing a local model or scarce verifier resources. Parallel generation is not proof of concurrent system execution. S10

The other mode shapes are different. Templates are supplied under examples/templates/:

formalspecgen system plans/system-refactor.json --mode refactor --max-workers 1 --out-dir runs/refactor-system-001 --json evidence/refactor-system.json
formalspecgen system plans/system-correct.json --mode correct --provider ollama --max-attempts 3 --max-workers 1 --out-dir runs/correct-system-001 --json evidence/correct-system.json

Copy and customize the templates before use. Refactor entries identify a file, pattern, and method. Corrective entries identify a file and weakness. --provider / --model are forwarded to corrective workers, not to implement workers by this handler; implement workers use their own defaults and inherited environment. Review each component verdict and the aggregate composition result. S01 S10

10. Security assessment, remediation, and intentional correction

Interface: operator-facing CLI workflow. The complete workflow is not admitted to default strict MCP. Java inspection or verification can be used separately under their own profiles; that does not authorize the surrounding steps. S48 S56

Use these workflows only for code you own or are authorized to assess. Keep assessment reports, proposed patches, and any test templates tied to the exact target revision.

Assess and triage

formalspecgen security-inspect src/Service.java --json evidence/vulnerabilities.json
formalspecgen assess-security src/Service.java --json evidence/security-assessment.json

security-inspect differs from the deterministic inspect: it can invoke formal/security tools and prepares a vulnerability report. Its zero exit means the report was produced, not that there are no findings. assess-security --no-sast explicitly reduces scope. Even a scoped VERIFIED_SECURE result is not immunity from every weakness. S01 S37

Generate review-only tests for findings

formalspecgen security-exploit evidence/vulnerabilities.json src/Service.java --out-dir security-pocs --json evidence/poc-generation.json

This generates supported local proof-of-concept source templates. The status can be POCS_GENERATED while the claim is POC_GENERATED_NOT_EXECUTED. The command does not compile, run, or transmit those templates. A generated test is not a demonstrated exploit. Review and authorize any subsequent execution separately. S38

Patch while reviewing the original contract

formalspecgen remediate src/Service.java evidence/vulnerabilities.json --provider ollama --out-dir remediated --json evidence/remediation.json

The workflow writes a separate candidate. Review the diff, the report's provenance, and the native verdict. A successful patch verification does not automatically establish preservation of all original behavior or prove that every reported issue was addressed. Use the preservation workflow separately when that is required. S39

Deliberately change behavior

formalspecgen correct-behavior src/BatchRunner.java --cwe CWE-400 --strategy bound-loop --provider ollama --out-dir corrections --json evidence/correction.json

This is not a preserving refactor. It can strengthen contracts or introduce bounded/error behavior. The explicit strategy choices are:

Strategy Review focus
bound-loop, bounded-cache, bounded-pool Chosen limits and what happens at capacity
static-pool Hardware profile, element size, derived capacity, and allocation behavior
checked-math Overflow/error semantics
lock-timeout Timeout and recovery behavior
canonicalize Accepted/rejected representations and trust boundary
fail-safe Failure state and its externally visible consequences
immutable-snapshot Snapshot lifetime and consistency assumptions

A strategy is accepted only for its supported source shape. --auto-strategy is an explicit alternative to selecting one. Hardware inputs are reviewed data, not something an LLM may fabricate. CAPACITY_BOUND_CANDIDATE_GENERATED can be a successful command outcome while still requiring review and subsequent proof. S27

11. Specialized verification workflows

Interface: operator-facing CLI workflow. The complete workflow is not admitted to default strict MCP. Java inspection or verification can be used separately under their own profiles; that does not authorize the surrounding steps. S48 S56

Each specialist command is an operator-facing workflow. Its existence does not add it to strict MCP or imply the native backend is sandbox-migrated. Inputs below are application-specific templates, not universal examples. Use the complete command reference for all flags.

Heap structures and hardware boundaries

Command Supported purpose Main limitation
verify-heap Supported Rust Box/heap structures or C intrusive-list reasoning Profile-specific shape and trusted boundary; not arbitrary pointer programs
verify-hal C/header MMIO/HAL patterns under declared assumptions Verification is about the model and access rules, not physical device behavior
macro-dictionary Load or propose macro meanings and check the resulting model A translated model does not itself establish source refinement
formalspecgen verify-heap src/list.rs --provider ollama --json evidence/heap.json
formalspecgen verify-hal src/device.c --json evidence/hal.json
formalspecgen macro-dictionary models/macros.json --source src/protocol.c --json evidence/macros.json

macro-dictionary --synthesize requires source and proposes a dictionary that must be reviewed. --no-verify explicitly omits model proof. Existing heap predicates or explicit invariants can avoid a generation step where supported. S40 S41 S42

Concurrency and distributed models

formalspecgen verify-lockfree src/spsc.c --json evidence/lockfree.json
formalspecgen verify-linearizability src/ConcurrentCounter.java --domain models/lock_counter.v2.yaml --json evidence/linearizability.json
formalspecgen verify-distributed models/protocol.v2.yaml --message-fields slot0,slot1 --faults message_loss,duplication,reordering --json evidence/distributed.json

The lock-free lane is for a supported C single-producer/single-consumer ring and bounded interleaving checks. Do not infer arbitrary weak-memory correctness or wait-freedom. The Java linearizability lane needs the supported lock-protocol model and source correspondence. Distributed checking requires an async_message_passing V2 model and real state fields representing messages; its result concerns bounded safety under the selected faults, not delivery guarantees or liveness. S43 S44 S45

Reviewed V2 async lowering to Rust can produce a Tokio scaffold and a static result. It does not automatically establish asynchronous source refinement or linearizability. The optional implement --parallel-wrapper rayon --parallel-kernel NAME route concerns a supported scalar kernel and partition boundary; it does not prove the Rayon scheduler. Treat external-adapter injection options the same way: generated glue is not proof of Stripe, AWS, curl, or a kernel device. S06 S46

Supported loop induction

formalspecgen verify-unbounded src/loop.c --invariant "i >= 0 && i <= n" --json evidence/induction.json

Supply an invariant with the actual program identifiers. Without one, the provider may propose it. The command checks establishment and preservation for supported simple-loop extraction. A successful induction result is not automatically a termination proof, whole-program correctness, or support for arbitrary nested loops. S47

12. Use MCP with AiderDesk and Qwen

12.1 Keep the two roles separate

AiderDesk and its Qwen endpoint propose edits and request tools. FormalSpecGen's strict MCP service exposes two specific profiles, not unrestricted access to the corresponding CLI families.

Tool / profile Public tool arguments Admitted invocation Effects and outputs
inspect_code / java-readonly-inspection file_path Java; internal mode inspect; builtin-java-inspector workspace_read; findings plus admission metadata; no proof receipt
verify_code / java-openjml-verification file_path, mode (default esc) Java/JML; parse, check, esc; OpenJML workspace_read, external_execution, evidence_publication; execution observation and committed receipt

Both profiles have an empty provider allowlist. Neither permits ordinary workspace writes. Verification may publish new immutable evidence, which is a separate permission. These backend, effect, and profile fields are selected by the server; they are not additional client arguments to add to tool calls. S03 S48

Unsupported direct and indirect workflows fail closed. doctor_environment, native verification, implementation, refactoring, and system orchestration remain blocked. Human trust actions have no agent-admissible profile. Keep FORMALSPECGEN_MCP_STRICT_JAVA_ONLY at its default or set it to 1. S48 S57

12.2 Register a separately pinned service

In AiderDesk, add a project-scoped MCP server and then enable it in the intended Agent Profile. Use Ask approvals initially. The template below needs real absolute paths and an administrator-provisioned cgroup parent. S49

{
  "mcpServers": {
    "formalspecgen": {
      "command": "/ABSOLUTE/PINNED_INSTALL/.venv/bin/python",
      "args": ["-u", "/ABSOLUTE/PINNED_INSTALL/mcp_server.py"],
      "env": {
        "FORMALSPECGEN_MCP_STRICT_JAVA_ONLY": "1",
        "OPENJML_BIN": "/ABSOLUTE/OPENJML_HOME/openjml",
        "OPENJML_HOME": "/ABSOLUTE/OPENJML_HOME",
        "FORMALSPECGEN_CGROUP_ROOT": "/sys/fs/cgroup/ADMIN_DELEGATED_PARENT"
      }
    }
  }
}

The project file is .aider-desk/mcp-servers.json. AiderDesk launches local MCP processes in the active task directory/worktree; FormalSpecGen uses that working directory as the workspace root. Keep application paths relative to the task, while the installed server path remains fixed. No public HTTP endpoint is needed for this local process connection. S03 S49

Keep the server installation, configuration, and authoritative evidence out of the agent's editing authority. A restricted MCP catalogue does not restrict AiderDesk's independent shell tool; control that separately. Selecting the correct Qwen model in the Agent Profile is necessary, and the serving endpoint must return structured tool calls rather than prose that resembles a function call.

12.3 Run a complete client smoke test

First confirm that the client lists exactly the two expected FormalSpecGen tools. Then request a tool call with arguments such as:

{"file_path": "src/BoundedCounter.java", "mode": "esc"}

Exercise the known-good and deliberately bad fixtures. Ask for a Rust/C input and confirm rejection without a shell retry. Check that Qwen accurately reports status, claim, request_satisfied, execution-policy compliance, mcp_admission, and the receipt. Validate the saved structured response using the chapter 13 helper with --require-admission. The backend acceptance tests are valuable, but direct Python handler tests are not an actual MCP transport or client-session test. S03 S04

The supplied examples/templates/pilot-agent-instructions.txt makes these expectations explicit. It is guidance for the model, not a replacement for enforced server policy.

12.4 Do not confuse proof with preservation

verify_code verifies the submitted file. It does not compare it with a baseline. For this pilot, require human review of all specification, assumption, annotation, import, constant, and declaration changes. A candidate that proves after its requirement was weakened has not established the original requirement. Keep preserving refactors in the separately operated CLI workflow until an appropriately isolated server route is available. S03 S12

12.5 Understand permission attenuation

A matching profile defines the maximum permissions available, not an automatic grant of them all:

Granted effects = Explicitly requested effects ∩ Profile effects
Boundary allowed = Required effect is in granted effects

For example, an internally admitted request that asks only for workspace_read cannot execute a verifier or publish evidence, even if its matching profile supports those effects. Unknown effects, wrong modes/backends, or disallowed providers do not become partial approvals. The current verify_code handler requests all three verification effects; inspect_code requests reading alone. S03 S55 S58

There is no --effects CLI flag or MCP effects argument in this baseline. Narrower requests are an internal integration mechanism; the eight effect-subset tests check that omitted permissions cannot reappear later. See the admission field guide for definitions, failure handling, and the requirements for admitting future workflows. S58

13. Publish, validate, and review evidence

Distinguish the output kinds

An ordinary --json output is a verdict file. A ledger-backed run contains an evidence/ directory, run identity artifact, transition artifacts with a hash chain, and a terminal manifest. The strict Java MCP response additionally returns an evidence receipt identifying the manifest. Not every CLI command publishes that same receipt. S03 S11

A typical strict MCP layout is:

.formalspecgen/mcp-evidence/<run-directory>/
└── evidence/
    ├── run.json
    ├── 001-....json
    ├── ...
    └── manifest.json

The terminal manifest is published last. An incomplete run is not a successful evidence-bearing result. Publication failure downgrades the strict MCP outcome rather than silently returning a proof without its required receipt. The receipt is the MCP response’s evidence object and contains run_id, manifest_path, manifest_sha256, and publication_status. S03 S11

Validate a receipt with trusted tooling

There is no built-in formalspecgen validate-evidence command at this revision. The package supplied with this guide includes an auxiliary tools/validate_receipt.py wrapper around the actual RunLedger.validate API. Run it from a trusted tool environment, not as arbitrary code supplied by the candidate.

python /path/to/guide/tools/validate_receipt.py evidence/mcp-response.json --evidence-root .formalspecgen/mcp-evidence --require-admission

The input can be the saved structured MCP response or its receipt object, not a chat transcript or the outer JSON-RPC envelope. The script checks that the manifest is inside the specified evidence root, matches the received digest, and agrees on run identity, then calls the ledger validator. With --require-admission, it also checks the manifest's admission summary against the two-profile snapshot bundled for 91c6790, recomputes the profile digest, verifies requested/granted-effect consistency, and compares response metadata when present. For an independently retained manifest digest, add --expected-manifest-sha256 DIGEST.

A successful ledger validation establishes internal consistency with the selected receipt, not authenticity against a privileged attacker who can replace both the ledger and the receipt. Retain a trusted copy of the receipt/digest, or use your signing and storage policy. The publication guarantee is application-level write-once/no-replace, not a claim that a host administrator cannot alter the filesystem. S11

Read the admission fields in evidence

The response's mcp_admission object is also stored at terminal.mcp_admission in the manifest and details.mcp_admission in the proof-stage artifact. The receipt itself remains the small evidence object; policy metadata is not a replacement receipt. S03

Field inside mcp_admission Review meaning
profile Named invocation profile, not a whole-command safety label
mode, language, backend, provider Selected invocation; current admitted provider is JSON null
requested_effects Effects explicitly requested by the handler
granted_effects The request/profile intersection; never infer missing permissions
profile_definition Canonical ceiling: name, modes, languages, backends, effects, providers, output scope, evidence requirement
profile_sha256 SHA-256 of the canonical definition's compact, sorted-key UTF-8 JSON
admission_policy_version mcp-admission-v2 for this baseline; distinct from package and guide versions

Array-valued fields in the canonical definition are sorted and deduplicated. The digest uses ensure_ascii=False and separators (',', ':'). A policy name may remain constant while its contents change, so retain the definition and digest together. S55

The helper's success means receipt/ledger integrity and, when requested, agreement with this edition's approved policy snapshot. It does not rerun the proof, authenticate an attacker-replaceable receipt, approve the specification, or compare the source with your independent baseline. Legacy evidence without admission metadata may still be checked in integrity-only mode, but it must not be described as satisfying the new policy check. An upgrade to profiles or policy version requires an explicit review and a matching guide/helper update.

Review the result and the execution separately

Before accepting a verification result, establish that the requested mode and proof scope succeeded, that required execution policy was enforced, that the receipt validates, and that the recorded source snapshot is the revision being reviewed. Resource failures, instrumentation-startup failures, missing tools, unsupported syntax, and publication failures remain NO_PROOF rather than candidate counterexamples. S03 S15 S50

Use unique run/output roots. Do not delete an earlier manifest merely to make a rerun succeed in the same directory. Mutable reports and “latest” convenience paths are not authoritative evidence identities.

Reviewer keys and signed artifacts

formalspecgen manage-trust --add-key reviewer-public.asc
formalspecgen manage-trust --list
formalspecgen sign-artifact domains/v2/bounded_counter.json --key REVIEWER_KEY_ID

These are human-operated actions. GPG must be installed and the signing key must be available through your approved key-management process. Promotion can sign with --signing-key; verify-refactor --signing-key requires a JSON destination. S22 S51

The default registry is trusted_keys.json; AUTHORIZED_REVIEWER_KEYS contributes to the authorized set. A custom manage-trust --registry file is not automatically selected by every downstream caller. Configure the registry at the location actually consumed by your verification path. With no authorized-key policy, signature verification can accept any verifying key; signature validity alone is not an approved-reviewer policy. FORMALSPECGEN_REQUIRE_SIGNATURES=1 enables the composition signature gate, not a universal signature requirement for every command. S09 S51

14. Automate safely in development and CI

Use command outcomes, not generic success assumptions

For direct verify, the exit status reflects whether the requested semantic decision is satisfied. Other commands have different contracts: documentation/extraction can succeed without proof; security-inspect can succeed while reporting findings; verify-bisimulation can succeed at preflight only; and a correction can successfully generate an unproved capacity candidate. S01 S04 S31

For every automated job, define the expected workflow result before running it. Parse the relevant structured fields. Fail on absent, unknown, or weaker claims rather than treating them as compatible. Save stderr, the exact invocation, tool versions, source revision, and evidence references. Run negative tests as well as positive tests.

A small application-level gate

set -eu
mkdir -p evidence
formalspecgen verify src/BoundedCounter.java --mode esc --json evidence/verification.json
formalspecgen verify-refactor baseline/BoundedCounter.java refactored/BoundedCounter.java --json evidence/preservation.json

This is a shell fragment for the bundled demo on a provisioned runner. It is not a declaration that ordinary CLI JSON has an MCP receipt. Do not add || true to these release gates; handle deliberate negative tests in separate jobs or explicit expected-failure assertions.

Keep real acceptance tests mandatory on the provisioned runner

The pinned repository separates the Python matrix, strict-offline Rust checking, and real Linux sandbox/OpenJML acceptance. The strict-offline stage prefetches locked Cargo dependencies first, then enforces offline checking. The sandbox job must have its actual prerequisites; missing prerequisites should fail that job rather than hide behind a skip. S04

FORMALSPECGEN_REQUIRE_SANDBOX_ACCEPTANCE=1 \
FORMALSPECGEN_REQUIRE_OPENJML_MCP_ACCEPTANCE=1 \
python -m pytest -q --no-cov tests/test_sandbox_acceptance.py tests/test_mcp_openjml_acceptance.py

Run this from the tool checkout, not the application. It needs the same resource delegation and tool setup as the pinned workflow. Do not copy CI-only host-policy adjustments into a shared desktop or production service without administration review.

Retain admission regressions alongside backend acceptance

python -m pytest -q --no-cov tests/test_mcp_admission_policy.py tests/test_mcp_effect_attenuation.py tests/test_mcp_isolation_dispatch.py

Run these from the pinned tool checkout. They check routing, incoherent profiles, and permission boundaries, including all eight verification-effect subsets. They do not replace the real backend tests above or a client transport smoke test. Review profile definitions and digests whenever policy changes, even when the two-tool catalogue is unchanged. S57 S58

Review gates for a merge

A practical merge record contains the original requirement and contract revision, approved semantic changes, exact candidate/source snapshot, verdicts at the requested scope, independent tests, validated evidence references, and remaining limitations. High unit-test coverage of FormalSpecGen does not establish the correctness of a newly generated application.

15. Use the interactive shell

Starting formalspecgen without a subcommand enters the interactive shell. It stores session state under .formalspecgen/session.json and history under .formalspecgen/history. Session state is convenience context, not proof evidence. /reset resets the session; it is not a guaranteed history or secret purge. S01

Shell instruction Purpose
/help Interactive help
/session Show current session context
/reset Reset saved session state
/quit or /exit Leave the shell
EOF or Ctrl-C Exit

The shell recognizes slash commands, plain recognized commands, and pasted formalspecgen ... forms. It supports backslash continuation. At this revision it recognizes 28 CLI command names:

doctor draft implement verify verify-refactor discover-algorithms
inspect apply-refactor architecture design-system domain validate-domain
promote-domain sign-artifact manage-trust verify-heap verify-hal
verify-distributed macro-dictionary verify-lockfree verify-linearizability
verify-unbounded prove-equivalence generate-traceability-matrix compose
reverify system document-code

Important: unrecognized input is treated as natural-language drafting. The full CLI has more commands than this REPL dispatch set. Use an ordinary shell for optimize-algorithm, assess-security, security-inspect, security-exploit, remediate, correct-behavior, verify-bisimulation, validate-architecture, unified-system, and analyze-codebase. Do not assume that an unrecognized slash command will fail as a CLI command. S01

For deterministic automation, use explicit CLI commands rather than the session-driven shell. Promotion and trust changes remain deliberate human actions even when entered interactively.

16. Troubleshooting and recovery

Symptom Likely boundary Safe next action
command not found: formalspecgen Wrong environment or missing editable install Activate the intended environment and check its Python/pip/entry point.
A flag is unrecognized Flag belongs to a different command, version, or REPL subset Run that exact subcommand's --help; compare the pinned reference.
SANDBOX_UNAVAILABLE Bubblewrap/namespaces cannot establish the required policy Repair the execution host; do not invoke the backend unrestricted.
RESOURCE_CONTROL_UNAVAILABLE Missing/delegation-incompatible cgroup parent Ask the administrator to check controllers, permissions, and process placement.
Memory, process, storage, time, or output limit failure Execution infrastructure budget, not a proof counterexample Inspect the observation; adjust an approved profile or reduce the workload.
Instrumentation cannot initialize Runtime/tool setup failure Fix the tool environment; do not regenerate code solely from this failure.
ISOLATION_UNSUPPORTED in MCP No matching command/mode/language/backend/provider/effect profile Read the rejection reason, retain NO_PROOF, and correct the request or escalate to the operator; do not relax strict mode.
Expected CLI tool is absent from MCP Default catalogue admits only two profiles Use the availability matrix; a handler, --no-llm, or an installed judge does not grant admission.
An effect boundary rejects an otherwise matched profile That invocation did not request the required effect Treat as an integration failure; do not substitute the profile ceiling for granted effects.
ADMISSION_INVALID from the guide helper Missing/incoherent metadata, changed profile, or policy-version mismatch Preserve the evidence; compare pinned installations and review any policy upgrade. Do not bypass with fabricated metadata.
doctor_environment is blocked Readiness checks execute tool probes Run operator-facing formalspecgen doctor; do not label it non-executing.
OpenJML/TLC/native judge missing Package installation did not install all backends Configure the exact tool bundle and rerun readiness checks.
API_ERROR or provider failure Endpoint, authentication, served model, context, or response problem Test the chosen endpoint and exact model ID; keep any fallback explicit.
Draft passes but implementation fails Drafting performed checking, not an implementation proof Inspect the actual ESC obligations; preserve the reviewed contract.
No architecture adapter / unsupported boundary Input outside the modeled subset Select an explicit narrower scope or develop/review an adapter; do not relabel no-proof as proof.
Contract-surface or proof-trust mismatch Candidate changed semantics, trust, or unsupported syntax Review the complete diff; restore the approved contract or create a new reviewed revision.
V2 promotion hash mismatch Candidate changed after validation/review Revalidate, review the new revision, and accept its exact identity.
Signature passes but reviewer is wrong Authorized-key policy is missing or misconfigured Configure the actual consumed registry/authorized keys and recheck.
Existing evidence directory / no-replace failure A run identifier/path is being reused Allocate a fresh run root and retain the old evidence.
Receipt or manifest validation fails Incomplete, changed, mismatched, or unavailable evidence Reject the receipt and investigate; rerun from trusted inputs if needed.
Optimization verified but slower Correctness was checked, performance was not Benchmark representative workloads separately.
Security report exits zero with findings Report creation succeeded Apply your finding/claim policy, not generic shell-success logic.

When reporting a tool issue, include the pinned commit, command, language/mode, sanitized environment/tool versions, source or minimal authorized reproduction, structured verdict, execution status, and receipt reference. Do not include API keys, private signing material, or unrelated application secrets.

17. Coverage, maintenance, and extension boundaries

What “all commands” means in this edition

The companion reference covers every command registered by pipeline.cli.build_parser() with its default arguments at 91c6790: 38 commands, 205 command-specific positional/option declarations, plus automatic help and the top-level version flag. Common provider/model options are counted per consuming command. It also distinguishes the 28-name REPL set and strict two-tool MCP catalogue. S01 S02 S03

Some repository descriptions mention broader MCP exposure or additional specialist names. Module functions, old documentation examples, unregistered plugins, and historical names are not automatically executable CLI commands. Use the pinned parser and strict registration as the authority. There is a command-plugin interface for explicitly supplied plugins; the default main() does not automatically discover and load arbitrary plugins. S01 S48

Keep the guide aligned with future commits

The supplied tools/check_command_coverage.py reads a local pipeline/cli.py with Python's AST module and compares command names, positional/option declarations, and supported literal parser settings with docs/command_inventory.json. It does not import FormalSpecGen or execute backends.

python /path/to/guide/tools/check_command_coverage.py /path/to/formalspecgen

Treat a detected change—or an unsupported parser construct—as a request for source review, not an automatic documentation update. The inventory is a source-inspected transcription; neither intervening commit changes pipeline/cli.py. The checker has not been run against a full checkout during this update. It is supplied so maintainers can make that comparison locally.

When upgrading the guide, review the parser, handler behavior, strict MCP registration, native dispatch, result/claim policy, evidence schema, supported grammar, and acceptance tests. Update worked examples and add a changelog entry. Review docs/admission_profiles.json, canonical profile digests, and the admission-policy version separately from command counts; unchanged CLI flags do not imply unchanged MCP authority. Never carry forward a proof claim simply because the command's name stayed the same.

Files in this documentation pack

File Purpose
docs/USER_GUIDE.md Workflow-oriented operating manual
docs/COMMAND_REFERENCE.md Complete built-in command/option reference
docs/command_inventory.json Machine-readable command inventory with strict-MCP availability
docs/MCP_ADMISSION.md User-facing admission rules, effects, evidence, and future-profile boundary
docs/admission_profiles.json Pinned two-profile snapshot used by the auxiliary receipt check
docs/CHANGELOG.md Edition baseline and change history
docs/FORMALSPECGEN_USER_GUIDE.html Self-contained browsable guide plus command reference
examples/guide_demo/ Positive/negative Java revisions, unreviewed V2 input, mappings, composition plan
examples/templates/ Strict MCP configuration, agent instructions, provider and system-plan templates
tools/check_command_coverage.py Local parser/documentation drift checker
tools/validate_receipt.py Auxiliary trusted ledger/receipt and admission-metadata validator
tools/check_pack.py Documentation-only examples, syntax, link, and inventory checks
docs/VALIDATION.md What was and was not tested while preparing this pack

18. Source register

Repository sources below are pinned to 91c6790. The external AiderDesk documentation is a current setup reference, not part of that commit. Source identifiers are used throughout this guide; code examples and explanatory wording are newly written unless explicitly identified as API values.

S01 CLI parser, handlers, REPL, and plugin registration.

S02 Packaging and installation requirements.

S03 MCP registration, strict dispatch, and receipts.

S04 Provisioned CI and real acceptance tests.

S05 Drafting orchestration.

S06 Implementation routing and special paths.

S07 Trusted implementation synthesis and final checks.

S08 Assurance profiles.

S09 Composition schema and supported boundary.

S10 Component system orchestration.

S11 Immutable ledger and validation.

S12 Java/native semantic preservation surfaces.

S13 Typed V2 domain schema.

S14 Environment and tool configuration.

S15 Sandbox, cgroup, snapshot, and resource policy.

S16 Readiness reporting.

S17 Provider selection and generation transport.

S18 Deterministic Java inspection.

S19 Single-file and multifile preservation gate.

S20 Domain creation and CLI validation/promotion lifecycle.

S21 V2 validation.

S22 V2 promotion, hashes, and signing.

S23 Canonical deterministic drafting.

S24 Requirements traceability.

S25 Brownfield extraction.

S26 Source documentation.

S27 Intentional behavior correction.

S28 Targeted refactoring actions.

S29 Algorithm optimization.

S30 Algorithm discovery.

S31 Bisimulation input preflight.

S32 Bounded V2 equivalence checking.

S33 Source-derived bounded architecture.

S34 Architecture design.

S35 Unified-system lowering.

S36 Composition rendering and impact re-verification.

S37 Formal/security assessment.

S38 Security reports and non-executed PoC templates.

S39 Defensive patch generation.

S40 Heap verification profiles.

S41 HAL/MMIO verification.

S42 Macro dictionaries and model checking.

S43 Supported bounded lock-free checking.

S44 Bounded linearizability.

S45 Distributed bounded safety.

S46 Rust async scaffold checking.

S47 Supported loop induction.

S48 Capability classification and isolation metadata.

S49 AiderDesk MCP setup (external, unpinned).

S50 Centralized verification decisions.

S51 Authorized reviewer registry.

S52 Native semantic bindings and literal preservation.

S53 Real strict OpenJML/MCP acceptance.

S54 Real sandbox tool/storage acceptance.

For native preservation details, see S52. The real proof and execution acceptance fixtures are S53 and S54. This manual does not claim that tests were rerun against the reader’s installation.

S55 Invocation admission, permission attenuation, and canonical profile digest.

S56 Upstream strict MCP admission guide.

S57 Admission mismatch and effect-boundary regressions.

S58 All effect-subset and policy-digest regression tests.

S59 Public CI summary for 91c6790 (not a local rerun).

S60 Invocation-policy change and unchanged CLI lineage.

S61 Permission-attenuation change.

MCP admission & permissions

User-guide edition 1.1 · FormalSpecGen revision 91c6790 · Admission policy mcp-admission-v2

This field guide accompanies the operating guide and complete CLI reference. It explains the current user-facing boundary and how to review the policy metadata returned by a tool. It is not a mechanism for installing or granting new server permissions.

A1. Choose the interface before the workflow

The full CLI remains available to an operator. Strict MCP is a smaller interface: it admits particular combinations of command, mode, language, backend, provider policy, and effects. Installing a judge, enabling a tool in a client, or finding a Python handler does not create an admitted combination. S01 S48

Task Strict MCP at this revision Other supported route
Inspect Java inspect_code CLI inspect
Parse, check, or prove submitted Java/JML verify_code; parse, check, esc respectively CLI verify
Diagnose tools Not admitted: doctor_environment launches probes Operator CLI doctor
Create contracts or implementations Not admitted Greenfield CLI recipes in chapters 5–6
Extract, document, refactor, or optimize a repository Not admitted Brownfield CLI recipes in chapters 7–8
Check native or composed systems Not admitted Scoped CLI workflows in chapters 9–11
Promote, sign, or change reviewer trust Human-only; cannot acquire an MCP profile Reviewer-operated CLI

The current profiles do not call a FormalSpecGen LLM provider. Qwen's access through AiderDesk is a separate client-side configuration and data-flow decision. No provider setting in the shell changes these profiles into generation workflows. S03 S17 S48

A2. Permissions are independent

Effect name What it authorizes Current profile use
workspace_read Read an approved input inside the workspace boundary Both tools
external_execution Reach the admitted compiler/verifier execution path Java/JML verification only
evidence_publication Publish a new immutable verification ledger and receipt Java/JML verification only
workspace_write_new Produce ordinary new artifacts in a designated output scope Not granted by current profiles
provider_access Contact an explicitly allowed provider Not granted by current profiles

Publishing verification evidence is not permission to edit source files. Read-only inspection is not permission to invoke version probes. A future deterministic generator would still need write authorization; a future LLM-assisted generator would additionally need provider authorization. Those are future admission decisions, not enabled modes in this release. S16 S48 S56

The loader rejects profiles with unknown effect names or output scopes, providers without the corresponding permission, provider access without an allowlist, writes without the designated output scope, and external execution in a non-executing classification. Trust actions cannot receive profiles. S48 S57

A3. Understand request-level attenuation

A profile is a ceiling. A successful internal admission receives only the effects explicitly requested within it:

granted_effects = requested_effects ∩ profile.effects

For the verification ceiling, a request containing only workspace_read remains read-only. Execution and publication checks reject it. For a rejected admission, the granted set is empty. The effect-subset tests cover all eight combinations of the three verification effects. S58

The public tools do not accept an effects, backend, provider, or profile argument. The server's verify_code handler requests reading, execution, and evidence publication together. inspect_code requests reading only. Send only the documented tool arguments: S03

{"file_path": "src/BoundedCounter.java", "mode": "esc"}

For inspection, send only file_path. Do not add policy fields copied from returned metadata. Adding an unknown or disallowed effect internally is a rejection, not a request that is quietly trimmed into permission. S55

A4. Interpret admission and evidence together

mcp_admission identifies the selected profile and invocation, the requested and granted effects, the canonical definition, its SHA-256, and the policy version. In a published verification run, the same summary appears in the response, manifest terminal metadata, and proof-stage details. Inspection returns findings and admission metadata, not a verification receipt. S03 S55

Use the metadata as an audit record, not as a capability token to submit with a later call. A profile digest identifies contents; it is not a reviewer signature. A committed receipt identifies publication; it does not establish that the proof succeeded or that you approved the specification.

The example examples/templates/admission-metadata.example.json contains illustrative metadata derived from the pinned profile. It deliberately has no run identifier, proof result, manifest, or receipt.

To check a real saved response from your deployment:

python /path/to/guide/tools/validate_receipt.py \
  /path/to/mcp-response.json \
  --evidence-root /path/to/project/.formalspecgen/mcp-evidence \
  --require-admission

This is a guide-pack helper, not a FormalSpecGen subcommand. It validates receipt/ledger consistency with the trusted installation and checks admission metadata against docs/admission_profiles.json. Retain the guide/helper and any independently trusted manifest digest outside the agent's editing authority. The helper does not rerun a verifier, establish receipt authenticity, or decide whether the submitted contract is the right requirement.

A5. Handle rejections without widening authority

A profile mismatch returns ISOLATION_UNSUPPORTED, NO_PROOF, and an unsatisfied request. A concrete boundary can also reject an omitted effect even after profile matching. An unavailable cgroup, tool failure, or failed publication is a different operational failure; neither permits unrestricted fallback. S03 S55

Keep the failed result and its diagnostics. Correct an accidental mode or path, or ask the operator to repair the host. Do not set strict mode to 0, substitute a legacy route, or ask the agent's shell to perform the same blocked workflow. AiderDesk's shell approvals and the MCP server's permissions are separate controls.

For a brownfield refactor, use the operator CLI preservation workflow and retain its baseline. For greenfield generation, review the proposed contract and provider use outside the strict MCP tools. A successful later verify_code call checks the submitted artifact; it does not retroactively approve the preceding workflow or prove preservation of another contract. S19

A6. Admit future workflows deliberately

For maintainers, each additional profile needs one of two reviewed paths. Executing workflows need the approved execution and publication chain for every reachable stage. Genuinely non-executing workflows need bounded processing and explicit limits on reading, writing, and provider access. A top-level label is insufficient when a child stage can launch a command or export source. S56

Before exposing a profile, document its full invocation tuple, permissible effects, output scope, evidence obligation, and human review step. Test mismatched modes/backends/providers, undeclared writes or execution, indirect dispatch, and failed publication. Keep actual backend acceptance distinct from client-transport testing. A human-only action remains human-only even when it could run inside a sandbox. S57

A7. Upgrade a pilot from the earlier guide

Pin the separate service installation to 91c6790, retain administrator-provisioned sandbox/cgroup configuration, and reload the client connection. Confirm that only two FormalSpecGen tools appear. Run one valid proof, one invalid implementation, and one unsupported native request through the actual client. Save their structured responses; validate the committed verification receipts and admission metadata with the updated helper.

The public CI summary for 91c6790 reports success across five jobs, including real sandbox/OpenJML acceptance. That is upstream evidence about the pinned build, not a record of your local deployment or an AiderDesk/Qwen transport session. S59

The numbered sources above resolve in the operating guide's source register. The upstream admission guide and policy implementation are the authoritative pinned references.

Command reference

Revision: 91c6790. Scope: all 38 subcommands registered by the default pipeline.cli.build_parser() in this revision. External command plugins are not auto-loaded by main().

Use the operating guide first for installation, review boundaries, greenfield and brownfield workflows. Every command also accepts -h / --help. Top-level --version reports the package version. Run reference examples from an ordinary shell unless the entry says the command is recognized in the REPL. S01

Notation. UPPERCASE placeholders stand for your paths or values. Bracketed [options] means the options in the entry, not literal text. “Unset” means argparse supplies no explicit value; the downstream workflow may choose its own default. Repeatable flags are labeled. --json PATH is not a global flag. Only doctor --json accepts an omitted PATH. Examples requiring application-specific files are templates, not bundled fixtures.

Execution boundary. All commands here are operator-facing CLI capabilities. Their presence does not establish that every backend they reach is migrated to the strict sandbox. Default MCP exposes only Java verify_code and non-executing inspect_code; do not use legacy MCP exposure to bypass that policy. S03

Command index

Command Workflow family REPL recognized Strict MCP
analyze-codebase Brownfield No; use shell Not admitted
apply-refactor Brownfield Yes Not admitted
architecture Architecture Yes Not admitted
assess-security Security No; use shell Not admitted
compose Architecture Yes Not admitted
correct-behavior Security No; use shell Not admitted
design-system Architecture Yes Not admitted
discover-algorithms Brownfield Yes Not admitted
doctor Orientation Yes Not admitted
document-code Documentation Yes Not admitted
domain Domains Yes Not admitted
draft Greenfield Yes Not admitted
generate-traceability-matrix Documentation Yes Not admitted
implement Greenfield Yes Not admitted
inspect Brownfield Yes Admitted subset
macro-dictionary Specialist Yes Not admitted
manage-trust Trust Yes Human-only
optimize-algorithm Brownfield No; use shell Not admitted
promote-domain Domains Yes Human-only
prove-equivalence Verification Yes Not admitted
remediate Security No; use shell Not admitted
reverify Architecture Yes Not admitted
security-exploit Security No; use shell Not admitted
security-inspect Security No; use shell Not admitted
sign-artifact Trust Yes Human-only
system Architecture Yes Not admitted
unified-system Architecture No; use shell Not admitted
validate-architecture Architecture No; use shell Not admitted
validate-domain Domains Yes Not admitted
verify Verification Yes Admitted subset
verify-bisimulation Verification No; use shell Not admitted
verify-distributed Specialist Yes Not admitted
verify-hal Specialist Yes Not admitted
verify-heap Specialist Yes Not admitted
verify-linearizability Specialist Yes Not admitted
verify-lockfree Specialist Yes Not admitted
verify-refactor Brownfield Yes Not admitted
verify-unbounded Specialist Yes Not admitted

analyze-codebase

Extract architecture and unreviewed V2 candidates from a source tree.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen analyze-codebase TARGET_DIR [options]
Argument or option Meaning Default / allowed values
target_dir Existing source directory. Required
--out-dir Extraction reports/artifact directory. extracted
--project-root Project receiving candidate domain registrations. .
--json Machine-readable verdict destination; use a distinct file for each run. Unset

Example

formalspecgen analyze-codebase src --out-dir extracted --project-root . --json evidence/extraction.json

Result. EXTRACTED report plus source/model candidates and identified limitations.

Boundary and common mistakes. Brownfield discovery is partial extraction, not verification. Bounds, initial state, resets, guards, and omitted behavior need human review. It can write candidate artifacts even though it is not a code-generation workflow.

Source: pipeline/codebase_analysis.py; CLI syntax: S01.

apply-refactor

Apply an explicitly selected supported transformation and its proof gate.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen apply-refactor SOURCE --method METHOD --out OUT [options]
Argument or option Meaning Default / allowed values
source Baseline source file. Required
--inspection Required for Java: matching hash-bound inspect JSON. Unset
--pattern Transformation profile. extract-method; choices: extract-method, factory-method, state, decorator, facade, null-object, strategy
--method Eligible method identified during inspection. Required
--out Same-named Java file, or the output required by the selected profile. Required
--json Machine-readable verdict destination; use a distinct file for each run. Unset

Example

formalspecgen apply-refactor src/Service.java --inspection evidence/inspection.json --pattern extract-method --method process --out refactored/Service.java --json evidence/applied-refactor.json

Result. Candidate artifact(s), transformation diagnostics, and preservation/proof result.

Boundary and common mistakes. Not all patterns work for arbitrary code. Native routes accept extract-method; Rust additionally supports strategy. Inspection-only recommendations such as proxy/command are not transformation flags.

Source: pipeline/refactor_actions.py; CLI syntax: S01.

architecture

Extract a supported domain model from source and run bounded TLC checking.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen architecture STUB [options]
Argument or option Meaning Default / allowed values
stub Source/contract whose semantics match a supported adapter. Required
--clarifications Reviewed concurrency assumptions as text. Unset
--abstraction Requested model abstraction. atomic_operations; choices: atomic_operations, lock_protocol
--emit-tla TLA+ output path; matching .cfg is also written. Unset
--json Machine-readable verdict destination; use a distinct file for each run. Unset

Example

formalspecgen architecture src/BoundedCounter.java --abstraction atomic_operations --emit-tla evidence/Counter.tla --json evidence/architecture.json

Result. Bounded architecture result and, when requested, rendered model/configuration.

Boundary and common mistakes. Adapter recognition and maturity matter. Unsupported models fail instead of implying general extraction. Bounded TLC evidence alone does not prove source/model refinement or deployed concurrency.

Source: pipeline/tla_backend.py; CLI syntax: S01.

assess-security

Combine formal diagnostics with configured SAST checks.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen assess-security SOURCE [options]
Argument or option Meaning Default / allowed values
source Supported source file. Required
--json Machine-readable verdict destination; use a distinct file for each run. Unset
--no-sast Omit SAST; explicitly reduces the assessment scope. false

Example

formalspecgen assess-security src/BoundedCounter.java --json evidence/security.json

Result. Security verdict; default file is security_verdict.json. Full success requires the configured formal and SAST checks.

Boundary and common mistakes. VERIFIED_SECURE is a scoped label, not immunity from every weakness. SAST omission or unavailable tools cannot establish a complete assessment. Only assess code you are authorized to examine.

Source: pipeline/security_assessment.py; CLI syntax: S01.

compose

Generate and check glue between operations in reviewed V2 domains.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen compose ARTIFACT [options]
Argument or option Meaning Default / allowed values
artifact CompositionSpec JSON containing architecture, bindings and use_cases. Required
--v2-dir Explicit reviewed-domain directory; defaults to the configured resource directory. Unset
--out-dir Generated composition sources. Unset
--json Machine-readable verdict destination; use a distinct file for each run. Unset
--no-esc Stop at the reduced checking stage; no deductive composition claim. false
--actors Comma-separated actor names for supported concurrent preflight. Unset
--lang Native composition target. java; choices: java, rust, c, cpp

Example

formalspecgen compose plans/composition.json --v2-dir domains/v2 --lang java --out-dir generated/composition --json evidence/composition.json

Result. Composition verdict and deterministic sources for the chosen lane.

Boundary and common mistakes. The core supported boundary is atomic, one operation per component per use case, with reviewed bindings. Java composition rejects internal boolean failure-and-stutter operations. External adapters are assumed at their contract boundary, not proven external services.

Source: pipeline/composition.py; CLI syntax: S01.

correct-behavior

Deliberately strengthen a contract and generate corresponding defensive behavior.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen correct-behavior TARGET --cwe CWE [options]
Argument or option Meaning Default / allowed values
target Source or supported typed-domain input for the chosen correction lane. Required
--cwe Weakness identifier, for example CWE-400. Required
--strategy Explicit correction policy. Unset; choices: bound-loop, static-pool, bounded-cache, bounded-pool, checked-math, lock-timeout, canonicalize, fail-safe, immutable-snapshot
--hardware Human-reviewed hardware profile JSON. Unset
--struct-size-bytes Explicit element size for hardware capacity derivation. Unset
--pool-field Bounded occupancy counter to materialize. Unset
--auto-strategy Use the deterministic shape-based strategy selector. false
--out-dir Strengthened contracts, candidates and verdicts. corrections
--max-attempts Maximum proof-repair attempts. 3
--json Machine-readable verdict destination; use a distinct file for each run. Unset
--provider Generation provider. ollama; choices: glm, openai, ollama
--model Override the provider model for this command. Unset

Example

formalspecgen correct-behavior src/BatchRunner.java --cwe CWE-400 --strategy bound-loop --provider ollama --out-dir corrections --json evidence/correction.json

Result. A reviewed correction candidate or BEHAVIOR_CORRECTION_VERIFIED, depending on the lane and completed evidence.

Boundary and common mistakes. Intentionally changes semantics and must not be described as a preserving refactor. CAPACITY_BOUND_CANDIDATE_GENERATED is an accepted command outcome, not an implementation proof. Hardware capacities and boundary behavior require human review.

Source: pipeline/behavior_correction.py; CLI syntax: S01.

design-system

Generate an architecture from requirements, with a staged typed option.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen design-system REQUIREMENT [options]
Argument or option Meaning Default / allowed values
requirement Quoted system-level requirement. Required
--provider Proposal provider. ollama; choices: glm, openai, ollama
--out-file Architecture JSON destination. architecture.json
--json Machine-readable verdict destination; use a distinct file for each run. Unset
--timeout TLC timeout in seconds. 120
--max-attempts Proposal/repair budget. 3
--staged Use typed fragments and the TLA/TLC publication gate. false
--lang Target filenames/lowering language in the staged route. java; choices: java, rust, c, cpp

Example

formalspecgen design-system "Coordinate two bounded counters atomically." --staged --lang java --provider ollama --out-file plans/architecture.json --json evidence/design.json

Result. Architecture JSON only after the required generation/validation gate succeeds; optional design evidence.

Boundary and common mistakes. A generated architecture is not a built system. The staged UnifiedArchitecture schema differs from the composition schema and from a system component-input plan. There is no --model flag on this command.

Source: pipeline/system_design.py; CLI syntax: S01.

discover-algorithms

Search multiple strategy-specific implementations behind proof gates.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen discover-algorithms SOURCE [options]
Argument or option Meaning Default / allowed values
source Java/JML specification or verified baseline. Required
--out-dir Root for strategy-isolated candidates. discovered
--strategies all, or comma-separated registered strategy names. all
--max-workers Concurrent strategy workers; use 1 with a constrained local model. 3
--json Machine-readable verdict destination; use a distinct file for each run. Unset
--provider Generation provider. ollama; choices: glm, openai, ollama
--model Override the provider model for this command. Unset

Example

formalspecgen discover-algorithms baseline/TwoSum.java --strategies hashmap,two_pointer --max-workers 1 --provider ollama --out-dir discovered --json evidence/discovery.json

Result. Per-strategy results and admitted candidates; successful discovery can report ALGORITHM_DISCOVERY_COMPLETE.

Boundary and common mistakes. Registered strategies: brute_force, two_pointer, hashmap, sliding_window, binary_search, prefix_sum, bit_manipulation, dynamic_programming. Complexity annotations are heuristic, not performance evidence.

Source: pipeline/algorithm_discovery.py; CLI syntax: S01.

doctor

Check configured judges, adapters, and evidence ceilings.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. doctor executes tool probes; it is not classified as non-executing. S48 S55

formalspecgen doctor [options]
Argument or option Meaning Default / allowed values
--json Write JSON to PATH; without a value, print JSON to stdout. Unset
--require Require a named judge to be READY. Repeat for multiple judges. []; repeatable
--strict Fail on the report's non-ready/misconfigured state. false
--judges Include the executable judge manifest. false

Example

formalspecgen doctor --require OpenJML --require TLC --json evidence/doctor.json

Result. A readiness report, plus a nonzero exit when required checks fail. The claim remains NO_PROOF.

Boundary and common mistakes. Tool availability is environmental metadata, not proof that an application is correct. This command can run tool smoke probes; it is not a non-executing MCP inspection tool.

Source: pipeline/doctor.py; CLI syntax: S01.

document-code

Render readable documentation from a source-derived V2 extraction.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen document-code SOURCE --out OUT [options]
Argument or option Meaning Default / allowed values
source Supported source file. Required
--out Markdown destination. Required
--project-root Project root for extraction context. .
--no-llm Use only the deterministic documentation sections. false
--json Machine-readable verdict destination; use a distinct file for each run. Unset
--provider Generation provider. ollama; choices: glm, openai, ollama
--model Override the provider model for this command. Unset

Example

formalspecgen document-code src/BoundedCounter.java --no-llm --out evidence/counter-documentation.md --json evidence/documentation.json

Result. DOCUMENTED with UNREVIEWED_EXTRACTION_DOCUMENTATION when extraction succeeds.

Boundary and common mistakes. This command documents application code; it does not generate the FormalSpecGen user manual. Documentation remains unreviewed and validation is separate. A provider narrative does not add proof.

Source: pipeline/code_documentation.py; CLI syntax: S01.

domain

Elicit a domain specification and create an unreviewed candidate.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen domain IDEA [options]
Argument or option Meaning Default / allowed values
idea Quoted domain idea; answers are gathered interactively. Required
--project-root Project containing domains and candidates. .
--force Allow replacing an existing candidate; does not itself authorize a reviewed replacement. false
--replace-reviewed-domain Explicitly authorize the reviewed-domain replacement path after human review. false
--restart-clarifications Discard saved domain answers and start elicitation again. false
--schema-version 1 creates plugin scaffolding; 2 creates a typed candidate. Choose 2 explicitly for this guide. 1; choices: 1, 2
--provider Generation provider. ollama; choices: glm, openai, ollama
--model Override the provider model for this command. Unset

Example

formalspecgen domain "Bounded counter with increment and decrement" --schema-version 2 --project-root . --provider ollama

Result. V2: domains/candidates/NAME.v2.yaml and validation evidence after the automatic check. V1: generated YAML plus adapter/renderer/test scaffolding.

Boundary and common mistakes. The default is V1, not V2. Generated candidates are unreviewed. V1 requires implementation and review of generated adapter TODOs; it cannot be passed to validate-domain.

Source: pipeline/domain_generator.py; CLI syntax: S01.

draft

Clarify requirements and produce a contract draft, or deterministically render a reviewed domain.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen draft REQUIREMENT [options]
Argument or option Meaning Default / allowed values
requirement Quoted natural-language requirement, not a filename. Required
--no-clarify Skip interactive clarification; use only with a previously reviewed, complete requirement. false
--lang Target language. java; choices: java, rust, c, cpp
--out-file Native/canonical contract file; Java generative drafting uses its run output rather than this option. Unset
--canonical-domain Reviewed V2 module name to render deterministically. Unset
--fallback-provider Explicit alternate provider. Unset; choices: glm, openai, ollama
--out Java drafting run root. Unset
--max-attempts Attempt cap; omitted values are resolved by the drafting pipeline. Unset
--resample-budget Fresh generation budget; pipeline default when omitted. Unset
--feedback-budget Diagnostic-feedback budget; pipeline default when omitted. Unset
--provider Generation provider. ollama; choices: glm, openai, ollama
--model Override the provider model for this command. Unset

Example

formalspecgen draft "A counter ranges from zero to five." --lang java --provider ollama --out draft-runs

Result. A proposed contract and diagnostic/run artifacts. Review the reported output path and the specification before implementation.

Boundary and common mistakes. Draft success is not an application implementation proof. C++ drafting requires --canonical-domain. Canonical domains are resolved under domains/v2 in the working project. --no-clarify does not authorize assumptions.

Source: pipeline/canonical_draft.py; CLI syntax: S01.

generate-traceability-matrix

Associate requirements with V2 invariants and located source lines.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen generate-traceability-matrix DOMAIN SOURCE --reqs REQS [options]
Argument or option Meaning Default / allowed values
domain V2 candidate/reviewed domain. Required
source Source file or directory. Required
--reqs Requirements text containing REQ-### identifiers. Required
--out Markdown matrix destination. traceability-matrix.md
--json Machine-readable verdict destination; use a distinct file for each run. Unset

Example

formalspecgen generate-traceability-matrix domains/candidates/bounded_counter.v2.yaml src --reqs requirements.txt --out evidence/traceability.md --json evidence/traceability.json

Result. Markdown matrix and optional JSON, including mapped/total counts.

Boundary and common mistakes. Traceability is a review aid, not certification or a proof that every requirement was implemented. Investigate unmatched and ambiguous links.

Source: pipeline/traceability.py; CLI syntax: S01.

implement

Generate implementations against a trusted contract and run the requested assurance workflow.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen implement STUB [options]
Argument or option Meaning Default / allowed values
stub Reviewed contract source: Java/JML, Rust, C, or C++. Required
--out Implementation/run output root. Unset
--json Machine-readable verdict destination; use a distinct file for each run. Unset
--max-attempts Maximum generation/proof attempts. 5
--resample-budget Fresh candidates without diagnostic feedback. 1
--feedback-budget Feedback-assisted attempts. 4
--accept-pass Explicitly accepted transformation pass; repeatable. Review each semantic effect. []; repeatable
--assurance-level Requested pipeline profile; returned claim is authoritative. critical; choices: critical, standard, lightweight
--method-proof-only Skip architecture/TLC and request method-level proof only; not critical assurance. false
--clarifications Authoritative concurrency assumptions as text, not a file path. Unset
--abstraction Concurrency abstraction. atomic_operations; choices: atomic_operations, lock_protocol
--v2-reviewed-domain Promoted V2 JSON for source/model refinement. Unset
--v2-validation-evidence Matching hash-bound validation evidence; supply with --v2-reviewed-domain. Unset
--parallel-wrapper Optional deterministic Rust wrapper. Unset; choices: rayon
--parallel-kernel Proved scalar Rust kernel name. process_chunk
--parallel-out Destination for the generated Rust parallel wrapper. Unset
--dependencies External adapter dependency; takes the adapter-injection branch. Unset; choices: stripe, aws, curl, kernel-driver
--dma-profile Declared kernel-driver DMA profile JSON; required for that dependency. Unset
--provider Generation provider. ollama; choices: glm, openai, ollama
--model Override the provider model for this command. Unset

Example

formalspecgen implement src/BoundedCounter.java --provider ollama --method-proof-only --out runs/implementation --json evidence/implementation.json

Result. Candidate source, stage results, and a final claim appropriate to the selected path. Read final_status, claim, and stage evidence together.

Boundary and common mistakes. Do not equate profiles across languages. Refinement needs both V2 files. Dependency injection is not a core-implementation proof. Java permits stripe; Rust permits aws/kernel-driver; C++ permits curl; C has no declared dependency mapping. Rayon proves a narrow partition boundary, not the scheduler.

Source: pipeline/orchestrator.py; CLI syntax: S01.

inspect

Inspect one Java class for deterministic modernization signals.

Interface availability. Strict MCP: admitted subset. MCP inspect_code admits Java inspection through builtin-java-inspector with workspace_read only. It returns findings and admission metadata, not a proof receipt. S48 S55

formalspecgen inspect SOURCE [options]
Argument or option Meaning Default / allowed values
source Java/JML file. Required
--json Machine-readable verdict destination; use a distinct file for each run. Unset

Example

formalspecgen inspect src/Service.java --json evidence/inspection.json

Result. INSPECTED findings and source-bound inspection data; no proof.

Boundary and common mistakes. Recommendations are not automatically admissible transformations. Re-run after changing the source because apply-refactor uses hash-bound inspection evidence. This is the CLI counterpart of strict MCP inspect_code.

Source: pipeline/java_inspection.py; CLI syntax: S01.

macro-dictionary

Load a semantic macro dictionary, translate source uses, or synthesize a V2 model.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen macro-dictionary DICTIONARY [options]
Argument or option Meaning Default / allowed values
dictionary Human-reviewed macros.json dictionary. Required
--source C/.h source containing relevant invocations. Unset
--synthesize Run the macros-to-V2 workflow; requires --source. false
--no-verify Skip the Z3 model-proof step; do not claim that proof. false
--provider Provider for unresolved semantic proposals. ollama
--json Machine-readable verdict destination; use a distinct file for each run. Unset

Example

formalspecgen macro-dictionary models/macros.json --source src/driver.h --synthesize --provider ollama --json evidence/macros.json

Result. Dictionary/translation/model artifacts, with a result reflecting whether the model proof ran.

Boundary and common mistakes. Dictionary loading and translation are successful operations but not source refinement. Review proposed macro meanings; --no-verify cannot establish model proof.

Source: pipeline/macro_semantics.py; CLI syntax: S01.

manage-trust

Maintain the authorized reviewer-key registry.

Interface availability. Strict MCP: not admitted; human-only CLI action. Human review/trust action. No MCP profile may authorize it; do not delegate signing keys or acceptance to the agent. S48 S55

formalspecgen manage-trust [options]
Argument or option Meaning Default / allowed values
--add-key Exported reviewer public-key path. Unset
--remove-key Reviewer key ID to remove. Unset
--list List keys; listing is also the default when no action is supplied. false
--registry Registry JSON path. trusted_keys.json

Example

formalspecgen manage-trust --list --registry trusted_keys.json

Result. Updated registry or the current key list.

Boundary and common mistakes. Human-only authorization action. Choose one action per invocation; the parser does not make add/remove mutually exclusive. Protect both the registry and the reviewer private keys.

Source: pipeline/trust.py; CLI syntax: S01.

optimize-algorithm

Propose a constrained rewrite of a verified Java algorithm.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen optimize-algorithm SOURCE --strategy STRATEGY --out OUT [options]
Argument or option Meaning Default / allowed values
source Verified Java/JML baseline. Required
--strategy Requested strategy; nested_loop is syntactically accepted but rejected as a potential regression. Required; choices: hashmap, two_pointer, binary_search, nested_loop
--out Candidate file; retain the public Java class filename. Required
--json Machine-readable verdict destination; use a distinct file for each run. Unset
--provider Generation provider. ollama; choices: glm, openai, ollama
--model Override the provider model for this command. Unset

Example

formalspecgen optimize-algorithm baseline/TwoSum.java --strategy hashmap --out optimized/TwoSum.java --provider ollama --json evidence/optimization.json

Result. ALGORITHM_OPTIMIZATION_VERIFIED only after its proof and preservation gates succeed.

Boundary and common mistakes. The label is not a measured speedup, asymptotic-complexity proof, or runtime bisimulation result. Benchmark separately and keep the baseline.

Source: pipeline/algorithm_optimization.py; CLI syntax: S01.

promote-domain

Human acceptance of a reviewed candidate, publishing its canonical artifact.

Interface availability. Strict MCP: not admitted; human-only CLI action. Human review/trust action. No MCP profile may authorize it; do not delegate signing keys or acceptance to the agent. S48 S55

formalspecgen promote-domain NAME [options]
Argument or option Meaning Default / allowed values
name Module name or candidate basename, not a path. Required
--project-root Project root. .
--replace-reviewed-domain Permit replacement of an existing reviewed artifact after deliberate review. false
--schema-version Select schema explicitly; otherwise infer V2 when its validation evidence exists. Unset; choices: 1, 2
--accept-candidate-sha256 Required for V2: the reviewed candidate digest from its validation evidence. Unset
--signing-key Reviewer-owned GPG key for a detached promotion signature. Unset

Example

formalspecgen promote-domain bounded_counter --schema-version 2 --project-root . --accept-candidate-sha256 "$REVIEWED_SHA256"

Result. V2 publication to domains/v2/NAME.json; optional .promotion.sig. V1 publication follows its plugin-review rules.

Boundary and common mistakes. Human-only trust action. Do not approve by changing review_status in JSON. Do not automatically accept whatever hash a generation step just produced. Signature creation is optional unless your policy requires it.

Source: pipeline/domain_v2_promotion.py; CLI syntax: S01.

prove-equivalence

Compare finite reachable V2 state spaces under an explicit relation.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen prove-equivalence BASELINE REFACTORED --mapping MAPPING [options]
Argument or option Meaning Default / allowed values
baseline Baseline V2 YAML/JSON. Required
refactored Candidate V2 YAML/JSON. Required
--mapping JSON object with a states list of baseline_state/refactored_state pairs. Required
--json Machine-readable verdict destination; use a distinct file for each run. Unset

Example

formalspecgen prove-equivalence models/old.v2.yaml models/new.v2.yaml --mapping mappings/states.json --json evidence/equivalence.json

Result. EQUIVALENCE_PROVED / BEHAVIORAL_EQUIVALENCE_PROVED for the checker's bounded state-space relation.

Boundary and common mistakes. A claim about the compared V2 transition systems, not Java/Rust heap topology, timing or I/O. Provide complete reachable-state coverage and review relation semantics; do not reuse verify-bisimulation's different mapping schema.

Source: pipeline/equivalence.py; CLI syntax: S01.

remediate

Generate a separate patch using a findings report, then request native verification.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen remediate TARGET REPORT [options]
Argument or option Meaning Default / allowed values
target Original source; preserved rather than overwritten. Required
report Matching vulnerability report. Required
--out-dir Patch and evidence directory. remediated
--json Machine-readable verdict destination; use a distinct file for each run. Unset
--provider Generation provider. ollama; choices: glm, openai, ollama
--model Override the provider model for this command. Unset

Example

formalspecgen remediate src/Service.java evidence/vulnerabilities.json --provider ollama --out-dir remediated --json evidence/remediation.json

Result. Patched candidate plus verdict; successful scoped checking can report REMEDIATION_VERIFIED.

Boundary and common mistakes. A verified patch is not automatically behaviorally equivalent or a demonstrated neutralization of a live exploit. Review contracts, external I/O, findings coverage, and the original/candidate diff.

Source: pipeline/remediation.py; CLI syntax: S01.

reverify

Re-evaluate a composition after a reviewed module changes.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen reverify ARTIFACT --changed-module CHANGED_MODULE [options]
Argument or option Meaning Default / allowed values
artifact Existing composition JSON. Required
--changed-module Name of the changed reviewed V2 module. Required
--v2-dir Reviewed-domain directory. Unset
--json Machine-readable verdict destination; use a distinct file for each run. Unset

Example

formalspecgen reverify plans/composition.json --changed-module bounded_counter --v2-dir domains/v2 --json evidence/reverification.json

Result. Impact and re-verification evidence for the changed composition.

Boundary and common mistakes. A new reviewed revision requires matching fresh evidence. This is not a cache-blessing operation, and it has no --lang switch in the built-in parser.

Source: pipeline/composition_render.py; CLI syntax: S01.

security-exploit

Generate local, review-only proof-of-concept source templates for supported findings.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen security-exploit REPORT TARGET [options]
Argument or option Meaning Default / allowed values
report JSON produced by security-inspect. Required
target The matching authorized source file. Required
--out-dir Generated local test-template directory. security-pocs
--json Machine-readable verdict destination; use a distinct file for each run. Unset

Example

formalspecgen security-exploit evidence/vulnerabilities.json src/Service.java --out-dir security-pocs --json evidence/poc-generation.json

Result. POCS_GENERATED with claim POC_GENERATED_NOT_EXECUTED for supported templates, or a scoped no-supported-case result.

Boundary and common mistakes. The command does not compile, execute, or transmit PoCs. Generated templates are not demonstrated exploits. Keep any later execution within an explicitly approved test environment.

Source: pipeline/security_poc.py; CLI syntax: S01.

security-inspect

Produce a findings report for defensive triage.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen security-inspect SOURCE [options]
Argument or option Meaning Default / allowed values
source Authorized target source file. Required
--json Machine-readable verdict destination; use a distinct file for each run. Unset

Example

formalspecgen security-inspect src/Service.java --json evidence/vulnerabilities.json

Result. Findings report, defaulting to vulnerability_report.json.

Boundary and common mistakes. This is distinct from the non-executing inspect command: it may launch formal/SAST tools. Its zero exit means the report was produced, not that there are no findings. A finding or absence of recognized findings is not a general exploitability verdict.

Source: pipeline/security_poc.py; CLI syntax: S01.

sign-artifact

Create a reviewer-owned detached GPG signature.

Interface availability. Strict MCP: not admitted; human-only CLI action. Human review/trust action. No MCP profile may authorize it; do not delegate signing keys or acceptance to the agent. S48 S55

formalspecgen sign-artifact ARTIFACT --key KEY [options]
Argument or option Meaning Default / allowed values
artifact Reviewed artifact or verdict path. Required
--key Local GPG identity/key ID. Required

Example

formalspecgen sign-artifact evidence/refactor.json --key "$REVIEWER_KEY"

Result. Detached signature path printed by the command.

Boundary and common mistakes. A signature attests to approval/identity, not correctness by itself. Run as the human reviewer; never expose signing authority to the agent.

Source: pipeline/domain_v2_promotion.py; CLI syntax: S01.

system

Coordinate component implementation, refactoring or corrective workflows.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen system ARTIFACT --out-dir OUT_DIR [options]
Argument or option Meaning Default / allowed values
artifact Mode-specific system JSON plan. Required
--out-dir Per-component output/evidence root. Required
--max-workers Parallel component workers. 4
--mode Plan interpretation and workflow. implement; choices: implement, refactor, correct
--provider Provider for corrective subagents; not forwarded to the implement workers by this handler. ollama
--model Model for corrective subagents. Unset
--max-attempts Corrective worker proof-repair cap. 3
--executable Internal subprocess executable override; hidden from ordinary help. formalspecgen; internal/hidden
--json Machine-readable verdict destination; use a distinct file for each run. Unset

Example

formalspecgen system plans/system-implement.json --mode implement --max-workers 1 --out-dir runs/system --json evidence/system.json

Result. Per-component results and an aggregate scoped result, with composition checked when required by the mode.

Boundary and common mistakes. Use the correct plan schema for each mode. Parallel tool execution is not proof of concurrent component behavior. Implement plans require exact coverage of composition bindings. Keep model concurrency low for local serving.

Source: pipeline/system_orchestrator.py; CLI syntax: S01.

unified-system

Lower a validated staged unified architecture toward source artifacts.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen unified-system ARTIFACT --evidence EVIDENCE --out-dir OUT_DIR [options]
Argument or option Meaning Default / allowed values
artifact Java: UnifiedArchitecture JSON. Native: the current handler expects a CompositionSpec-shaped artifact instead. Required
--evidence Matching validation evidence JSON. Required
--out-dir Lowered/generated output root. Required
--lang Target language. java; choices: java, rust, c, cpp
--v2-dir Reviewed V2 directory for non-Java composition lowering. Unset
--json Machine-readable verdict destination; use a distinct file for each run. Unset

Example

formalspecgen unified-system plans/architecture.json --evidence evidence/architecture-validation.json --lang java --out-dir generated/system --json evidence/unified.json

Result. Lowered artifacts or stronger evidence only when the downstream gates actually run and pass.

Boundary and common mistakes. LOWERED and VERIFIED are different outcomes. The staged UnifiedArchitecture plus evidence path is Java-specific here. For a non-Java --lang the handler routes to native composition checking, requires a CompositionSpec-shaped input, and does not consume --evidence even though the parser requires it. Prefer compose for native composition; do not claim native unified-evidence validation.

Source: pipeline/unified_system_runner.py; CLI syntax: S01.

validate-architecture

Validate a staged unified architecture artifact with TLC.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen validate-architecture ARTIFACT [options]
Argument or option Meaning Default / allowed values
artifact UnifiedArchitecture JSON, normally from staged design-system. Required
--json Machine-readable verdict destination; use a distinct file for each run. Unset
--timeout TLC timeout in seconds. 120

Example

formalspecgen validate-architecture plans/architecture.json --timeout 120 --json evidence/architecture-validation.json

Result. BOUNDED_ARCHITECTURE_EVIDENCE when the requested model check succeeds.

Boundary and common mistakes. Do not pass a generic system plan or raw V2 domain. This is model evidence under finite bounds, not implementation verification.

Source: pipeline/architecture_tlc_gate.py; CLI syntax: S01.

validate-domain

Validate a typed V2 candidate using traversal and TLC.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen validate-domain NAME [options]
Argument or option Meaning Default / allowed values
name Module name or displayed candidate basename, not a path. Required
--project-root Project root. .
--emit-tla Model path; also emits matching .cfg. Unset

Example

formalspecgen validate-domain bounded_counter --project-root . --emit-tla evidence/BoundedCounter.tla

Result. NAME.v2.validation.json on success, or NAME.v2.validation_failed.json on failure, under domains/candidates.

Boundary and common mistakes. No --json option: evidence paths are derived. Validation is not promotion. Editing the candidate invalidates its old hash-bound evidence.

Source: pipeline/domain_v2_validation.py; CLI syntax: S01.

verify

Check an existing source file with the selected native verifier.

Interface availability. Strict MCP: admitted subset. MCP verify_code accepts Java/JML through OpenJML in parse, check, or esc mode only. The handler requests workspace_read, external_execution, and evidence_publication; no provider or source-write permission is granted. S48 S55

formalspecgen verify SOURCE [options]
Argument or option Meaning Default / allowed values
source Java/JML, Rust, C, or C++ source file. Required
--mode Requested checking stage. esc; choices: parse, check, esc
--json Machine-readable verdict destination; use a distinct file for each run. Unset
--backend Rust backend; ignored for other languages. prusti; choices: prusti, kani

Example

formalspecgen verify src/BoundedCounter.java --mode esc --json evidence/verify.json

Result. A structured verdict when --json is used. The command returns zero only when the requested verification decision is satisfied.

Boundary and common mistakes. parse/check are not deductive proof. C and C++ accept esc only here. Prusti, Kani, Frama-C and ESBMC have different scopes; inspect the returned claim. CLI JSON is not automatically an MCP-style immutable receipt.

Source: pipeline/verification_policy.py; CLI syntax: S01.

verify-bisimulation

Validate inputs and a scoped mapping for a bisimulation workflow.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen verify-bisimulation BASELINE REFACTORED MAPPING [options]
Argument or option Meaning Default / allowed values
baseline Baseline source. Required
refactored Candidate source. Required
mapping Source-mapping JSON for the preflight checker. Required
--json Machine-readable verdict destination; use a distinct file for each run. Unset

Example

formalspecgen verify-bisimulation baseline/Service.java refactored/Service.java mappings/source-mapping.json --json evidence/bisimulation-preflight.json

Result. BISIMULATION_PREFLIGHT_READY means the preflight was accepted.

Boundary and common mistakes. This command does not prove equivalence. Its mapping schema is not the enumerated state-pair schema used by prove-equivalence; inspect pipeline/bisimulation.py for the source mapping contract.

Source: pipeline/bisimulation.py; CLI syntax: S01.

verify-distributed

Check V2 safety under explicitly selected network faults.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen verify-distributed DOMAIN --message-fields MESSAGE_FIELDS [options]
Argument or option Meaning Default / allowed values
domain async_message_passing V2 YAML/JSON model. Required
--faults Comma-separated fault models. message_loss,duplication,reordering
--message-fields Comma-separated state fields representing message slots. Required
--json Machine-readable verdict destination; use a distinct file for each run. Unset

Example

formalspecgen verify-distributed models/protocol.v2.yaml --message-fields slot0,slot1 --faults message_loss,duplication,reordering --json evidence/distributed.json

Result. DISTRIBUTED_SAFETY_PROVED only for the checked bounded model and fault assumptions.

Boundary and common mistakes. Not deployment-level reliability or guaranteed delivery. Supported faults are message_loss, duplication, reordering; field names must exist in the model. Safety evidence is distinct from liveness.

Source: pipeline/distributed.py; CLI syntax: S01.

verify-hal

Check supported C register and address-window discipline.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen verify-hal SOURCE [options]
Argument or option Meaning Default / allowed values
source C/.h HAL source with supported MMIO/bitfield patterns. Required
--json Machine-readable verdict destination; use a distinct file for each run. Unset

Example

formalspecgen verify-hal src/registers.h --json evidence/hal.json

Result. HAL_VERIFICATION_PROVED when the configured Frama-C witness gates succeed.

Boundary and common mistakes. Modeled register properties do not certify a physical device, volatile timing, a DMA engine, or all hardware behavior. Review extracted assumptions and the named lanes.

Source: pipeline/hal_mmio.py; CLI syntax: S01.

verify-heap

Request scoped heap-shape reasoning for supported linked structures.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen verify-heap SOURCE [options]
Argument or option Meaning Default / allowed values
source Rust Box-linked source, or C/.h intrusive-list source. Required
--provider Predicate proposal provider when the source lacks the required predicate. ollama
--json Machine-readable verdict destination; use a distinct file for each run. Unset

Example

formalspecgen verify-heap src/list.rs --provider ollama --json evidence/heap.json

Result. HEAP_VERIFICATION_PROVED only when the applicable native proof checks succeed; inspect recorded assumptions.

Boundary and common mistakes. Not arbitrary heap equivalence, allocator correctness, or a proof of every list property. Source-supplied ghost predicates can avoid LLM use. C and Rust have different framing/acyclicity assumptions.

Source: pipeline/heap.py; CLI syntax: S01.

verify-linearizability

Check Java lock/model correspondence and bounded histories.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen verify-linearizability SOURCE --domain DOMAIN [options]
Argument or option Meaning Default / allowed values
source Java source using the supported locking discipline. Required
--domain Matching lock-protocol V2 YAML/JSON. Required
--json Machine-readable verdict destination; use a distinct file for each run. Unset

Example

formalspecgen verify-linearizability src/ConcurrentCounter.java --domain models/lock_counter.v2.yaml --json evidence/linearizability.json

Result. LINEARIZABILITY_PROVED when the correspondence and bounded-history gates succeed.

Boundary and common mistakes. The bound and model are part of the result. This is not a proof for arbitrary Java concurrency or a substitute for atomicity assumptions and source/model correspondence.

Source: pipeline/linearizability.py; CLI syntax: S01.

verify-lockfree

Check the supported SPSC ring profile under bounded thread interleavings.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen verify-lockfree SOURCE [options]
Argument or option Meaning Default / allowed values
source Supported C pthread single-producer/single-consumer ring source. Required
--json Machine-readable verdict destination; use a distinct file for each run. Unset

Example

formalspecgen verify-lockfree src/spsc.c --json evidence/lockfree.json

Result. LOCK_FREE_LINEARIZABILITY_PROVED only from the lane's successful ESBMC and coverage gates.

Boundary and common mistakes. The label is scoped to the supported profile and its interleaving bounds. Do not infer wait-freedom, arbitrary weak-memory correctness, or all possible native lock-free algorithms.

Source: pipeline/lockfree.py; CLI syntax: S01.

verify-refactor

Check contract preservation and verify both revisions.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen verify-refactor BASELINE REFACTORED [options]
Argument or option Meaning Default / allowed values
baseline Previously reviewed source file. Required
refactored Candidate source file, or supported Java collaborator directory. Required
--json Machine-readable verdict destination; use a distinct file for each run. Unset
--signing-key GPG key for a detached verdict signature; requires --json. Unset

Example

formalspecgen verify-refactor baseline/BoundedCounter.java refactored/BoundedCounter.java --json evidence/refactor.json

Result. Preservation verdict covering the accepted contract surface and backend checks.

Boundary and common mistakes. Not general behavioral equivalence, timing equivalence, or proof for unsupported syntax. Java multifile candidates retain the baseline class filename. Rust/C use native preservation paths; do not infer strict MCP isolation from CLI availability.

Source: pipeline/refactor_gate.py; CLI syntax: S01.

verify-unbounded

Check induction establishment and preservation for supported simple loops.

Interface availability. Strict MCP: not admitted. Available through the operator-facing CLI, but no invocation profile admits this workflow to default strict MCP. An installed handler or a no-LLM option does not authorize it. S48 S55

formalspecgen verify-unbounded SOURCE [options]
Argument or option Meaning Default / allowed values
source C/C++ source containing supported simple while-loops. Required
--invariant Human-supplied invariant expression; otherwise a provider proposes one. Unset
--provider Invariant proposal provider. ollama
--json Machine-readable verdict destination; use a distinct file for each run. Unset

Example

formalspecgen verify-unbounded src/loop.c --invariant "i >= 0 && i <= n" --json evidence/induction.json

Result. UNBOUNDED_VERIFIED when its ESBMC induction harnesses succeed.

Boundary and common mistakes. The claim concerns the supported invariant/loop extraction. It is not automatically termination, whole-program correctness, or a solution for arbitrary nested loops. Supplying the invariant avoids generation.

Source: pipeline/unbounded.py; CLI syntax: S01.

Source notes

S01 Pinned CLI parser and command handlers. S48 Pinned capability profiles. S55 Pinned admission policy. S03 Pinned MCP registration and dispatch.

The wording in this reference is newly written. Command names, flags, defaults and choice values are API data transcribed from the pinned parser. The accompanying coverage checker compares that inventory with a local checkout without executing tool backends.

Edition history

Edition 1.1 — 91c6790 — 24 September 2026

Updates edition 1.0 through the direct public commit chain 0487f24 → 814c5f4 → 91c6790. The two updates do not change pipeline/cli.py; the inventory remains 38 commands and 205 command-specific argument declarations.

The operating guide now separates CLI availability, default strict-MCP admission, and human-only actions. Every command-reference entry and its machine-readable record carries a strict-MCP availability label. Greenfield, brownfield, specialist, and system recipes remain intact as operator workflows rather than being relabeled as agent-admitted workflows.

Added the standalone MCP admission field guide, request-level attenuation explanation, the five independent effects, the two current profiles, and evidence-field definitions. The current CLI surface and the default two-tool MCP catalogue are not expanded by this documentation update.

Updated the AiderDesk pilot instructions and troubleshooting. Extended the auxiliary receipt helper with required admission checks against a pinned profile snapshot, including canonical digests, requested/granted consistency, and agreement across response, terminal manifest, and proof-stage metadata. Added helper regressions and an explicitly non-evidentiary metadata example.

Rebuilt the offline HTML, source register, reference, validation records, and archive manifest. Earlier preparation records are retained under docs/history/edition-1.0/; they are not represented as new proof runs. See VALIDATION.md for the exact checks performed during this edition.

Source changes: invocation admission and permission attenuation.

Edition 1.0 — 0487f24 — 24 September 2026

Initial 18-chapter operating guide, full CLI reference, offline HTML, source register, bounded-counter examples, project templates, command-coverage checker, and receipt-integrity helper. Preparation included Java syntax compilation and documentation-helper tests; formal example runs and a client transport session were not performed.