loopx-project

name	loopx-project
description	Use when connecting a repository or project goal document to LoopX, maintaining project-local goal state, refreshing stale dashboard status, syncing local projects into the shared global registry, or diagnosing LoopX CLI/PATH/status/history issues across multiple repos. For registering durable project materials such as Lark/wiki/design docs, prefer the narrower loopx-doc-registry skill.

LoopX Project Workflow

Use this skill when the task mentions LoopX, loopx, a project goal document, multi-project dashboard/status, stale latest run, .loopx/registry.json, .codex/goals, refresh-state, sync-global, or connecting a new repo. If the task is mainly about reading, remembering, recording, indexing, or registering a durable project material, load loopx-doc-registry and use that narrower workflow first.

LoopX has two layers:

• Project-local state: each repo owns .loopx/registry.json and .codex/goals/<goal-id>/ACTIVE_GOAL_STATE.md.
• Shared local control plane: ~/.codex/loopx stores run history and registry.global.json for multi-project status.

Do not manually copy one project's registry entry into another project. Local connect and refresh-state should sync into the shared global registry automatically.

Slash Command Fallback

When the visible user message is exactly a LoopX slash command or starts with a LoopX slash command plus arguments, do not treat it as ordinary chat.

Recognized project-local goal-start command:

• /loopx <goal text>

Recognized repo-review commands:

• /loopx-pr-review
• /loopx-pr-review <time window or filter text>

If there is any non-whitespace text after /loopx, it is goal text. Preserve that exact trailing text, pass it to the guided start preview, and do not downgrade the request into a status or inspection turn.

When the target is a linked git worktree, trust the command pack's canonical_project_alias / source_registry route. Do not manually run loopx bootstrap in the linked worktree merely because its local .loopx state is missing or stale; that can create a worktree-local shadow goal instead of updating the canonical project state.

From the target project root, pass the text after /loopx as the explicit goal-start objective before planning or writing project state:

loopx start-goal --guided --project . --goal-text "<GOAL_TEXT>"

Include --goal-id <STABLE_GOAL_ID> and --agent-id <REGISTERED_AGENT_ID> when they are known. If start-goal --guided is not available, refresh the local LoopX CLI or use the checked-out LoopX repository CLI for validation; do not silently downgrade /loopx <goal text> into a bare /loopx read-only command. Use loopx bootstrap-command-pack --project . --goal-text "<GOAL_TEXT>" only when implementing or debugging the lower-level host handoff packet.

If the connected goal later needs a wider or corrected write boundary, do not rerun loopx bootstrap --force just to change scope. Use the incremental configuration path instead:

loopx configure-goal \
  --goal-id <STABLE_GOAL_ID> \
  --write-scope "<SAFE_WRITE_SCOPE>" \
  --execute

If a destructive reconnect is explicitly required, pass --preserve-todos with --force unless the user intends to rebuild the active state file and discard existing todo projection.

/loopx <goal text> is an explicit goal-start intent: first produce a concise ordered plan, then write todos in priority order, using planner order plus todo add write order as the same-priority tie-breaker. For broad or fuzzy product directions, use a small public-safe planning set; for clear bounded problems, use the minimum sufficient ordered todo plan and avoid management-only filler.

Global manager slash commands such as /loopx-global-summary, /loopx-global-gates, /loopx-global-todos, and /loopx-global-risks are not project bootstrap commands. Route them to the global manager command contract or status summary surface instead of bootstrap-command-pack. Legacy /loop-global-* forms may be treated as aliases, but canonical help and packets should use /loopx-global-*.

Repo-review slash commands are also not project bootstrap commands. If the visible request starts with /loopx-pr-review, stop this project-bootstrap workflow and load the narrower loopx-pr-review skill. That skill owns the required first command, packet-preservation rules, and five-block per-PR review contract. Do not handle /loopx-pr-review from this broader project skill, and do not route it to loopx-pr-merge unless the user later asks to approve, comment on, merge, self-merge, or admin-bypass a specific PR.

When a user has just connected a project, receives a guided start packet, or receives a bootstrap command pack for the first time, briefly tell them the usable commands instead of assuming they will inspect CLI help:

• /loopx <goal text>: start a concrete goal with a plan-before-todo-write flow.
• /loopx-global-summary: read the global progress digest.
• /loopx-global-gates, /loopx-global-todos, /loopx-global-risks: inspect manager-level gates, work, and risks.
• /loopx-pr-review: use the loopx-pr-review skill to run loopx pr-review and review unmerged/merged PR groups one by one.

For command-line discovery, use:

loopx slash-commands

