MantaPos

Imported from AtonFreson/MantaPos (AGENTS.md). Install upstream with npx skills add AtonFreson/MantaPos. Copyright stays with the author.

MantaPos repository guidance

Task scope and working method

• Follow current user direction and higher-priority host policies. These are repository defaults, not additional permissions.
• Check applicable instruction files before editing a directory; use the host's instruction precedence.
• Before modifying repository files or performing a diff-based review, inspect the working directory, Git status, and relevant diff. Treat existing changes as user-owned.
• Confirm the requested review baseline. A local remote-tracking ref is not proof of the server's current state.
• A review permits inspection and proportionate read-only checks; write a report only when requested.
• An implementation request includes necessary local edits and verification. Continue within that scope without repeatedly asking permission.
• Ask only for a material unresolved decision or an action outside the authorized scope; explain the exact blocker.
• Do not discard unrelated work, stage, commit or push unless the current task authorizes that operation.
• Prefer scoped rg searches and focused reads. Parallelize independent reads and bounded reviews when useful.
• Give short progress updates. Assign concurrent editors separate ownership and re-read files before modifying them.

Repository map and input contracts

• mantaPos-runKalmanFilter.py: offline replay, V1/V2/V3 configuration, sessions, scoring and plot dispatch.
• mantaPosLib.py: shared library, including the estimators and fixed-lag smoother.
• visualise_ukf.py: difference plots, timelines and animation. tests/: maintained regression suite.
• Treat recorded data, calibration/capture inputs, pressure logs and existing pickle artifacts as read-only unless changes are requested.
• Use the existing archive loader; do not assume MantaPos_data.json is a standard JSON document.
• Pressure records require both pressure_z0 and pressure_z1; direct indexing and missing-key failure are intentional.
• Do not add missing-key defaults or legacy-format compatibility without a concrete supported use case in the task.
• Preserve existing finite-value checks and other current validation; required keys do not imply every value is valid.

Editing, diagnostics and restoration

• Make repository file mutations through host-native tracked edits, such as apply_patch or editor workspace edits.
• Do not create, edit, copy, rename, move or delete repository files or directories through terminal commands, including redirection, rewrite scripts, Set-Content, Out-File, New-Item, Copy-Item, Move-Item, Remove-Item or equivalent tools.
• This file-mutation rule includes project dotfiles; it does not prohibit read-only commands or Git operations within the already-authorized task.
• If the required native edit operation is unavailable, explain that limitation instead of silently substituting a console write.
• Announce material edits before applying them and verify their resulting diff before claiming completion.
• Temporary variables and in-memory probes are normal diagnostic tools. Keep temporary files and disposable verification outputs in an OS temporary directory.
• Clean up only task-owned temporary artifacts. Do not leave debug scripts, copied recordings or generated results in the repository.
• New durable source, tests or documentation are appropriate when they belong to the requested implementation.
• python -B prevents bytecode writes only; it does not prevent code from creating directories, saving results or opening a GUI.
• For read-only runner verification, use known headless tests and direct evaluator calls rather than executing the interactive main block.
• Preserve existing file encodings and line endings; avoid unrelated whitespace churn.
• Do not emulate a host Restore Checkpoint with Git reset/checkout or manual source rewrites.
• After a host restore or unexpected concurrent edit, re-read status and affected content before continuing; report the actual state.
• Native edit success verifies the file edit; do not claim it proves a host checkpoint was created or restored.

Offline estimator conventions

• These model rules apply to the offline runner and its V2/V3 estimators, not every vector or subsystem in the library.
• Paired V2/V3 settings use [Y,Z]. Their states are [y,z,vy,vz] and [y,z,vy,vz,ay,az].
• Filters and smoothers start fresh for each recording run; do not carry state across sessions.
• V2/V3 reference records are for offline scoring/diagnostics, not estimator initialization or measurement updates.
• Legacy V1 intentionally initializes Z from the session's first reference-Z record; preserve that accepted exception.
• Predict to an estimator-event timestamp before applying measurements stamped at that timestamp.
• V2 may use previously available held IMU acceleration as deterministic control when enabled.
• V3 fuses current IMU acceleration through update_acceleration; raw acceleration is not injected by its prediction method.
• V3 starts with zero velocity/acceleration means and configurable prior covariance; later camera updates can inform acceleration.
• Keep state time distinct from release/availability time; preserve per-run full-lag retention and tail exclusion.
• In the standard V2/V3 presets, fixed_lag and synced_fixed_lag are release-time and historical-state-time views of the same retained smoothed states. Preserve their numerical identity while reporting preset identity separately.
• This comparison assumes matching input, lag and numerical settings. Custom preset divergence remains allowed and reported separately; do not silently force overrides equal.
• These are current intended contracts, not immutable restrictions; update them together with an authorized change in behavior.

