fpf-thinking-map 2.0.2__tar.gz → 2.0.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of fpf-thinking-map might be problematic. Click here for more details.

Files changed (26) hide show
  1. {fpf_thinking_map-2.0.2/fpf_thinking_map.egg-info → fpf_thinking_map-2.0.3}/PKG-INFO +129 -98
  2. fpf_thinking_map-2.0.3/README.md +236 -0
  3. {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.0.3/fpf_thinking_map.egg-info}/PKG-INFO +129 -98
  4. {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.0.3}/pyproject.toml +2 -2
  5. fpf_thinking_map-2.0.2/README.md +0 -205
  6. {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.0.3}/LICENSE +0 -0
  7. {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.0.3}/NOTICE +0 -0
  8. {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.0.3}/fpf_thinking_map/__init__.py +0 -0
  9. {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.0.3}/fpf_thinking_map/agentic_structure.py +0 -0
  10. {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.0.3}/fpf_thinking_map/authorization.py +0 -0
  11. {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.0.3}/fpf_thinking_map/checkpoint.py +0 -0
  12. {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.0.3}/fpf_thinking_map/examples.py +0 -0
  13. {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.0.3}/fpf_thinking_map/guards.py +0 -0
  14. {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.0.3}/fpf_thinking_map/logic.py +0 -0
  15. {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.0.3}/fpf_thinking_map/move_intent.py +0 -0
  16. {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.0.3}/fpf_thinking_map/pending_input.py +0 -0
  17. {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.0.3}/fpf_thinking_map/primitives.py +0 -0
  18. {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.0.3}/fpf_thinking_map/py.typed +0 -0
  19. {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.0.3}/fpf_thinking_map/reachability.py +0 -0
  20. {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.0.3}/fpf_thinking_map/state.py +0 -0
  21. {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.0.3}/fpf_thinking_map/traversal.py +0 -0
  22. {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.0.3}/fpf_thinking_map/verify.py +0 -0
  23. {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.0.3}/fpf_thinking_map.egg-info/SOURCES.txt +0 -0
  24. {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.0.3}/fpf_thinking_map.egg-info/dependency_links.txt +0 -0
  25. {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.0.3}/fpf_thinking_map.egg-info/top_level.txt +0 -0
  26. {fpf_thinking_map-2.0.2 → fpf_thinking_map-2.0.3}/setup.cfg +0 -0
@@ -1,11 +1,11 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: fpf-thinking-map
3
- Version: 2.0.2
3
+ Version: 2.0.3
4
4
  Summary: Deterministic Python runtime for lawful agent traversal with explicit state, evidence, authorization, waiting, and move identity.
5
5
  Author-email: "CONSOLIDARE CONTINUUM S.R.L." <info@consolidare-continuum.com>
6
6
  Maintainer-email: "CONSOLIDARE CONTINUUM S.R.L." <info@consolidare-continuum.com>
7
7
  License-Expression: MIT
8
- Project-URL: Homepage, https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map
8
+ Project-URL: Homepage, https://consolidare-continuum.com/fpf-thinking-map/
9
9
  Project-URL: Repository, https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map
10
10
  Project-URL: Documentation, https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map#readme
11
11
  Project-URL: Issues, https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/issues
@@ -34,85 +34,35 @@ License-File: LICENSE
34
34
  License-File: NOTICE
35
35
  Dynamic: license-file
36
36
 
37
- <p align="center">
38
- <img src="https://raw.githubusercontent.com/Consolidare-Continuum/fpf-agentic-thinking-map/main/docs/assets/fpf-agentic-thinking-map-header-v20260818.png" alt="FPF Agentic Thinking Map — Agent freedom. Explicit movement rules." width="100%" />
39
- </p>
37
+ # fpf-thinking-map
40
38
 
41
- # FPF Agentic Thinking Map
39
+ A small Python library that tracks the state of a multi-step agent workflow
40
+ and answers one question: *is this next move allowed right now, and if not,
41
+ why?*
42
42
 
43
- Deterministic Python runtime for agents that may reason freely but must move
44
- through a workflow lawfully.
43
+ You describe a workflow as a graph (contexts, roles, evidence, gates,
44
+ transitions). Your agent harness feeds the library the current state and the
45
+ move the agent proposes. The library returns a legal/illegal outcome with the
46
+ reason and a trace. It does not call a model, run tools, poll, or schedule
47
+ anything.
45
48
 
