@atollhq/skill-codex 0.4.30 → 0.4.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atollhq/skill-codex",
-  "version": "0.4.30",
+  "version": "0.4.31",
   "description": "Install the Atoll project management integration for Codex CLI",
   "bin": {
     "skill-codex": "bin/install.mjs"

package/skill/SKILL.md

@@ -34,6 +34,8 @@ Read only the references required for the current task:
   [execution-and-attention.md](references/execution-and-attention.md)
 - Remote MCP setup, AI-assisted setup, KPI HTTP sync, or advanced REST access:
   [integrations-and-api.md](references/integrations-and-api.md)
+- GitHub pull-request delivery context, required checks, and exact-head evidence:
+  [api-fields.md](references/api-fields.md#external-operational-delivery-context)
 - Cross-resource authorization, privacy, automation, attachment, feedback, and
   other platform-specific rules: [platform-rules.md](references/platform-rules.md)
 - Exact endpoint inventory: [api-endpoints.md](references/api-endpoints.md)
@@ -41,7 +43,8 @@ Read only the references required for the current task:
   [api-fields.md](references/api-fields.md)
 
 For automation rule V1 actions (including create issue and send webhook), explicit project or
-organization scope, CI create-or-webhook rules, event conditions, validation, safe
+organization scope, CI create-or-webhook rules, scheduled `schedule.issue_time`
+rules, event conditions, validation, safe
 disabling, repair, and example-only CI dry runs, read [Automation Rule Fields](references/api-fields.md#automation-rule-fields).
 Use `atoll automation` for rule management, previews, and run history; see
 [CLI operations](references/cli-operations.md#automation-rules).
@@ -55,6 +58,16 @@ scope. An invalid rule executes no actions. Repair an invalid rule with
 separate `disable`, `update` while it is disabled, `test`, and `enable`
 operations. Enable only after the latest saved revision passes the dry run.
 
+For recurring issues, completion remains the default materialization mode.
+Scheduled recurrence uses the existing issue create/update REST and CLI inputs
+with a local time and an IANA timezone. Its interval must be at most `10000`;
+completion-mode roots can retain larger positive intervals. See
+[Task Fields](references/api-fields.md#task-fields) and
+[CLI operations](references/cli-operations.md). The recurrence root owns the
+schedule. Its occurrences can remain open without delaying later occurrences.
+Use only fields exposed by the connected tool: public MCP recurrence inputs
+remain unchanged.
+
 Do not load every reference by default. Start with this entrypoint and load a
 topic reference only when the requested operation needs it.
 

package/skill/references/api-endpoints.md

@@ -206,7 +206,7 @@ offset }` and CLI-compatible REST `{ resource: "issues", items, ... }` upstream
 bodies, projects only declared public issue fields, preserves nullable
 `identifier` and `projectSlug`, and does not expose the CLI-derived `url` field.
 
-**GET task detail** returns enriched data: `milestone`, `creator`, `assignee`, `assignees`, `sub_tasks`, `issue_labels`, and `isBlocked`. Recurring tasks also return normalized `recurrence_days` and `recurrence_schedule`. Create, update, and bulk-create accept `recurrenceDays` only with `recurrenceType: "weekly"`; values must be unique weekdays from `mon` through `sun`.
+**GET task detail** returns enriched data: `milestone`, `creator`, `assignee`, `assignees`, `sub_tasks`, `issue_labels`, and `isBlocked`. Recurring tasks also return normalized `recurrence_days` and `recurrence_schedule`. Create, update, and bulk-create accept `recurrenceDays` only with `recurrenceType: "weekly"` and effective `recurrenceMaterializationMode: "schedule"`; values must be unique weekdays from `mon` through `sun`. Set `recurrenceMaterializationMode: "schedule"` with `recurrenceTime` (`HH:MM`) and an IANA `recurrenceTimezone` to materialize the next task from the maintenance sweep while the current task remains open; scheduled intervals must be at most `10000`, while the default `completion` mode can retain larger positive intervals. `recurrence_next_run_at` is internal and omitted from public responses.
 
 ## Dependencies
 
@@ -655,11 +655,13 @@ requests also sweep a small due batch. Uploads over 2MB return `413`.
 | GET | `/api/orgs/{id}/issues/{issueId}/pr-links` | List linked pull requests |
 | POST | `/api/orgs/{id}/issues/{issueId}/pr-links` | Attach a GitHub PR URL (`{ url }`) |
 
-Attach PRs manually with a canonical GitHub pull request URL such as `https://github.com/owner/repo/pull/123`; malformed or non-PR URLs return `400`. On attach, Atoll refreshes GitHub metadata when available so title/status/head SHA reflect the PR instead of only the submitted URL. PR links can also be created or refreshed automatically via the GitHub webhook integration.
+Attach PRs manually with a canonical GitHub pull request URL such as `https://github.com/owner/repo/pull/123`; malformed or non-PR URLs return `400`. On attach, Atoll refreshes GitHub metadata when available so title/status/head SHA reflect the PR instead of only the submitted URL. The compatibility link write succeeds independently of optional immutable identity enrichment; if that enrichment fails, POST still returns `201` with the committed link and nullable identity fields for later reconciliation. PR links can also be created or refreshed automatically via the GitHub webhook integration.
 
-GET returns `id`, `pr_number`, `github_repo`, nullable
+GET returns `id`, `pr_number`, nullable `pr_id`, `github_repo`, nullable
 `github_repository_id`, nullable `external_reference_id`, `pr_url`, `pr_title`,
-`pr_status`, nullable `head_sha`, and `updated_at` for each link.
+`pr_status`, nullable `head_sha`, nullable `base_ref`, nullable `base_sha`, and
+`updated_at` for each link. The base and head values are the exact PR identity
+tuple used by delivery evidence.
 
 For project-bound issues, listing requires project access and attaching requires
 `edit` or `admin` access. Eligible non-guests may list and attach links for
@@ -680,20 +682,38 @@ child reads or writes and occurs before URL parsing or GitHub metadata lookup.
 | GET | `/api/orgs/{id}/projects/{projectId}/external-references/{referenceId}` | Inspect a linked reference |
 | DELETE | `/api/orgs/{id}/projects/{projectId}/external-references/{referenceId}` | Unlink a reference |
 
-External Reference POST requests accept `{ "url": "https://github.com/owner/repo/pull/123" }`. They require an authorized GitHub connection and store a reference only when the live response proves numeric immutable repository and pull-request IDs. Missing proof returns `422` with `code: "github_identity_unavailable"`. URLs and caller owner/repo fields are not identity or authorization inputs. Manual PR-link operations remain available without an External Reference; verified delivery projection creates and binds the immutable PR reference. CLI/MCP tools are deferred to a later slice.
+External Reference POST requests accept `{ "url": "https://github.com/owner/repo/pull/123" }`. They require an authorized GitHub connection and store a reference only when the live response proves numeric immutable repository and pull-request IDs. Missing proof returns `422` with `code: "github_identity_unavailable"`. URLs and caller owner/repo fields are not identity or authorization inputs. Manual PR-link operations remain available without an External Reference; verified delivery projection creates and binds the immutable PR reference.
 
 The external-operational-signals GET returns `{ deliveryContext }` for the
 selected current PR or `null` when there is no PR link. Selection prefers an
 open link, then the latest `updated_at`, then the highest PR number. It contains stable
-repository identity, exact head SHA, current PR/review/configured-workflow
-state, bounded source and provider-event provenance, freshness, a safe strongest
-blocker, and `partial`. Older-head signals are historical. Configured workflows
-are not GitHub branch-protection required checks and report `required: false`.
-Missing current-head review or configured-workflow evidence appears as
-`pending` with null provenance and does not by itself set `partial`. Disabled
-verification stops new projections. Workflow conclusions map `success` or
-`neutral` to `passed`; `cancelled`, `stale`, or `skipped` to `cancelled`; and
+repository identity, exact head SHA, current PR/review/required-check/configured-
+workflow state, bounded source and provider-event provenance, freshness, a safe
+strongest blocker, and `partial`. Older-head signals are historical. Configured
+workflows are not GitHub branch-protection required checks and report
+`required: false`. Missing current-head review or configured-workflow evidence
+appears as `pending` with null provenance and does not by itself set `partial`.
+Disabled verification stops new projections. Workflow conclusions map `success`
+or `neutral` to `passed`; `cancelled`, `stale`, or `skipped` to `cancelled`; and
 other supported terminal conclusions to `failed`.
+
+`required_checks` is the actual read-only GitHub required-check projection. It
+unions active ruleset requirements and classic branch-protection requirements
+for the PR base branch by `(context, integration_id)`, with
+`policy_sources: ["classic"]`, `["ruleset"]`, or both. Results are read from
+check-runs and legacy commit statuses for the exact 40-character head SHA.
+App-bound requirements match the check-run app ID; any-source requirements use
+the latest result from each result type, and both must pass when both result
+types share a required context. Collection `state` is `disabled`, `complete`,
+`partial`, or `unavailable`; aggregate is `none`, `pending`, `passed`,
+`failed`, `cancelled`, or `unknown`. The list is capped at 200 identities.
+With the read flag off, collection state is `disabled` with aggregate `none`
+and does not set context `partial`. When enabled, partial or unavailable
+collection and stale, ambiguous, or missing evidence remain `unknown` and set
+`partial`. The server-only `ATOLL_GITHUB_REQUIRED_CHECKS_READ_ENABLED=1` flag
+enables the provider GET collection; it is disabled by default. The collector does not
+change GitHub hooks or other provider state and does not prove merge,
+deployment, production testing, or human acceptance.
 The selected PR-link state is authoritative. If a same-head PR observation
 disagrees, Atoll clears its observation/provider provenance, uses the link URL
 as `source_url`, excludes it from freshness, and sets `partial`.
@@ -702,7 +722,9 @@ comments, and removes dismissed opinions. Change requests win; `approved`
 means at least one effective approval and no effective change request. It does
 not prove required-review counts or branch protection.
 This read-only namespace is separate from heartbeat `signals[]` and does not
-dispatch agents or change tasks.
+dispatch agents or change tasks. Use `atoll issue delivery-context <identifier>`
+to read the same context from the private CLI; `--json` preserves the REST
+envelope.
 
 ## Project Status Updates
 
@@ -781,7 +803,15 @@ require a canonical `event`; snapshots cannot establish transitions. See
 [Automation Rule Fields](api-fields.md#automation-rule-fields) for the grammar
 and legacy normalization. No public MCP tool is added.
 
-Trigger events: `issue.created`, `issue.status_changed`, `issue.assigned`, `issue.priority_changed`, `pr.merged`, `ci.run.completed`.
+Scheduled dry runs use an `issue_id` or issue sample with the selected time
+fields, return `scheduled_for`, `due`, and `conditions_matched`, and reject an
+event preview. They remain side-effect free.
+
+Trigger events: `issue.created`, `issue.status_changed`, `issue.assigned`, `issue.priority_changed`, `pr.merged`, `ci.run.completed`, `schedule.issue_time`.
+The `schedule.issue_time` trigger requires `schedule_config` with an
+`updated_at`, `status_changed_at`, or `due_date` anchor and an integer
+`offset_minutes`; the first two anchors require a non-negative offset, while
+due-date offsets may be signed. See [Automation Rule Fields](api-fields.md#automation-rule-fields).
 Create and update requests reject unsupported action types or malformed action
 values before persistence. Activity returns safe durable run/action history;
 non-matches, dry runs, and rules without executable actions create no history,

package/skill/references/api-fields.md

@@ -191,6 +191,9 @@ return `413`.
   "recurrenceType": "weekly",
   "recurrenceInterval": 1,
   "recurrenceDays": ["mon", "wed", "fri"],
+  "recurrenceMaterializationMode": "schedule",
+  "recurrenceTime": "09:00",
+  "recurrenceTimezone": "Europe/Stockholm",
   "labelIds": ["label-uuid-1", "label-uuid-2"]
 }
 ```
@@ -199,7 +202,7 @@ Most fields work on both POST (create) and PATCH (update). `labelIds` is accepte
 
 - **Multiple assignees**: Use `assigneeIds` (array). Legacy `assigneeId` (single) still works. Responses include `assignees` array with `id`, `display_name`, `type`, `avatar_url`.
 - **Start date**: Sets when work begins. Combined with `dueDate`, defines the Gantt time span.
-- **Recurring tasks**: Set `recurrenceType` + optional `recurrenceInterval` (default 1). Weekly series can set unique `recurrenceDays` values from `mon` through `sun`; Atoll sorts them into calendar order. When marked `done`, one next instance is auto-created in the same series. Responses include normalized `recurrence_days` and `recurrence_schedule: { type, interval, days }`.
+- **Recurring tasks**: Set `recurrenceType` + optional `recurrenceInterval` (default 1). Completion mode is the default and creates the next occurrence when the current task is marked `done`. Set `recurrenceMaterializationMode` to `schedule` with `recurrenceTime` (`HH:MM`) and an IANA `recurrenceTimezone` to create occurrences from the maintenance sweep even while older tasks remain open; completing a scheduled occurrence does not create another task. Scheduled weekly series can set unique `recurrenceDays` values from `mon` through `sun`; Atoll sorts them into calendar order. Weekday arrays, including `[]`, require scheduled mode; `null` can clear selected weekdays in completion mode too. Scheduled intervals must be at most `10000`; completion mode retains its existing positive PostgreSQL integer range. Responses include normalized `recurrence_days` and `recurrence_schedule: { type, interval, days }`; the internal `recurrence_next_run_at` cursor is omitted. Appearance and due dates are separate, and the root due date is not advanced. Chains that have never entered scheduled mode retain and edit each occurrence's completion settings locally. Activating scheduled mode through a child adopts that child's cadence on the authorized root unless overridden. Once a chain has entered scheduled mode, the root owns recurrence settings even after a later switch back to completion; authorized list, detail, and update responses use those settings while preserving each child's identity. In those chains, send child-local task edits separately from root recurrence edits. Root deletion preserves completion-mode child recurrence, while scheduled-mode children become ordinary tasks. Do not PATCH `recurrenceParentId`.
 - **Archived tasks**: Have `archived_at` timestamp. Excluded by default; pass `includeArchived=true`.
 - **GET detail** returns enriched data: `milestone`, `creator`, `assignee`, `assignees`, `sub_tasks`, `issue_labels`, `isBlocked`.
 
@@ -493,6 +496,39 @@ multiple exact-name milestones already exist, upsert returns a structured
 }
 ```
 
+Time-based rules use the same definition with `trigger_event:
+"schedule.issue_time"` and a required `schedule_config`:
+
+```json
+{
+  "trigger_event": "schedule.issue_time",
+  "schedule_config": {
+    "anchor": "due_date",
+    "offset_minutes": -60
+  }
+}
+```
+
+`anchor` is `updated_at`, `status_changed_at`, or `due_date`. An `updated_at`
+rule represents inactivity; a `status_changed_at` rule represents time in the
+current status; and a `due_date` rule represents deadline timing. Offsets for
+`updated_at` and `status_changed_at` must be non-negative. A `due_date` offset
+may be negative (before due), zero (at due), or positive (after due). Date-only
+due dates are evaluated at midnight UTC. Scheduled rules reject change
+conditions; combine a status field condition with `status_changed_at` when the
+rule targets a specific status. Event-triggered rules must omit or clear
+`schedule_config`.
+
+Atoll evaluates scheduled rules from the existing authenticated maintenance
+sweep every 15 minutes in bounded batches with a durable rotating rule cursor.
+Busy workspaces can take multiple sweeps. It catches up occurrences whose time has
+passed, excludes archived issues, and deduplicates each `(rule, issue,
+scheduled_for)` occurrence. A condition mismatch is terminal for that
+occurrence and is recorded as skipped. Scheduled execution reuses the existing
+condition evaluator, action path, and `automation.executed` Activity history;
+it does not add cron expressions, recurrence rules, calendars, or a second rule
+store.
+
 Supported action values are: `set_status` (canonical project status key),
 `set_assignee` (replace the full assignee set with one member UUID, or `null` to
 clear it), `add_assignee` (add a member UUID without removing others), `unassign`
@@ -543,6 +579,12 @@ Dry runs create no issue and fail clearly when required content fields are missi
 Custom repository or branch conditions can fail to match this example; a preview
 does not verify a live run.
 
+**Scheduled dry-run test:** Send `{ "issue_id": "issue-uuid" }` for a real
+issue, or `{ "issue": { "updated_at": "2026-01-01T00:00:00Z", "status_changed_at": "2026-01-01T00:00:00Z", "due_date": "2026-01-03" } }`
+for a sample. The existing test endpoint returns `scheduled_for`, `due`, and
+`conditions_matched`, plus `matched` and `actions_that_would_run`. A scheduled
+preview uses an issue, not a canonical event, and remains side-effect free.
+
 **Issue dry-run test**: Send `{ "issue_id": "uuid" }` or `{ "issue": { "status": "todo", "priority": 2 } }`. Returns `{ matched, actions_that_would_run }`.
 
 **Rule definition V1:** `schema_version` defaults to `1`. Conditions are ANDed;
@@ -1025,7 +1067,10 @@ metadata are never returned by the public API.
 | Comment create response | `outcome.mentions.transport` | Asynchronous Google Chat dispatch state; `dispatch: "scheduled"` is not final delivery, `final` is null while any result is unknown, `mixed` means terminal recipient results differ, and `error` exposes safe lookup/scheduling failure details |
 | Comment create response | `outcome.mentions.skipped[]` | Mention targets that did not create notification rows; each entry includes `member_id` and `reason` |
 | Task | `recurrenceType` | `daily`, `weekly`, `biweekly`, `monthly`, `custom` |
-| Weekly task | `recurrenceDays[]` | Unique `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun` values |
+| Scheduled task | `recurrenceMaterializationMode` | `completion` or `schedule` |
+| Scheduled task | `recurrenceTime` | Local `HH:MM` time used with `schedule` |
+| Scheduled task | `recurrenceTimezone` | IANA timezone used with `schedule` |
+| Scheduled weekly task | `recurrenceDays[]` | Unique `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun` values |
 | Goal | `status` | `active`, `achieved`, `missed`, `paused`, `cancelled` |
 | KPI | `unit` | `count`, `percentage`, `currency`, `duration`, `ratio`, `custom` |
 | KPI | `target_direction` | `increase`, `decrease`, `maintain` |
@@ -1038,7 +1083,7 @@ metadata are never returned by the public API.
 | Status update | `status` | `on_track`, `at_risk`, `off_track` |
 | Member | `role` | `owner`, `admin`, `member`, `guest` |
 | Project member | `accessLevel` | `view`, `edit`, `admin` |
-| Automation | `trigger_event` | `issue.created`, `issue.status_changed`, `issue.assigned`, `issue.priority_changed`, `pr.merged`, `ci.run.completed` |
+| Automation | `trigger_event` | `issue.created`, `issue.status_changed`, `issue.assigned`, `issue.priority_changed`, `pr.merged`, `ci.run.completed`, `schedule.issue_time` |
 | Heartbeat signal | `type` | `kpi_off_pace`, `kpi_stale`, `issue_stale`, `issue_blocked`, `milestone_overdue`, `initiative_stalled`, `initiative_target_due_soon`, `initiative_target_overdue`, `initiative_target_blocked`, `webhook_failing` |
 | Heartbeat signal | `severity` | `info`, `warning`, `critical` |
 | Custom view | `display_mode` | `board`, `list` |
@@ -1113,9 +1158,10 @@ metadata-only Activity actions `external_reference.linked`,
 links, selection prefers an open PR, then the latest `updated_at`, then the
 highest PR number. Otherwise it
 contains `repository`, `pull_request`, nullable `review`, `workflows`,
-`freshness`, nullable `strongest_blocker`, and `partial`. PR, review, and
-workflow evidence includes nullable `observed_at`, `provider_updated_at`,
-`provider_event_id`, and `source_url`. The PR includes the exact `head_sha`.
+`required_checks`, `freshness`, nullable `strongest_blocker`, and `partial`. PR,
+review, and workflow evidence includes nullable `observed_at`,
+`provider_updated_at`, `provider_event_id`, and `source_url`. The PR includes
+the exact `head_sha`.
 Review state is `pending`, `approved`, or `changes_requested`; workflow state is
 `pending`, `passed`, `failed`, or `cancelled`. Older-head evidence is not
 current. Workflow `required` is always `false` because configured workflow
@@ -1130,6 +1176,19 @@ The selected PR-link state is authoritative. If a same-head PR observation
 disagrees, its `observed_at`, `provider_updated_at`, and `provider_event_id` are
 null, `source_url` uses the link URL, the observation is excluded from
 `freshness`, and `partial` is true.
+`required_checks.state` is `disabled`, `complete`, `partial`, or `unavailable`;
+`required_checks.aggregate` is `none`, `pending`, `passed`, `failed`,
+`cancelled`, or `unknown`. Each item includes `context`, nullable
+`integration_id`, `policy_sources` (`classic`, `ruleset`, or both), normalized
+`state`, bounded nullable provider state/conclusion, a safe nullable GitHub
+`url`, and nullable `provider_updated_at`. The collection has at most 200
+items, plus nullable safe `error_code` and `observed_at`. The server-only
+`ATOLL_GITHUB_REQUIRED_CHECKS_READ_ENABLED=1` flag enables the read-only
+provider collection; disabled is the default. With reads disabled, state
+`disabled` and aggregate `none` do not set `partial`. When enabled, partial or
+unavailable collection, stale, ambiguous, or missing evidence remains `unknown`
+and sets `partial`.
+
 Review aggregation keeps each reviewer's latest exact-head opinion, ignores
 comments, and removes dismissed opinions. Change requests win; `approved`
 means at least one effective approval and no effective change request. It does

package/skill/references/cli-operations.md

@@ -58,6 +58,7 @@ atoll issue list --scope blocked --initiative initiative-uuid --order-by due_dat
 # View a task
 atoll issue get ATOLL-42
 atoll issue view ATOLL-42   # alias kept for humans
+atoll issue delivery-context ATOLL-42
 
 # Discover compact issue Artifacts, then fetch one body explicitly
 atoll artifact list ATOLL-42
@@ -69,7 +70,7 @@ atoll artifact update <artifact-id> --issue ATOLL-42 --expected-revision-id <rev
 atoll issue create --title "Fix login bug" --status todo --priority 1
 atoll issue create --title "Plan rollout" --project project-slug --milestone "Launch"
 atoll issue create --title "Weekly status review" --due-date 2026-07-06 --recurrence weekly
-atoll issue create --title "MWF status review" --due-date 2026-07-06 --recurrence weekly --recurrence-days mon,wed,fri
+atoll issue create --title "MWF status review" --due-date 2026-07-06 --recurrence weekly --recurrence-days mon,wed,fri --recurrence-mode schedule --recurrence-time 09:00 --recurrence-timezone Asia/Singapore
 atoll issue upsert --match-title --project <project-id> --title "Fix login bug" --status todo
 atoll issue bulk-create --file ./issues.json --continue-on-error
 
@@ -181,12 +182,12 @@ CLI JSON conventions:
 - Machine-readable JSON preserves API strings exactly; human terminal output removes ANSI/VT, control, and bidirectional formatting characters from API-supplied strings.
 - Interactive CLI update notices also go to stderr and are suppressed for JSON/non-TTY/CI/completion flows.
 - `atoll agent-context` returns a versioned command/flag manifest, available profile context, and structured `cli.update_available` metadata.
-- Weekly issue recurrence accepts unique selected weekdays with `--recurrence weekly --recurrence-days mon,wed,fri`. Read JSON exposes normalized `recurrence_days` and `recurrence_schedule`; unrelated updates preserve the schedule.
+- Weekly issue recurrence accepts unique selected weekdays with `--recurrence weekly --recurrence-days mon,wed,fri --recurrence-mode schedule --recurrence-time 09:00 --recurrence-timezone Asia/Singapore`. Read JSON exposes normalized `recurrence_days` and `recurrence_schedule`; unrelated updates preserve the schedule. Scheduled recurrence intervals are limited to `10000`. Use `--recurrence-mode schedule` with `--recurrence-time HH:MM` and `--recurrence-timezone IANA/Zone` to create the next task from the maintenance sweep while the current task remains open; `completion` remains the default and can retain larger positive intervals.
 - `atoll heartbeat --json` includes the same structured `cli` update metadata for agents, plus `attention_items`, `attention_summary`, and `recommended_action` when Atoll can propose one concrete strategy-backed next action. `atoll heartbeat --signals-only --json` preserves filtered `signals`, `attention_items`, `attention_summary`, and `recommended_action` for short polling. Handle direct attention items first, then call each handled item's `ack_endpoint`. Follow `recommended_action.usage_guidance`: prefer `suggested_write.operation` when it still matches the board, preserve KPI/initiative/initiative_target/why-now/expected-impact/first-step/success-criteria evidence, and avoid copying deferred busywork into issue or comment payloads. If a `start_work` recommendation uses `issue.update` with a body, update the issue status and preserve that body as an issue comment; `PATCH /issues/{issueId}` accepts `comment_body` for this same-request progress note.
 - Authorized humans can configure an agent's included heartbeat sections and generated-signal focus in the Atoll **Heartbeats** UI. The saved policy is applied by the API before CLI or MCP request-level narrowing; it never changes project access, and existing heartbeat commands require no new arguments.
 - GitHub `workflow_run` signals are accepted only when HMAC-signed and completed, then reread and matched exactly by repository, PR, workflow path, run attempt, and head SHA. Workflow verification is disabled by default and observe-only until an owner/admin enables it in **Settings > Integrations > GitHub**. `attention` mode can add one bounded `verification.completed` attention item through authorized REST or CLI heartbeat for exactly one eligible current agent assignee or, when there is no unambiguous assignee, an eligible configured delivery agent. The public MCP heartbeat excludes this private event type. Unresolved recipients and cancelled, obsolete, superseded, mismatched, or unreadable runs create no attention. Owners and admins can configure 1–10 workflow paths of at most 255 characters each; the bounded evidence list defaults to 25 items and accepts a maximum `limit` of 100. Signed pull-request writes and reconciliation bind PR links to the stable GitHub repository ID, so repository renames keep existing workflow evidence linked. Do not expect raw payloads, secrets, logs, or thread IDs in evidence; owner/admin reconciliation retries pending evidence after current GitHub and PR-link readback.
 - Release-added required GitHub hook events mark existing reconciled and already-pending connections pending. The bounded 15-minute service sweep verifies immutable repository identity and upgrades hooks automatically; transient failures remain pending for retry, and owners/admins can reconcile manually.
-- Issue delivery context selects an open PR first, then the latest updated link, then the highest PR number. `pending` review/workflow state with null provenance means no current-head observation and does not by itself set `partial`. Disabled GitHub verification stops new projections. Workflow conclusions map success/neutral to passed, cancelled/stale/skipped to cancelled, and other supported terminal conclusions to failed.
+- Issue delivery context is read with `atoll issue delivery-context <identifier>`; `--json` preserves `{ deliveryContext }`, while TTY output includes the full head SHA, review, actual required checks, configured verification, freshness, blocker, and partial state. The endpoint selects an open PR first, then the latest updated link, then the highest PR number. Required checks union active rulesets and classic branch protection for the base branch and use exact-head check-run/status evidence. `pending` review/workflow state with null provenance means no current-head observation and does not by itself set `partial`. Required-check collection is disabled by default; with the reader disabled, state `disabled` and aggregate `none` do not set `partial`. The server-only `ATOLL_GITHUB_REQUIRED_CHECKS_READ_ENABLED=1` flag enables read-only provider GETs; when enabled, partial or unavailable collection or aggregate `unknown` sets `partial`. This result does not authorize merge, deployment, production testing, or human acceptance. Configured workflows report `required: false`.
 - Aggregate review state keeps each reviewer's latest exact-head opinion, ignores comments, and removes dismissed opinions. Change requests win. `approved` means at least one effective approval and no effective change request; it does not prove required-review counts or branch protection.
 - `atoll plan validate/apply` consumes `schemaVersion: "atoll.plan.v1"` files with `milestones`, `issues`, `dependencies`, `initiativeLinks`, and `milestoneLinks`; local `key` values can be referenced by `milestoneKey`, `issueKey`, `dependsOn`, `blockedBy`, or `blocks`.
 

package/skill/references/integrations-and-api.md

@@ -216,6 +216,29 @@ Webhook creation returns a raw `whsec_...` secret once. Delivery requests includ
 
 Webhook administration is owner/admin only. Lists return an origin-only `destination_display`; paths, queries, and signing material are never returned. Payload schema version `2` is allowlisted and omits descriptions, comment bodies, and raw change values. Delivery rows expose safe `delivery_id`, `status`, `status_code`, `error_code`, and retry timing, but not payloads, receiver response bodies, or raw errors. Network failures and 5xx responses retry quickly in-process, then persist `status: retry_pending` with `next_retry_at`; an internal drain retries due deliveries every 15 minutes.
 
+### GitHub delivery context
+
+Use `atoll issue delivery-context <identifier>` or
+`GET /api/orgs/{id}/issues/{issueId}/external-operational-signals` to inspect a
+linked pull request's current delivery evidence. The response is authorized to
+the issue and selects an open PR first, then the latest updated link, then the
+highest PR number. All revision-sensitive evidence is bound to the exact
+40-character head SHA.
+
+The `required_checks` projection unions active base-branch rulesets and classic
+branch protection by check context and optional integration/app ID. It reads
+check-runs and legacy commit statuses for that exact head. If both result types
+share a required context, both must pass. Collection states are `disabled`,
+`complete`, `partial`, and `unavailable`; an aggregate of `unknown` is
+fail-closed when missing, stale, ambiguous, or inaccessible evidence could
+change the result. With the reader disabled, state `disabled` and aggregate
+`none` do not set context `partial`; when enabled, partial or unavailable
+collection or aggregate `unknown` sets `partial`. The server-only
+`ATOLL_GITHUB_REQUIRED_CHECKS_READ_ENABLED=1` flag enables provider GETs and is
+off by default. This evidence does not grant merge, deployment, production
+testing, or acceptance authority, and the endpoint does not change GitHub
+state. Configured Atoll workflow paths remain `required: false`.
+
 ## Planning Artifacts
 
 Use the connected typed Artifact tools for PRDs and implementation plans. Read

package/skill/references/platform-rules.md

@@ -123,11 +123,20 @@ resolvability. Reads require project visibility; writes require project
 For compact implementation evidence, the private REST endpoint
 `GET /api/orgs/{id}/issues/{issueId}/external-operational-signals` returns the
 selected PR, stable repository identity, exact current head SHA, current-head
-review and configured workflow states, bounded provenance, freshness, and a
-safe strongest blocker. Older-head evidence is historical. Configured
-workflows are not GitHub branch-protection required checks. This namespace is
-separate from heartbeat `signals[]` and never changes tasks or dispatches
-agents.
+review, actual required checks, and configured workflow states, bounded
+provenance, freshness, and a safe strongest blocker. Older-head evidence is
+historical. Configured workflows are not GitHub branch-protection required
+checks. Required checks union active base-branch rulesets and classic branch
+protection, use the exact head SHA, and report `disabled`, `complete`,
+`partial`, or `unavailable` collection states. Partial, unavailable, stale,
+ambiguous, or missing evidence remains aggregate `unknown`. With provider reads
+disabled, aggregate `none` does not set context `partial`; enabled partial or
+unavailable collection and aggregate `unknown` set `partial`. Read-only
+required-check provider collection is disabled by default and requires the
+server-only
+`ATOLL_GITHUB_REQUIRED_CHECKS_READ_ENABLED=1` flag. This namespace is separate
+from heartbeat `signals[]`, never changes provider state, and never changes
+tasks or dispatches agents.
 The selected PR-link state is authoritative. If a same-head PR observation
 disagrees, Atoll clears its observation/provider provenance, falls back to the
 link URL, excludes it from freshness, and sets `partial`.