Register Project Authority And Material Sources

When a project agent discovers a durable design document, research note, benchmark paper, owner packet, migration report, or external material that future agents may need for routing, validation, or conflict resolution, treat that as a doc-registry skill trigger. Identify the target project and goal first; do not register material into the current meta goal just because this worker found it.

For material owned by the current project, update the project-local doc registry or equivalent authority map first, then register the compact redacted source contract in the same project's ignored .loopx/registry.json:

loopx register-authority-source --goal-id <STABLE_GOAL_ID> ...

For another project's DOC_REGISTRY-style map, import only the compact authority summary instead of copying raw paths, document ids, URLs, comments, or source bodies:

loopx import-doc-registry-authority --goal-id <STABLE_GOAL_ID> ...

After registration, refresh status or state so review packets, read-only maps, and heartbeat workers can find the new authority without relying on chat memory. Stop and write a project-local todo or blocker when the target project is ambiguous, the source cannot be represented as public-safe metadata, or the next step would require reading a gated source body.

Owner-Facing Explore Views

Treat the canonical Explore topology and an owner-facing decision graph as two different read models over one evidence source:

• canonical JSON, Mermaid, and Nodes/Edges/Findings tables preserve complete public-safe node identity, evidence, and lineage;
• focused status/tag exports are bounded evidence subsets, not executive views by default;
• an executive graph applies semantic compression for operator decisions. It should show the decision contract, baseline/incumbent, decisive negative evidence, active work or capacity, material risk, terminal gate, and next decision. Semantic compression may tighten labels and remove true duplication, but it must preserve material decision and evidence nodes plus their lineage.

Never overwrite an executive whiteboard directly from a full or focused canonical export unless a declared presentation contract proves that the export already carries those semantic roles. For a recurring sync, keep a project-local display contract with required roles, stable canonical ids, semantic sections or linked subgraphs, and a non-identity guard. The default cardinality policy is graph growth: do not omit or merge away a material node because the graph crossed a generic count such as 20 nodes. A hard max_nodes or max_edges limit is valid only as an explicit opt-in presentation policy with declared scope and overflow behavior; absent that policy, treat those limits as unbounded.

Render with the target renderer, run overlap and text-overflow checks, inspect the actual preview, then sync and verify the remote source or digest. Repair a failed readability check by relayout, shorter labels, larger frames, or more semantic subgraphs, not by deleting material evidence. If any check still fails, keep the previous owner view; do not publish a structurally valid but unreadable graph.

This separation does not transfer quota, todo, launch, stop, or promotion authority into the presentation layer. Record material experiment transitions in canonical Explore state first, then refresh the executive projection.

Preflight

From the target project shell:

export PATH="$HOME/.local/bin:$PATH"
loopx doctor

If loopx is not on PATH:

install_script="$HOME/loopx/scripts/install-local.sh"
if [ -x "$install_script" ]; then
  "$install_script"
  export PATH="$HOME/.local/bin:$PATH"
fi
loopx doctor

If this still fails, report the exact missing piece and do not fake a successful connection.

Diagnose For The User

When the user asks whether LoopX is working, whether a project can self-drive, why it is stuck, or says "diagnose LoopX", do not hand the user shell commands. Run the diagnostic surfaces yourself and then reason from the evidence.

Prefer the agent-facing packet:

loopx diagnose

If the target goal is known:

loopx diagnose --goal-id <STABLE_GOAL_ID>

The diagnose command is not the final judge. It returns compact status, quota should-run, todo, interaction-contract, and boundary signals plus a reasoning checklist. Use those signals as evidence, then answer in your own words:

• whether the project can currently self-drive;
• what evidence supports that conclusion;
• what blocks autonomous delivery or self-repair;
• the exact user/controller question, if one is projected;
• what the agent will do next.

Only claim autonomous readiness when your reasoning confirms that the user gate does not block the selected path, quota permits a turn, goal_boundary allows the work, and there is a concrete agent todo or recommended action. If diagnose cannot read status/quota, repair installation, PATH, registry path, or project connection first; do not infer readiness from chat memory.

Before Spending Automatic Compute

Before a heartbeat, scheduled tick, long-running adapter, or autonomous project agent spends another delivery turn, ask LoopX whether this goal is eligible:

loopx --format json --registry "$HOME/.codex/loopx/registry.global.json" quota should-run --goal-id <STABLE_GOAL_ID>

For a registered multi-agent goal, include this agent's identity:

loopx --format json --registry "$HOME/.codex/loopx/registry.global.json" quota should-run --goal-id <STABLE_GOAL_ID> --agent-id <REGISTERED_AGENT_ID>