46
- Operational state, evidence freshness, transition legality, authorization,
47
- waiting, and move identity live **outside** model prose. The model proposes;
48
- the runtime decides whether the move is valid.
49
+ **PyPI:** [`fpf-thinking-map`](https://pypi.org/project/fpf-thinking-map/) · **Current:** **2.0.3** · **License:** MIT
49
50
 
50
- **PyPI:** [`fpf-thinking-map`](https://pypi.org/project/fpf-thinking-map/) · **Current:** **2.0.2**
51
-
52
- [![PyPI](https://img.shields.io/pypi/v/fpf-thinking-map?style=flat-square&label=PyPI&color=3775A9)](https://pypi.org/project/fpf-thinking-map/)
53
- [![Python](https://img.shields.io/pypi/pyversions/fpf-thinking-map?style=flat-square&label=Python&color=f0b429)](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/blob/main/pyproject.toml)
54
- [![Zero dependencies](https://img.shields.io/badge/dependencies-0-ff9f43?style=flat-square)](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/blob/main/pyproject.toml)
55
- [![Verification](https://img.shields.io/badge/verify-39%2F39-59d18c?style=flat-square)](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/blob/main/fpf_thinking_map/verify.py)
56
- [![Live demo](https://img.shields.io/badge/live-demo-dd8cff?style=flat-square)](https://consolidare-continuum.github.io/fpf-agentic-thinking-map/demos/three-runs.html)
51
+ [![PyPI](https://img.shields.io/pypi/v/fpf-thinking-map?style=flat-square&label=PyPI)](https://pypi.org/project/fpf-thinking-map/)
52
+ [![Python](https://img.shields.io/pypi/pyversions/fpf-thinking-map?style=flat-square&label=Python)](pyproject.toml)
53
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
57
54
 
58
55
  ## Install
59
56
 
60
- Requires **Python ≥ 3.12**. Zero runtime dependencies.
57
+ Requires **Python ≥ 3.12**. No runtime dependencies.
61
58
 
62
59
  ```bash
63
- pip install "fpf-thinking-map==2.0.1"
64
- python -m fpf_thinking_map.verify # 40/40 (39/39 at v2.0.1)
60
+ pip install "fpf-thinking-map==2.0.3"
61
+ python -m fpf_thinking_map.verify # the package's own self-tests, 40 checks
65
62
  python -m fpf_thinking_map.examples
66
63
  ```
67
64
 
68
- Full 2.0 line is on the index: [`2.0.0`](https://pypi.org/project/fpf-thinking-map/2.0.0/), [`2.0.1`](https://pypi.org/project/fpf-thinking-map/2.0.1/) (also [`1.9.6`](https://pypi.org/project/fpf-thinking-map/1.9.6/)).
69
-
70
- ## What it is
71
-
72
- Agents lose workflow rules in long runs. This package moves the non-negotiable
73
- parts into ordinary code:
74
-
75
- - current context and state
76
- - evidence presence and TTL freshness
77
- - gates, guards, and lawful transitions
78
- - cross-context bridges
79
- - human authorization (`AuthorizationReceipt`)
80
- - external wait (`PendingInput` / `AWAIT`)
81
- - concrete move identity (`MoveIntent`)
82
- - typed claim scope / pathwise reliability
83
- - tool-call plan closure and autonomy budgets
84
-
85
- Not a prompt. A compact **control surface** around reasoning.
86
-
87
- ## Contract
88
-
89
- | Agent / host | This runtime |
90
- | --- | --- |
91
- | Interprets the task | Holds explicit traversal state |
92
- | Generates options | Computes which moves are legal |
93
- | Collects evidence | Checks presence and freshness |
94
- | Proposes a move | Inspects or attempts that move |
95
- | Explains the result | Returns a bounded outcome and trace |
96
- | Requests human input | Enforces the authorization boundary |
97
- | Runs tools and jobs | Never executes, polls, or schedules them |
98
-
99
- ## Structural controls (shipped)
100
-
101
- | Concern | Structures | Effect |
102
- | --- | --- | --- |
103
- | Claim / assurance | `ContextSlice`, `ClaimScope`, `FormalityLevel`, `ReliabilityPath` | Typed scope; unknown stays unknown |
104
- | Tool plans | `CallPlanPrimitive`, `BudgetEnvelope` | Incomplete plans → `REVISE_PLAN` |
105
- | Autonomy | `AutonomyBudgetDecl`, `AutonomyLedgerEntry` | Opt-in budget; fail → `ESCALATE` |
106
- | Work attribution | `WorkPrimitive.performed_under` | Wrong holder/context cannot complete |
107
- | Gate join | `GateDecision`, `OutcomeCause` | `ABSTAIN` ≠ `BLOCK` (`cause=gate_block`) |
108
- | Map integrity | `ThinkingMapTraversal.validate_map()` | Dangling refs / unknown IDs fail closed |
109
- | Adjacency (2.0) | `AdjacencyClearanceRule`, `AdjacentlyCleared` | Confirmed-absent percept clears declared neighbors |
110
-
111
- ## Demo
112
-
113
- [![Four test-backed traces](https://raw.githubusercontent.com/Consolidare-Continuum/fpf-agentic-thinking-map/main/docs/assets/three-runs-preview.png)](https://consolidare-continuum.github.io/fpf-agentic-thinking-map/demos/three-runs.html)
114
-
115
- **[Interactive four-run trace](https://consolidare-continuum.github.io/fpf-agentic-thinking-map/demos/three-runs.html)** — evidence recovery, `AWAIT`, `MoveIntent`, authorization, and `ABSTAIN` vs `BLOCK`.
65
+ Other releases on the index: [`2.0.1`](https://pypi.org/project/fpf-thinking-map/2.0.1/), [`2.0.0`](https://pypi.org/project/fpf-thinking-map/2.0.0/), [`1.9.6`](https://pypi.org/project/fpf-thinking-map/1.9.6/).
116
66
 
117
67
  ## Minimal example
118
68
 
@@ -171,11 +121,86 @@ state = traversal.build_active_state(
171
121
  inspection = traversal.step(state)
172
122
  result = traversal.attempt_transition(state, "ship")
173
123
  print(inspection.kind, result.kind, state.current_state)
124
+ # OutcomeKind.CONTINUE OutcomeKind.CONTINUE released
174
125
  ```
175
126
 
176
- Replace the deploy vocabulary with your own contexts, roles, evidence, and gates.
127
+ Replace the deploy vocabulary with your own contexts, roles, evidence and gates.
177
128
 
178
- ## Gate join (keep these apart)
129
+ ## What it does
130
+
131
+ - Holds explicit traversal state: current context, state, and evidence.
132
+ - Checks evidence presence and freshness. Freshness decays over **traversal
133
+ steps**, not wall-clock time.
134
+ - Evaluates gates, guards and transitions and says which moves are legal.
135
+ - Supports cross-context bridges with validated writeback.
136
+ - Supports human authorization (`AuthorizationReceipt`): scoped, non-replayable.
137
+ - Distinguishes waiting on external input (`PendingInput` / `AWAIT`) from idle.
138
+ - Gives a proposed move a concrete identity (`MoveIntent`) that can be inspected.
139
+ - Can checkpoint and restore a paused traversal (`ActiveState.checkpoint()`,
140
+ `from_checkpoint()`); restore is all-or-nothing and never repairs.
141
+
142
+ Given the same map, state, evidence and receipts, it returns the same result.
143
+ The core modules call no clock, random source, network or model.
144
+
145
+ ## Division of work
146
+
147
+ | Agent / host | This library |
148
+ | --- | --- |
149
+ | Interprets the task | Holds explicit traversal state |
150
+ | Generates options | Computes which moves are legal |
151
+ | Collects evidence | Checks presence and freshness |
152
+ | Proposes a move | Inspects or attempts that move |
153
+ | Explains the result | Returns a bounded outcome and trace |
154
+ | Requests human input | Enforces the authorization boundary |
155
+ | Runs tools and jobs | Never executes, polls or schedules them |
156
+
157
+ ## Limits
158
+
159
+ - **It only constrains what is routed through it.** A harness or agent that
160
+ does not call the library is not constrained. There is no sandbox.
161
+ - **State lives in the host process.** The library keeps no storage of its
162
+ own; use `checkpoint()` to persist a paused traversal.
163
+ - **Several inputs are self-asserted.** For example `active_context_id`
164
+ (advisory ADV-03): the harness must own continuity.
165
+ - **Defaults are minimal.** Stale evidence warns but does not block unless a
166
+ gate requires it, and `requires_human_authorization` defaults off.
167
+ - **It is not a universal reasoner,** a vector store, a tool runner or
168
+ scheduler, or a certificate that an agent system is safe.
169
+
170
+ Full list of integrator boundaries: [ADVISORIES.md](docs/deep/ADVISORIES.md).
171
+
172
+ ## What the evidence shows
173
+
174
+ - **Self-tests.** `python -m fpf_thinking_map.verify` (40 checks) and
175
+ `dev_mcp/test_server.py` (45 checks) are written and run by the authors. They
176
+ check that the library does what it is specified to do. They have not been
177
+ audited by a third party.
178
+ - **Does it make agents safer?** One small benchmark exists
179
+ ([bench/RESULTS.md](bench/RESULTS.md)): two tasks, one frontier-model class,
180
+ 5 runs per condition, 20 runs total. The model made **no policy violations
181
+ with or without** the library, so there is **no measured compliance
182
+ improvement** for a cooperative model on a clearly stated task. With the
183
+ library the model made *more* tool calls (4.4 vs 1.0 and 2.0 vs 1.0), because
184
+ it used the inspection calls before acting. Weaker or adversarial models were
185
+ not tested.
186
+ - **ISO.** [docs/ISO_EVIDENCE_PACKET.md](docs/ISO_EVIDENCE_PACKET.md) maps
187
+ release 2.0.1 against ISO/IEC 25010, 27001 and 9001 as a self-assessed
188
+ checklist. It is **not** an audit and **not** a certification.
189
+
190
+ ## Shipped structures
191
+
192
+ | Concern | Structures | Effect |
193
+ | --- | --- | --- |
194
+ | Claim / assurance | `ContextSlice`, `ClaimScope`, `FormalityLevel`, `ReliabilityPath` | Typed scope; unknown stays unknown |
195
+ | Tool plans | `CallPlanPrimitive`, `BudgetEnvelope` | Incomplete plans → `REVISE_PLAN` |
196
+ | Autonomy | `AutonomyBudgetDecl`, `AutonomyLedgerEntry` | Opt-in budget; failure → `ESCALATE` |
197
+ | Work attribution | `WorkPrimitive.performed_under` | Wrong holder/context cannot complete |
198
+ | Gate join | `GateDecision`, `OutcomeCause` | `ABSTAIN` ≠ `BLOCK` (`cause=gate_block`) |
199
+ | Map integrity | `ThinkingMapTraversal.validate_map()` | Dangling refs / unknown IDs fail closed |
200
+ | Adjacency (2.0) | `AdjacencyClearanceRule`, `AdjacentlyCleared` | A confirmed-absent percept clears declared neighbours |
201
+ | Continuity (2.0.2) | `ActiveState.checkpoint()`, `from_checkpoint()` | Persist and restore a paused traversal |
202
+
203
+ ### Gate join
179
204
 
180
205
  | Gate result | Meaning | Typical outcome |
181
206
  | --- | --- | --- |
@@ -185,57 +210,63 @@ Replace the deploy vocabulary with your own contexts, roles, evidence, and gates
185
210
  `BLOCK` is hard for that evaluation; it is not automatically permanent. Checks
186
211
  opt into `BLOCK` with `failure_decision=GateDecision.BLOCK`.
187
212
 
188
- ## Release line
213
+ ## Demo
189
214
 
190
- | Line | Capability |
215
+ [Four interactive traces](https://consolidare-continuum.github.io/fpf-agentic-thinking-map/demos/three-runs.html)
216
+ (evidence recovery, `AWAIT`, `MoveIntent` with authorization, `ABSTAIN` vs
217
+ `BLOCK`). They follow behavior covered by the test suite as of v1.9.5; they are
218
+ not a recording of a live model run and do not show later features.
219
+
220
+ ## Releases
221
+
222
+ | Line | Change |
191
223
  | --- | --- |
192
224
  | v1.0–v1.5 | Primitives, TTL, bridges, stagnation, stable public boundary |
193
225
  | v1.6–v1.8 | Human authorization, receipts, `AWAIT` |
194
226
  | v1.9 / 1.9.5 | Move identity; A.21 gate join (`ABSTAIN` vs `BLOCK`) |
195
227
  | v1.9.6 | Failed-run revert terminal (XOR + distance bound) |
196
- | **v2.0.0** | Adjacency Clearance (`ADV-17`) |
197
- | **v2.0.1** | Current — docs/metadata/reference hardware; runtime verify **39/39** |
228
+ | v2.0.0 | Adjacency clearance (`ADV-17`) |
229
+ | v2.0.1 | Docs and metadata only; runtime identical to 2.0.0 |
230
+ | v2.0.2 | Copyright and SPDX notices on every source file (license unchanged); includes traversal checkpoint and restore (`ADV-08`) |
231
+ | **v2.0.3** | Docs and metadata only; runtime identical to 2.0.2. Removes the upstream-intake advisory (`ADV-16`) and every named reference to the external specification this package was historically informed by; independence disclaimer reworded |
198
232
 
199
233
  History: [VERSION_TRACKER.md](docs/VERSION_TRACKER.md) · [CHANGELOG.md](CHANGELOG.md) · [Releases](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/releases)
200
234
 
201
- ## Integrator notes (read before production)
202
-
203
- Deliberate minimal defaults — not defects. Full text: [ADVISORIES.md](docs/deep/ADVISORIES.md).
235
+ ## Integrator notes
204
236
 
205
237
  | Priority | Advisory | One line |
206
238
  | --- | --- | --- |
207
- | Sharp | **ADV-03** | `active_context_id` is self-asserted — harness must own continuity |
208
- | Sharp | **ADV-07** | `RiskAbove` string match is case-sensitive and fails silent |
239
+ | Sharp | **ADV-03** | `active_context_id` is self-asserted: the harness must own continuity |
240
+ | Sharp | **ADV-07** | `RiskAbove` string match is case-sensitive and fails silently |
209
241
  | Common | **ADV-01** | Stale evidence warns; it does not block unless gated |
210
242
  | Common | **ADV-10** | `requires_human_authorization` defaults off |
211
243
  | 2.0 | **ADV-17** | Adjacency clearance is only as sound as your declared biconditional |
212
244
 
213
- MCP harness: [`dev_mcp/`](dev_mcp/) — `run_scenario`, `get_advisories`, `run_verify`.
214
-
215
- ## Scope
216
-
217
- **Use when you need:** bounded multi-step legality, evidence-aware state,
218
- inspectable block/escalate reasons, human authorization, wait vs idle,
219
- compact LLM state slices.
220
-
221
- **Do not use as:** a universal reasoner, vector store, tool runner/scheduler,
222
- or a certificate that an entire agent system is safe.
245
+ MCP test harness: [`dev_mcp/`](dev_mcp/) (`run_scenario`, `get_advisories`, `run_verify`).
223
246
 
224
- ## Docs
247
+ ## Repository
225
248
 
226
249
  | Path | Purpose |
227
250
  | --- | --- |
228
- | [`fpf_thinking_map/`](fpf_thinking_map/) | Zero-dependency runtime (PyPI **2.0.1**) |
251
+ | [`fpf_thinking_map/`](fpf_thinking_map/) | The runtime (no dependencies) |
229
252
  | [ARCHITECTURE.md](ARCHITECTURE.md) | Control flow |
230
253
  | [docs/deep/ADVISORIES.md](docs/deep/ADVISORIES.md) | Integrator boundaries |
231
- | [SHA256SUMS](SHA256SUMS) | Source fingerprints |
254
+ | [bench/](bench/) | The ablation benchmark and its raw results |
255
+ | [SHA256SUMS](SHA256SUMS) | Source file checksums |
232
256
 
233
- ## Product continuation
257
+ ## License and ownership
234
258
 
235
- **CONSOLIDARE CONTINUUM S.R.L.** designs, owns, and ships this runtime for its own products and client work. No third-party framework affiliation. No external attribution required for use of this package.
259
+ MIT. Copyright (c) 2026 CONSOLIDARE CONTINUUM S.R.L.
236
260
 
237
- ## ISO evidence
261
+ Copyrighted build: release **2.0.2**, commit
262
+ [`f0a17a543a23cbc8a33071b170a02ccf41fd33b7`](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/commit/f0a17a543a23cbc8a33071b170a02ccf41fd33b7)
263
+ (signed tag `v2.0.2`). Every source file in that commit carries the copyright
264
+ and SPDX notice.
238
265
 
239
- [docs/ISO_EVIDENCE_PACKET.md](docs/ISO_EVIDENCE_PACKET.md) — ISO/IEC 25010 · 27001 · 9001 alignment for **v2.0.1** (**not** certification).
266
+ The MIT license requires
267
+ that the copyright notice and license text be kept in copies and substantial
268
+ portions of the software; see [LICENSE](LICENSE) and [NOTICE](NOTICE).
240
269
 
241
- **Agent freedom. Explicit movement rules.**
270
+ This is an independent implementation, out of scope of and not derived from
271
+ any third-party framework's document or ontology. It is not affiliated
272
+ with, sponsored by, or endorsed by any such project.
@@ -0,0 +1,236 @@
1
+ # fpf-thinking-map
2
+
3
+ A small Python library that tracks the state of a multi-step agent workflow
4
+ and answers one question: *is this next move allowed right now, and if not,
5
+ why?*
6
+
7
+ You describe a workflow as a graph (contexts, roles, evidence, gates,
8
+ transitions). Your agent harness feeds the library the current state and the
9
+ move the agent proposes. The library returns a legal/illegal outcome with the
10
+ reason and a trace. It does not call a model, run tools, poll, or schedule
11
+ anything.
12
+
13
+ **PyPI:** [`fpf-thinking-map`](https://pypi.org/project/fpf-thinking-map/) · **Current:** **2.0.3** · **License:** MIT
14
+
15
+ [![PyPI](https://img.shields.io/pypi/v/fpf-thinking-map?style=flat-square&label=PyPI)](https://pypi.org/project/fpf-thinking-map/)
16
+ [![Python](https://img.shields.io/pypi/pyversions/fpf-thinking-map?style=flat-square&label=Python)](pyproject.toml)
17
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
18
+
19
+ ## Install
20
+
21
+ Requires **Python ≥ 3.12**. No runtime dependencies.
22
+
23
+ ```bash
24
+ pip install "fpf-thinking-map==2.0.3"
25
+ python -m fpf_thinking_map.verify # the package's own self-tests, 40 checks
26
+ python -m fpf_thinking_map.examples
27
+ ```
28
+
29
+ Other releases on the index: [`2.0.1`](https://pypi.org/project/fpf-thinking-map/2.0.1/), [`2.0.0`](https://pypi.org/project/fpf-thinking-map/2.0.0/), [`1.9.6`](https://pypi.org/project/fpf-thinking-map/1.9.6/).
30
+
31
+ ## Minimal example
32
+
33
+ ```python
34
+ from fpf_thinking_map import (
35
+ SemanticMap,
36
+ ContextPrimitive,
37
+ RolePrimitive,
38
+ GatePrimitive,
39
+ GateCheck,
40
+ TransitionPrimitive,
41
+ RuntimeBinding,
42
+ ThinkingMapTraversal,
43
+ )
44
+
45
+ semantic_map = SemanticMap()
46
+ semantic_map.register_context(ContextPrimitive("deploy", "Deploy"))
47
+ semantic_map.register_role(RolePrimitive("owner", "Owner", "deploy"))
48
+ semantic_map.register_gate(
49
+ GatePrimitive(
50
+ "release_gate",
51
+ "Release gate",
52
+ "deploy",
53
+ checks=[
54
+ GateCheck(
55
+ "tests",
56
+ "Tests are green",
57
+ required_evidence=["test_results"],
58
+ )
59
+ ],
60
+ )
61
+ )
62
+ semantic_map.register_transition(
63
+ TransitionPrimitive(
64
+ "ship",
65
+ "Ship release",
66
+ "deploy",
67
+ "candidate",
68
+ "released",
69
+ required_gate_id="release_gate",
70
+ required_evidence=["test_results"],
71
+ )
72
+ )
73
+
74
+ traversal = ThinkingMapTraversal(semantic_map)
75
+ state = traversal.build_active_state(
76
+ RuntimeBinding(
77
+ task="release",
78
+ actor_role_ids=["owner"],
79
+ active_context_id="deploy",
80
+ current_evidence=["test_results"],
81
+ ),
82
+ current_state="candidate",
83
+ )
84
+
85
+ inspection = traversal.step(state)
86
+ result = traversal.attempt_transition(state, "ship")
87
+ print(inspection.kind, result.kind, state.current_state)
88
+ # OutcomeKind.CONTINUE OutcomeKind.CONTINUE released
89
+ ```
90
+
91
+ Replace the deploy vocabulary with your own contexts, roles, evidence and gates.
92
+
93
+ ## What it does
94
+
95
+ - Holds explicit traversal state: current context, state, and evidence.
96
+ - Checks evidence presence and freshness. Freshness decays over **traversal
97
+ steps**, not wall-clock time.
98
+ - Evaluates gates, guards and transitions and says which moves are legal.
99
+ - Supports cross-context bridges with validated writeback.
100
+ - Supports human authorization (`AuthorizationReceipt`): scoped, non-replayable.
101
+ - Distinguishes waiting on external input (`PendingInput` / `AWAIT`) from idle.
102
+ - Gives a proposed move a concrete identity (`MoveIntent`) that can be inspected.
103
+ - Can checkpoint and restore a paused traversal (`ActiveState.checkpoint()`,
104
+ `from_checkpoint()`); restore is all-or-nothing and never repairs.
105
+
106
+ Given the same map, state, evidence and receipts, it returns the same result.
107
+ The core modules call no clock, random source, network or model.
108
+
109
+ ## Division of work
110
+
111
+ | Agent / host | This library |
112
+ | --- | --- |
113
+ | Interprets the task | Holds explicit traversal state |
114
+ | Generates options | Computes which moves are legal |
115
+ | Collects evidence | Checks presence and freshness |
116
+ | Proposes a move | Inspects or attempts that move |
117
+ | Explains the result | Returns a bounded outcome and trace |
118
+ | Requests human input | Enforces the authorization boundary |
119
+ | Runs tools and jobs | Never executes, polls or schedules them |
120
+
121
+ ## Limits
122
+
123
+ - **It only constrains what is routed through it.** A harness or agent that
124
+ does not call the library is not constrained. There is no sandbox.
125
+ - **State lives in the host process.** The library keeps no storage of its
126
+ own; use `checkpoint()` to persist a paused traversal.
127
+ - **Several inputs are self-asserted.** For example `active_context_id`
128
+ (advisory ADV-03): the harness must own continuity.
129
+ - **Defaults are minimal.** Stale evidence warns but does not block unless a
130
+ gate requires it, and `requires_human_authorization` defaults off.
131
+ - **It is not a universal reasoner,** a vector store, a tool runner or
132
+ scheduler, or a certificate that an agent system is safe.
133
+
134
+ Full list of integrator boundaries: [ADVISORIES.md](docs/deep/ADVISORIES.md).
135
+
136
+ ## What the evidence shows
137
+
138
+ - **Self-tests.** `python -m fpf_thinking_map.verify` (40 checks) and
139
+ `dev_mcp/test_server.py` (45 checks) are written and run by the authors. They
140
+ check that the library does what it is specified to do. They have not been
141
+ audited by a third party.
142
+ - **Does it make agents safer?** One small benchmark exists
143
+ ([bench/RESULTS.md](bench/RESULTS.md)): two tasks, one frontier-model class,
144
+ 5 runs per condition, 20 runs total. The model made **no policy violations
145
+ with or without** the library, so there is **no measured compliance
146
+ improvement** for a cooperative model on a clearly stated task. With the
147
+ library the model made *more* tool calls (4.4 vs 1.0 and 2.0 vs 1.0), because
148
+ it used the inspection calls before acting. Weaker or adversarial models were
149
+ not tested.
150
+ - **ISO.** [docs/ISO_EVIDENCE_PACKET.md](docs/ISO_EVIDENCE_PACKET.md) maps
151
+ release 2.0.1 against ISO/IEC 25010, 27001 and 9001 as a self-assessed
152
+ checklist. It is **not** an audit and **not** a certification.
153
+
154
+ ## Shipped structures
155
+
156
+ | Concern | Structures | Effect |
157
+ | --- | --- | --- |
158
+ | Claim / assurance | `ContextSlice`, `ClaimScope`, `FormalityLevel`, `ReliabilityPath` | Typed scope; unknown stays unknown |
159
+ | Tool plans | `CallPlanPrimitive`, `BudgetEnvelope` | Incomplete plans → `REVISE_PLAN` |
160
+ | Autonomy | `AutonomyBudgetDecl`, `AutonomyLedgerEntry` | Opt-in budget; failure → `ESCALATE` |
161
+ | Work attribution | `WorkPrimitive.performed_under` | Wrong holder/context cannot complete |
162
+ | Gate join | `GateDecision`, `OutcomeCause` | `ABSTAIN` ≠ `BLOCK` (`cause=gate_block`) |
163
+ | Map integrity | `ThinkingMapTraversal.validate_map()` | Dangling refs / unknown IDs fail closed |
164
+ | Adjacency (2.0) | `AdjacencyClearanceRule`, `AdjacentlyCleared` | A confirmed-absent percept clears declared neighbours |
165
+ | Continuity (2.0.2) | `ActiveState.checkpoint()`, `from_checkpoint()` | Persist and restore a paused traversal |
166
+
167
+ ### Gate join
168
+
169
+ | Gate result | Meaning | Typical outcome |
170
+ | --- | --- | --- |
171
+ | `ABSTAIN` (`insufficient`) | Not enough basis to say yes | `COLLECT_EVIDENCE` when evidence is declared |
172
+ | `BLOCK` | Declared policy says no for this evaluation | Denied with `cause=GATE_BLOCK` |
173
+
174
+ `BLOCK` is hard for that evaluation; it is not automatically permanent. Checks
175
+ opt into `BLOCK` with `failure_decision=GateDecision.BLOCK`.
176
+
177
+ ## Demo
178
+
179
+ [Four interactive traces](https://consolidare-continuum.github.io/fpf-agentic-thinking-map/demos/three-runs.html)
180
+ (evidence recovery, `AWAIT`, `MoveIntent` with authorization, `ABSTAIN` vs
181
+ `BLOCK`). They follow behavior covered by the test suite as of v1.9.5; they are
182
+ not a recording of a live model run and do not show later features.
183
+
184
+ ## Releases
185
+
186
+ | Line | Change |
187
+ | --- | --- |
188
+ | v1.0–v1.5 | Primitives, TTL, bridges, stagnation, stable public boundary |
189
+ | v1.6–v1.8 | Human authorization, receipts, `AWAIT` |
190
+ | v1.9 / 1.9.5 | Move identity; A.21 gate join (`ABSTAIN` vs `BLOCK`) |
191
+ | v1.9.6 | Failed-run revert terminal (XOR + distance bound) |
192
+ | v2.0.0 | Adjacency clearance (`ADV-17`) |
193
+ | v2.0.1 | Docs and metadata only; runtime identical to 2.0.0 |
194
+ | v2.0.2 | Copyright and SPDX notices on every source file (license unchanged); includes traversal checkpoint and restore (`ADV-08`) |
195
+ | **v2.0.3** | Docs and metadata only; runtime identical to 2.0.2. Removes the upstream-intake advisory (`ADV-16`) and every named reference to the external specification this package was historically informed by; independence disclaimer reworded |
196
+
197
+ History: [VERSION_TRACKER.md](docs/VERSION_TRACKER.md) · [CHANGELOG.md](CHANGELOG.md) · [Releases](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/releases)
198
+
199
+ ## Integrator notes
200
+
201
+ | Priority | Advisory | One line |
202
+ | --- | --- | --- |
203
+ | Sharp | **ADV-03** | `active_context_id` is self-asserted: the harness must own continuity |
204
+ | Sharp | **ADV-07** | `RiskAbove` string match is case-sensitive and fails silently |
205
+ | Common | **ADV-01** | Stale evidence warns; it does not block unless gated |
206
+ | Common | **ADV-10** | `requires_human_authorization` defaults off |
207
+ | 2.0 | **ADV-17** | Adjacency clearance is only as sound as your declared biconditional |
208
+
209
+ MCP test harness: [`dev_mcp/`](dev_mcp/) (`run_scenario`, `get_advisories`, `run_verify`).
210
+
211
+ ## Repository
212
+
213
+ | Path | Purpose |
214
+ | --- | --- |
215
+ | [`fpf_thinking_map/`](fpf_thinking_map/) | The runtime (no dependencies) |
216
+ | [ARCHITECTURE.md](ARCHITECTURE.md) | Control flow |
217
+ | [docs/deep/ADVISORIES.md](docs/deep/ADVISORIES.md) | Integrator boundaries |
218
+ | [bench/](bench/) | The ablation benchmark and its raw results |
219
+ | [SHA256SUMS](SHA256SUMS) | Source file checksums |
220
+
221
+ ## License and ownership
222
+
223
+ MIT. Copyright (c) 2026 CONSOLIDARE CONTINUUM S.R.L.
224
+
225
+ Copyrighted build: release **2.0.2**, commit
226
+ [`f0a17a543a23cbc8a33071b170a02ccf41fd33b7`](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/commit/f0a17a543a23cbc8a33071b170a02ccf41fd33b7)
227
+ (signed tag `v2.0.2`). Every source file in that commit carries the copyright
228
+ and SPDX notice.
229
+
230
+ The MIT license requires
231
+ that the copyright notice and license text be kept in copies and substantial
232
+ portions of the software; see [LICENSE](LICENSE) and [NOTICE](NOTICE).
233
+
234
+ This is an independent implementation, out of scope of and not derived from
235
+ any third-party framework's document or ontology. It is not affiliated
236
+ with, sponsored by, or endorsed by any such project.
@@ -1,11 +1,11 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: fpf-thinking-map
3
- Version: 2.0.2
3
+ Version: 2.0.3
4
4
  Summary: Deterministic Python runtime for lawful agent traversal with explicit state, evidence, authorization, waiting, and move identity.
5
5
  Author-email: "CONSOLIDARE CONTINUUM S.R.L." <info@consolidare-continuum.com>
6
6
  Maintainer-email: "CONSOLIDARE CONTINUUM S.R.L." <info@consolidare-continuum.com>
7
7
  License-Expression: MIT
8
- Project-URL: Homepage, https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map
8
+ Project-URL: Homepage, https://consolidare-continuum.com/fpf-thinking-map/
9
9
  Project-URL: Repository, https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map
10
10
  Project-URL: Documentation, https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map#readme
11
11
  Project-URL: Issues, https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/issues
@@ -34,85 +34,35 @@ License-File: LICENSE
34
34
  License-File: NOTICE
35
35
  Dynamic: license-file
36
36
 
37
- <p align="center">
38
- <img src="https://raw.githubusercontent.com/Consolidare-Continuum/fpf-agentic-thinking-map/main/docs/assets/fpf-agentic-thinking-map-header-v20260818.png" alt="FPF Agentic Thinking Map — Agent freedom. Explicit movement rules." width="100%" />
39
- </p>
37
+ # fpf-thinking-map
40
38
 
41
- # FPF Agentic Thinking Map
39
+ A small Python library that tracks the state of a multi-step agent workflow
40
+ and answers one question: *is this next move allowed right now, and if not,
41
+ why?*
42
42
 
43
- Deterministic Python runtime for agents that may reason freely but must move
44
- through a workflow lawfully.
43
+ You describe a workflow as a graph (contexts, roles, evidence, gates,
44
+ transitions). Your agent harness feeds the library the current state and the
45
+ move the agent proposes. The library returns a legal/illegal outcome with the
46
+ reason and a trace. It does not call a model, run tools, poll, or schedule
47
+ anything.
45
48
 
46
- Operational state, evidence freshness, transition legality, authorization,
47
- waiting, and move identity live **outside** model prose. The model proposes;
48
- the runtime decides whether the move is valid.
49
+ **PyPI:** [`fpf-thinking-map`](https://pypi.org/project/fpf-thinking-map/) · **Current:** **2.0.3** · **License:** MIT
49
50
 
50
- **PyPI:** [`fpf-thinking-map`](https://pypi.org/project/fpf-thinking-map/) · **Current:** **2.0.2**
51
-
52
- [![PyPI](https://img.shields.io/pypi/v/fpf-thinking-map?style=flat-square&label=PyPI&color=3775A9)](https://pypi.org/project/fpf-thinking-map/)
53
- [![Python](https://img.shields.io/pypi/pyversions/fpf-thinking-map?style=flat-square&label=Python&color=f0b429)](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/blob/main/pyproject.toml)
54
- [![Zero dependencies](https://img.shields.io/badge/dependencies-0-ff9f43?style=flat-square)](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/blob/main/pyproject.toml)
55
- [![Verification](https://img.shields.io/badge/verify-39%2F39-59d18c?style=flat-square)](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/blob/main/fpf_thinking_map/verify.py)
56
- [![Live demo](https://img.shields.io/badge/live-demo-dd8cff?style=flat-square)](https://consolidare-continuum.github.io/fpf-agentic-thinking-map/demos/three-runs.html)
51
+ [![PyPI](https://img.shields.io/pypi/v/fpf-thinking-map?style=flat-square&label=PyPI)](https://pypi.org/project/fpf-thinking-map/)
52
+ [![Python](https://img.shields.io/pypi/pyversions/fpf-thinking-map?style=flat-square&label=Python)](pyproject.toml)
53
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
57
54
 
58
55
  ## Install
59
56
 
60
- Requires **Python ≥ 3.12**. Zero runtime dependencies.
57
+ Requires **Python ≥ 3.12**. No runtime dependencies.
61
58
 
62
59
  ```bash
63
- pip install "fpf-thinking-map==2.0.1"
64
- python -m fpf_thinking_map.verify # 40/40 (39/39 at v2.0.1)
60
+ pip install "fpf-thinking-map==2.0.3"
61
+ python -m fpf_thinking_map.verify # the package's own self-tests, 40 checks
65
62
  python -m fpf_thinking_map.examples
66
63
  ```
67
64
 
68
- Full 2.0 line is on the index: [`2.0.0`](https://pypi.org/project/fpf-thinking-map/2.0.0/), [`2.0.1`](https://pypi.org/project/fpf-thinking-map/2.0.1/) (also [`1.9.6`](https://pypi.org/project/fpf-thinking-map/1.9.6/)).
69
-
70
- ## What it is
71
-
72
- Agents lose workflow rules in long runs. This package moves the non-negotiable
73
- parts into ordinary code:
74
-
75
- - current context and state
76
- - evidence presence and TTL freshness
77
- - gates, guards, and lawful transitions
78
- - cross-context bridges
79
- - human authorization (`AuthorizationReceipt`)
80
- - external wait (`PendingInput` / `AWAIT`)
81
- - concrete move identity (`MoveIntent`)
82
- - typed claim scope / pathwise reliability
83
- - tool-call plan closure and autonomy budgets
84
-
85
- Not a prompt. A compact **control surface** around reasoning.
86
-
87
- ## Contract
88
-
89
- | Agent / host | This runtime |
90
- | --- | --- |
91
- | Interprets the task | Holds explicit traversal state |
92
- | Generates options | Computes which moves are legal |
93
- | Collects evidence | Checks presence and freshness |
94
- | Proposes a move | Inspects or attempts that move |
95
- | Explains the result | Returns a bounded outcome and trace |
96
- | Requests human input | Enforces the authorization boundary |
97
- | Runs tools and jobs | Never executes, polls, or schedules them |
98
-
99
- ## Structural controls (shipped)
100
-
101
- | Concern | Structures | Effect |
102
- | --- | --- | --- |
103
- | Claim / assurance | `ContextSlice`, `ClaimScope`, `FormalityLevel`, `ReliabilityPath` | Typed scope; unknown stays unknown |
104
- | Tool plans | `CallPlanPrimitive`, `BudgetEnvelope` | Incomplete plans → `REVISE_PLAN` |
105
- | Autonomy | `AutonomyBudgetDecl`, `AutonomyLedgerEntry` | Opt-in budget; fail → `ESCALATE` |
106
- | Work attribution | `WorkPrimitive.performed_under` | Wrong holder/context cannot complete |
107
- | Gate join | `GateDecision`, `OutcomeCause` | `ABSTAIN` ≠ `BLOCK` (`cause=gate_block`) |
108
- | Map integrity | `ThinkingMapTraversal.validate_map()` | Dangling refs / unknown IDs fail closed |
109
- | Adjacency (2.0) | `AdjacencyClearanceRule`, `AdjacentlyCleared` | Confirmed-absent percept clears declared neighbors |
110
-
111
- ## Demo
112
-
113
- [![Four test-backed traces](https://raw.githubusercontent.com/Consolidare-Continuum/fpf-agentic-thinking-map/main/docs/assets/three-runs-preview.png)](https://consolidare-continuum.github.io/fpf-agentic-thinking-map/demos/three-runs.html)
114
-
115
- **[Interactive four-run trace](https://consolidare-continuum.github.io/fpf-agentic-thinking-map/demos/three-runs.html)** — evidence recovery, `AWAIT`, `MoveIntent`, authorization, and `ABSTAIN` vs `BLOCK`.
65
+ Other releases on the index: [`2.0.1`](https://pypi.org/project/fpf-thinking-map/2.0.1/), [`2.0.0`](https://pypi.org/project/fpf-thinking-map/2.0.0/), [`1.9.6`](https://pypi.org/project/fpf-thinking-map/1.9.6/).
116
66
 
117
67
  ## Minimal example
118
68
 
@@ -171,11 +121,86 @@ state = traversal.build_active_state(
171
121
  inspection = traversal.step(state)
172
122
  result = traversal.attempt_transition(state, "ship")
173
123
  print(inspection.kind, result.kind, state.current_state)
124
+ # OutcomeKind.CONTINUE OutcomeKind.CONTINUE released
174
125
  ```
175
126
 
176
- Replace the deploy vocabulary with your own contexts, roles, evidence, and gates.
127
+ Replace the deploy vocabulary with your own contexts, roles, evidence and gates.
177
128
 
178
- ## Gate join (keep these apart)
129
+ ## What it does
130
+
131
+ - Holds explicit traversal state: current context, state, and evidence.
132
+ - Checks evidence presence and freshness. Freshness decays over **traversal
133
+ steps**, not wall-clock time.
134
+ - Evaluates gates, guards and transitions and says which moves are legal.
135
+ - Supports cross-context bridges with validated writeback.
136
+ - Supports human authorization (`AuthorizationReceipt`): scoped, non-replayable.
137
+ - Distinguishes waiting on external input (`PendingInput` / `AWAIT`) from idle.
138
+ - Gives a proposed move a concrete identity (`MoveIntent`) that can be inspected.
139
+ - Can checkpoint and restore a paused traversal (`ActiveState.checkpoint()`,
140
+ `from_checkpoint()`); restore is all-or-nothing and never repairs.
141
+
142
+ Given the same map, state, evidence and receipts, it returns the same result.
143
+ The core modules call no clock, random source, network or model.
144
+
145
+ ## Division of work
146
+
147
+ | Agent / host | This library |
148
+ | --- | --- |
149
+ | Interprets the task | Holds explicit traversal state |
150
+ | Generates options | Computes which moves are legal |
151
+ | Collects evidence | Checks presence and freshness |
152
+ | Proposes a move | Inspects or attempts that move |
153
+ | Explains the result | Returns a bounded outcome and trace |
154
+ | Requests human input | Enforces the authorization boundary |
155
+ | Runs tools and jobs | Never executes, polls or schedules them |
156
+
157
+ ## Limits
158
+
159
+ - **It only constrains what is routed through it.** A harness or agent that
160
+ does not call the library is not constrained. There is no sandbox.
161
+ - **State lives in the host process.** The library keeps no storage of its
162
+ own; use `checkpoint()` to persist a paused traversal.
163
+ - **Several inputs are self-asserted.** For example `active_context_id`
164
+ (advisory ADV-03): the harness must own continuity.
165
+ - **Defaults are minimal.** Stale evidence warns but does not block unless a
166
+ gate requires it, and `requires_human_authorization` defaults off.
167
+ - **It is not a universal reasoner,** a vector store, a tool runner or
168
+ scheduler, or a certificate that an agent system is safe.
169
+
170
+ Full list of integrator boundaries: [ADVISORIES.md](docs/deep/ADVISORIES.md).
171
+
172
+ ## What the evidence shows
173
+
174
+ - **Self-tests.** `python -m fpf_thinking_map.verify` (40 checks) and
175
+ `dev_mcp/test_server.py` (45 checks) are written and run by the authors. They
176
+ check that the library does what it is specified to do. They have not been
177
+ audited by a third party.
178
+ - **Does it make agents safer?** One small benchmark exists
179
+ ([bench/RESULTS.md](bench/RESULTS.md)): two tasks, one frontier-model class,
180
+ 5 runs per condition, 20 runs total. The model made **no policy violations
181
+ with or without** the library, so there is **no measured compliance
182
+ improvement** for a cooperative model on a clearly stated task. With the
183
+ library the model made *more* tool calls (4.4 vs 1.0 and 2.0 vs 1.0), because
184
+ it used the inspection calls before acting. Weaker or adversarial models were
185
+ not tested.
186
+ - **ISO.** [docs/ISO_EVIDENCE_PACKET.md](docs/ISO_EVIDENCE_PACKET.md) maps
187
+ release 2.0.1 against ISO/IEC 25010, 27001 and 9001 as a self-assessed
188
+ checklist. It is **not** an audit and **not** a certification.
189
+
190
+ ## Shipped structures
191
+
192
+ | Concern | Structures | Effect |
193
+ | --- | --- | --- |
194
+ | Claim / assurance | `ContextSlice`, `ClaimScope`, `FormalityLevel`, `ReliabilityPath` | Typed scope; unknown stays unknown |
195
+ | Tool plans | `CallPlanPrimitive`, `BudgetEnvelope` | Incomplete plans → `REVISE_PLAN` |
196
+ | Autonomy | `AutonomyBudgetDecl`, `AutonomyLedgerEntry` | Opt-in budget; failure → `ESCALATE` |
197
+ | Work attribution | `WorkPrimitive.performed_under` | Wrong holder/context cannot complete |
198
+ | Gate join | `GateDecision`, `OutcomeCause` | `ABSTAIN` ≠ `BLOCK` (`cause=gate_block`) |
199
+ | Map integrity | `ThinkingMapTraversal.validate_map()` | Dangling refs / unknown IDs fail closed |
200
+ | Adjacency (2.0) | `AdjacencyClearanceRule`, `AdjacentlyCleared` | A confirmed-absent percept clears declared neighbours |
201
+ | Continuity (2.0.2) | `ActiveState.checkpoint()`, `from_checkpoint()` | Persist and restore a paused traversal |
202
+
203
+ ### Gate join
179
204
 
180
205
  | Gate result | Meaning | Typical outcome |
181
206
  | --- | --- | --- |
@@ -185,57 +210,63 @@ Replace the deploy vocabulary with your own contexts, roles, evidence, and gates
185
210
  `BLOCK` is hard for that evaluation; it is not automatically permanent. Checks
186
211
  opt into `BLOCK` with `failure_decision=GateDecision.BLOCK`.
187
212
 
188
- ## Release line
213
+ ## Demo
189
214
 
190
- | Line | Capability |
215
+ [Four interactive traces](https://consolidare-continuum.github.io/fpf-agentic-thinking-map/demos/three-runs.html)
216
+ (evidence recovery, `AWAIT`, `MoveIntent` with authorization, `ABSTAIN` vs
217
+ `BLOCK`). They follow behavior covered by the test suite as of v1.9.5; they are
218
+ not a recording of a live model run and do not show later features.
219
+
220
+ ## Releases
221
+
222
+ | Line | Change |
191
223
  | --- | --- |
192
224
  | v1.0–v1.5 | Primitives, TTL, bridges, stagnation, stable public boundary |
193
225
  | v1.6–v1.8 | Human authorization, receipts, `AWAIT` |
194
226
  | v1.9 / 1.9.5 | Move identity; A.21 gate join (`ABSTAIN` vs `BLOCK`) |
195
227
  | v1.9.6 | Failed-run revert terminal (XOR + distance bound) |
196
- | **v2.0.0** | Adjacency Clearance (`ADV-17`) |
197
- | **v2.0.1** | Current — docs/metadata/reference hardware; runtime verify **39/39** |
228
+ | v2.0.0 | Adjacency clearance (`ADV-17`) |
229
+ | v2.0.1 | Docs and metadata only; runtime identical to 2.0.0 |
230
+ | v2.0.2 | Copyright and SPDX notices on every source file (license unchanged); includes traversal checkpoint and restore (`ADV-08`) |
231
+ | **v2.0.3** | Docs and metadata only; runtime identical to 2.0.2. Removes the upstream-intake advisory (`ADV-16`) and every named reference to the external specification this package was historically informed by; independence disclaimer reworded |
198
232
 
199
233
  History: [VERSION_TRACKER.md](docs/VERSION_TRACKER.md) · [CHANGELOG.md](CHANGELOG.md) · [Releases](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/releases)
200
234
 
201
- ## Integrator notes (read before production)
202
-
203
- Deliberate minimal defaults — not defects. Full text: [ADVISORIES.md](docs/deep/ADVISORIES.md).
235
+ ## Integrator notes
204
236
 
205
237
  | Priority | Advisory | One line |
206
238
  | --- | --- | --- |
207
- | Sharp | **ADV-03** | `active_context_id` is self-asserted — harness must own continuity |
208
- | Sharp | **ADV-07** | `RiskAbove` string match is case-sensitive and fails silent |
239
+ | Sharp | **ADV-03** | `active_context_id` is self-asserted: the harness must own continuity |
240
+ | Sharp | **ADV-07** | `RiskAbove` string match is case-sensitive and fails silently |
209
241
  | Common | **ADV-01** | Stale evidence warns; it does not block unless gated |
210
242
  | Common | **ADV-10** | `requires_human_authorization` defaults off |
211
243
  | 2.0 | **ADV-17** | Adjacency clearance is only as sound as your declared biconditional |
212
244
 
213
- MCP harness: [`dev_mcp/`](dev_mcp/) — `run_scenario`, `get_advisories`, `run_verify`.
214
-
215
- ## Scope
216
-
217
- **Use when you need:** bounded multi-step legality, evidence-aware state,
218
- inspectable block/escalate reasons, human authorization, wait vs idle,
219
- compact LLM state slices.
220
-
221
- **Do not use as:** a universal reasoner, vector store, tool runner/scheduler,
222
- or a certificate that an entire agent system is safe.
245
+ MCP test harness: [`dev_mcp/`](dev_mcp/) (`run_scenario`, `get_advisories`, `run_verify`).
223
246
 
224
- ## Docs
247
+ ## Repository
225
248
 
226
249
  | Path | Purpose |
227
250
  | --- | --- |
228
- | [`fpf_thinking_map/`](fpf_thinking_map/) | Zero-dependency runtime (PyPI **2.0.1**) |
251
+ | [`fpf_thinking_map/`](fpf_thinking_map/) | The runtime (no dependencies) |
229
252
  | [ARCHITECTURE.md](ARCHITECTURE.md) | Control flow |
230
253
  | [docs/deep/ADVISORIES.md](docs/deep/ADVISORIES.md) | Integrator boundaries |
231
- | [SHA256SUMS](SHA256SUMS) | Source fingerprints |
254
+ | [bench/](bench/) | The ablation benchmark and its raw results |
255
+ | [SHA256SUMS](SHA256SUMS) | Source file checksums |
232
256
 
233
- ## Product continuation
257
+ ## License and ownership
234
258
 
235
- **CONSOLIDARE CONTINUUM S.R.L.** designs, owns, and ships this runtime for its own products and client work. No third-party framework affiliation. No external attribution required for use of this package.
259
+ MIT. Copyright (c) 2026 CONSOLIDARE CONTINUUM S.R.L.
236
260
 
237
- ## ISO evidence
261
+ Copyrighted build: release **2.0.2**, commit
262
+ [`f0a17a543a23cbc8a33071b170a02ccf41fd33b7`](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/commit/f0a17a543a23cbc8a33071b170a02ccf41fd33b7)
263
+ (signed tag `v2.0.2`). Every source file in that commit carries the copyright
264
+ and SPDX notice.
238
265
 
239
- [docs/ISO_EVIDENCE_PACKET.md](docs/ISO_EVIDENCE_PACKET.md) — ISO/IEC 25010 · 27001 · 9001 alignment for **v2.0.1** (**not** certification).
266
+ The MIT license requires
267
+ that the copyright notice and license text be kept in copies and substantial
268
+ portions of the software; see [LICENSE](LICENSE) and [NOTICE](NOTICE).
240
269
 
241
- **Agent freedom. Explicit movement rules.**
270
+ This is an independent implementation, out of scope of and not derived from
271
+ any third-party framework's document or ontology. It is not affiliated
272
+ with, sponsored by, or endorsed by any such project.
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "fpf-thinking-map"
3
- version = "2.0.2"
3
+ version = "2.0.3"
4
4
  description = "Deterministic Python runtime for lawful agent traversal with explicit state, evidence, authorization, waiting, and move identity."
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -32,7 +32,7 @@ classifiers = [
32
32
  ]
33
33
 
34
34
  [project.urls]
35
- Homepage = "https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map"
35
+ Homepage = "https://consolidare-continuum.com/fpf-thinking-map/"
36
36
  Repository = "https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map"
37
37
  Documentation = "https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map#readme"
38
38
  Issues = "https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/issues"
@@ -1,205 +0,0 @@
1
- <p align="center">
2
- <img src="https://raw.githubusercontent.com/Consolidare-Continuum/fpf-agentic-thinking-map/main/docs/assets/fpf-agentic-thinking-map-header-v20260818.png" alt="FPF Agentic Thinking Map — Agent freedom. Explicit movement rules." width="100%" />
3
- </p>
4
-
5
- # FPF Agentic Thinking Map
6
-
7
- Deterministic Python runtime for agents that may reason freely but must move
8
- through a workflow lawfully.
9
-
10
- Operational state, evidence freshness, transition legality, authorization,
11
- waiting, and move identity live **outside** model prose. The model proposes;
12
- the runtime decides whether the move is valid.
13
-
14
- **PyPI:** [`fpf-thinking-map`](https://pypi.org/project/fpf-thinking-map/) · **Current:** **2.0.2**
15
-
16
- [![PyPI](https://img.shields.io/pypi/v/fpf-thinking-map?style=flat-square&label=PyPI&color=3775A9)](https://pypi.org/project/fpf-thinking-map/)
17
- [![Python](https://img.shields.io/pypi/pyversions/fpf-thinking-map?style=flat-square&label=Python&color=f0b429)](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/blob/main/pyproject.toml)
18
- [![Zero dependencies](https://img.shields.io/badge/dependencies-0-ff9f43?style=flat-square)](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/blob/main/pyproject.toml)
19
- [![Verification](https://img.shields.io/badge/verify-39%2F39-59d18c?style=flat-square)](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/blob/main/fpf_thinking_map/verify.py)
20
- [![Live demo](https://img.shields.io/badge/live-demo-dd8cff?style=flat-square)](https://consolidare-continuum.github.io/fpf-agentic-thinking-map/demos/three-runs.html)
21
-
22
- ## Install
23
-
24
- Requires **Python ≥ 3.12**. Zero runtime dependencies.
25
-
26
- ```bash
27
- pip install "fpf-thinking-map==2.0.1"
28
- python -m fpf_thinking_map.verify # 40/40 (39/39 at v2.0.1)
29
- python -m fpf_thinking_map.examples
30
- ```
31
-
32
- Full 2.0 line is on the index: [`2.0.0`](https://pypi.org/project/fpf-thinking-map/2.0.0/), [`2.0.1`](https://pypi.org/project/fpf-thinking-map/2.0.1/) (also [`1.9.6`](https://pypi.org/project/fpf-thinking-map/1.9.6/)).
33
-
34
- ## What it is
35
-
36
- Agents lose workflow rules in long runs. This package moves the non-negotiable
37
- parts into ordinary code:
38
-
39
- - current context and state
40
- - evidence presence and TTL freshness
41
- - gates, guards, and lawful transitions
42
- - cross-context bridges
43
- - human authorization (`AuthorizationReceipt`)
44
- - external wait (`PendingInput` / `AWAIT`)
45
- - concrete move identity (`MoveIntent`)
46
- - typed claim scope / pathwise reliability
47
- - tool-call plan closure and autonomy budgets
48
-
49
- Not a prompt. A compact **control surface** around reasoning.
50
-
51
- ## Contract
52
-
53
- | Agent / host | This runtime |
54
- | --- | --- |
55
- | Interprets the task | Holds explicit traversal state |
56
- | Generates options | Computes which moves are legal |
57
- | Collects evidence | Checks presence and freshness |
58
- | Proposes a move | Inspects or attempts that move |
59
- | Explains the result | Returns a bounded outcome and trace |
60
- | Requests human input | Enforces the authorization boundary |
61
- | Runs tools and jobs | Never executes, polls, or schedules them |
62
-
63
- ## Structural controls (shipped)
64
-
65
- | Concern | Structures | Effect |
66
- | --- | --- | --- |
67
- | Claim / assurance | `ContextSlice`, `ClaimScope`, `FormalityLevel`, `ReliabilityPath` | Typed scope; unknown stays unknown |
68
- | Tool plans | `CallPlanPrimitive`, `BudgetEnvelope` | Incomplete plans → `REVISE_PLAN` |
69
- | Autonomy | `AutonomyBudgetDecl`, `AutonomyLedgerEntry` | Opt-in budget; fail → `ESCALATE` |
70
- | Work attribution | `WorkPrimitive.performed_under` | Wrong holder/context cannot complete |
71
- | Gate join | `GateDecision`, `OutcomeCause` | `ABSTAIN` ≠ `BLOCK` (`cause=gate_block`) |
72
- | Map integrity | `ThinkingMapTraversal.validate_map()` | Dangling refs / unknown IDs fail closed |
73
- | Adjacency (2.0) | `AdjacencyClearanceRule`, `AdjacentlyCleared` | Confirmed-absent percept clears declared neighbors |
74
-
75
- ## Demo
76
-
77
- [![Four test-backed traces](https://raw.githubusercontent.com/Consolidare-Continuum/fpf-agentic-thinking-map/main/docs/assets/three-runs-preview.png)](https://consolidare-continuum.github.io/fpf-agentic-thinking-map/demos/three-runs.html)
78
-
79
- **[Interactive four-run trace](https://consolidare-continuum.github.io/fpf-agentic-thinking-map/demos/three-runs.html)** — evidence recovery, `AWAIT`, `MoveIntent`, authorization, and `ABSTAIN` vs `BLOCK`.
80
-
81
- ## Minimal example
82
-
83
- ```python
84
- from fpf_thinking_map import (
85
- SemanticMap,
86
- ContextPrimitive,
87
- RolePrimitive,
88
- GatePrimitive,
89
- GateCheck,
90
- TransitionPrimitive,
91
- RuntimeBinding,
92
- ThinkingMapTraversal,
93
- )
94
-
95
- semantic_map = SemanticMap()
96
- semantic_map.register_context(ContextPrimitive("deploy", "Deploy"))
97
- semantic_map.register_role(RolePrimitive("owner", "Owner", "deploy"))
98
- semantic_map.register_gate(
99
- GatePrimitive(
100
- "release_gate",
101
- "Release gate",
102
- "deploy",
103
- checks=[
104
- GateCheck(
105
- "tests",
106
- "Tests are green",
107
- required_evidence=["test_results"],
108
- )
109
- ],
110
- )
111
- )
112
- semantic_map.register_transition(
113
- TransitionPrimitive(
114
- "ship",
115
- "Ship release",
116
- "deploy",
117
- "candidate",
118
- "released",
119
- required_gate_id="release_gate",
120
- required_evidence=["test_results"],
121
- )
122
- )
123
-
124
- traversal = ThinkingMapTraversal(semantic_map)
125
- state = traversal.build_active_state(
126
- RuntimeBinding(
127
- task="release",
128
- actor_role_ids=["owner"],
129
- active_context_id="deploy",
130
- current_evidence=["test_results"],
131
- ),
132
- current_state="candidate",
133
- )
134
-
135
- inspection = traversal.step(state)
136
- result = traversal.attempt_transition(state, "ship")
137
- print(inspection.kind, result.kind, state.current_state)
138
- ```
139
-
140
- Replace the deploy vocabulary with your own contexts, roles, evidence, and gates.
141
-
142
- ## Gate join (keep these apart)
143
-
144
- | Gate result | Meaning | Typical outcome |
145
- | --- | --- | --- |
146
- | `ABSTAIN` (`insufficient`) | Not enough basis to say yes | `COLLECT_EVIDENCE` when evidence is declared |
147
- | `BLOCK` | Declared policy says no for this evaluation | Denied with `cause=GATE_BLOCK` |
148
-
149
- `BLOCK` is hard for that evaluation; it is not automatically permanent. Checks
150
- opt into `BLOCK` with `failure_decision=GateDecision.BLOCK`.
151
-
152
- ## Release line
153
-
154
- | Line | Capability |
155
- | --- | --- |
156
- | v1.0–v1.5 | Primitives, TTL, bridges, stagnation, stable public boundary |
157
- | v1.6–v1.8 | Human authorization, receipts, `AWAIT` |
158
- | v1.9 / 1.9.5 | Move identity; A.21 gate join (`ABSTAIN` vs `BLOCK`) |
159
- | v1.9.6 | Failed-run revert terminal (XOR + distance bound) |
160
- | **v2.0.0** | Adjacency Clearance (`ADV-17`) |
161
- | **v2.0.1** | Current — docs/metadata/reference hardware; runtime verify **39/39** |
162
-
163
- History: [VERSION_TRACKER.md](docs/VERSION_TRACKER.md) · [CHANGELOG.md](CHANGELOG.md) · [Releases](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/releases)
164
-
165
- ## Integrator notes (read before production)
166
-
167
- Deliberate minimal defaults — not defects. Full text: [ADVISORIES.md](docs/deep/ADVISORIES.md).
168
-
169
- | Priority | Advisory | One line |
170
- | --- | --- | --- |
171
- | Sharp | **ADV-03** | `active_context_id` is self-asserted — harness must own continuity |
172
- | Sharp | **ADV-07** | `RiskAbove` string match is case-sensitive and fails silent |
173
- | Common | **ADV-01** | Stale evidence warns; it does not block unless gated |
174
- | Common | **ADV-10** | `requires_human_authorization` defaults off |
175
- | 2.0 | **ADV-17** | Adjacency clearance is only as sound as your declared biconditional |
176
-
177
- MCP harness: [`dev_mcp/`](dev_mcp/) — `run_scenario`, `get_advisories`, `run_verify`.
178
-
179
- ## Scope
180
-
181
- **Use when you need:** bounded multi-step legality, evidence-aware state,
182
- inspectable block/escalate reasons, human authorization, wait vs idle,
183
- compact LLM state slices.
184
-
185
- **Do not use as:** a universal reasoner, vector store, tool runner/scheduler,
186
- or a certificate that an entire agent system is safe.
187
-
188
- ## Docs
189
-
190
- | Path | Purpose |
191
- | --- | --- |
192
- | [`fpf_thinking_map/`](fpf_thinking_map/) | Zero-dependency runtime (PyPI **2.0.1**) |
193
- | [ARCHITECTURE.md](ARCHITECTURE.md) | Control flow |
194
- | [docs/deep/ADVISORIES.md](docs/deep/ADVISORIES.md) | Integrator boundaries |
195
- | [SHA256SUMS](SHA256SUMS) | Source fingerprints |
196
-
197
- ## Product continuation
198
-
199
- **CONSOLIDARE CONTINUUM S.R.L.** designs, owns, and ships this runtime for its own products and client work. No third-party framework affiliation. No external attribution required for use of this package.
200
-
201
- ## ISO evidence
202
-
203
- [docs/ISO_EVIDENCE_PACKET.md](docs/ISO_EVIDENCE_PACKET.md) — ISO/IEC 25010 · 27001 · 9001 alignment for **v2.0.1** (**not** certification).
204
-
205
- **Agent freedom. Explicit movement rules.**