What Information Does the LoopX Review Packet Command Present to Owners?

The reviewpacket command in LoopX generates a comprehensive markdown report that consolidates decision evidence, authority material counts, freshness warnings, and executable gate commands to help owners understand exactly what supports a decision and which actions are required to proceed.

The review_packet command is a critical oversight component of the huangruiteng/loopx repository, bridging automated decision-making with human review. When an owner needs to evaluate a goal's progression, this command assembles a structured packet in loopx/review_packet.py that reveals the evidentiary foundation of the current decision state and the specific gate conditions that must be satisfied before execution continues.

Goal Identity and Action Classification

Every review packet opens with clear identification metadata. The build_review_packet function (lines [107-109]) generates header fields labeled 目标 (target) and 类型 (type) that display the goal_id and the inferred action classification. These classifications include Controller, Codex, Reward, or Focus Wait operations, ensuring owners immediately understand the operational scope before evaluating underlying evidence.

Decision Evidence and Authority Materials

The Decision Evidence section provides quantified metrics about the knowledge base supporting the automated recommendation. This is generated by the authority_material_summary function (lines [74-92]).

The summary presents:

• Material volumes: Topic counts and total materials (e.g., topics=3, materials=27)
• Repository coverage: Number of source repositories consulted (repositories=2)
• Review flags: Boolean indicators for owner review requirements (owner_review_required=1)
• Risk assessments: Categorized risk levels (risk=low) alongside stale item counts

This structured metadata allows owners to verify that sufficient authoritative sources informed the decision and to identify when material staleness might compromise recommendation quality.

Freshness and Temporal Integrity Warnings

The review packet surfaces temporal integrity issues through two distinct warning systems that prevent owners from acting on outdated analysis.

Decision Freshness Alerts

When LoopX reuses an existing decision rather than generating a new one, the decision_freshness_packet_lines helper (lines [13-33]) generates alerts showing:

• The chronological age of the recycled decision
• Current freshness state classification
• Original evaluation metadata and context

This transparency ensures owners recognize when they are approving actions based on historical rather than current analysis.

Stale Latest Run Detection

The stale_latest_run_packet_lines function (lines [36-48]) performs a critical synchronization check. It compares the active system state against the latest run projection, and if the projection predates the current state, the packet issues an urgent refresh notification. This warns owners that the system's view of execution reality has drifted from actual runtime conditions.

Gate Commands and Execution Boundaries

Beyond presenting evidence, the packet provides actionable pathways for owner intervention through the gate control system.

Dry-Run Gate Operations

The operator_gate_decision_commands generator (lines [86-90]) produces a Gate Commands section containing executable CLI snippets. These commands support three operations:

• approve: Record owner acceptance of the decision
• reject: Record owner refusal
• defer: Postpone the decision pending additional review

Each command includes the --dry-run flag by default, allowing owners to preview the durable operator gate state before committing changes. The source code explicitly marks these as "human confirmation preview" tools rather than direct Agent execution commands.

Execution Constraints and Suggested Decisions

The suggested_decision and human_prompt invocations (lines [70-78]) populate the packet with:

• A concise recommendation (e.g., "同意 … 先做 read-only map dry-run")
• A copy-paste reply template for rapid owner response
• Execution boundary definitions clarifying read-only versus destructive operation limits

These elements appear within project_agent_section blocks (lines [61-78]), which delineate stop conditions and operational constraints for different agent types, ensuring owners understand the exact execution envelope.

How to Generate a Review Packet

Owners can produce review packets via the CLI front-end in loopx/cli_commands/pr_review.py or programmatically using the Python API.

Using the CLI

Invoke the reviewpacket subcommand with a status JSON payload:

# Assuming status.json contains output from `loopx status ...`

loopx reviewpacket \
    --status-json status.json \
    --goal-id GOAL-1234 \
    --review-url https://github.com/owner/repo/pull/42

The output displays the Decision Evidence section with authority counts and the Gate Commands section formatted with Chinese headers (用户本地 Gate 记录草稿) explaining local gate recording rules.

Using the Python API

For custom integrations, import the core functions directly:

from loopx.review_packet import build_review_packet, render_review_packet_markdown

# Load runtime status payload

status_payload = {...}  # Dictionary from LoopX runtime

goal_id = "GOAL-5678"

packet = build_review_packet(
    status_payload,
    goal_id=goal_id,
    review_url="https://github.com/owner/repo/pull/99"
)

# Access structured fields programmatically

print("Authority evidence:", packet["authority_summary"])
print("Freshness warning:", packet["decision_freshness_warning"])

# Render final markdown

print(render_review_packet_markdown(packet))

The returned dictionary contains the packet field (lines [73-75]) holding the assembled markdown string, along with individual warning components for programmatic inspection.

Supporting Infrastructure

The review packet system relies on several co-located modules:

• loopx/control_plane/handoff/review_packet_context.py: Provides context builders including agent_member_from_item and project_asset_source
• loopx/control_plane/handoff/delivery_contract.py: Supplies delivery contract summaries appearing in the packet's "交付合同" section

Summary

• The review packet command consolidates decision metadata, authority evidence, and gate controls into a single markdown document for owner review.
• Decision evidence includes quantified authority material counts, risk assessments, and repository coverage generated by authority_material_summary (lines [74-92]).
• Freshness and stale-run warnings alert owners to outdated decisions through decision_freshness_packet_lines (lines [13-33]) and stale_latest_run_packet_lines (lines [36-48]).
• Gate commands provide copy-paste CLI operations with --dry-run protection for safe owner confirmation before durable state changes.
• The system supports both CLI invocation via loopx reviewpacket and programmatic access through build_review_packet in loopx/review_packet.py.

Frequently Asked Questions

What is the difference between a freshness warning and a stale-run warning?

A freshness warning (generated by decision_freshness_packet_lines at lines [13-33]) indicates that LoopX is reusing an old decision rather than generating a new one, displaying the decision's age and state metadata. A stale-run warning (from stale_latest_run_packet_lines at lines [36-48]) specifically detects when the latest run projection is older than the active system state, signaling that the execution context has changed since the last evaluation.

How do I execute the gate commands shown in the review packet?

The gate commands include --dry-run by default for safety. Remove this flag only after confirming the decision locally. As implemented in operator_gate_decision_commands (lines [86-90]), these commands update the durable operator gate state—never execute them as raw Agent commands without removing the preview flag first.

Where does the authority material summary source its data?

The authority_material_summary function (lines [74-92]) aggregates data from the LoopX knowledge graph, counting topics, materials, repositories, and risk assessments. It accesses context helpers from loopx/control_plane/handoff/review_packet_context.py to resolve asset sources and membership information, ensuring the evidence presented reflects actual system knowledge.

Can I customize the suggested decision templates in the packet?

The suggested_decision and human_prompt functions (invoked in build_review_packet at lines [70-78]) generate the recommendation text and reply templates based on goal type and authority state. While the current implementation uses fixed logic, the modular structure in loopx/review_packet.py allows for customization by extending the project_agent_section builders (lines [61-78]) or overriding the prompt generation logic.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}