fpf-thinking-map 1.3.0__tar.gz → 1.4.0__tar.gz

{fpf_thinking_map-1.3.0 → fpf_thinking_map-1.4.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: fpf-thinking-map
-Version: 1.3.0
+Version: 1.4.0
 Summary: Agentic thinking map — structured reasoning constraints for LLMs with TTL evidence decay, deterministic guards, and propositional logic glue. Compiled from FPF (First Principles Framework).
 Author-email: "prichindel.com" <igareosh@igareosh.com>
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/igareosh/prichindel.com-agentic-thinking-map
 Project-URL: Repository, https://github.com/igareosh/prichindel.com-agentic-thinking-map
 Project-URL: Documentation, https://github.com/igareosh/prichindel.com-agentic-thinking-map#readme
@@ -12,7 +12,6 @@ Keywords: agentic,thinking-map,llm,reasoning,propositional-logic,evidence-decay,
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
@@ -27,24 +26,53 @@ Dynamic: license-file
 
 # prichindel.com Agentic Thinking Map
 
-**v1.3.0** — [FPF (First Principles Framework)](https://github.com/ailev/FPF) compiled into a semi-formal thinking map for agentic AI guidance.
+**v1.4.0** — [FPF (First Principles Framework)](https://github.com/ailev/FPF), compiled into a small traversal map for LLM agents.
 
-A Python package that gives an AI model a small, structured board to reason on — one move at a time. Instead of freeform text generation, the model navigates a pre-shaped semantic field with deterministic guards and propositional logic constraints.
+A Python package that gives a model a bounded move board instead of a giant framework to digest at runtime. Instead of rereading a sprawling semantic corpus and improvising from it, the model gets a small JSON slice: what context it is in, what move is open, what evidence is missing, what is risky, and what outcome class applies.
 
 **[Visual architecture →](ARCHITECTURE.md)** — module graph, step flowchart, floor map, evidence lifecycle, slice structure, deploy sequence diagram.
 
+## Why this exists
+
+FPF is valuable, but it is large, clumsy at runtime, and poorly shaped for direct model consumption. A human can read a 51k-line framework, understand its distinctions, and apply them carefully. A model usually does something else: it absorbs the vocabulary, performs the tone of the framework, and still drifts on the actual task.
+
+This package exists because the useful part is not making the model sound more scientific. The useful part is compiling the parts of FPF that help operational decisions into something small, explicit, and inspectable. We took what mattered for bounded traversal, left out what would bloat or bias the model, and evolved the result as publishers of a practical library rather than trying to reproduce the whole upstream framework inside another AI mega-system.
+
+The goal is simple: give the model enough structure to behave understandably, without building a cage so elaborate that it becomes another source of drift.
+
+We do not compete with FPF and we do not need to. FPF stays FPF: broad, ambitious, and useful as a frame. This library is the smaller usable tool for people who want the frame without carrying the whole corpus into every project.
+
 ## What it does
 
-You define a domain as a semantic map (contexts, roles, gates, evidence, transitions). The model gets a per-move slice — just the current transition, its gate, its evidence, and whether it can fire. Deterministic guards enforce hard constraints the model cannot override. Propositional logic rules (NOT, AND, OR, XOR, IMPLIES, IFF) provide decision glue between the semantic primitives and the model's reasoning.
+You define a domain as a semantic map: contexts, roles, gates, evidence, transitions. The model gets a per-move slice, not a theory dump. Deterministic guards handle the hard checks. Propositional logic rules (NOT, AND, OR, XOR, IMPLIES, IFF) provide explicit decision glue between the semantic primitives and the current state.
+
+The model's job is not "what does FPF mean?" It is: **given this map and this state, what is the best lawful next move?**
+
+In practice this does two useful things:
+
+- it reduces unexplained drift by moving state tracking and hard checks out of freeform model reasoning
+- it gives the model simple, understandable outcomes such as `CONTINUE`, `COLLECT_EVIDENCE`, `BRIDGE`, `IDLE`, `ESCALATE`, instead of making it reconstruct its own epistemic condition from scratch
+
+This is not a panacea. Models still miss information. They still drift. But with a bounded traversal map, the failure mode becomes much easier to explain: missing evidence, wrong context, blocked move, stale basis, unlicensed bridge. The weirdness gets smaller because the state is smaller.
+
+## Provable practical gains
 
-The model's job is not "what does FPF mean?" — it is: **given this semantic map and this state, what is the best lawful next move?**
+The improvements here are intentionally simple and operational:
+
+- less random drift, because the agent reads explicit state instead of reconstructing state from prose
+- fewer unlawful moves, because guards and scoped transitions check them before the model improvises
+- clearer failure, because "why blocked" is surfaced directly
+- smaller runtime payload, because the model gets a slice, not a corpus
+- easier debugging, because outcomes are discrete and inspectable
+
+That is the whole point: practical gain, not intellectual theater.
 
 ## Quick start
 
 ```bash
 # No dependencies. Python 3.12+.
 
-# Verify the package (21 checks)
+# Verify the package (22 checks)
 python -m fpf_thinking_map.verify
 
 # Run the deploy decision scenario
@@ -60,7 +88,7 @@ fpf_thinking_map/
 ├── guards.py                 9 deterministic guards (context, role, gate, evidence, assignment, speech act, readiness)
 ├── logic.py                  6 logic operators + decision rules + LogicLayer
 ├── traversal.py              Step engine with 10 lawful outcomes (incl. IDLE, BRIDGE)
-├── verify.py                 Self-verification harness (21/21 checks)
+├── verify.py                 Self-verification harness (22/22 checks)
 ├── examples.py               5 deploy decision scenarios (missing evidence, role conflict, logic glue, truth table)
 ├── README.md                 Full documentation (any-model readable)
 ├── SOURCES.md                Source attribution (FPF spec + Mitev lectures)
@@ -76,6 +104,8 @@ fpf_thinking_map/
 
 This package is built on [ailev/FPF](https://github.com/ailev/FPF) by Anatoly Levenchuk. It is an independent implementation — our own research and code, MIT-licensed, with further development rights.
 
+It is not an attempt to "finish" FPF, replace FPF, or repackage the whole corpus for LLM ingestion. It is a selective compilation for agentic traversal.
+
 ### What we reviewed
 
 We cross-checked the following FPF commits (June 2026 precision restoration cluster) against our code:
@@ -104,6 +134,33 @@ Two FPF pattern families rejected for activation bias — they amplify existing
 
 **Design rule**: the map evaluates and constrains moves. It does not propose them. Generative, branch-friendly, candidate-multiplying patterns are the opposite of what a per-move guard-constrained thinking map should contain.
 
+## Scope and non-goals
+
+This library is intentionally small in scope.
+
+- It is for bounded, stepwise agent traversal in a defined domain.
+- It is for making model behavior more understandable, not more magical.
+- It is for simple +/- operational decisions in context, not for open-ended idea generation.
+- It is for constraining and instrumenting an agent run, not replacing the model.
+
+It is not:
+
+- a full semantic ingestion layer for all of FPF
+- a universal reasoning engine
+- a replacement for ordinary application logic or policy code
+- a proof that an LLM will behave correctly just because the map exists
+- Memory-Augmented Generation (MAG) — no embeddings, no vector store, no cross-session retrieval, ever, inside this engine. Rejected deliberately and permanently, not by omission. See below.
+
+## What this actually guarantees
+
+fpf does not ship better reasoning. It ships **inspectability**: did the agent follow the lawful path, and was evidence honestly reported at the one place that matters — the wire between what the agent actually did and what this library was told.
+
+Take the stagnation counter as the concrete case. It bounds repetition — but only if the integration maps one real attempt to one `step()` call, and only adds evidence when something genuinely new was found. Whether that actually catches a real LLM thrashing depends entirely on whether the calling harness wires evidence honestly, not just "a tool returned something." That wiring discipline lives outside this library, in whatever integrates it — an agent loop, an MCP server, application code. fpf can't verify that discipline was followed; it can only guarantee that if it was, repetition is bounded.
+
+That boundary is the correct seam, not a gap to apologize for. Judging whether a piece of evidence is actually meaningful is a semantic question, and semantic questions need prompting, an LLM judge, or domain logic to answer — which is exactly where that belongs: outside fpf, at the evidence-wiring layer, not folded into a library whose entire value is staying small and deterministic. If you want semantics and clever prompting, that's the plug-in point.
+
+**This is also why Memory-Augmented Generation (MAG) is rejected as fpf's own architecture, deliberately and permanently.** MAG — retrieval, embeddings, cross-session recall — solves a different problem (what did we discuss three sessions ago) than fpf solves (is this move lawful right now), and it needs exactly the dependency profile this library rules out by design. That is a scope boundary, not a verdict on MAG as a technique: a MAG system is a legitimate thing to run *upstream* of fpf. Whatever it retrieves becomes an evidence_id in `RuntimeBinding.current_evidence` like any other — fpf doesn't care how evidence was produced, only whether it's present, fresh, and licensed. Memory belongs at the evidence-wiring layer, alongside every other semantic judgment this library deliberately doesn't make.
+
 ## Sources
 
 - **[FPF (First Principles Framework)](https://github.com/ailev/FPF)** by Anatoly Levenchuk — transdisciplinary specification (~51k lines). We extracted 10 semantic primitives and 9 guard rules. This is a compiled distillation, not a port.
@@ -111,6 +168,22 @@ Two FPF pattern families rejected for activation bias — they amplify existing
 
 Full attribution in [SOURCES.md](fpf_thinking_map/SOURCES.md).
 
+## Why it works
+
+The core advantage is not "more theory." It is less runtime burden.
+
+Without a compiled map, the model keeps re-addressing its own run: am I allowed to move, did I already satisfy the gate, am I missing evidence, am I in the wrong context, am I done or blocked? That self-management loop is where a lot of bad agent behavior comes from.
+
+This package turns that loop into a small stateful instrument panel. The model sees what can fire, what cannot, and why. That is enough of an operating surface for many practical agent tasks. Not a panacea, not a grand theory of intelligence, just enough window and file-handles for the model to open the right thing without smashing the house.
+
+The bottleneck was never raw model capability — it's self-management overhead eating the capability that's already there. Most orgs running these models, at any scale, hit that ceiling: infra and process that never actually asked the model for full capacity, so upgrading the model changes nothing. This library doesn't make the model smarter. It shrinks what the model has to hold in its head at any one step, so whatever capability is actually there gets spent on the real problem instead of on self-management overhead.
+
+Clean product truth:
+
+- FPF is the frame.
+- This library is the usable tool.
+- It keeps the frame where it helps, removes the bloat where it hurts, and gives agents a small operational board that produces simpler, more provable behavior.
+
 ## Why v1.1 exists — reasoning about reasoning is the bug
 
 When an LLM navigates a multi-step decision, it faces the same sub-questions at every step: "Is my evidence still valid? Am I going in circles? Is there another path? Why am I blocked?" Without structure, the model re-derives these answers from scratch each time — re-reasoning on its own prior reasoning. Each pass costs tokens, drifts from the original question, and eventually the context fills up with the model arguing with itself about whether it already checked something it checked three steps ago.
@@ -131,6 +204,18 @@ The model's job shrinks from "figure out the entire epistemic state of your own
 - **Evidence status in prompt** — the LLM prompt state now includes per-evidence freshness and TTL remaining. The model sees "test_results: 3 steps left" instead of just "test_results: exists." Decisions informed by countdown, not by guessing.
 - **Response contract** — every slice now ends with a `response_contract`: the structured template the model must fill when responding. Pre-filled fields (scope, basis with freshness/TTL, allowed use, not allowed use, modality, canonical terms, audience) come from the computed state. Empty fields (claim, risky aliases) are for the model. This is why all the code exists — so the contract has precomputed, validated values instead of being re-derived by the model from scratch.
 
+## v1.3.0 changes
+
+- **Bridge crossing is enforced, not just advertised** — `ActiveState.cross_bridge()` / `ThinkingMapTraversal.attempt_bridge()` actually perform a cross-context hop and check `substitution_license` against `risk_level` before mutating state. An unlicensed bridge under `high`/`critical` risk is refused (`ESCALATE`), not silently allowed. Before this, `bridge_options()` was advisory metadata only — the model decided for itself whether a lossy translation was acceptable.
+- **`include_full_state=False`** — `step()` can now ship the scoped `slice()` alone, without the whole board bolted on. Default stays `True`; opt in when the caller already knows its `transition_id` and wants the lean payload.
+- 21/21 self-verification checks (`python -m fpf_thinking_map.verify`), two new: bridge crossing and lean-slice payload shape.
+
+## v1.4.0 changes
+
+- **Stagnation counter** — `ActiveState.register_visit()` / `visit_count` / `visits_remaining` / `is_stagnant` count consecutive `step()`s at the same `(context, state)` pair with no new evidence gathered; the counter resets the moment the evidence set changes. `visits_remaining` mirrors `ttl_remaining`'s exact shape — a countdown, not a boolean. Surfaced in both `slice()` and `to_llm_prompt_state()` as a `stagnation` block. Pure signal: no new outcome kind, nothing blocks, no restraint added to the model's options. Closes a real blind spot — `MoveTrace` is deliberately last-move-only (no narrative accumulation), so the engine previously had no way to notice "I've revisited this exact state N times with nothing new to show for it."
+- The guarantee is conditional, and the docs say so plainly: this tracks evidence *set membership*, not evidence *meaning*. It bounds repetition only if the integration maps one real attempt to one `step()` call and only adds evidence that's genuinely new — see [What this actually guarantees](#what-this-actually-guarantees).
+- 22/22 self-verification checks, one new: `check_stagnation_counter`.
+
 ## Design principles
 
 - **Only add structure when it changes agentic behavior** — not for source fidelity alone
@@ -140,10 +225,10 @@ The model's job shrinks from "figure out the entire epistemic state of your own
 
 ## Using as a dependency
 
-This package is the reasoning engine. Your domain maps run on top of it.
+This package is the compiled map, not a thinking replacement for the model. Denying unlawful moves is only half the job. The bigger half is returning the lawful surface as a small, plain-JSON slice: what can fire, what is missing, what is risky, why a move is blocked, what response shape is expected. That lets the model self-address its own run with simple signals such as `can_fire`, `blockers`, and `outcome.kind` instead of re-reasoning about its state from prose.
 
 ```bash
-pip install git+https://github.com/igareosh/prichindel.com-agentic-thinking-map.git
+pip install fpf-thinking-map
 ```
 
 ```python
@@ -207,10 +292,25 @@ Built with Claude Code (Anthropic claude-sonnet-4-6). Tested and verified to wor
 
 This is not a compliance seal. It means: we used these models against this package and they produced correct, usable results. The per-move slice is small enough for mid-tier models. The logic and guard outputs are plain JSON — no special tokenization or prompt format required.
 
+## Why release this
+
+We release this because it is useful beyond our own stack.
+
+- It captures a practical subset of FPF in a form models can actually use.
+- It gives agent builders a small constraint surface instead of another giant AI framework.
+- It helps turn model failure from mystical drift into inspectable state.
+- It stays intentionally narrow, so it can remain legible instead of becoming another overbuilt "agent platform."
+
+## Credits
+
+- **igareosh** — project direction, scope discipline, practical use-case pressure, and product truth
+- **Claude Code (Anthropic)** — implementation support, library iteration, and earlier release preparation
+- **Codex / OpenAI** — product framing polish, packaging cleanup, verification, and release-readiness work
+
 ## License
 
 MIT. See [LICENSE](LICENSE).
 
 ---
 
-**prichindel.com** — v1.2.1 — 2026-06-26
+**prichindel.com** — v1.4.0 — 2026-07-07

{fpf_thinking_map-1.3.0 → fpf_thinking_map-1.4.0}/README.md

@@ -1,23 +1,52 @@
 # prichindel.com Agentic Thinking Map
 
-**v1.3.0** — [FPF (First Principles Framework)](https://github.com/ailev/FPF) compiled into a semi-formal thinking map for agentic AI guidance.
+**v1.4.0** — [FPF (First Principles Framework)](https://github.com/ailev/FPF), compiled into a small traversal map for LLM agents.
 
-A Python package that gives an AI model a small, structured board to reason on — one move at a time. Instead of freeform text generation, the model navigates a pre-shaped semantic field with deterministic guards and propositional logic constraints.
+A Python package that gives a model a bounded move board instead of a giant framework to digest at runtime. Instead of rereading a sprawling semantic corpus and improvising from it, the model gets a small JSON slice: what context it is in, what move is open, what evidence is missing, what is risky, and what outcome class applies.
 
 **[Visual architecture →](ARCHITECTURE.md)** — module graph, step flowchart, floor map, evidence lifecycle, slice structure, deploy sequence diagram.
 
+## Why this exists
+
+FPF is valuable, but it is large, clumsy at runtime, and poorly shaped for direct model consumption. A human can read a 51k-line framework, understand its distinctions, and apply them carefully. A model usually does something else: it absorbs the vocabulary, performs the tone of the framework, and still drifts on the actual task.
+
+This package exists because the useful part is not making the model sound more scientific. The useful part is compiling the parts of FPF that help operational decisions into something small, explicit, and inspectable. We took what mattered for bounded traversal, left out what would bloat or bias the model, and evolved the result as publishers of a practical library rather than trying to reproduce the whole upstream framework inside another AI mega-system.
+
+The goal is simple: give the model enough structure to behave understandably, without building a cage so elaborate that it becomes another source of drift.
+
+We do not compete with FPF and we do not need to. FPF stays FPF: broad, ambitious, and useful as a frame. This library is the smaller usable tool for people who want the frame without carrying the whole corpus into every project.
+
 ## What it does
 
-You define a domain as a semantic map (contexts, roles, gates, evidence, transitions). The model gets a per-move slice — just the current transition, its gate, its evidence, and whether it can fire. Deterministic guards enforce hard constraints the model cannot override. Propositional logic rules (NOT, AND, OR, XOR, IMPLIES, IFF) provide decision glue between the semantic primitives and the model's reasoning.
+You define a domain as a semantic map: contexts, roles, gates, evidence, transitions. The model gets a per-move slice, not a theory dump. Deterministic guards handle the hard checks. Propositional logic rules (NOT, AND, OR, XOR, IMPLIES, IFF) provide explicit decision glue between the semantic primitives and the current state.
+
+The model's job is not "what does FPF mean?" It is: **given this map and this state, what is the best lawful next move?**
+
+In practice this does two useful things:
+
+- it reduces unexplained drift by moving state tracking and hard checks out of freeform model reasoning
+- it gives the model simple, understandable outcomes such as `CONTINUE`, `COLLECT_EVIDENCE`, `BRIDGE`, `IDLE`, `ESCALATE`, instead of making it reconstruct its own epistemic condition from scratch
+
+This is not a panacea. Models still miss information. They still drift. But with a bounded traversal map, the failure mode becomes much easier to explain: missing evidence, wrong context, blocked move, stale basis, unlicensed bridge. The weirdness gets smaller because the state is smaller.
+
+## Provable practical gains
 
-The model's job is not "what does FPF mean?" — it is: **given this semantic map and this state, what is the best lawful next move?**
+The improvements here are intentionally simple and operational:
+
+- less random drift, because the agent reads explicit state instead of reconstructing state from prose
+- fewer unlawful moves, because guards and scoped transitions check them before the model improvises
+- clearer failure, because "why blocked" is surfaced directly
+- smaller runtime payload, because the model gets a slice, not a corpus
+- easier debugging, because outcomes are discrete and inspectable
+
+That is the whole point: practical gain, not intellectual theater.
 
 ## Quick start
 
 ```bash
 # No dependencies. Python 3.12+.
 
-# Verify the package (21 checks)
+# Verify the package (22 checks)
 python -m fpf_thinking_map.verify
 
 # Run the deploy decision scenario
@@ -33,7 +62,7 @@ fpf_thinking_map/
 ├── guards.py                 9 deterministic guards (context, role, gate, evidence, assignment, speech act, readiness)
 ├── logic.py                  6 logic operators + decision rules + LogicLayer
 ├── traversal.py              Step engine with 10 lawful outcomes (incl. IDLE, BRIDGE)
-├── verify.py                 Self-verification harness (21/21 checks)
+├── verify.py                 Self-verification harness (22/22 checks)
 ├── examples.py               5 deploy decision scenarios (missing evidence, role conflict, logic glue, truth table)
 ├── README.md                 Full documentation (any-model readable)
 ├── SOURCES.md                Source attribution (FPF spec + Mitev lectures)
@@ -49,6 +78,8 @@ fpf_thinking_map/
 
 This package is built on [ailev/FPF](https://github.com/ailev/FPF) by Anatoly Levenchuk. It is an independent implementation — our own research and code, MIT-licensed, with further development rights.
 
+It is not an attempt to "finish" FPF, replace FPF, or repackage the whole corpus for LLM ingestion. It is a selective compilation for agentic traversal.
+
 ### What we reviewed
 
 We cross-checked the following FPF commits (June 2026 precision restoration cluster) against our code:
@@ -77,6 +108,33 @@ Two FPF pattern families rejected for activation bias — they amplify existing
 
 **Design rule**: the map evaluates and constrains moves. It does not propose them. Generative, branch-friendly, candidate-multiplying patterns are the opposite of what a per-move guard-constrained thinking map should contain.
 
+## Scope and non-goals
+
+This library is intentionally small in scope.
+
+- It is for bounded, stepwise agent traversal in a defined domain.
+- It is for making model behavior more understandable, not more magical.
+- It is for simple +/- operational decisions in context, not for open-ended idea generation.
+- It is for constraining and instrumenting an agent run, not replacing the model.
+
+It is not:
+
+- a full semantic ingestion layer for all of FPF
+- a universal reasoning engine
+- a replacement for ordinary application logic or policy code
+- a proof that an LLM will behave correctly just because the map exists
+- Memory-Augmented Generation (MAG) — no embeddings, no vector store, no cross-session retrieval, ever, inside this engine. Rejected deliberately and permanently, not by omission. See below.
+
+## What this actually guarantees
+
+fpf does not ship better reasoning. It ships **inspectability**: did the agent follow the lawful path, and was evidence honestly reported at the one place that matters — the wire between what the agent actually did and what this library was told.
+
+Take the stagnation counter as the concrete case. It bounds repetition — but only if the integration maps one real attempt to one `step()` call, and only adds evidence when something genuinely new was found. Whether that actually catches a real LLM thrashing depends entirely on whether the calling harness wires evidence honestly, not just "a tool returned something." That wiring discipline lives outside this library, in whatever integrates it — an agent loop, an MCP server, application code. fpf can't verify that discipline was followed; it can only guarantee that if it was, repetition is bounded.
+
+That boundary is the correct seam, not a gap to apologize for. Judging whether a piece of evidence is actually meaningful is a semantic question, and semantic questions need prompting, an LLM judge, or domain logic to answer — which is exactly where that belongs: outside fpf, at the evidence-wiring layer, not folded into a library whose entire value is staying small and deterministic. If you want semantics and clever prompting, that's the plug-in point.
+
+**This is also why Memory-Augmented Generation (MAG) is rejected as fpf's own architecture, deliberately and permanently.** MAG — retrieval, embeddings, cross-session recall — solves a different problem (what did we discuss three sessions ago) than fpf solves (is this move lawful right now), and it needs exactly the dependency profile this library rules out by design. That is a scope boundary, not a verdict on MAG as a technique: a MAG system is a legitimate thing to run *upstream* of fpf. Whatever it retrieves becomes an evidence_id in `RuntimeBinding.current_evidence` like any other — fpf doesn't care how evidence was produced, only whether it's present, fresh, and licensed. Memory belongs at the evidence-wiring layer, alongside every other semantic judgment this library deliberately doesn't make.
+
 ## Sources
 
 - **[FPF (First Principles Framework)](https://github.com/ailev/FPF)** by Anatoly Levenchuk — transdisciplinary specification (~51k lines). We extracted 10 semantic primitives and 9 guard rules. This is a compiled distillation, not a port.
@@ -84,6 +142,22 @@ Two FPF pattern families rejected for activation bias — they amplify existing
 
 Full attribution in [SOURCES.md](fpf_thinking_map/SOURCES.md).
 
+## Why it works
+
+The core advantage is not "more theory." It is less runtime burden.
+
+Without a compiled map, the model keeps re-addressing its own run: am I allowed to move, did I already satisfy the gate, am I missing evidence, am I in the wrong context, am I done or blocked? That self-management loop is where a lot of bad agent behavior comes from.
+
+This package turns that loop into a small stateful instrument panel. The model sees what can fire, what cannot, and why. That is enough of an operating surface for many practical agent tasks. Not a panacea, not a grand theory of intelligence, just enough window and file-handles for the model to open the right thing without smashing the house.
+
+The bottleneck was never raw model capability — it's self-management overhead eating the capability that's already there. Most orgs running these models, at any scale, hit that ceiling: infra and process that never actually asked the model for full capacity, so upgrading the model changes nothing. This library doesn't make the model smarter. It shrinks what the model has to hold in its head at any one step, so whatever capability is actually there gets spent on the real problem instead of on self-management overhead.
+
+Clean product truth:
+
+- FPF is the frame.
+- This library is the usable tool.
+- It keeps the frame where it helps, removes the bloat where it hurts, and gives agents a small operational board that produces simpler, more provable behavior.
+
 ## Why v1.1 exists — reasoning about reasoning is the bug
 
 When an LLM navigates a multi-step decision, it faces the same sub-questions at every step: "Is my evidence still valid? Am I going in circles? Is there another path? Why am I blocked?" Without structure, the model re-derives these answers from scratch each time — re-reasoning on its own prior reasoning. Each pass costs tokens, drifts from the original question, and eventually the context fills up with the model arguing with itself about whether it already checked something it checked three steps ago.
@@ -104,6 +178,18 @@ The model's job shrinks from "figure out the entire epistemic state of your own
 - **Evidence status in prompt** — the LLM prompt state now includes per-evidence freshness and TTL remaining. The model sees "test_results: 3 steps left" instead of just "test_results: exists." Decisions informed by countdown, not by guessing.
 - **Response contract** — every slice now ends with a `response_contract`: the structured template the model must fill when responding. Pre-filled fields (scope, basis with freshness/TTL, allowed use, not allowed use, modality, canonical terms, audience) come from the computed state. Empty fields (claim, risky aliases) are for the model. This is why all the code exists — so the contract has precomputed, validated values instead of being re-derived by the model from scratch.
 
+## v1.3.0 changes
+
+- **Bridge crossing is enforced, not just advertised** — `ActiveState.cross_bridge()` / `ThinkingMapTraversal.attempt_bridge()` actually perform a cross-context hop and check `substitution_license` against `risk_level` before mutating state. An unlicensed bridge under `high`/`critical` risk is refused (`ESCALATE`), not silently allowed. Before this, `bridge_options()` was advisory metadata only — the model decided for itself whether a lossy translation was acceptable.
+- **`include_full_state=False`** — `step()` can now ship the scoped `slice()` alone, without the whole board bolted on. Default stays `True`; opt in when the caller already knows its `transition_id` and wants the lean payload.
+- 21/21 self-verification checks (`python -m fpf_thinking_map.verify`), two new: bridge crossing and lean-slice payload shape.
+
+## v1.4.0 changes
+
+- **Stagnation counter** — `ActiveState.register_visit()` / `visit_count` / `visits_remaining` / `is_stagnant` count consecutive `step()`s at the same `(context, state)` pair with no new evidence gathered; the counter resets the moment the evidence set changes. `visits_remaining` mirrors `ttl_remaining`'s exact shape — a countdown, not a boolean. Surfaced in both `slice()` and `to_llm_prompt_state()` as a `stagnation` block. Pure signal: no new outcome kind, nothing blocks, no restraint added to the model's options. Closes a real blind spot — `MoveTrace` is deliberately last-move-only (no narrative accumulation), so the engine previously had no way to notice "I've revisited this exact state N times with nothing new to show for it."
+- The guarantee is conditional, and the docs say so plainly: this tracks evidence *set membership*, not evidence *meaning*. It bounds repetition only if the integration maps one real attempt to one `step()` call and only adds evidence that's genuinely new — see [What this actually guarantees](#what-this-actually-guarantees).
+- 22/22 self-verification checks, one new: `check_stagnation_counter`.
+
 ## Design principles
 
 - **Only add structure when it changes agentic behavior** — not for source fidelity alone
@@ -113,10 +199,10 @@ The model's job shrinks from "figure out the entire epistemic state of your own
 
 ## Using as a dependency
 
-This package is the reasoning engine. Your domain maps run on top of it.
+This package is the compiled map, not a thinking replacement for the model. Denying unlawful moves is only half the job. The bigger half is returning the lawful surface as a small, plain-JSON slice: what can fire, what is missing, what is risky, why a move is blocked, what response shape is expected. That lets the model self-address its own run with simple signals such as `can_fire`, `blockers`, and `outcome.kind` instead of re-reasoning about its state from prose.
 
 ```bash
-pip install git+https://github.com/igareosh/prichindel.com-agentic-thinking-map.git
+pip install fpf-thinking-map
 ```
 
 ```python
@@ -180,10 +266,25 @@ Built with Claude Code (Anthropic claude-sonnet-4-6). Tested and verified to wor
 
 This is not a compliance seal. It means: we used these models against this package and they produced correct, usable results. The per-move slice is small enough for mid-tier models. The logic and guard outputs are plain JSON — no special tokenization or prompt format required.
 
+## Why release this
+
+We release this because it is useful beyond our own stack.
+
+- It captures a practical subset of FPF in a form models can actually use.
+- It gives agent builders a small constraint surface instead of another giant AI framework.
+- It helps turn model failure from mystical drift into inspectable state.
+- It stays intentionally narrow, so it can remain legible instead of becoming another overbuilt "agent platform."
+
+## Credits
+
+- **igareosh** — project direction, scope discipline, practical use-case pressure, and product truth
+- **Claude Code (Anthropic)** — implementation support, library iteration, and earlier release preparation
+- **Codex / OpenAI** — product framing polish, packaging cleanup, verification, and release-readiness work
+
 ## License
 
 MIT. See [LICENSE](LICENSE).
 
 ---
 
-**prichindel.com** — v1.2.1 — 2026-06-26
+**prichindel.com** — v1.4.0 — 2026-07-07

{fpf_thinking_map-1.3.0 → fpf_thinking_map-1.4.0}/fpf_thinking_map/README.md

@@ -1,6 +1,6 @@
 # FPF Thinking Map
 
-This folder contains a Python package that helps an AI model make decisions step by step. It does this by combining two things: a structured framework for reasoning (called FPF) and basic logic operations (AND, OR, NOT, etc.) from computer science.
+This folder contains a Python package that helps an AI model make bounded decisions step by step. It combines a compiled subset of FPF with basic logic operations from computer science so the model can read a small move board instead of digesting a giant framework at runtime.
 
 No external dependencies. Pure Python 3.12+. No pip install needed.
 
@@ -15,6 +15,14 @@ This package gives the model a small, structured board to reason on. The board h
 
 The model reads the board, then picks from a fixed set of moves: continue, ask, abstain, escalate, collect evidence, etc.
 
+The point is not to make the model "more intelligent." The point is to make its behavior smaller, more understandable, and less likely to drift for stupid reasons.
+
+## Why this package exists next to FPF
+
+FPF is strong material for humans, but too big and too clumsy to hand to a model raw and expect clean operational behavior. A model tends to absorb the vocabulary, imitate the posture of rigor, and still miss the simple thing it needed to do.
+
+So we did not port the whole framework. We extracted what was useful for bounded traversal, made it executable, and left out the parts that would inflate runtime payload or trigger open-ended academic-pattern generation. This package is not "FPF but more." It is "the part of FPF that helps agents behave better, compiled into something they can actually use."
+
 ## Where this comes from
 
 Two sources, both real academic material:
@@ -42,7 +50,7 @@ fpf_thinking_map/
 ├── guards.py                9 deterministic guards the model cannot break
 ├── logic.py                 6 logic operators + EvidenceFresh + decision rules
 ├── traversal.py             Step engine with 10 lawful outcomes (incl. IDLE, BRIDGE)
-├── verify.py                Self-test: run it, if 18/18 pass, package works
+├── verify.py                Self-test: run it, if 21/21 pass, package works
 │
 ├── examples.py              5 deploy decision scenarios (all features in action)
 │
@@ -135,7 +143,7 @@ Output: an Outcome with:
   - llm_prompt_state: the JSON the model reads to decide its next move
 ```
 
-When `transition_id` is given, the model gets a `slice()` — a tiny dict with just the move, its gate, its evidence, and whether it can fire. That is the per-move maneuver board.
+When `transition_id` is given, the model gets a `slice()` — a tiny dict with just the move, its gate, its evidence, and whether it can fire. That is the per-move maneuver board. If the caller wants it, the package can now return that lean slice without bolting the full state back on.
 
 ## How state works (state.py)
 
@@ -158,7 +166,7 @@ Three objects:
 - `slice(transition_id)` — tiny dict for one move
 - `transition_to(transition_id)` — execute a transition (checks context, evidence, and gates)
 
-**MoveTrace** — compressed history. Only stores last move, not full history: previous_state, last_transition_id, blockers, evidence_delta.
+**MoveTrace** — compressed history. Only stores last move, not full history: previous_state, last_transition_id, bridge_target, blockers, evidence_delta.
 
 ## Boundary rules (enforced, not advisory)
 
@@ -174,7 +182,7 @@ These constraints are checked at execution time, not just in the display layer:
 ```bash
 # From the repo root:
 
-# Verify the package works (18 checks)
+# Verify the package works (21 checks)
 python -m fpf_thinking_map.verify
 
 # Run the deploy decision scenario
@@ -253,9 +261,10 @@ outcome = engine.step(state, transition_id="start_to_reviewed")
 
 - Not a prompt template or system prompt
 - Not a retrieval/RAG system for FPF text
-- Not a replacement for the full FPF spec (51k lines — we extracted 8 objects)
+- Not a replacement for the full FPF spec
 - Not a symbolic AI / expert system (the LLM interprets; logic + guards constrain)
 - Not a framework to build on top of — it is a small self-contained package
+- Not a panacea for agent drift; it reduces and explains drift, it does not eliminate it
 
 ## Known design decisions
 

{fpf_thinking_map-1.3.0 → fpf_thinking_map-1.4.0}/fpf_thinking_map/WHY_THIS_EXISTS.md

@@ -4,6 +4,8 @@ This document explains why this package exists adjacent to the original FPF spec
 
 This is not a critique of FPF itself. As a human-readable transdisciplinary framework, FPF is strong and well-structured. The problem is not the framework — it is the assumption that a language model can absorb a 51,000-line specification and then apply it the way a human reader would.
 
+We are not trying to turn FPF into another giant AI stack. We took what was useful for bounded traversal, compiled it, and kept the result intentionally small. That is the product choice here: publish a practical instrument, not an empire.
+
 ## The triple tax: what happens when a model reads raw FPF
 
 When you give a language model the FPF specification text and ask it to make a decision, three things happen in sequence. Each one costs tokens, time, and accuracy.
@@ -52,6 +54,8 @@ One pass. No translation. No re-reasoning. The code already did the FPF thinking
 
 The model's job shrinks from "understand this 51k-line philosophy of reasoning and then apply it" to "read this small JSON, fill in the claim field, pick the next move."
 
+That smallness matters. It gives the model a simple operating surface for self-addressing its own run: what can fire, what cannot, what is missing, what is risky, whether it should continue, bridge, idle, or escalate. Not mystical agency. Just enough instrumentation to behave properly.
+
 ## Three problems with feeding raw FPF to a model
 
 ### 1. It makes the model re-reason N times
@@ -87,6 +91,8 @@ FPF as a human-readable specification: strong.
 FPF as raw input to a language model: triple tax.
 FPF compiled into a thinking map with precomputed state: what this package does.
 
+This is also why we release it publicly. The value is not private magic. The value is that other people building agents can stop overfeeding models with giant conceptual blobs and start giving them smaller, inspectable decision surfaces instead.
+
 ---
 
-prichindel.com | 2026-06-27 | v1.1.3
+prichindel.com | 2026-07-06 | v1.3.1

{fpf_thinking_map-1.3.0 → fpf_thinking_map-1.4.0}/fpf_thinking_map/state.py

@@ -187,7 +187,10 @@ class ActiveState:
     current_state: str = "initial"
     trace: MoveTrace = field(default_factory=MoveTrace)
     step_count: int = 0
+    stagnation_threshold: int = 3
     _evidence_added_at: dict[str, int] = field(default_factory=dict, init=False, repr=False)
+    _state_visits: dict[str, int] = field(default_factory=dict, init=False, repr=False)
+    _state_visit_evidence: dict[str, frozenset[str]] = field(default_factory=dict, init=False, repr=False)
 
     def __post_init__(self) -> None:
         for eid in self.binding.current_evidence:
@@ -276,6 +279,56 @@ class ActiveState:
         added_at = self._evidence_added_at.get(evidence_id, 0)
         return max(0, ttl - (self.step_count - added_at))
 
+    def _visit_key(self) -> str:
+        return f"{self.binding.active_context_id}:{self.current_state}"
+
+    def register_visit(self) -> int:
+        """#28: count consecutive step()s at this (context, state) pair.
+
+        A revisit with the same evidence set is not progress — it's the
+        countable, deterministic version of "the agent is stuck," instead
+        of asking the model to introspect about its own psychology. New
+        evidence resets the counter: different evidence means there's
+        something new to try, not a loop.
+
+        Called once per step() — see traversal.py. Returns the new count.
+
+        Syntactic, not semantic: this tracks set membership on evidence_ids,
+        not whether anything meaningful actually happened. Two consequences
+        a caller should know about. (1) A harness that adds a new evidence_id
+        on every attempt — even a low-value one — resets the counter every
+        time and this will never fire, no matter how unproductive the loop
+        actually is. (2) This only sees what reaches step(); flailing that
+        happens inside a single turn and never gets reported back as a step()
+        call is invisible to it. The guarantee this method gives is
+        conditional: if one real attempt maps to one step() call, and
+        evidence is only added when it's genuinely new, revisits are bounded
+        at stagnation_threshold. It cannot judge whether an attempt was real
+        progress — that's a semantic question this library doesn't answer.
+        """
+        key = self._visit_key()
+        snapshot = frozenset(self.available_evidence_ids)
+        if self._state_visit_evidence.get(key) != snapshot:
+            self._state_visits[key] = 0
+            self._state_visit_evidence[key] = snapshot
+        self._state_visits[key] = self._state_visits.get(key, 0) + 1
+        return self._state_visits[key]
+
+    @property
+    def visit_count(self) -> int:
+        """How many consecutive step()s have landed on this (context, state)
+        with the current evidence set, without advancing."""
+        return self._state_visits.get(self._visit_key(), 0)
+
+    @property
+    def visits_remaining(self) -> int:
+        """Countdown to stagnation_threshold — mirrors ttl_remaining's shape."""
+        return max(0, self.stagnation_threshold - self.visit_count)
+
+    @property
+    def is_stagnant(self) -> bool:
+        return self.visit_count >= self.stagnation_threshold
+
     @property
     def possible_transitions(self) -> list[TransitionPrimitive]:
         """#1: scoped to active context + current state."""
@@ -524,6 +577,12 @@ class ActiveState:
             ],
             "can_fire": can_fire,
             "blockers": blockers,
+            "stagnation": {
+                "visits": self.visit_count,
+                "remaining": self.visits_remaining,
+                "threshold": self.stagnation_threshold,
+                "is_stagnant": self.is_stagnant,
+            },
             "response_contract": self.response_contract(transition_id),
         }
 
@@ -577,6 +636,12 @@ class ActiveState:
             "available_tools": self.binding.available_tools,
             "audience": self.binding.audience,
             "step_count": self.step_count,
+            "stagnation": {
+                "visits": self.visit_count,
+                "remaining": self.visits_remaining,
+                "threshold": self.stagnation_threshold,
+                "is_stagnant": self.is_stagnant,
+            },
             "trace": {
                 "previous_state": self.trace.previous_state,
                 "last_transition": self.trace.last_transition_id,

{fpf_thinking_map-1.3.0 → fpf_thinking_map-1.4.0}/fpf_thinking_map/traversal.py

@@ -161,6 +161,8 @@ class ThinkingMapTraversal:
                 llm_prompt_state=state.to_llm_prompt_state(),
             )
 
+        state.register_visit()
+
         ctx_id = state.binding.active_context_id or ""
 
         if transition_id:

{fpf_thinking_map-1.3.0 → fpf_thinking_map-1.4.0}/fpf_thinking_map/verify.py

@@ -596,6 +596,64 @@ def check_ttl_decay():
     assert s3.effective_freshness("fast_ev") == Freshness.STALE
 
 
+def check_stagnation_counter():
+    """#28: visit counter + countdown for repeated (context, state) with no new evidence."""
+    sm = SemanticMap()
+    sm.register_context(ContextPrimitive("ctx", "Test"))
+    sm.register_transition(TransitionPrimitive(
+        "t1", "Go", "ctx", "stuck", "done", required_evidence=["missing_ev"],
+    ))
+
+    b = RuntimeBinding(active_context_id="ctx")
+    engine = ThinkingMapTraversal(sm)
+    s = engine.build_active_state(b, current_state="stuck")
+
+    # First visit: 1 visit registered, threshold default 3, 2 remaining, not stagnant
+    o1 = engine.step(s)
+    st1 = o1.llm_prompt_state["stagnation"]
+    assert st1["visits"] == 1, st1
+    assert st1["remaining"] == 2, st1
+    assert st1["threshold"] == 3
+    assert st1["is_stagnant"] is False
+
+    # Same state, same (empty) evidence, no progress — counter climbs
+    o2 = engine.step(s)
+    o3 = engine.step(s)
+    st3 = o3.llm_prompt_state["stagnation"]
+    assert st3["visits"] == 3, st3
+    assert st3["remaining"] == 0, st3
+    assert st3["is_stagnant"] is True
+
+    # New evidence arrives — counter resets, this is not a loop anymore
+    s.add_evidence("missing_ev")
+    o4 = engine.step(s)
+    st4 = o4.llm_prompt_state["stagnation"]
+    assert st4["visits"] == 1, "new evidence must reset the stagnation counter"
+    assert st4["is_stagnant"] is False
+
+    # slice() carries the same signal for a transition-focused call
+    s2 = engine.build_active_state(RuntimeBinding(active_context_id="ctx"), current_state="stuck")
+    o5 = engine.step(s2, transition_id="t1")
+    assert "stagnation" in o5.llm_prompt_state
+    assert o5.llm_prompt_state["stagnation"]["visits"] == 1
+
+    # Custom threshold is honored
+    s3 = ActiveState(sm, RuntimeBinding(active_context_id="ctx"), current_state="stuck", stagnation_threshold=1)
+    s3.register_visit()
+    assert s3.is_stagnant is True
+    assert s3.visits_remaining == 0
+
+    # attempt_transition (a real move) does not itself register a visit —
+    # only step() (the "what can I do" scan) counts as one
+    sm2 = SemanticMap()
+    sm2.register_context(ContextPrimitive("ctx2", "Test2"))
+    sm2.register_transition(TransitionPrimitive("t2", "Go", "ctx2", "a", "b"))
+    engine2 = ThinkingMapTraversal(sm2)
+    s4 = engine2.build_active_state(RuntimeBinding(active_context_id="ctx2"), current_state="a")
+    engine2.attempt_transition(s4, "t2")
+    assert s4.visit_count == 0
+
+
 def check_idle_outcome():
     """Verify IDLE outcome for clean terminal states."""
     sm = SemanticMap()
@@ -1077,6 +1135,7 @@ def main():
         ("end-to-end logic scenario", check_logic_end_to_end),
         ("horizontal properties (25 items)", check_horizontal_properties),
         ("TTL evidence decay", check_ttl_decay),
+        ("stagnation counter (visit countdown)", check_stagnation_counter),
         ("IDLE outcome", check_idle_outcome),
         ("BRIDGE outcome (cross-context)", check_bridge_outcome),
         ("bridge crossing (validated writeback)", check_bridge_crossing),

{fpf_thinking_map-1.3.0 → fpf_thinking_map-1.4.0}/fpf_thinking_map.egg-info/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: fpf-thinking-map
-Version: 1.3.0
+Version: 1.4.0
 Summary: Agentic thinking map — structured reasoning constraints for LLMs with TTL evidence decay, deterministic guards, and propositional logic glue. Compiled from FPF (First Principles Framework).
 Author-email: "prichindel.com" <igareosh@igareosh.com>
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/igareosh/prichindel.com-agentic-thinking-map
 Project-URL: Repository, https://github.com/igareosh/prichindel.com-agentic-thinking-map
 Project-URL: Documentation, https://github.com/igareosh/prichindel.com-agentic-thinking-map#readme
@@ -12,7 +12,6 @@ Keywords: agentic,thinking-map,llm,reasoning,propositional-logic,evidence-decay,
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
@@ -27,24 +26,53 @@ Dynamic: license-file
 
 # prichindel.com Agentic Thinking Map
 
-**v1.3.0** — [FPF (First Principles Framework)](https://github.com/ailev/FPF) compiled into a semi-formal thinking map for agentic AI guidance.
+**v1.4.0** — [FPF (First Principles Framework)](https://github.com/ailev/FPF), compiled into a small traversal map for LLM agents.
 
-A Python package that gives an AI model a small, structured board to reason on — one move at a time. Instead of freeform text generation, the model navigates a pre-shaped semantic field with deterministic guards and propositional logic constraints.
+A Python package that gives a model a bounded move board instead of a giant framework to digest at runtime. Instead of rereading a sprawling semantic corpus and improvising from it, the model gets a small JSON slice: what context it is in, what move is open, what evidence is missing, what is risky, and what outcome class applies.
 
 **[Visual architecture →](ARCHITECTURE.md)** — module graph, step flowchart, floor map, evidence lifecycle, slice structure, deploy sequence diagram.
 
+## Why this exists
+
+FPF is valuable, but it is large, clumsy at runtime, and poorly shaped for direct model consumption. A human can read a 51k-line framework, understand its distinctions, and apply them carefully. A model usually does something else: it absorbs the vocabulary, performs the tone of the framework, and still drifts on the actual task.
+
+This package exists because the useful part is not making the model sound more scientific. The useful part is compiling the parts of FPF that help operational decisions into something small, explicit, and inspectable. We took what mattered for bounded traversal, left out what would bloat or bias the model, and evolved the result as publishers of a practical library rather than trying to reproduce the whole upstream framework inside another AI mega-system.
+
+The goal is simple: give the model enough structure to behave understandably, without building a cage so elaborate that it becomes another source of drift.
+
+We do not compete with FPF and we do not need to. FPF stays FPF: broad, ambitious, and useful as a frame. This library is the smaller usable tool for people who want the frame without carrying the whole corpus into every project.
+
 ## What it does
 
-You define a domain as a semantic map (contexts, roles, gates, evidence, transitions). The model gets a per-move slice — just the current transition, its gate, its evidence, and whether it can fire. Deterministic guards enforce hard constraints the model cannot override. Propositional logic rules (NOT, AND, OR, XOR, IMPLIES, IFF) provide decision glue between the semantic primitives and the model's reasoning.
+You define a domain as a semantic map: contexts, roles, gates, evidence, transitions. The model gets a per-move slice, not a theory dump. Deterministic guards handle the hard checks. Propositional logic rules (NOT, AND, OR, XOR, IMPLIES, IFF) provide explicit decision glue between the semantic primitives and the current state.
+
+The model's job is not "what does FPF mean?" It is: **given this map and this state, what is the best lawful next move?**
+
+In practice this does two useful things:
+
+- it reduces unexplained drift by moving state tracking and hard checks out of freeform model reasoning
+- it gives the model simple, understandable outcomes such as `CONTINUE`, `COLLECT_EVIDENCE`, `BRIDGE`, `IDLE`, `ESCALATE`, instead of making it reconstruct its own epistemic condition from scratch
+
+This is not a panacea. Models still miss information. They still drift. But with a bounded traversal map, the failure mode becomes much easier to explain: missing evidence, wrong context, blocked move, stale basis, unlicensed bridge. The weirdness gets smaller because the state is smaller.
+
+## Provable practical gains
 
-The model's job is not "what does FPF mean?" — it is: **given this semantic map and this state, what is the best lawful next move?**
+The improvements here are intentionally simple and operational:
+
+- less random drift, because the agent reads explicit state instead of reconstructing state from prose
+- fewer unlawful moves, because guards and scoped transitions check them before the model improvises
+- clearer failure, because "why blocked" is surfaced directly
+- smaller runtime payload, because the model gets a slice, not a corpus
+- easier debugging, because outcomes are discrete and inspectable
+
+That is the whole point: practical gain, not intellectual theater.
 
 ## Quick start
 
 ```bash
 # No dependencies. Python 3.12+.
 
-# Verify the package (21 checks)
+# Verify the package (22 checks)
 python -m fpf_thinking_map.verify
 
 # Run the deploy decision scenario
@@ -60,7 +88,7 @@ fpf_thinking_map/
 ├── guards.py                 9 deterministic guards (context, role, gate, evidence, assignment, speech act, readiness)
 ├── logic.py                  6 logic operators + decision rules + LogicLayer
 ├── traversal.py              Step engine with 10 lawful outcomes (incl. IDLE, BRIDGE)
-├── verify.py                 Self-verification harness (21/21 checks)
+├── verify.py                 Self-verification harness (22/22 checks)
 ├── examples.py               5 deploy decision scenarios (missing evidence, role conflict, logic glue, truth table)
 ├── README.md                 Full documentation (any-model readable)
 ├── SOURCES.md                Source attribution (FPF spec + Mitev lectures)
@@ -76,6 +104,8 @@ fpf_thinking_map/
 
 This package is built on [ailev/FPF](https://github.com/ailev/FPF) by Anatoly Levenchuk. It is an independent implementation — our own research and code, MIT-licensed, with further development rights.
 
+It is not an attempt to "finish" FPF, replace FPF, or repackage the whole corpus for LLM ingestion. It is a selective compilation for agentic traversal.
+
 ### What we reviewed
 
 We cross-checked the following FPF commits (June 2026 precision restoration cluster) against our code:
@@ -104,6 +134,33 @@ Two FPF pattern families rejected for activation bias — they amplify existing
 
 **Design rule**: the map evaluates and constrains moves. It does not propose them. Generative, branch-friendly, candidate-multiplying patterns are the opposite of what a per-move guard-constrained thinking map should contain.
 
+## Scope and non-goals
+
+This library is intentionally small in scope.
+
+- It is for bounded, stepwise agent traversal in a defined domain.
+- It is for making model behavior more understandable, not more magical.
+- It is for simple +/- operational decisions in context, not for open-ended idea generation.
+- It is for constraining and instrumenting an agent run, not replacing the model.
+
+It is not:
+
+- a full semantic ingestion layer for all of FPF
+- a universal reasoning engine
+- a replacement for ordinary application logic or policy code
+- a proof that an LLM will behave correctly just because the map exists
+- Memory-Augmented Generation (MAG) — no embeddings, no vector store, no cross-session retrieval, ever, inside this engine. Rejected deliberately and permanently, not by omission. See below.
+
+## What this actually guarantees
+
+fpf does not ship better reasoning. It ships **inspectability**: did the agent follow the lawful path, and was evidence honestly reported at the one place that matters — the wire between what the agent actually did and what this library was told.
+
+Take the stagnation counter as the concrete case. It bounds repetition — but only if the integration maps one real attempt to one `step()` call, and only adds evidence when something genuinely new was found. Whether that actually catches a real LLM thrashing depends entirely on whether the calling harness wires evidence honestly, not just "a tool returned something." That wiring discipline lives outside this library, in whatever integrates it — an agent loop, an MCP server, application code. fpf can't verify that discipline was followed; it can only guarantee that if it was, repetition is bounded.
+
+That boundary is the correct seam, not a gap to apologize for. Judging whether a piece of evidence is actually meaningful is a semantic question, and semantic questions need prompting, an LLM judge, or domain logic to answer — which is exactly where that belongs: outside fpf, at the evidence-wiring layer, not folded into a library whose entire value is staying small and deterministic. If you want semantics and clever prompting, that's the plug-in point.
+
+**This is also why Memory-Augmented Generation (MAG) is rejected as fpf's own architecture, deliberately and permanently.** MAG — retrieval, embeddings, cross-session recall — solves a different problem (what did we discuss three sessions ago) than fpf solves (is this move lawful right now), and it needs exactly the dependency profile this library rules out by design. That is a scope boundary, not a verdict on MAG as a technique: a MAG system is a legitimate thing to run *upstream* of fpf. Whatever it retrieves becomes an evidence_id in `RuntimeBinding.current_evidence` like any other — fpf doesn't care how evidence was produced, only whether it's present, fresh, and licensed. Memory belongs at the evidence-wiring layer, alongside every other semantic judgment this library deliberately doesn't make.
+
 ## Sources
 
 - **[FPF (First Principles Framework)](https://github.com/ailev/FPF)** by Anatoly Levenchuk — transdisciplinary specification (~51k lines). We extracted 10 semantic primitives and 9 guard rules. This is a compiled distillation, not a port.
@@ -111,6 +168,22 @@ Two FPF pattern families rejected for activation bias — they amplify existing
 
 Full attribution in [SOURCES.md](fpf_thinking_map/SOURCES.md).
 
+## Why it works
+
+The core advantage is not "more theory." It is less runtime burden.
+
+Without a compiled map, the model keeps re-addressing its own run: am I allowed to move, did I already satisfy the gate, am I missing evidence, am I in the wrong context, am I done or blocked? That self-management loop is where a lot of bad agent behavior comes from.
+
+This package turns that loop into a small stateful instrument panel. The model sees what can fire, what cannot, and why. That is enough of an operating surface for many practical agent tasks. Not a panacea, not a grand theory of intelligence, just enough window and file-handles for the model to open the right thing without smashing the house.
+
+The bottleneck was never raw model capability — it's self-management overhead eating the capability that's already there. Most orgs running these models, at any scale, hit that ceiling: infra and process that never actually asked the model for full capacity, so upgrading the model changes nothing. This library doesn't make the model smarter. It shrinks what the model has to hold in its head at any one step, so whatever capability is actually there gets spent on the real problem instead of on self-management overhead.
+
+Clean product truth:
+
+- FPF is the frame.
+- This library is the usable tool.
+- It keeps the frame where it helps, removes the bloat where it hurts, and gives agents a small operational board that produces simpler, more provable behavior.
+
 ## Why v1.1 exists — reasoning about reasoning is the bug
 
 When an LLM navigates a multi-step decision, it faces the same sub-questions at every step: "Is my evidence still valid? Am I going in circles? Is there another path? Why am I blocked?" Without structure, the model re-derives these answers from scratch each time — re-reasoning on its own prior reasoning. Each pass costs tokens, drifts from the original question, and eventually the context fills up with the model arguing with itself about whether it already checked something it checked three steps ago.
@@ -131,6 +204,18 @@ The model's job shrinks from "figure out the entire epistemic state of your own
 - **Evidence status in prompt** — the LLM prompt state now includes per-evidence freshness and TTL remaining. The model sees "test_results: 3 steps left" instead of just "test_results: exists." Decisions informed by countdown, not by guessing.
 - **Response contract** — every slice now ends with a `response_contract`: the structured template the model must fill when responding. Pre-filled fields (scope, basis with freshness/TTL, allowed use, not allowed use, modality, canonical terms, audience) come from the computed state. Empty fields (claim, risky aliases) are for the model. This is why all the code exists — so the contract has precomputed, validated values instead of being re-derived by the model from scratch.
 
+## v1.3.0 changes
+
+- **Bridge crossing is enforced, not just advertised** — `ActiveState.cross_bridge()` / `ThinkingMapTraversal.attempt_bridge()` actually perform a cross-context hop and check `substitution_license` against `risk_level` before mutating state. An unlicensed bridge under `high`/`critical` risk is refused (`ESCALATE`), not silently allowed. Before this, `bridge_options()` was advisory metadata only — the model decided for itself whether a lossy translation was acceptable.
+- **`include_full_state=False`** — `step()` can now ship the scoped `slice()` alone, without the whole board bolted on. Default stays `True`; opt in when the caller already knows its `transition_id` and wants the lean payload.
+- 21/21 self-verification checks (`python -m fpf_thinking_map.verify`), two new: bridge crossing and lean-slice payload shape.
+
+## v1.4.0 changes
+
+- **Stagnation counter** — `ActiveState.register_visit()` / `visit_count` / `visits_remaining` / `is_stagnant` count consecutive `step()`s at the same `(context, state)` pair with no new evidence gathered; the counter resets the moment the evidence set changes. `visits_remaining` mirrors `ttl_remaining`'s exact shape — a countdown, not a boolean. Surfaced in both `slice()` and `to_llm_prompt_state()` as a `stagnation` block. Pure signal: no new outcome kind, nothing blocks, no restraint added to the model's options. Closes a real blind spot — `MoveTrace` is deliberately last-move-only (no narrative accumulation), so the engine previously had no way to notice "I've revisited this exact state N times with nothing new to show for it."
+- The guarantee is conditional, and the docs say so plainly: this tracks evidence *set membership*, not evidence *meaning*. It bounds repetition only if the integration maps one real attempt to one `step()` call and only adds evidence that's genuinely new — see [What this actually guarantees](#what-this-actually-guarantees).
+- 22/22 self-verification checks, one new: `check_stagnation_counter`.
+
 ## Design principles
 
 - **Only add structure when it changes agentic behavior** — not for source fidelity alone
@@ -140,10 +225,10 @@ The model's job shrinks from "figure out the entire epistemic state of your own
 
 ## Using as a dependency
 
-This package is the reasoning engine. Your domain maps run on top of it.
+This package is the compiled map, not a thinking replacement for the model. Denying unlawful moves is only half the job. The bigger half is returning the lawful surface as a small, plain-JSON slice: what can fire, what is missing, what is risky, why a move is blocked, what response shape is expected. That lets the model self-address its own run with simple signals such as `can_fire`, `blockers`, and `outcome.kind` instead of re-reasoning about its state from prose.
 
 ```bash
-pip install git+https://github.com/igareosh/prichindel.com-agentic-thinking-map.git
+pip install fpf-thinking-map
 ```
 
 ```python
@@ -207,10 +292,25 @@ Built with Claude Code (Anthropic claude-sonnet-4-6). Tested and verified to wor
 
 This is not a compliance seal. It means: we used these models against this package and they produced correct, usable results. The per-move slice is small enough for mid-tier models. The logic and guard outputs are plain JSON — no special tokenization or prompt format required.
 
+## Why release this
+
+We release this because it is useful beyond our own stack.
+
+- It captures a practical subset of FPF in a form models can actually use.
+- It gives agent builders a small constraint surface instead of another giant AI framework.
+- It helps turn model failure from mystical drift into inspectable state.
+- It stays intentionally narrow, so it can remain legible instead of becoming another overbuilt "agent platform."
+
+## Credits
+
+- **igareosh** — project direction, scope discipline, practical use-case pressure, and product truth
+- **Claude Code (Anthropic)** — implementation support, library iteration, and earlier release preparation
+- **Codex / OpenAI** — product framing polish, packaging cleanup, verification, and release-readiness work
+
 ## License
 
 MIT. See [LICENSE](LICENSE).
 
 ---
 
-**prichindel.com** — v1.2.1 — 2026-06-26
+**prichindel.com** — v1.4.0 — 2026-07-07

{fpf_thinking_map-1.3.0 → fpf_thinking_map-1.4.0}/pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "fpf-thinking-map"
-version = "1.3.0"
+version = "1.4.0"
 description = "Agentic thinking map — structured reasoning constraints for LLMs with TTL evidence decay, deterministic guards, and propositional logic glue. Compiled from FPF (First Principles Framework)."
 readme = "README.md"
-license = {text = "MIT"}
+license = "MIT"
 requires-python = ">=3.12"
 authors = [
     {name = "prichindel.com", email = "igareosh@igareosh.com"},
@@ -17,7 +17,6 @@ classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "Intended Audience :: Science/Research",
-    "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.12",