---
agent: 'agent'
description: 'Companion to fw.prompt.md — connects the /fw pipeline stages to the fw-engine MCP server tools. Load this file alongside fw.prompt.md to enable tool-assisted verification.'
---

# /fw Tool Integration — fw-engine MCP Server

> **Role**: This file is a **companion** to `fw.prompt.md`, NOT a replacement.
> It augments the pipeline by mapping each stage to concrete MCP tools that
> can produce verified, structured evidence.  Without this file, `/fw` still
> works — it just reasons without tool assistance.
>
> **MCP Server**: `fw-engine` (configured in `.vscode/mcp.json`)
> **Transport**: stdio  |  **Entry**: `python -m fw_server.server`

---

## Quick Reference — 12 Tools

| # | Tool | Stage(s) | Purpose |
|---|------|----------|--------|
| 1 | `run_single_lens` | 2, 3, 4, 5 | Run one of the 7 formal lenses and get convergence score |
| 2 | `run_bileshke_pipeline` | 5, 9B | Run all lenses → composite score → full QualityReport |
| 3 | `check_kavaid` | 5 | Evaluate all 8 kavaid with structural auto-checks |
| 4 | `verify_chains` | 8 | Trace inference chains through FOL axiom references |
| 5 | `get_framework_summary` | PRE-FLIGHT, 1 | Aggregate framework_summary() from all modules |
| 6 | `hcp_ingest` | PRE-FLIGHT | Feed source text into HCP for holographic retrieval |
| 7 | `hcp_query` | 2–8 | Retrieve relevant context via holographic attention |
| 8 | `hcp_diagnostics` | 9B | Get HCP state for transparency disclosure |
| 9 | `hcp_create_workflow` | PRE-FLIGHT | Create a multi-step workflow chain with typed stage contracts |
| 10 | `hcp_advance_workflow` | 2–9 | Advance a workflow by one stage, recording output |
| 11 | `hcp_export_state` | 9B | Export full HCP state as a JSON checkpoint |
| 12 | `hcp_import_state` | PRE-FLIGHT | Import a previously exported HCP state checkpoint |

---

## Per-Stage Integration

### PRE-FLIGHT: CONTEXT LOADING + DIRECTIVE + CLASSIFICATION

**After loading AGENTS.md and copilot-instructions.md:**

1. **Ingest source text** into HCP for later retrieval:
   ```
   hcp_ingest(text=<AGENTS.md content or relevant section>)
   ```
   This seeds the holographic context so that `hcp_query` in later stages can
   retrieve structurally relevant passages without re-reading the full file.

2. **Get framework summary** to confirm all modules are operational:
   ```
   get_framework_summary()
   ```
   Check the returned dict — each module key should have data (not an error).
   If a module reports an error, note it as a coverage gap per AX52.

3. **(Optional) Restore a previous session checkpoint**:
   ```
   hcp_import_state(state_json="<JSON from previous hcp_export_state>")
   ```
   Restores all ingested chunks, seed, workflows, and config. Useful for
   resuming a multi-session analysis.

4. **(Optional) Create a workflow chain** for structured multi-stage execution:
   ```
   hcp_create_workflow(
     stages='[{"name": "classify", "expected_output": "path"}, {"name": "analyze"}, {"name": "synthesize"}]'
   )
   ```
   Returns a workflow_id to track stage-by-stage progress via `hcp_advance_workflow`.

---

### STAGE 1 — Output Translation (AGENTS.md Layer 8)

**Tool**: `get_framework_summary()` — use the kavram_sozlugu summary to
confirm which ontological terms are registered and available for §8.2 translation.

**Tool**: `hcp_query(question="output translation rules for this domain", keywords=["translation", "audience", "term"])` — retrieve relevant context if source text was ingested.

---

### STAGE 2 — Foundational Commitments (AGENTS.md Layer 1)

**Tool**: `run_single_lens(lens_id="fol", params={"text": "<relevant text>"})`
— extract axiom references (AX1–AX13) from the query domain. The FOL lens
returns `details.axiom_refs` listing which axioms appear structurally.

**Tool**: `hcp_query(question="three-phase actualization pattern", keywords=["AX2", "AX3", "AX4", "distinction", "selection", "actualization"])`

---

### STAGE 3 — Ontological Framework (AGENTS.md Layer 2)

