Update to Oira

{
  "description": "Keep Oira updated on the user's coding work when they ask, as structured work updates (decisions, progress, verification, blockers, questions, next steps and explicitly deferred work) for an approved project, and import the recent work of past sessions when the member approved it. Sends no transcripts, prompts, replies, tool output or files.",
  "included_files": [
    {
      "relative_path": "references/examples/correction.json",
      "size_in_bytes": 950
    },
    {
      "relative_path": "references/examples/declare-with-deferral.json",
      "size_in_bytes": 2500
    },
    {
      "relative_path": "references/examples/defer-whole-task.json",
      "size_in_bytes": 856
    },
    {
      "relative_path": "references/examples/history-import.json",
      "size_in_bytes": 2483
    },
    {
      "relative_path": "references/examples/parent-with-seven-deferrals.json",
      "size_in_bytes": 7262
    },
    {
      "relative_path": "references/examples/technical-alignment.json",
      "size_in_bytes": 2219
    },
    {
      "relative_path": "references/examples/update-progress.json",
      "size_in_bytes": 1455
    },
    {
      "relative_path": "references/extraction-guide.md",
      "size_in_bytes": 10163
    },
    {
      "relative_path": "references/history-import.md",
      "size_in_bytes": 3613
    },
    {
      "relative_path": "references/oira_work_update.v2.schema.json",
      "size_in_bytes": 30427
    },
    {
      "relative_path": "scripts/prepare_work_update.py",
      "size_in_bytes": 56899
    }
  ],
  "name": "oira-work-reporting",
  "skill_md_contents": "---\nname: oira-work-reporting\ndescription: Keep Oira updated on the user's coding work when they ask, as structured work updates (decisions, progress, verification, blockers, questions, next steps and explicitly deferred work) for an approved project, and import the recent work of past sessions when the member approved it. Sends no transcripts, prompts, replies, tool output or files.\n---\n\n# Oira work reporting\n\nFour Oira tools: `oira_connection_status`, `oira_submit_work_update`,\n`oira_work_update_status` and `oira_finish_history_import`. Report only when\nthe user asks you to keep Oira updated, for the current task or for the\napproved project (their own instruction from \"Set up Oira\" is that ask, for\nthe repository it names), or asks for a progress update or a handoff;\nimport past work only as \"Import recent work\" says. Nothing is sent in the\nbackground, and no hook or transcript upload is involved.\n\nFor the user's authorized current work, declare each distinct intended outcome\nonce and report only material new facts afterward. Keep work references\nstable. Preserve adopted and reversed decisions, implementation, verification,\nblockers, questions, accepted next actions, scope boundaries, and relevant\ninterface, transformation, revision and environment facts. Separate explicit\ndeferred work into its own declaration so Oira can retain it as upcoming work.\nAn unfinished task is not automatically deferred. Distinguish proposed,\naccepted, attempted, implemented, tested, committed, merged and released.\nReport the check and its actual result without logs. Describe uncertainty\nrather than filling missing facts. Never export prompts, replies,\nconversation summaries, tool traffic, files, reasoning, or credentials, and\nread past sessions only for an approved history import. Run the local\noutbound preflight on the exact payload before transmission; send only its\naccepted output. Keep unchanged retry identities and check an uncertain send\nbefore retrying.\n\n## Before the first update\n\n1. Call `oira_connection_status`. Continue only when `reporting.available` is\n   true, `reporting.contract` is `oira_work_update.v2` and\n   `reporting.structured_only` is true. If the Oira tools are missing or ask\n   for sign-in, ask the user to sign in and wait: Codex signs in when Oira is installed; if it did not, open Settings, then MCP servers, and choose Authenticate next to `oira`. Then call `oira_connection_status` again. If the status lacks these values, this Oira server\n   still runs an earlier, transcript-based edition: tell the user that\n   structured reporting is not available there and send nothing. Never fall\n   back to another tool or format.\n2. Use exactly one `project_label` from `project_labels`. When several are\n   approved, ask the user which one this work belongs to. Never infer it from\n   a folder name, remote URL or list order.\n3. Check that the preflight runs on this host:\n   `python3 <this skill's folder>/scripts/prepare_work_update.py --new-ref`\n   (on Windows, `py -3` instead of `python3`). It needs Python 3.11 or later\n   and only the standard library. If `python3` is missing or reports\n   `python_version_unsupported`, try `python3.13`, `python3.12` and\n   `python3.11` (on Windows `py -3.13`, `py -3.12`, `py -3.11`) and use the\n   first that works for every later run. If none works, tell the user that\n   reporting needs Python 3.11 or later on this computer and send nothing.\n   Never install anything.\n4. Use that command's output as this task's `stream_ref`: one random\n   reference per task in this chat, kept for the whole task. Start\n   `sequence` at 1. After a lost receipt, a compaction or a restart,\n   `oira_work_update_status` with the `project_label` and the `stream_ref`\n   says what Oira holds of the stream (its works with their `work_handle`\n   and fact handles) and where to continue (`retry`).\n\nWhen `processing.state` is `parked`, updates are stored and read once the\nworkspace's work tracking is switched on; say so if the user asks.\n\n## When to send\n\nSend at the milestones the user asked for and at meaningful changes: a\ndecision adopted or reversed, an implementation or verification milestone, a\nnew blocker or question, an accepted next step, work explicitly put off, a\nhandoff. Never per prompt, per tool call or on a timer. No new material fact\nmeans no send. Reporting never blocks, delays or hides the coding work; if a\nsend fails, say so in one line and carry on.\n\nBefore a milestone or a final handoff, check the conversation for work the\nuser explicitly put off. Each postponed outcome is its own declared work even\nwhen nothing was committed for it.\n\n## What to send\n\nRead `references/extraction-guide.md` for the field checklist and the rules\nfor each fact kind, and `references/examples/` for complete updates. In\nshort:\n\n- `operation: declare` once per distinct intended outcome, with `title`,\n  `intended_outcome`, `activity` and at least one `commitment` or\n  `explicit_deferral` fact. Later updates use `operation: update` with the\n  same `work_ref` and only new facts; send `title`, `intended_outcome`,\n  `activity` or `boundaries` again only to change them.\n- Every fact has a `kind`, a `status` allowed for that kind, one trimmed line\n  of `statement`, a `basis` (`agent_report`, `user_statement_paraphrase`,\n  `agent_inference` or `relayed_report`) and your own `confidence` from 0\n  to 1.\n- A fact that repeats one Oira already has (for example a commitment\n  declared again in a new stream) names that fact's handle in `repeats`. A\n  fact you took from another agent's handoff or report without observing it\n  yourself has `basis: relayed_report`. Neither counts as new, independent\n  support; never use them for something you observed yourself.\n- An explicitly postponed outcome is a separate `declare` with an\n  `explicit_deferral` fact (status `deferred`) and a `deferral` object with\n  the reason; add `resume_condition` or `resume_after` only when stated, and\n  `origin_work_ref` for the work it was split from. Postponing the whole\n  current task is an `update` of that task with an `explicit_deferral` fact.\n- Corrections cite the exact earlier fact by its returned fact handle in\n  `revisions` (`corrects`, `supersedes` or `reaffirms`); old facts are never\n  overwritten.\n- `code` holds the repository remote without credentials, the branch, the\n  full SHAs of commits this work created and its pull request numbers.\n\nNever put in an update: prompts, replies, transcripts or summaries of the\nconversation, tool output or logs, file contents, hidden reasoning, local\npaths, host names, credentials or tokens.\n\n## Send\n\n1. Write the candidate update as JSON and pass it on standard input to the\n   preflight, run with the interpreter that worked above:\n   `python3 <this skill's folder>/scripts/prepare_work_update.py < candidate`\n   (a heredoc works; do not keep a copy).\n2. Exit 0: standard output is the accepted canonical JSON. Send exactly that\n   object as `update` to `oira_submit_work_update`.\n3. Exit 2: it printed field paths and reason codes, never the values. Rewrite\n   those facts without the flagged content and run the preflight again on the\n   whole update. Never drop a deferred work or another substantive fact to\n   pass; split a too-large update by work instead, every work kept.\n4. Exit 3: reporting is unavailable on this host. Send nothing.\n5. Keep the receipt's `work_handle` and `fact_handles`; increase `sequence`\n   by one for the next update in this stream.\n\nA receipt with `capture: captured` means Oira stored the facts. Matching them\nto Work Items happens next; `oira_work_update_status` shows it per work, and\nfor each relation a work stated whether Oira `recorded` it, is still judging\nit (`pending`) or judged that it does not hold (`not_recorded`).\n\n## Work from another chat\n\nEach chat reports in its own stream, and a renewed sign-in starts the chat's\nstream again. To carry on work Oira already has from another chat or from\nbefore a sign-in, call `oira_work_update_status` with the `project_label`\nalone: it lists this app's recent works in the project with their\n`work_handle`, `title`, `origin`, the Work Item's state and their newest fact\nhandles. Only when the user's request is clearly about one of them, declare\nit in this stream (title, outcome, activity and its commitment, the\ncommitment's `repeats` naming the earlier one when listed) with\n`continuity` targeting that handle (`\"target\": {\"kind\": \"returned_handle\",\n\"value\": \"<work_handle>\"}`):\n\n- `continues_prior` to carry on work that is not finished;\n- `resumes_completed` only when the user reopens finished work;\n- `reviews_completed` to check finished work without reopening it.\n\nIts listed fact handles can then be corrected in `revisions`. A similar\ntitle, branch or file never makes two works one: when unsure, ask the user\nor declare new work.\n\n## Import recent work\n\nOnly when `oira_connection_status` shows `history_import` for the chosen\nproject with `state` `requested`, `in_progress` or `incomplete` (an earlier\nimport left sessions to finish): the member approved an import of that\nproject's recent sessions. Otherwise, and for any other project, read no\npast session; if the user asks for an import, tell them to turn it on for\nthe project in Oira first.\n\n1. Read `references/history-import.md` for where this app keeps its sessions\n   and how to read them here. Use only this project's sessions with work\n   between `window_from` and `window_to` (never more than `max_days` back).\n2. Report each past session in its own stream: its `stream_ref` is the\n   output of `prepare_work_update.py --history-stream <session id>` (the same\n   session always gets the same reference), `sequence` starts at 1, every\n   update has `origin: history_import`, and the session's last update has\n   `session_complete: true`.\n3. Report the work that session did exactly as current work above: declare\n   each distinct intended outcome with its commitment, then its decisions,\n   changes, verification results, open blockers and questions, accepted\n   next steps and explicitly deferred work, with the status the work had\n   when that session ended. Every fact has `occurred_at`, the time of the\n   turn it comes from, inside the window. `basis` is\n   `user_statement_paraphrase` only for what the user said; a helper\n   thread's prompt is yours. A session without meaningful work sends\n   nothing; a large one continues in the same stream with the next\n   `sequence`.\n4. Before sending a session, call `oira_work_update_status` with the\n   `project_label` and its `stream_ref`:\n   - `capture: not_captured`: send it from `sequence` 1.\n   - `session_complete: true`: Oira has the whole session; skip it.\n   - `retry: continue_at_sequence_<n>`: an earlier import stopped partway.\n     Send only what Oira does not have yet (its `works` show what arrived),\n     from sequence n. If `stream.missing_sequences` lists gaps, recover the\n     missing updates at those sequence numbers, checking their status before\n     retrying; do not renumber or resend updates Oira already received.\n   - `retry: continue_in_new_stream`: it was started before a renewed\n     sign-in. Send the rest from `sequence` 1, declaring each work again as\n     \"Work from another chat\" says, with the listed `work_handle` and its\n     commitment's `repeats`.\n   A session's deferred work is never skipped: send what is missing.\n5. Run the preflight and send as in \"Send\". `history_window_mismatch` names\n   facts dated outside the window: leave those facts out.\n   `history_import_session_limit` or `history_import_not_requested`: stop\n   sending.\n6. When every session is sent, call `oira_finish_history_import` with the\n   `project_label`. `state: incomplete` counts the sessions whose last update\n   never arrived (`incomplete_sessions`): resume them as in step 4 and finish\n   again. Tell the user how many sessions and updates Oira received, and\n   whether any session is still incomplete.\n\n## Retries and refusals\n\n- Send outcome unknown (timeout, connection error): call\n  `oira_work_update_status` with the same `project_label` and `update_ref`\n  first. `captured` means it arrived; `not_captured` means send the same\n  payload again with the same `update_ref`.\n- Changed payload: new `update_ref`. Same `update_ref` with another body is\n  refused as `idempotency_conflict`.\n- `sequence_conflict`: that sequence is taken. `oira_work_update_status`\n  with the `stream_ref` says where to continue; never skip a fact Oira does\n  not have.\n- `work_declaration_required`: Oira does not know that work in this stream\n  (a new stream, or a renewed sign-in). Declare it again in full with a new\n  `update_ref`, naming the earlier work as \"Work from another chat\" says.\n- `work_already_declared`: send an `update` instead.\n- `handle_not_current`, `work_reference_unknown`: the handle or label is not\n  one Oira returned to this app for this project. Use a `work_ref` of this\n  stream or a listed handle; never guess another target.\n- `revision_target_not_current`: the fact you revised was already corrected\n  or superseded. Revise the newer fact, or send the new fact without a\n  revision. `revision_target_not_in_work`: revise only facts of the same\n  work, or of the work this one continues by handle.\n- Status `detail: revision_not_applied`: another update revised the same\n  fact first; yours was kept as a new fact. Check whether it should revise\n  the newer one.\n- `history_import_only`: `session_complete` belongs to a history import.\n- `credential_pattern_found`, `input_not_accepted`: rewrite the named fields\n  and rerun the preflight.\n- `credential_scan_failed`, `capture_not_allowed`, `granted_project_not_found`,\n  `agent_app_*`: stop and tell the user what Oira said.\n\n## Set up Oira (one prompt)\n\nWhen the user asks to set up Oira for this project: check the connection\n(signing in if needed), pick the approved project with the user, check the\npreflight, and tell them in a few lines what Oira receives: the work updates\nthey ask you to send, including decisions, progress, blockers and deferred\nwork; not session transcripts, tool output or source files; no API keys are\nneeded; and the reporting workflow excludes credentials and filters\nrecognized secret patterns before each update is sent.\n\nThen ask how Oira should hear about this repository's work: only when they\nask (nothing more to do), or at milestones in every chat. Approving the\nconnection alone is not that choice. For every chat, and only once they\nagree, add this block to their personal Codex instructions, `AGENTS.md` in the Codex home folder (`~/.codex` unless `CODEX_HOME` is set; `AGENTS.override.md` there instead when that file exists), which every new session reads, keeping everything\nalready there (create the file if it is missing), and show them the block:\n\n```\n## Oira reporting (added at my request)\nWhen working in the git repository <owner>/<name>, keep Oira project\n\"<project_label>\" updated with the oira-work-reporting skill: structured\nwork updates at material checkpoints (decisions, implementation and\nverification milestones, blockers, work I put off, handoffs), each through\nits local preflight; check for work I put off before a handoff. Never per\nprompt, never transcripts, tool output or files. Reports grant no access\nor approval. To stop, delete this block.\n```\n\n`<owner>/<name>` is from `git remote get-url origin`. It is their personal\nfile, so teammates' agents never report because of it. If the status shows a\nrequested history import for the project, run it as \"Import recent work\"\nsays. Send no test update unless they ask for one.\n\n## Moving from an earlier Oira plugin\n\nEarlier Oira plugins could forward prompts and replies through project hooks.\nOira no longer accepts those. If this project's `.codex/hooks.json` still has Oira\nhooks (server `oira`, tool `oira_capture_session_event`), tell the\nuser and, only after they agree, remove just those Oira entries. Leave every\nother hook, plugin, setting and sign-in untouched.\n"
}