Skip to content

Independent Auditing of AI Agents. Run by human or the agent itself, to answer the most crucial question in the AI Agent Economy. Is the agent doing what is supposed to do? With iFixAi you can have this answer in less than 120 seconds.

docs: fold design notes into the guides (#318)

n-papaioannouebec2941b9e8
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 480b119..3bcb9d2 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -47,3 +47,9 @@ jobs:
test -f SECURITY.md || { echo "SECURITY.md missing"; exit 1; }
test -f docs/inspections.md || { echo "docs/inspections.md missing"; exit 1; }
echo "governance docs present"
+ broken=0
+ while IFS= read -r target; do
+ test -e "docs/$target" || { echo "docs/README.md links to missing docs/$target"; broken=1; }
+ done < <(grep -oE '[]][(][^)#]+' docs/README.md | sed 's/^](//' | grep -vE '^[a-z]+:')
+ test "$broken" -eq 0 || exit 1
+ echo "docs index links resolve"
diff --git a/docs/README.md b/docs/README.md
index 53bb3f9..481bede 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -13,6 +13,7 @@ needs: **learning**, **doing**, **looking up**, and **understanding**
- **[Test your own agent](testing-your-agent.md)**: wire in your real agent via `--provider http` or a `ChatProvider` adapter, with the provider reference.
- **[Author a fixture](fixture_authoring.md)**: declare your roles, tools, permissions, policies, and governance.
- **[Business Policy Lab](business-policy-lab.md)**: explore harmful permitted-action compositions and check repairs that preserve completion goals.
+- **[Recorded trajectory assurance](trajectory-assurance.md)**: check a recorded sequence of agent actions against a business policy, then replay the findings offline.
- **[Reproduce a run](reproducibility.md)**: the manifest, the digest algorithm, and verification helpers.
## 📖 Looking something up → reference
diff --git a/docs/adr/003-business-policy-lab.md b/docs/adr/003-business-policy-lab.md
deleted file mode 100644
index b6d4b23..0000000
--- a/docs/adr/003-business-policy-lab.md
+++ /dev/null
@@ -1,39 +0,0 @@
-# ADR-003: Explicit business-policy reachability and goal-preserving repair
-
-Status: Proposed
-
-## Context
-
-Individual role/tool authorization tests and scripted conversations can miss harmful compositions of individually allowed business actions. Recorded trajectories only cover paths already observed. An auditor needs a prospective check that can expose a short forbidden path before rollout and assess whether a proposed authorization change destroys useful business completion.
-
-Tool descriptions and fixture mock responses cannot establish transition semantics. Arbitrary automatic execution of imported actions would introduce authority and side effects unrelated to inspecting a model.
-
-## Decision
-
-Add a separate offline Policy Lab with explicit finite Boolean state, exact actors and permission rules, simultaneous guarded effects, named forbidden conjunctions and existential completion goals. Preserve every configured budget counter in visited-state identity. Deterministic breadth-first search retains one shortest witness per objective using parent pointers. Explore the complete reachable frontier unless bounded depth, state or examination limits require an inconclusive result. Counterexample evidence remains valid even when the frontier is incomplete; safe certification requires complete coverage and useful enabled transitions. Completion goals prevent a deny-all policy from becoming an accepted repair.
-
-Permission repair enumerates one- or two-rule removals with shared candidate and examination budgets. Accept only globally verified candidates and qualify minimum cardinality when any smaller candidate was inconclusive. Preserve the original facts, guards, effects, goals and budgets. Produce a candidate artifact; never mutate deployed policy.
-
-Use canonical typed JSON bundles with strict parse, digest verification and full recomputation on replay. Checksums establish consistency rather than truth or authentication. Project existing fixture authorization only when exact IDs and role matrices agree, explicitly recording its absent scope/effect semantics.
-
-Keep actual witness execution a separate Python API requiring caller-supplied synchronous bindings, reset and full independent observations. Validate evidence and binding declarations before any execution. Compare initial, pre-action and post-action snapshots; stop on mismatch or exception. Imported JSON never dispatches Python names or providers. No hidden threads, asynchronous continuation or unsupported timeouts.
-
-Expose check, replay, compare, repair and fixture projection through an additive CLI group, public Python exports, private evidence files and a self-contained report. Add no runtime dependency or inspection-grade coupling.
-
-## Alternatives considered
-
-- More scripted systemic-harm prompts: useful behavioral coverage but no exhaustive model reachability or shortest-path guarantee.
-- A passive trajectory checker: verifies declared observations but cannot discover an unobserved composition.
-- Infer action effects from prose using a model: would mistake hypotheses for business ground truth and add non-determinism and billing.
-- An SMT dependency or generalized planning language: broader expressiveness but heavier integration and semantic surface than the bounded Boolean/counter contract requires.
-- Repair by blocking every tool: eliminates some unsafe paths but fails declared business completion and is explicitly rejected.
-
-## Consequences and boundaries
-
-Model authors must declare sufficient state. Model verification is relative to those declarations, not proof of deployment safety, fairness, universal liveness or cross-tenant authorization. Finite exploration is exponential in facts and counters; hard input/search/batch bounds and honest inconclusive decisions replace unsupported scalability claims. Native observations provide evidence for one explicitly exercised local witness and can miss unmodeled side effects. Caller-supplied callables retain their normal authority.
-
-Frozen models use detached revalidation to avoid mutable nested containers and Pydantic copy/coercion bypasses. Exact counter identity can increase exploration but is required for correct budget reachability. Permission removal minimality is cardinality within the declared search space, not global business-policy optimality.
-
-## Acceptance and rollout
-
-Use a separately implemented exhaustive primitive oracle, adversarial evaluator tests, native match/mismatch/failure tests, fixture and CLI integration, private escaped reports, existing regressions, repository lint/security/layout checks, same-revision wheel and exact patch-alone verification. Demonstrate real synchronous local refund-store operations: a three-action harmful composition and a repaired independent-approval path, both independently observed. Preserve evidence and obtain an independent non-implementer review of the exact commit before publication. Keep existing inspection scores unchanged and retain manual maintainer merge authority.
diff --git a/docs/adr/ADR-002-recorded-trajectory-assurance.md b/docs/adr/ADR-002-recorded-trajectory-assurance.md
deleted file mode 100644
index 6d3a086..0000000
--- a/docs/adr/ADR-002-recorded-trajectory-assurance.md
+++ /dev/null
@@ -1,93 +0,0 @@
-# ADR-002: Audit retained agent trajectories against explicit business policy
-
-Status: proposed for this feature PR.
-
-## Context and problem
-
-Individual inspection outcomes cannot reconstruct authority across a production
-agent sequence. A worker may reuse an approval for changed arguments, receive an
-overbroad child delegation, or exhaust a shared budget through multiple actors.
-These failures depend on recorded relationships across steps. A generic telemetry
-span name does not identify an approver, bound arguments or delegated authority.
-The repository needs a reproducible way to inspect those relationships without
-executing imported actions or making a model-based governance decision.
-
-## Decision
-
-Add an independent `ifixai.trajectory` package with strict, bounded, declarative
-event and policy models, an iterative dependency graph evaluator, a supplied-callable
-recorder and passive JSONL / explicitly instrumented OTLP JSON importers. Retain
-one tenant and trace per capture. Expose audit, replay and alternate-policy analysis
-through the SDK and a dedicated CLI group. Existing inspection registrations,
-weights, grades, providers and schemas remain unchanged.
-
-Evaluate six families: graph coverage, closed-world permissions, exact approval
-binding/use/expiry/revocation, attenuating delegation chains, integer shared budgets
-and recorded citation lineage. Every finding retains event witnesses. Preserve
-missing evidence as INCONCLUSIVE rather than fabricating authority. A malformed
-graph prevents authority evaluation. BLOCK takes precedence when evaluated facts
-contain violations; CLEAR requires checked actions and complete enabled coverage.
-
-Use literal exact/prefix resource scopes, integer units and canonical JSON digests.
-Do not infer permission from timestamps, actor labels or arbitrary OTLP span names.
-Require each OTLP semantic span to contain the canonical event and bind it to the
-span ID, trace ID and timestamp. Retain dropped/inconsistent instrumentation as
-coverage uncertainty. Collector identity and completeness remain declarations.
-
-Freeze policy, capture and report together in a checksummed portable bundle.
-Replay validates the normalized shape and checksum, then recomputes the report.
-Alternate-policy analysis reads the same capture and records a finding-set delta;
-it does not execute an intervention. Export owner-only HTML, JSON and Markdown
-with no remote resources, raw arguments or model response text. Refuse overwrite.
-
-## Alternatives considered
-
-1. Add a synthetic inspection: smaller integration, but it would test supplied
- scenarios rather than audit a retained application trace. It cannot answer
- which actual recorded steps consumed an approval or a shared budget.
-2. Interpret ordinary GenAI spans automatically: convenient, but missing business
- semantics would force guesses about authority and completeness. Reject this.
-3. Add an inline enforcement gateway: can prevent selected actions, but requires
- application authorization integration and runtime availability guarantees.
- This passive feature has no such authority and cannot claim prevention.
-4. Ask an LLM to judge trajectory authorization: flexible interpretation, but
- nondeterministic, potentially costly and unsuitable for exact grant accounting.
- Explicit policy is reproducible and has no provider dependence.
-5. Sign bundles: useful for later collector provenance, but a signature would
- not prove completeness or factual truth. Leave authenticated collection to
- a separate integration with an explicit trust and key-management design.
-
-## Consequences, limitations and rollback
-
-Applications must emit the explicit instrumentation contract and choose policies.
-The recorder observes synchronous supplied callables; arguments, actors, human
-identity and costs are supplied semantic declarations. Failed calls make coverage
-incomplete because side effects may precede an exception. Citation checks establish
-observed lineage only. Hashes detect mutation, not authenticity. Reports describe
-retained evidence, not unobserved activity or production certification.
-
-The graph has bounded input and lazy ancestor queries, avoiding a full transitive
-closure. Delegation depth is capped at 128; exceeding the cap is INCONCLUSIVE rather than truncated positive assurance. Cumulative ancestor traversal is capped at 2,000,000 steps and exhaustion halts authority evaluation with a coverage gap. Many repeated ancestor queries can still
-cost more than flat traces; benchmarks report actual local time/memory and do not
-claim network or production latency. Schema version 1 is explicit; changed report
-semantics may require a compatible evaluator for old replays.
-
-The change adds no runtime dependency, network operation, inspection grade change
-or automatic publication. Roll back by removing the package, CLI registration,
-public SDK exports and docs together. Previously retained bundles remain local
-evidence and should not be deleted automatically.
-
-## Acceptance and evidence
-
-Require independent hand-derived policy oracles, adversarial graph/grant/citation
-tests, recorder side-effect/failure checks, strict JSONL/OTLP parsing, bundle tamper
-and rehash tests, immutable what-if workflow, HTML escaping, and no network/provider
-resolution. Run synthetic local callables through native CLI audit and replay,
-measure 1,000/10,000-event traces, and verify the exact feature patch and built
-wheel independently. Run the repository's required lint/security/layout/fixture
-gates and compare advisory typing diagnostics with unchanged main. Before public
-submission, require non-implementer review of the exact candidate revision.
-
-The feature is independent of the separately proposed paired-experiment feature;
-neither unmerged PR is a runtime prerequisite. Number 002 preserves distinct
-decision identifiers if both proposals are accepted.
diff --git a/docs/business-policy-lab.md b/docs/business-policy-lab.md
index 21f789f..8ca0beb 100644
--- a/docs/business-policy-lab.md
+++ b/docs/business-policy-lab.md
@@ -81,6 +81,15 @@ Supply bindings for every action in the retained witness. Each synchronous calla
`MATCHED` means this local implementation matched this particular witness. It is not full runtime verification, enforcement, isolation, a timeout, or production authorization. Supplied callables can have side effects before raising. Costs are declared units, not observed billing. Run such replay only against an implementation and reset you explicitly intend to exercise.
+## What it doesn't do
+
+- Results hold only for the model you declare. Leave out state the business depends on and the search can't see it.
+- `VERIFIED` isn't proof that the deployment is safe or fair, that goals are reached on every path, or that one tenant can't act on another's data.
+- Search grows exponentially with facts and budget counters. Hard limits stop it, and a search that stops early is never `VERIFIED`.
+- Replaying a witness on your code checks that one path on that one local setup. It can miss side effects the model doesn't describe.
+- Callables you pass in run with whatever access they already have.
+- The smallest repair means the fewest rule removals within the search you asked for. It doesn't mean it's the best policy for your business.
+
## Validate changes
```sh
diff --git a/docs/trajectory-assurance.md b/docs/trajectory-assurance.md
index 9402528..ee551f7 100644
--- a/docs/trajectory-assurance.md
+++ b/docs/trajectory-assurance.md
@@ -180,6 +180,20 @@ The envelope follows the official [OTLP JSON encoding specification](https://ope
The `ifixai.*` instrumentation contract is specific to this feature and is not
an OpenTelemetry semantic convention or an automatically installed integration.
+## What it doesn't do
+
+- It only knows what your application tells it. You add the instrumentation and
+ choose the policy. Arguments, actors, human identity and costs are your
+ declarations, and the recorder only watches synchronous callables you pass it.
+- It doesn't assume a failed call did nothing. A call that raises leaves coverage
+ incomplete, because it may have had side effects first.
+- Citation checks only follow the recorded links from an output back to its sources.
+- The checksum catches changes to a bundle. It can't show who made it.
+- Delegation chains deeper than 128 grants, and audits that hit the 2,000,000-step
+ ancestry limit, can't come back CLEAR.
+- A report covers the evidence it was given. It says nothing about activity nobody
+ recorded, and it isn't a production certificate.
+
## Verification
Run `python -m pytest ifixai/tests/trajectory -q` for independent policy oracles,