aitp-runtime

name	aitp-runtime
description	Continue an AITP v5 theoretical-physics topic through typed claims, source provenance, artifacts, evidence, validation gates, human checkpoints, and trust-controlled memory.

AITP Runtime v5

For every active AITP research iteration, decide whether the current request needs AITP before answering:

aitp_v5_codex_autoroute(base="", request_summary=<current user request>, session_id=<session-id if known>, topics=<topics if known>, semantic_assessment=<model semantic assessment>)

If autoroute says answer_without_aitp, answer normally and do not write AITP records. If it returns enter_existing_session, recover_topic, or recover_workspace, call the returned recommended_next_tool with recommended_args, then restore the bounded Codex entry card:

The semantic assessment is the model's research-intent judgment, not evidence. Use it to declare whether the request needs prior research state, latest topic state, an existing claim/topic, durable output recording, validation/evidence boundaries, failed-route memory, or trust/claim-status handling. If a possible research request is uncertain, route into AITP read-only.

aitp_v5_codex_enter(base="", session_id=<session-id>, request_summary=<current user request>, payload_profile="minimal")

Use base="" unless the user explicitly provides a topics root. The MCP server resolves the empty base through AITP_TOPICS_ROOT, which the plugin launcher sets from environment, AITP install records, or the default ~/.aitp/topics.

The entry card includes the low-interruption continuation view. It is orientation-only and cannot update claim trust, evidence, validation, L2 memory, or skills. It should name the current objective, active work package, can-say/cannot-say boundaries, blockers, next actions, prior failed/superseded route hints, and expansion commands. Request payload_profile="context_pack" only when a richer turn-input fragment is needed.

Expand explicitly before any trust-sensitive interpretation:

aitp_v5_codex_expand(base="", session_id=<session-id>, expansion="brief")
aitp_v5_codex_expand(base="", session_id=<session-id>, expansion="relation_map")

The full brief is the execution contract. Follow current_focus, flow_profile, risk_assessment, evidence_coverage, next_action_candidates, forbidden_now, and human_checkpoint.

The claim relation map is the boundary layer. Read supported_by, limited_by, not_tested_by, contradicted_by, current_conclusion.can_say, current_conclusion.cannot_say, current_blockers, and next_valid_actions before interpreting the active claim.

Typed Runtime Loop

1. Autoroute the request.
2. Restore the Codex entry card when autoroute requires AITP.
3. Expand to the full brief and relation map only when the task needs audit, trust, validation, evidence, or final synthesis.
4. If a human checkpoint is needed, present it plainly and wait.
5. If policy forbids trust-changing actions, collect missing source, evidence, or validation first.
6. If evidence coverage is missing, record only the durable typed object needed: source, artifact, code state, tool recipe, tool run, evidence, validation contract, validation result, proof obligation, or sensemaking report.
7. Do the physics, code, or literature work.
8. Record durable outputs before summarizing them as research state.
9. Verify expected records with aitp_v5_verify_recording_effect when recording navigation is used.

Closeout and quiet checkpoint returns include record_completeness_audit. Inspect it before saying that AITP recording is complete. ok=true only means the preview/apply call succeeded. If missing_recommended_slots is non-empty, report those slots or continue through existing typed tools after the needed user confirmation.

Moment Policy

AITP is not a transcript logger. Record only durable research moments:

• reusable source identity or source location,
• completed tool/code run with research-relevant output,
• artifact/report/table/plot/log/raw dump,
• result, anomaly, contradiction, negative result, or failed check,
• proof gap, validation gap, missing provenance, route blocker,
• selected, pivoted, abandoned, or split route,
• active claim scope or status change,
• final answer that depends on an active claim,
• trust update, promotion, or human decision request,
• session-end handoff with new durable state.

Do not record generic explanation, unaccepted brainstorming, repeated summaries, file scans with no research change, or setup checks with no research information.

Progressive Recording

Use the lightest recording route:

aitp_v5_codex_recording_step(base="", session_id=<session-id>, event_type=<event>, summary=<durable moment>)
aitp_v5_codex_recording_step(base="", session_id=<session-id>, event_type=<event>, summary=<durable moment>, slot=<one slot>)
aitp_v5_codex_record_apply(base="", session_id=<session-id>, slot=<one slot>, payload=<typed slot payload>)