**Tool**: `run_single_lens(lens_id="ontoloji", params={"kavramlar": [...]})`
— register concepts from the query domain and measure ontological convergence.
Each kavram needs: `{"isim": "...", "tanim": "...", "esma_pirlanta": ["..."], "pirlanta_detay": {"...": "..."}}`.

**Tool**: `run_single_lens(lens_id="mereoloji", params={"parts": [...], "relations": [...]})`
— analyze part-whole structure. Parts: `{"id": "...", "name": "...", "parent_id": "..."}`.
Relations: `{"source": "...", "target": "...", "rel_type": "..."}`.

**Tool**: `run_single_lens(lens_id="holografik", params={})` — check holographic
seed omnipresence (KV₆). Returns score and details on B01–B22 dimensions.

---

### STAGE 4 — Epistemic Architecture (AGENTS.md Layer 3)

**Tool**: `run_single_lens(lens_id="bayes", params={})` — Bayesian convergence
analysis. Returns convergence score and epistemic grade.

**Tool**: `hcp_query(question="epistemic grade for this analysis", keywords=["Tasavvur", "Tasdik", "Ilmelyakin", "T15", "kulliyat", "tafsilat"])`

---

### STAGE 5 — Quality Framework + Kavaid Check (AGENTS.md Layers 4–5)

This is the **primary integration point**. Three tools fire here:

1. **Run the full composite pipeline**:
   ```
   run_bileshke_pipeline(
     lens_params={
       "ontoloji": {"kavramlar": [...]},
       "mereoloji": {"parts": [...], "relations": [...]},
       "fol": {"text": "..."},
       "bayes": {},
       "oyun_teorisi": {},
       "kategori_teorisi": {},
       "holografik": {}
     },
     weights=null,       // null = equal 1/7 each (default)
     ortam_bits=[1,1,1]  // all 3 epistemic media covered
   )
   ```
   Returns: `composite_score`, `grade`, `coverage`, `kv4_warning`, `ax57_disclosure`, `per_lens` results.

2. **Check all 8 kavaid**:
   ```
   check_kavaid(
     composite_score=<from bileshke>,
     latife_bits=[1,1,1,1,1,1,0],  // 6/7 max — Ahfâ always 0 (T17)
     kavaid_overrides={"KV1": true, "KV2": true, ...}  // semantic overrides
   )
   ```
   Returns: per-kavaid pass/fail with explanations.
   **Conflict resolution**: KV₃, KV₄, KV₇ are structurally computed (tool wins).
   KV₁, KV₂, KV₅, KV₆, KV₈ accept overrides but divergence is disclosed.

3. **Game-theoretic lens** (if strategic interaction is relevant):
   ```
   run_single_lens(lens_id="oyun_teorisi", params={})
   ```

**CRITICAL — AX52 Gate**: If `run_bileshke_pipeline` returns ANY lens with
score = 0.0, or if `check_kavaid` returns ANY kavaid as FAIL, this is a
zero-dimension collapse. Do NOT proceed past Stage 5 until addressed.

---

### STAGE 6 — Structural Incompleteness (AGENTS.md Layer 7)

No dedicated tool — use the output from Stage 5:
- `coverage.latife_completeness` reveals the 6/7 max (T17)
- `grade` confirms ≤ İlmelyakîn (AX56)
- `kv4_warning` flags if composite approaches 1.0
- The AX58 gap (şuhud–istidlal) is structural and always present

---

### STAGE 7 — copilot-instructions.md Full Pass

No dedicated tool. This stage is pure routing/translation validation.
Use results from Stages 5–6 to populate the compliance check table.

---

### STAGE 8 — Inference Graph Activation

**Tool**: `verify_chains(chain_id="<C1-C7>", text="<relevant text>")`
— verify a specific inference chain from the Inference Graph (AGENTS.md §IG.2).
Returns `chain_id`, `verified` (bool), `axiom_refs`, `chain_trace`, `grade`.

Valid chain IDs: `C1` through `C7` (matching AGENTS.md §IG.2 seven primary chains).

**Tool**: `hcp_query(question="inference chain cross-validation", keywords=["kaskad", "tesanud", "hub node", "KV4"])`

---

### STAGE 9 — Synthesis, Actualization, Final Output

#### 9A — Actualize (BUILD/HYBRID modes)