If a registered goal returns automation_prompt_upgrade.required=true, treat the installed automation prompt as stale and regenerate it with heartbeat-prompt --agent-id ... --agent-scope ....

If the default loopx payload contradicts the just-merged source checkout or a PYTHONPATH=<checkout> python3 -m loopx.cli ... cross-check, pause delivery and run loopx doctor before trusting quota. The installed command is normally a release snapshot wrapper, so a self-merged fix may require refreshing the local install from latest trusted origin/main with loopx update --execute --ref main or a clean main checkout's scripts/install-local.sh; rerun the default loopx command after the refresh and only spend quota after the runtime payload matches the repaired source behavior. A dirty or non-main checkout is canary-only by default. Use LOOPX_PROMOTE_DEFAULT=1 scripts/install-local.sh only after the checkout has passed its promotion validation and the default replacement is an intentional write.

If the response has state=operator_gate, treat it as a user/controller interaction, not a silent skip. Read gate_prompt, operator_question, recommended_action, next_handoff_condition, missing_gates, and user_todo_summary and agent_todo_summary when present, then ask the concrete gate in Chinese unless the same unresolved question was already surfaced in the recent visible thread. Before repeating a public PR merge-approval gate, reconcile it against current compact PR lifecycle state. When the todo has a merge-scoped decision such as direction:action:merge_pr_<number> and the public PR URL is unambiguous, run:

loopx issue-fix pr-gate-reconcile \
  --goal-id <STABLE_GOAL_ID> \
  --todo-id <USER_GATE_TODO_ID> \
  --url <PUBLIC_GITHUB_PR_URL> \
  --fetch-metadata \
  --execute

Then rerun quota should-run. The command may complete only the matching user_gate, and only after compact public metadata reports MERGED or CLOSED; it records no body, comments, logs, provider payload, or external write. If the URL is ambiguous or the public read fails, preserve the gate and surface that exact resolution failure instead of claiming the owner still needs to approve an already-terminal PR. Only when interaction_contract.user_channel.action_required=true or user_todo_summary.open_count > 0, the notification must name concrete payload todo(s)/questions, never only "owner gate"; if those required user-facing items are not projected, say "具体 user todo 未投影，需修复 LoopX 状态投影"; never say "no new user action" for this case. When interaction_contract.user_channel.action_required=false and user_todo_summary.open_count=0, allow "无用户待办/无需通知" or a quiet no-notification result; do not imply a state projection bug. Do not run agent_command, adapter work, write-control, production actions, or the gated path while asking.

Prefer the guard's interaction_contract when present. It is the current machine-readable protocol for the user / agent / LoopX CLI split: interaction_contract.user_channel says whether to ask the user, agent_channel says whether Codex must attempt work or may quiet no-op, and cli_channel says which CLI transition and spend policy apply. Treat older fields such as execution_obligation, heartbeat_recommendation, work_lane_contract, and goal_boundary as compatibility/drill-down fields under that contract, not as competing sources of truth.

If the response has should_run=false and not safe_bypass_allowed=true, do not run implementation or adapter work for that goal in this turn. When effective_action=monitor_quiet_skip, append at most one no-spend quota monitor-poll --goal-id <STABLE_GOAL_ID> --source heartbeat --execute event, rerun quota should-run, and follow autonomous_replan_required / execution_obligation.must_attempt_work=true if the next guard exposes it; otherwise quietly report or record the public-safe reason only when there is no operator gate to ask. Keep the heartbeat automation active: unchanged monitor-only polls are liveness-preserving no-ops, not self-stop signals. If the command exits non-zero, fail closed: run loopx doctor / loopx status and fix status collection before spending compute.

If the response has state=operator_gate and safe_bypass_allowed=true, the gate blocks only the gated delivery path. After the gate has already been surfaced, you may still read the active state and do one bounded safe-bypass step from the Priority Stack, such as read-only steering analysis, documentation, or another P0/P1 item that does not depend on that gate. If that safe-bypass step actually spends automatic compute, validate it, write back progress/critic/next action, optionally refresh state, and append one quota spend event. If user_todo_summary.open_count > 0, the safe-bypass report must include those existing open user todos and must not say there is "no new user action". If agent_todo_summary.open_count > 0, use it as the project agent's safe follow-up checklist instead of mining chat history or an overlong Next Action.