If the classifier says ignore or defer, do not write. Expand one slot at a time. aitp_v5_codex_record_apply returns a verification block; use the separate aitp_v5_verify_recording_effect only in full-kernel maintenance mode.

Record Boundaries

• Definitions and systems: aitp_v5_record_physics_object.
• Relations and equations: aitp_v5_record_object_relation.
• Papers, notes, and source locations: aitp_v5_codex_literature_step or aitp_v5_codex_record_apply with slot="source_asset" / slot="reference_location".
• Files and reports: aitp_v5_attach_artifact.
• Numerical or code-dependent work: code state, tool recipe, tool run, evidence, validation result.
• Numerical closeout completeness: durable PDF/report/note/plot/data/log output should have an artifact; changed files, scripts, repo paths, or worktree-dependent results should have code_state; validation commands or explicit validation boundaries should have validation_result or a validation-gap record.
• Open theorem or review gaps: aitp_v5_create_proof_obligation.
• Claim maturity/status observations: aitp_v5_update_claim_status.
• Interpretation: aitp_v5_record_sensemaking_report, marked orientation-only unless backed by typed evidence or validation.

Source references and artifacts are provenance/context by themselves. Do not treat them as claim support until typed evidence or validation links them to the claim. Unresolved artifact refs from quiet checkpoint or closeout are not verified evidence. Quiet checkpoints and sensemaking remain orientation-only and must not promote trust.

Literature And Writing

For paper learning, web references, and note/article drafting, use the Codex facade first:

aitp_v5_codex_literature_step(base="", session_id=<session-id>, action="suggest", uri=<url-or-path>, label=<source label>)
aitp_v5_codex_literature_step(base="", session_id=<session-id>, action="record_reference", uri=<url-or-path>, label=<source label>)
aitp_v5_codex_expand(base="", session_id=<session-id>, expansion="note_outline", style="jhep")

Register references in layers: source identity, exact reference location, reading artifact, claim-linked evidence, physics object/relation, validation basis, and trust basis. A paper, web page, local note, or RAG chunk is not evidence until it is linked to a specific claim with scoped typed evidence.

For session end or discussion closeout, do not rely on a Codex stop hook. Use:

aitp_v5_codex_closeout(base="", session_id=<session-id>, summary=<handoff summary>)

The closeout tool previews by default. Set apply=true only when there is a durable handoff or quiet checkpoint worth writing. It cannot update claim trust. After closeout, read record_completeness_audit.recording_complete, recorded_slots, missing_recommended_slots, recommended_next_records, trust_boundary, and requires_user_confirmation. Missing slots are plan-only recommendations; actual writes still use the typed tools above. Trust promotion still requires separate preflight and the explicit human gate.

Physics Validation Obligations

Before treating a result as strong, check the relevant obligations:

• dimensional and algebraic consistency,
• limiting cases and known limits,
• symmetry, Ward identity, causality, unitarity, or conservation checks where applicable,
• approximation validity and scale separation,
• numerical convergence, benchmark comparison, and error bars,
• explicit mismatch or negative-result records when a check fails.

Do not bury a failed check in prose. Record it as typed protocol state.

Fallback Commands

uv run --with pyyaml --with jsonschema --with fastmcp --with "pypdf>=5,<7" python scripts/aitp-pm.py doctor
uv run --with pyyaml --with jsonschema --with fastmcp --with "pypdf>=5,<7" python -m brain.v5.cli --base "$env:AITP_TOPICS_ROOT" status context-pack <session-id>
uv run --with pyyaml --with jsonschema --with fastmcp --with "pypdf>=5,<7" python -m brain.v5.cli --base "$env:AITP_TOPICS_ROOT" brief <session-id>
uv run --with pyyaml --with jsonschema --with fastmcp --with "pypdf>=5,<7" python -m brain.v5.cli --base "$env:AITP_TOPICS_ROOT" relation-map <session-id>
uv run --with pyyaml --with jsonschema --with fastmcp --with "pypdf>=5,<7" python -m py_compile brain/v5/native_mcp.py brain/v5/mcp_tools.py brain/v5/brief.py brain/v5/context_pack.py