Operating guide
Greenfield development · Brownfield adoption · Verification · Review · Evidence
One guide, two first-class interfaces. The CLI supports direct operation and scripted automation. MCP exposes the same admitted capabilities for structured client and agent orchestration. Agent-assisted MCP can reduce command-level effort by handling tool selection, argument preparation, and result chaining, while permissions, verification requirements, and human approvals remain enforced.
Use the interface decision table, current CLI/CI quick starts, and current MCP catalogue alongside this full manual. All 38 command recipes remain available here; CLI availability does not confer MCP admission.
Version scope: detailed recipes, source citations, and teaching fixtures below originate at 91c6790. They are retained for manual operation, not relabeled as newly executed acceptance. Current interface guidance and generated command availability supersede that edition's two-tool pilot. Backend implementation notes and source-register links remain pinned historical references; check installed --help and the generated live inventory. The unchanged original edition remains separately available.
Publication update: migrated workflows use bounded shared services and controlled no-replace publication. Give analysis, documentation, refactoring, and traceability fresh output namespaces. An export failure may leave an earlier artifact intact while making the request unsuccessful. Follow returned publication paths and digests; do not delete evidence to force retries.
Machine-output update: built-in commands with --json accept --json - for one formalspecgen-cli-result-v1 response on stdout; diagnostics go to stderr. The response has command, exit_code, operation_satisfied, the unchanged command payload in result, and error. No result means null, not an invented proof. Parser errors still use stderr and exit 2. File exports retain their existing result shape but now refuse replacement, including negative exports. The shared legacy writer has an 8 MiB export limit; migrated workflows keep their own budgets. This does not change other legacy artifact writers. Stdout does not suppress requested artifacts; traceability still publishes its matrix and default sidecar. Signing needs a real file destination. doctor and evidence accept bare --json; the read-only evidence command supports stdout only, not file export; plugin option semantics are unchanged.
Approval update: protected refactor signing has an authenticated continuation. Standalone promotion, trust administration, local signing, and CLI --signing-key remain explicitly human-operated; their presence does not imply an authenticated MCP coordinator exists for each operation. See current approval support before using older signing recipes.
Examples are templates, not proof receipts. Supply the referenced project inputs, qualify the toolchain, and evaluate actual outcomes and claim limits. Only the new landing-page CLI examples are parser-checked; preserving a historical recipe does not certify its execution on this revision.
Contents
- Choose your workflow
- Understand contracts, claims, and review
- Install and configure the tool
- First run: inspect, prove, and reject a bad candidate
- Greenfield: requirements to implementation
- Greenfield: reviewed V2 domain to source
- Brownfield: understand and specify an existing project
- Brownfield: refactor and optimize without changing the contract
- Architecture, composition, and system workflows
- Security assessment, remediation, and intentional correction
- Specialized verification workflows
- Use MCP with AiderDesk and Qwen
- Publish, validate, and review evidence
- Automate safely in development and CI
- Use the interactive shell
- Troubleshooting and recovery
- Coverage, maintenance, and extension boundaries
- 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 | Admitted MCP inspection, verification, and supporting workflows; see current catalogue | 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
Choose direct CLI/CI or agent-assisted MCP according to the task. The command index and per-command availability labels are generated from the current registry. Admission applies to a particular invocation, not every option or backend in a CLI family. Agents must not fall back to an unrestricted shell when a tool is unavailable.
Recommended project layout
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
Interfaces: direct CLI and admitted MCP for the bounded Java assessment and review-only template steps. The full remediation/correction sequence is not admitted to default strict MCP; admission of assessment does not authorize patch generation, replacement, or integration. Current assessment scope takes precedence over historical examples. 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 CHECKS_PASSED 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
The client or model selects admitted typed tools; application code authorizes effects. Use current tool schemas and actual discovery. Inspection and verification now take source, not the archived file_path argument.
12.2 Register a separately pinned service
Keep the trusted installation outside the editable application workspace and configure your MCP client to launch its server. Keep strict mode enabled. Operator-owned roots, provider allowlists, and evidence/signing services define authority, not client prompts. See the deployment instructions.
12.3 Run a complete client smoke test
Discover tools, inspect an approved input, run permitted verification, and check the actual result, source identity, claim, and receipt. Exercise a negative fixture. Use current verification payloads; registry discovery alone is not a transport test.
12.4 Do not confuse proof with preservation
verify_code checks the submitted artifact; verify_refactor additionally binds baseline/candidate contract and proof-trust checks. Neither model agreement nor independent verification establishes general behavioral equivalence. See current refactoring and signing guidance.
12.5 Understand permission attenuation
Granted effects are requested effects intersected with the profile ceiling. The handler determines required effects; models cannot grant execution, provider access, writes, or publication. A rejection calls for clarification or explicit authorization, not compatibility mode or a shell workaround.
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; provider-free requests use JSON null. Documentation may instead use an approved provider. |
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 tool names are 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. Current routing, help, and completion are derived from the
same parser as the CLI, including explicitly registered plugins. Use
/help for the live command list.
Current behavior: unknown commands, bare prose, and
malformed quoting are rejected without starting a workflow. Draft explicitly
with /draft "Design a counter"; drafting may contact the configured
provider. This supersedes the historical 28-command fallback described by
the archived edition.
security-inspect now exits unsuccessfully for unavailable inputs
or incomplete tool checks, retaining per-file diagnostics and any findings.
A completed inspection can report findings and exit zero; this is not a proof
or a clean-security assertion. Skipped SAST remains visible. Configurable
findings thresholds are not yet implemented.
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.
S06 Implementation routing and special paths.
S07 Trusted implementation synthesis and final checks.
S09 Composition schema and supported boundary.
S10 Component system orchestration.
S11 Immutable ledger and validation.
S12 Java/native semantic preservation surfaces.
S14 Environment and tool configuration.
S15 Sandbox, cgroup, snapshot, and resource policy.
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.
S22 V2 promotion, hashes, and signing.
S23 Canonical deterministic drafting.
S24 Requirements traceability.
S27 Intentional behavior correction.
S28 Targeted refactoring actions.
S31 Bisimulation input preflight.
S32 Bounded V2 equivalence checking.
S33 Source-derived bounded architecture.
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.
S42 Macro dictionaries and model checking.
S43 Supported bounded lock-free checking.
S45 Distributed bounded safety.
S46 Rust async scaffold checking.
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).