If the response has safe_bypass_kind=outcome_floor_recovery or heartbeat_recommendation.recommended_mode=outcome_floor_recovery, the outcome floor blocks surface-only delivery but permits one bounded recovery attempt: produce the required ranker/cross-domain evidence artifact named by quota.must_advance, or write back the concrete blocker that prevents that artifact. Avoid summary/queue/contract propagation and synthetic-only test chains. Spend exactly once only after validated evidence/blocker writeback.

This guard is only a compute-allocation check. It does not grant write permission, bypass operator gates, or replace run-bound human reward. Operator gates block the gated delivery path, not unrelated safe steering work. For an eligible current goal, dependency or sibling-goal todos must not consume the whole eligible turn. Record or surface those todos as dependency blockers, but continue the steering audit and choose a gate-independent P0/P1/P2 candidate for the current goal when one exists. Stop before delivery only when the open user/owner todo belongs to the current goal's guard payload or project asset and blocks the selected delivery path. Routine public repo publication is a boundary decision, not a standing operator gate: when the active state permits the step, validation passes, and the public/private boundary scan is clean, commit, push, and PR creation can proceed autonomously. Stop for private or company-internal material, credentials, destructive git operations, production actions, or repository rules that explicitly require review. Use the shared global registry for this guard so the project agent reads the same operator gates, user todos, agent todos, and quota state as the dashboard. This does not mean all project work is global: todo add, refresh-state, adapter runs, and project-file reads still use the project-local state/registry and then sync the public-safe projection back into the global control plane. If two projects share a goal_id, treat that as a registry health bug and fix the id/source mapping.

If should_run=true, do not simply continue the nearest previous TODO. Read the active state's Priority Stack, recent progress, and critic, then run a short steering audit before choosing work: list at least three plausible next-action candidates across different P0/P1/P2 lanes when useful; if the same topic has consumed several recent delivery slices, apply a continuation check and state why continuing still wins; keep compute quota separate from focus quota; record any losing high-value candidate that should not be forgotten. Include a product bottleneck lens: ask whether the core goal is currently bottlenecked by user experience, agent capability, evidence quality, adapter readiness, or priority-rule gaps, and promote one concrete bottleneck candidate when it should outrank the nearest local TODO. Then choose exactly one bounded, verifiable step from that audit.

When you tell the user a connected LoopX plan, top-todo list, priority stack, or route change, treat that as a writeback trigger, not chat memory. If the plan contains concrete future P0/P1/P2 work, user actions, route decisions, or deprecations, update active-state todos / Next Action / refresh-state before the final response, or explicitly say why the plan is only speculative and was not written. Use loopx todo add / todo update for durable work items; do not leave them only in prose, a review doc, or a Lark/chat reply.

For connected delivery goals, also read goal_boundary from the quota should-run payload before choosing a step. It carries the registry's adapter status, allowed write scope, parent-approval scopes, guards, and stop condition. Treat it as the project-specific boundary contract so automation prompts can stay short instead of repeating long per-project protected-scope lists. When reading status or quota routing, use attention_queue.items and project_asset as current authority only when the item is project-asset-backed. If project_asset is absent or the source is legacy/raw fallback, do not infer owner, gate, or stop-condition authority from raw queue fields.

Set Up Recurring Heartbeats

When a user or controller wants a recurring Codex App heartbeat for a connected goal, prefer the generator instead of hand-copying the quota lifecycle:

loopx heartbeat-prompt --goal-id <STABLE_GOAL_ID>

The default generated body is thin when the target Codex agent can inspect LoopX state and CLI output itself. Passing --thin remains accepted and explicit:

loopx heartbeat-prompt --thin --goal-id <STABLE_GOAL_ID>

Use the compact body after reviewing the full generated contract when the installed prompt should carry more lifecycle detail inline:

loopx heartbeat-prompt --compact --goal-id <STABLE_GOAL_ID>

If the installed automation body still needs to be smaller, use the brief body:

loopx heartbeat-prompt --brief --goal-id <STABLE_GOAL_ID>

For a shared-control-plane goal with coordination.registered_agents, always include the registered identity and scope in the installed automation prompt:

loopx heartbeat-prompt --thin --goal-id <STABLE_GOAL_ID> \
  --agent-id <REGISTERED_AGENT_ID> \
  --agent-scope "<THIS_AGENT_SCOPE>"

Once agents are registered, an unscoped heartbeat-prompt call fails closed so stale automations surface an upgrade error instead of running without identity.

For connected goals, omit --active-state; the CLI resolves the active state from the registry goal state_file, which keeps installed automations from pinning a stale path. Pass --active-state <ACTIVE_GOAL_STATE_PATH> only for detached state files, migration checks, or compatibility tests.