Use any creation/execution tools as needed. The fw-engine tools are
analysis instruments — they inform what to build, not what to deploy.

#### 9B — Synthesize + AX57 Disclosure

**Tool**: `hcp_diagnostics()` — get HCP state for transparency disclosure.

**Tool**: `hcp_export_state()` — capture a full state checkpoint for later resumption.
Store the returned JSON so you can resume this session via `hcp_import_state`.

**Workflow completion**: If a workflow was created, all stages should be complete.
Check via `hcp_diagnostics` → `workflows` section.

**For the AX57 disclosure block**, use data from:
- `run_bileshke_pipeline` → composite_score, coverage, grade, per_lens
- `check_kavaid` → kavaid pass/fail
- `verify_chains` → chain activation count, tesanüd instances
- `hcp_diagnostics` → context state

Populate the disclosure block with **computed values**, not estimates:
```
Kavaid: KV₁[computed] KV₂[computed] KV₃[computed] KV₄[computed — composite: x.xx] ...
Epistemic grade: [from bileshke grade field]
Cross-validation: [from chain verification count]
```

---

## Tool Parameter Reference

### run_single_lens
```json
{
  "lens_id": "ontoloji|mereoloji|fol|bayes|oyun_teorisi|kategori_teorisi|holografik",
  "params": { }  // lens-specific, see per-stage sections above
}
```

### run_bileshke_pipeline
```json
{
  "lens_params": { "<lens_id>": { } },  // all 7 lenses
  "weights": null | { "<lens_id>": 0.xx },  // null = equal
  "ortam_bits": [1, 1, 1]  // Nesim, Ziya, Ab-ı Hayat
}
```

### check_kavaid
```json
{
  "composite_score": 0.xx,
  "latife_bits": [1,1,1,1,1,1,0],  // 7 bits, Ahfâ always 0
  "kavaid_overrides": { "KV1": true, ... }  // optional semantic overrides
}
```

### verify_chains
```json
{
  "chain_id": "C1|C2|C3|C4|C5|C6|C7",
  "text": "text to verify against chain"
}
```

### hcp_ingest / hcp_query / hcp_diagnostics
```json
// ingest
{ "text": "source text to seed",
  "source_metadata": "{\"source\": \"AGENTS.md\", \"section\": \"Layer 2\"}"  // optional JSON
}

// query
{ "question": "...", "keywords": ["..."], "top_k": 5 }

// diagnostics — no parameters
```

### hcp_create_workflow
```json
{
  "stages": "[{\"name\": \"classify\", \"expected_input\": \"query\", \"expected_output\": \"path\", \"prompt_template\": \"...\", \"metadata\": \"...\"}, ...]",
  "workflow_id": null  // optional — auto-generated if omitted
}
```
Each stage object requires `name`; all other keys are optional.

### hcp_advance_workflow
```json
{
  "workflow_id": "wf-...",
  "output": "the output produced for this stage",
  "success": true,        // default true
  "error": null            // optional error message
}
```

### hcp_export_state / hcp_import_state
```json
// export — no parameters, returns full state JSON with schema_version

// import
{ "state_json": "<JSON string from a previous hcp_export_state call>" }
```

### get_framework_summary / check_kavaid
```json
// framework_summary — no parameters
// check_kavaid — see above
```

---

## Architectural Notes

- **KV₇ Compliance**: Every lens adapter creates FRESH instances. No shared state
  between lenses. HCP is the sole exception — it is classified as AX27 (transparent
  vessel: mediates but doesn't originate), and its singleton nature enables
  cross-stage context accumulation without violating instrument independence.

- **AX56 Ceiling**: The grade_map module NEVER returns Hakkalyakîn. The maximum
  achievable grade is İlmelyakîn (score ≥ 0.86). This is structural, not a bug.

- **T17 Bound**: `latife_bits[6]` (Ahfâ) is ALWAYS 0. The system enforces 6/7
  maximum completeness. Do not override this.

- **KV₄ Warning**: If `composite_score ≥ 0.95`, the bileshke pipeline returns a
  `kv4_warning` string. This is NOT success — it indicates the map is being
  confused with the territory. Downgrade confidence and investigate.

---

*Companion file to fw.prompt.md. Relation: NeAynNeGayr — augments the pipeline without replacing it. 0 < Fidelity < 1.*