Verification and maintained tests

• Use the project's working Python environment; Python 3.11 is the currently verified interpreter.
• For functional edits, run relevant existing tests during development, then the complete suite before handoff: python -B -m unittest discover -s tests -v
• Keep tests visible to Git and intended for versioning; do not ignore them as agent scratch or stage them without authorization.
• When behavior or interfaces deliberately change, update or replace affected tests in the same task; remove stale tests only when their contract is deliberately removed. Add durable coverage when it protects meaningful behavior.
• Do not weaken valid assertions or delete valid coverage merely to obtain a pass.
• Reuse existing tests where they answer the question; small read-only probes need not wait for an unrelated full-suite run.
• When changes affect estimator numerics, presets, event/release timing or scoring behavior, also use the formal run-isolated evaluator on the relevant archived runs.
• Final comparisons for shared estimator changes should cover all available recordings; use selected runs for focused development checks.
• For V2/V3 comparisons use evaluate_v2_v3_modes; confirm exact comparison-population identity, not just sample counts.
• With numerical claims record the source version, archive hash, selected runs, resolved presets, units and scoring time basis.
• Distinguish archive/tuning evidence from validation on new recordings and report regressions as well as improvements.
• New performance claims need matching current evidence. Attribute historical results; replay when the numerical code, data or settings invalidate them.
• For documentation-only changes, check structure, links and claims; do not rerun unrelated numerical checks.
• Prefer headless or mocked plot checks unless interactive behavior is part of the task. Do not open hardware/live streams as a side effect.
• Once relevant checks pass, rerun only for new edits, failures or unresolved concerns. Report unavailable checks honestly.

Reports and approval records

• Current user direction determines intent; live source/data/tests establish current facts. Investigate disagreements.
• Dated reports preserve historical evidence; do not treat their old instructions, hashes, metrics or conclusions as automatically current.
• When asked to update a ledger, record explicit user decisions faithfully and distinguish acceptance from verification.
• Preserve numbered items and original findings; append dated corrections, superseding decisions and new items.
• Preserve each ledger's existing heading and navigation status convention; keep cleared and pending items explicit.
• Acceptance may close a non-issue without changing code. Approval of one item does not approve neighboring proposals.
• Cross-reference other ledgers when relevant, respecting any request for an independent review; qualify item numbers by ledger.
• Keep AI-discussion snapshots in report/ai_discussion/ with snapshot disclaimers; retain their creation-date prefix.
• Other reports use their last substantive-edit date; metadata-only disclaimer or link maintenance does not require renaming them.
• Repair live links after requested renames; retain old literal paths when they are historical evidence.
• Use $...$ and $$...$$ for Markdown mathematics. Do not refresh historical measurements merely by changing their labels.

Handoff and guidance upkeep

• Recheck the final diff for intended scope, artifacts and newly introduced whitespace; distinguish pre-existing findings.
• Summarize changed files, behavior, verification and remaining decisions. Do not claim staging, push or GUI checks that did not occur.
• When an authorized implementation changes a durable contract or workflow, update affected AGENTS.md rules, maintained documentation and tests in the same task; do not expand a review-only request into edits.
• Preserve historical report findings; append dated corrections or decisions in the affected ledger when the task calls for updating that record. Do not rewrite every old snapshot.
• Keep this file concise. Keep hashes, metrics and temporary approval lists in reports.
• After creating or materially revising this file, verify discovery in a fresh Codex run/session; existing sessions may have older instructions.
• Record the actual loaded instruction paths when available. If fresh-session verification is unavailable, report it as unverified.