Copy the generated task body into the Codex App heartbeat automation. The thin body is the installed default for trusted local workers: it keeps the automation prompt project-agnostic and tells Codex to re-read registry/global quota truth, active state, status/run history, repo state, and project signals on each wakeup. Use --full for the expanded audit source. The compact body is useful when context pressure matters but the installed prompt should still carry the quota, gate, blocker-push, recommendation, steering-audit, writeback, refresh, and spend lifecycle inline. The brief body keeps only preflight/guard, core invariants, and spend accounting in the installed prompt while delegating detailed branches back to the generated compact/full contracts. The generated guard and spend commands explicitly use the shared global registry so project heartbeats read the same operator gates and user todos as the dashboard, regardless of their current repo. Completed heartbeat delivery spends through quota spend-slot --source heartbeat --execute, not through a natural-language report. Quota slots are minute-granularity by default: minute heartbeats spend --slots 1, while coarser fixed-interval automations should spend the scheduler minutes consumed by that completed turn.

Keep project-specific behavior out of the automation prompt. Encode local differences in the project registry, .codex/goals/<goal-id>/ACTIVE_GOAL_STATE.md, adapter output, or narrow public/private boundary rules. If a lifecycle rule is useful across projects, update loopx heartbeat-prompt and its smoke contract rather than hand-editing one heartbeat automation. For delivery-specific boundaries, prefer the registry fields surfaced in quota should-run.goal_boundary; the automation prompt only needs to say to obey that payload and stop when useful work falls outside it.

When a LoopX client/prompt contract changes, update the matching smoke coverage in the same patch. Interface-budget and regression constraints belong in lightweight smoke scripts such as examples/control_plane/heartbeat-prompt-smoke.py, examples/control_plane/quota-plan-smoke.py, or examples/control_plane/quota-contract-smoke.py; heavier Codex CLI plus LoopX end-to-end checks should stay explicit or low-frequency instead of becoming the default heartbeat path.

The quota guard returns execution_obligation and heartbeat_recommendation. It also returns scheduler_hint, which controls the next wakeup cadence and external-loop unchanged-poll self-stop; this is scheduling policy, not delivery permission. Codex CLI TUI and Claude Code loops should run the final quota/replan check from scheduler_hint before applying their after_limit; if the guard changes or returns run_now, follow the new quota contract instead of stopping. Codex App heartbeat workers should search/use automation_update when available. If scheduler_hint.action=stop_until_explicit_resume and scheduler_hint.codex_app.host_action=pause_or_delete_current_heartbeat, call automation_update once to pause the current heartbeat (delete only when the host cannot pause), verify the host result, spend no quota, and end the turn. This terminal host action takes precedence over RRULE handling and requires no scheduler ACK. Otherwise use automation_update only when scheduler_hint.codex_app.stateful_backoff.apply_needed=true and scheduler_hint.codex_app.recommended_rrule is present. After a successful RRULE update, run loopx with scheduler_hint.codex_app.ack_hint.cli_args (normally quota scheduler-ack-current, which re-reads the latest scheduler hint instead of hand-copying short-lived reset tokens). Attempt the host update at most once per hint and turn. If it fails or times out, do not retry or ACK; run scheduler_hint.codex_app.failure_hint.cli_args once. That no-spend writeback records the failed target/observed-host pair so later heartbeats suppress the exact repeat until either value changes. Continue allowed delivery under the observed host cadence. If apply_needed=false but ack_needed=true, a matching host readback already proves the RRULE; skip automation_update and run the bound ack hint directly. LoopX owns reset/progression state and omits recommended_rrule when the desired RRULE is already applied. Cadence changes, reset-to-initial updates, final checks, and self-stop changes do not spend quota. For a uniquely matched active Codex App heartbeat, quota should-run automatically reconciles the installed RRULE with LoopX's ACK ledger. Treat stateful_backoff.host_observation.status=drift_detected as authoritative for cadence repair; a stale or premature ACK must not suppress apply_needed. When readback matches a reset RRULE that is not yet bound in scheduler state, the ack hint carries the exact reset token, identity signature, and CLI route; missing readback must not use this shortcut. This readback is cadence-only and never exposes the automation prompt or grants LoopX permission to edit Codex App files directly.

Read execution_obligation before deciding on a quiet no-op: heartbeat_recommendation.notify is only the user-notification policy, not an execution gate. If execution_obligation.must_attempt_work=true, attempt one bounded progress batch or segment even when notify=DONT_NOTIFY; a quiet no-op requires execution_obligation.must_attempt_work=false and no notify_user_on_open_todo=true blocker-push notification. New connected read-only goals should follow recommended_mode=run_first_read_only_map: run one real loopx read-only-map --goal-id <STABLE_GOAL_ID>, validate the saved read_only_project_map, spend exactly once after validation, then sync or refresh state if needed. Already mapped goals should follow recommended_mode=mapped_noop_if_unchanged: if there is no new instruction, owner evidence, agent todo, stale source, or safe handoff, return a quiet no-op without another dry-run, file edit, or quota spend.

