skills/orgx-runtime-reporting/SKILL.md

---
name: orgx-runtime-reporting
description: Use when a Codex execution should report progress, artifacts, blockers, or completion state back to OrgX during a live task.
---

# OrgX Runtime Reporting

Use this skill when Codex should keep OrgX updated during execution.

## Reporting contract

There are two reporting paths:

- **Active path:** call OrgX MCP tools during the work when you know the
  initiative, task, decision, blocker, or artifact context.
- **Chronicle readout:** for operator reporting, call
  `get_operator_chronicle` first when available and present
  `reportingNarrative.briefMarkdown` before drilling into individual entities.
- **Stale-client fallback:** if bootstrap or docs advertise
  `get_operator_chronicle` but the current AI client session has not refreshed
  its callable tool list, immediately call `orgx_recommend` or
  `_orgx_recommend` with `mode: "morning_brief"` and present the returned
  `reportingNarrative.briefMarkdown`. Do not ask the user to reconnect before
  giving the report.
- **Passive backstop:** Codex runtime hooks installed by `orgx-wizard hooks
  install` record compact session events and run summary-only local Work Graph
  reconciliation on `Stop`.

Do not treat hook presence as a substitute for intentional OrgX writes. Hooks
answer whether OrgX was used and can write a local report automatically; MCP
calls, or an explicitly opted-in successful Work Graph post, make the work
durable in OrgX while the session is still fresh.

## Workflow

1. Resolve available IDs from args, env, or the current OrgX context:
- `ORGX_INITIATIVE_ID`
- `ORGX_WORKSTREAM_ID`
- `ORGX_TASK_ID`
- `ORGX_RUN_ID`
- `ORGX_CORRELATION_ID`

2. For reporting questions, retrieve the operator chronicle:
- Use `get_operator_chronicle` with `period: "30d"` for broad clarity when it
  is callable in the current client.
- Use `period: "day"` or `period: "week"` when the user asks for yesterday or
  this week.
- If `get_operator_chronicle` is not callable in the current client, use the
  existing `orgx_recommend` / `_orgx_recommend` fallback with
  `mode: "morning_brief"` and the broadest supported period. Treat the direct
  tool as preferred, but do not block on client schema refresh.
- Lead with `reportingNarrative.briefMarkdown`, then call out gaps and the
  next action.

3. Emit activity at meaningful milestones:
- `intent`
- `execution`
- `handoff`
- `blocked`
- `completed`

4. Register proof of work:
- When you produce a file, diff, document, screenshot, or report, register it as an artifact with a concrete summary.

5. Handle blockers structurally:
- If judgment is required, request a decision with explicit options.
- If context is missing, report the exact missing dependency.

6. Close execution cleanly:
- When the task is complete and verified, emit completion activity and update entity state if the task ID is available.

7. If no OrgX IDs are available:
- Continue the work, but make the final response easy for the hook reconciler to
  classify: name decisions, artifacts, blockers, next actions, and verification.
- Do not claim OrgX was updated unless an MCP tool or API call actually
  succeeded.

8. Preserve Work Graph continuity:
- When a Work Graph report is generated, include its `work_graph_fingerprint`
  and `signup_hydration.hydration_key` in summaries or artifacts that are safe
  to store.
- Automatic Stop-hook reconciliation writes the latest local report to
  `~/.config/useorgx/wizard/hooks/reports/latest-work-graph-report.json`.
- Stop-hook posting requires `ORGX_HOOK_RECONCILE_POST=true` or
  `ORGX_WIZARD_HOOK_RECONCILE_POST=true` plus `ORGX_API_KEY`.
- Treat the fingerprint as the durable claim key that lets OrgX hydrate
  pre-signup audit value into a user's future workspace.
- Never derive the fingerprint from secrets or raw transcripts that would need
  to leave the local machine.

## Quality bar

- Never post empty status updates.
- Messages must be evidence-based and specific.
- Include OrgX IDs whenever available.
- Use `source_client=codex`.
- Preserve secrets: never emit tokens, cookies, API keys, or storage state into
  activity, retro, hook summaries, or final reports.