The generated task body also carries a no-progress self-repair guard. More importantly, quota should-run may expose a hard autonomous_replan_obligation / execution_obligation.must_attempt_work=true contract when active state or public run history shows 2 consecutive stalled turns. quota_monitor_poll events are no-spend stall evidence for this detector. Obey that machine contract before another quiet no-op: run one bounded self-repair/replan batch through implementation, validation, and writeback when that boundary is clear, then spend once. Do not stop at the first tiny substep when the repair has an obvious validation boundary. Cancel or pause the heartbeat automation only when that repair path is itself stuck for 2 more eligible turns, explain the no-progress loop with NOTIFY, and skip quota spend for that self-cancel turn. The same generated task body also makes routine public commit, push, and PR creation autonomous after validation plus a clean public/private boundary scan. Do not reintroduce a user gate for public-safe publication itself. It also respects notify_user_on_open_todo=true: open user todos in focus-wait, waiting, or external-evidence lanes should become a compact blocker-push NOTIFY with at most three items, while skipping delivery work and quota spend for that blocker-push turn. If the payload includes open_todo_notification_policy=repeat_until_resolved, repeat that NOTIFY until the todo is done, deferred, or replaced. When the user confirms that an existing review or action already happened, write back that exact todo immediately: complete only with an explicit typed decision, otherwise supersede the stale gate without granting authority; then refresh state and rerun quota so a successor or autonomous replan can surface. When user_gate_notification_cooldown.notification_suppressed=true, preserve the pending gate but return quiet DONT_NOTIFY; the bounded reminder window or a material gate/host change reopens the notification. Other blocker-push cases may still be de-duplicated when the same blocker was already surfaced recently. Eligible monitor-only no-transition polls keep user todos visible in the payload but should stay quiet unless a material transition appears.

Keep the Codex App visible goal text short, for example 按 ACTIVE_GOAL_STATE.md，基于 LoopX 体系，推进项目. Do not use that short text as the automation body. Across projects, the automation body should be the same generated lifecycle prompt with only goal_id, active_state, and narrow project boundary rules changed. When a project appears to need a custom automation branch, treat that as a LoopX product gap first, not as a reason to paste one-off control logic into the scheduler.

Generate A Review Packet

When a project agent, controller thread, or local shell needs the current operator packet, prefer the CLI packet over asking the user to find a dashboard copy button:

loopx review-packet --goal-id <STABLE_GOAL_ID>

For machine-readable inspection, put the global format flag before the subcommand:

loopx --format json review-packet --goal-id <STABLE_GOAL_ID>

When the human/controller decision is already approved and the only remaining step is to relay the target-agent instruction, use the minimal handoff form:

loopx review-packet --goal-id <STABLE_GOAL_ID> --handoff-only

This command is read-only. It packages the current status into the same Review Packet shape as the dashboard; it does not append human reward, append an operator gate, refresh state, grant write-control, or authorize production actions. --handoff-only only strips the human decision wrapper from markdown output; JSON output returns a minimized handoff payload with handoff_text instead of the full operator packet. If the selected queue item is legacy/raw fallback rather than project-asset-backed, do not treat raw queue fields as owner, gate, or stop-condition authority.

Read the packet in order:

• 人只需判断: the user or controller decides in the dashboard/operator view or trusted local shell. A target project agent cannot self-approve this section.
• 用户本地 Gate 记录草稿: a local preview for the user/controller. The target project agent must not run this draft as its own command.
• 给项目 Agent: the executable handoff context only after the packet's forwarding condition is already satisfied. If its stop condition fires, stop and report the exact blocker instead of continuing.

Connect A New Project

1. Read the project goal document and inspect the repo narrowly.
2. Extract a stable goal_id, one-line objective, domain, authority sources, validation surfaces, first safe action, and public/private boundary.
3. Run connect from the project root. Prefer read-only until the goal doc explicitly authorizes mutation:

loopx connect \
  --goal-id <STABLE_GOAL_ID> \
  --objective "<OBJECTIVE_FROM_GOAL_DOC>" \
  --domain <DOMAIN> \
  --goal-doc <GOAL_DOC_PATH> \
  --adapter-kind read_only_project_map_v0 \
  --adapter-status connected-read-only

connect should create or update the local registry/state and auto-sync the public-safe entry into ~/.codex/loopx/registry.global.json.

One repository can host multiple peer-owned goals, such as delivery and a low-conflict validation lane. Run connect once per stable goal_id; keep one shared .loopx/registry.json, but use one active state per goal:

.codex/goals/<delivery-goal-id>/ACTIVE_GOAL_STATE.md
.codex/goals/<validation-goal-id>/ACTIVE_GOAL_STATE.md

Do not reuse one state_file for two goal ids. loopx registry treats that as a health error, and read-only-map checks the selected goal's own .codex/goals/<goal-id>/ directory so one healthy lane does not hide another lane's missing state.

If the goal state or registry contains private evidence, add .loopx/ and .codex/goals/ to that project's .gitignore.

For a generic read-only connection, create the first non-generic map run:

loopx read-only-map --goal-id <STABLE_GOAL_ID>

This reads registry metadata, the active state, and a bounded project-file inventory, then appends a read_only_project_map run. Use it before writing a project-specific adapter when the dashboard would otherwise stay on state_refreshed or connected_without_run.

For a planned high-complexity adapter, preview the same bounded map before controller opt-in:

loopx read-only-map --goal-id <STABLE_GOAL_ID> --dry-run

If the adapter status is planned, only the --dry-run preview is allowed and the result should include opt_in_required=true. Do not append a real map until the user or target controller has moved the adapter to read-only-map-ready, connected-read-only, or connected. Relay the returned residual_risks labels directly; do not invent a separate free-form risk summary.

When the user or target controller answers the opt-in gate, record that answer before handing the command to another project agent:

loopx operator-gate \
  --goal-id <STABLE_GOAL_ID> \
  --decision approve \
  --reason-summary "<PUBLIC_SAFE_CHINESE_REASON>" \
  --dry-run

Use approve, reject, or defer. The dry-run writes nothing; the real append creates an operator_gate_* compact run so loopx status and the dashboard can tell whether the project agent may run the approved command. This is not a human reward signal and does not grant write-control.

Refresh State After Non-Adapter Work

If the agent updated ACTIVE_GOAL_STATE.md, a progress ledger, a planning doc, or external coordination state without producing a new adapter run, append a state-only refresh:

loopx refresh-state --goal-id <STABLE_GOAL_ID> --agent-id <REGISTERED_AGENT_ID>

For multi-agent goals, keep the same --agent-id envelope that passed quota should-run. This default is an agent-lane refresh. To update the goal-level route or durable ## Next Action, any registered peer may add --progress-scope goal.

If that refresh records a validated progress artifact rather than a pure state-only note, include a public-safe classification and explicit delivery hints so status, review packets, and quota guards do not infer scale/outcome from the classification name:

loopx refresh-state \
  --goal-id <STABLE_GOAL_ID> \
  --classification <PUBLIC_SAFE_PROGRESS_CLASSIFICATION> \
  --delivery-batch-scale multi_surface \
  --delivery-outcome outcome_progress \
  --agent-id <REGISTERED_AGENT_ID> \
  --progress-scope goal

If the current run may write local LoopX state but its runtime boundary forbids configured external sink writes, keep explore_graph.enabled unchanged and add --suppress-external-sinks. This preserves canonical local graph projection, records the run-scoped authorization boundary, and leaves sink digests pending for a later authorized refresh. Do not toggle the goal-level Graph setting as a one-off workaround for an external-write boundary.

Use delivery_outcome as a machine enum, not as prose:

• surface_only: docs, contracts, smokes, setup, or preparation moved, but the primary product/case result did not.
• outcome_gap: the run should have advanced the primary result but ended with a concrete blocker or missing outcome.
• outcome_progress: primary result evidence advanced materially, but the selected stage is not fully complete.
• primary_goal_outcome: the selected stage's primary result is complete, validated, and written back.

Do not rely on classification names such as *_contract_v0_delivered to carry this meaning. classification is a human/history label; delivery_outcome is the control-plane signal consumed by quota, status, and review packets.

This fixes stale dashboards where the latest run still shows an old ready_for_controller_opt_in or similar state. It also auto-syncs the project entry into the global registry. If you do not pass --recommended-action, the refresh run should publish the first local-control-plane item from ## Next Action as the compact dashboard action, including wrapped continuation lines. recommended_action may include private/local routing references needed by the individual operator, but must not include credentials, auth headers, or inline secrets; shareable/public projections are responsible for redaction.

For complex projects, do not pack a whole user reading queue into ## Next Action. Keep the first Next Action item as one routing sentence, then use the CLI to write explicit checkbox sections instead of hand-editing section names:

loopx todo add \
  --goal-id <STABLE_GOAL_ID> \
  --role user \
  --text "Read the short review packet before approving delivery."

loopx todo add \
  --goal-id <STABLE_GOAL_ID> \
  --role agent \
  --text "Build the next read-only worksheet after the user decision is recorded."

The CLI creates the canonical section when needed and avoids duplicate exact todo text. The resulting Markdown shape is:

## User Todo / Owner Review Reading Queue

- [ ] Read the short review packet.
- [ ] Record the owner decision in the worksheet.

## Agent Todo

- [ ] Build the next read-only worksheet after the user decision is recorded.

loopx status lifts those sections into user_todos and agent_todos. The dashboard uses user_todos for the first-screen human checklist; project agents should read agent_todos only after health, operator gates, evidence, and quota allow execution.

For non-trivial feature work, prefer todo succession over extra lifecycle states. When a slice merges or validates, complete the current todo only after creating the next concrete agent/user todo for rollout, product-path audit, docs, telemetry, benchmark proof, or operator decision; if there is truly no follow-up, write a compact no-follow-up rationale in the completion note. An open feature PR that is waiting for ordinary human review does not by itself block further project work. Complete the feature slice with its validated PR evidence, derive the review reminder with --next-user-todo ... and --next-user-task-class user_action, and keep a runnable agent successor. Add a separate continuous_monitor for PR lifecycle readback. Use user_gate only for an exact authority boundary such as merging an aggregate experiment branch into main, release, benchmark launch, credentials, or protected production action. A stable experiment integration branch may collect feature PRs from isolated worktrees; keep the aggregate PR to main as the final review gate. When the next agent slice is not yet known, keep the bound user_action visible without converting it into a gate. If bounded no-progress evidence accumulates while the agent frontier is empty, follow autonomous_replan_required: create and claim a concrete runnable agent todo, then record runnable_todo_set. Only authoritative terminal-closure evidence may replace that todo writeback with explicit no-follow-up. successor_todo_ids records lineage only: linking successors does not suspend an open parent. When splitting a parent into explicit successors, decide whether the parent still has an independent immediate action. If it does not, explicitly defer it with a supported resume_when or complete it; do not infer aggregate semantics from successor links alone. Treat parent_successor_advisory in the todo update response as the machine-readable authoring reminder for this decision, not as a new persisted lifecycle state.

Record Human Reward

When the user gives a clear reward judgment for an exact run, first validate the overlay and active-state writeback:

loopx reward \
  --goal-id <STABLE_GOAL_ID> \
  --run-generated-at <RUN_GENERATED_AT> \
  --decision <DECISION_LABEL> \
  --reward positive \
  --reason-summary "<PUBLIC_SAFE_CHINESE_REASON>" \
  --follow-up "<PUBLIC_SAFE_NEXT_ACTION>" \
  --write-active-state-summary \
  --dry-run

Only after the user has explicitly approved recording the reward, rerun without --dry-run. The durable source of truth is still the run-bound human_reward overlay. The active-state writeback is a Progress Ledger summary for future agents; project agents should read the reward through the returned project_agent_visibility.history_command.

Multi-Project Status

Inside a project:

loopx status

To focus the status projection on one goal while preserving global health fields, pass the goal id:

loopx --format json status --goal-id <STABLE_GOAL_ID>

Outside a project, loopx status should fall back to:

~/.codex/loopx/registry.global.json

Use explicit sync only for diagnosis or recovery:

loopx sync-global

If status shows unregistered_runtime_goal:

• If the project is active, run loopx sync-global or reconnect from that project's local registry.
• If the runtime record is obsolete, preview cleanup with loopx archive-runtime --goal-id <GOAL_ID> and only execute cleanup when that is clearly intended.

Validation

After connect or refresh, run the smallest useful set:

loopx registry
loopx status
loopx check --scan-path <PUBLIC_SAFE_FILE_OR_DIR>

For multi-project UI updates, refresh the dashboard status JSON from the global registry:

loopx --registry "$HOME/.codex/loopx/registry.global.json" \
  --format json status > <dashboard>/public/status.local.json

Reporting

Report in Chinese when the user is reviewing:

• changed files and whether they are public or local-private;
• validation commands and results;
• how the goal appears in dashboard or attention queue;
• the next safe action;
• any missing gates before decision-advisor or write-controller behavior.

Never include credentials, private docs, raw internal links, production task ids, or raw local evidence in public repo docs or examples.