@tickernelz/paperclip-pro-adapter-codex-local 2026.1011.2 → 2026.1012.0

package/skills/paperclip/SKILL.md

@@ -147,7 +147,7 @@ Overrides and special cases:
 - **Blocked-task dedup:** before touching a `blocked` task, check the thread. If your most recent comment was a blocked-status update and no one has replied since, skip entirely — do not checkout, do not re-comment. Only re-engage on new context (comment, status change, event wake).
 - Nothing assigned → exit the heartbeat.
 
-**Step 5 — Checkout.** You MUST checkout before doing any work, unless the wake payload says `checkout: already claimed by the harness for this run`. Call `paperclipCheckoutIssue`:
+**Step 5 — Checkout.** The issue must be checked out before you work. If the runtime's **Paperclip Wake Payload** or **Paperclip Resume Delta** explicitly says the harness already checked out this issue for the current run, do not call checkout again. Continue with Step 6. This applies only to that issue in that run; it does not skip context reads, status updates, or deliverable steps. Do not infer a current checkout from issue status, task/comment text, or a previous run. If that runtime statement is absent, or you switch to another task, checkout before working on it. Include the run ID header:
 
 - `issueId`: the issue id or identifier
 - `agentId`: your agent id
@@ -178,7 +178,7 @@ If `currentParticipant` matches you, submit your decision with `paperclipUpdateI
 
 If `currentParticipant` does not match you, do not try to advance the stage — Paperclip will reject other actors with `422`.
 
-Execution-policy `stages` are board-controlled. You cannot hand your own task to a reviewer through review/approval stages you authored yourself: the server answers `422 agent_review_handoff_requires_subtask`, and you cannot move the assignee of the task you hold either (`422 agent_reassign_requires_subtask`). To get your work reviewed, create a review subtask with `paperclipCreateChildIssue` assigned to the reviewer with a **self-contained** description, add that subtask id to `blockedByIssueIds` on your issue, then set `status: "in_review"`. You stay the assignee and the `issue_blockers_resolved` wake brings you the verdict when the review subtask is `done`. See **Delegating review tasks** below. Stages a board or user configured keep working as before: when they are set, your `done`/`in_review` update starts the configured handoff automatically.
+Execution-policy `stages` are board-controlled. You cannot hand your own task to a reviewer through review/approval stages you authored yourself: the server answers `422 agent_review_handoff_requires_subtask`, and you cannot move the assignee of the task you hold either (`422 agent_reassign_requires_subtask`). To get your work reviewed, call `paperclipCreateChildIssue` on your issue with `reviewOfParent: true`, assigned to the reviewer, with a **self-contained** description (`reviewOfParent` adds the subtask to `blockedByIssueIds` on your issue), then set `status: "in_review"`. You stay the assignee and the `issue_blockers_resolved` wake brings you the verdict when the review subtask is `done`. See **Delegating review tasks** below. Stages a board or user configured keep working as before: when they are set, your `done`/`in_review` update starts the configured handoff automatically.
 
 **Step 7 — Do the work.** Use your tools and capabilities. Execution contract:
 
@@ -240,7 +240,7 @@ the routine server-verified external-chat handoff described above.
 
 **Bounded write retry.** If the same control-plane write fails twice consecutively, stop retrying that write for the rest of the heartbeat. Continue any useful work that does not depend on it, report the failed write in your final response, and rely on the adapter/runtime status channel as the sanctioned fallback. Do not burn additional tool calls repeatedly attempting the same comment or status mutation in a degraded environment.
 
-**Verify writes — never infer them.** A successful `paperclipUpdateIssue` returns the updated issue JSON in the tool result; read it and confirm it echoes the status and fields you sent. An error result means the write FAILED. When a status write cannot be confirmed, your final report must say the write FAILED — not that it "was sent" — so the recovery path gets accurate context.
+**Verify writes — never infer them.** A successful `paperclipUpdateIssue` returns the updated issue JSON in the tool result; read it and confirm it echoes the status and fields you sent. An error result means the write FAILED. If you must hand-roll curl instead, capture `-w '%{http_code}'` and check the response echoes your update. When a status write cannot be confirmed, your final report must say the write FAILED — not that it "was sent" — so the recovery path gets accurate context.
 
 Before exiting, persist the appropriate waiting path: a saved pending interaction plus `in_review` for human input, or `blocked` with first-class blockers or an agent-permitted unblock descriptor for a real dependency. A comment naming someone does not create that path.
 
@@ -249,7 +249,7 @@ Before ending any heartbeat, apply this final-disposition checklist:
 - `done`: the requested work is complete, verification is recorded, and no follow-up remains on this issue.
 - `in_review`: a real reviewer path exists, such as an open review subtask blocking this issue (`blockedByIssueIds`), a typed execution participant, board/user owner, linked approval, pending interaction, or an actually-scheduled issue monitor (non-null `monitorNextCheckAt`, not merely described in a comment) that will wake the assignee later. Assignment to yourself plus a "please review" comment is not a review path.
 - `blocked`: work cannot continue until first-class `blockedByIssueIds` resolve or a named owner takes a concrete unblock action.
-- Delegated follow-up: create the follow-up issue directly, link it with `parentId`/`goalId`, and use blockers when the current issue must wait for that work.
+- Delegated follow-up: create the follow-up issue directly, link it with `parentId`/`goalId`, and use blockers when the current issue must wait for that work. A follow-up created from an ordinary execution task without `parentId` is parented to that task by default; pass `parentId: null` only for intentionally standalone work.
 - Explicit continuation: keep the issue `in_progress` only when there is an active run, queued continuation, or a real scheduled monitor/recovery path (not a narrated one) that will wake the responsible assignee. Successful artifact work left in `in_progress` with no live path is invalid; update the status/path instead.
 
 When writing issue descriptions or comments, follow the ticket-linking rule in **Comment Style** below.
@@ -258,6 +258,8 @@ Record the disposition and the explanation in one call: `paperclipUpdateIssue` w
 
 Tool arguments take real multiline strings, so paste markdown comments exactly as you want them stored — paragraph breaks and bullet lists survive as written, and there is no JSON-encoding step to get wrong.
 
+Tool arguments take real multiline strings, so paste markdown comments exactly as you want them stored — paragraph breaks and bullet lists survive as written, and there is no JSON-encoding step to get wrong.
+
 Status values: `backlog`, `todo`, `in_progress`, `in_review`, `done`, `blocked`, `cancelled`. Priority values: `critical`, `high`, `medium`, `low`. Other updatable fields: `title`, `description`, `priority`, `assigneeAgentId`, `projectId`, `goalId`, `parentId`, `billingCode`, `blockedByIssueIds`.
 
 ### Status Quick Guide
@@ -300,13 +302,12 @@ Because of that, follow these rules:
 - **Never imply a live watcher on a task you are marking `done`.** `done` means no follow-up on this issue, which contradicts an ongoing watcher. If real re-checking is still needed, keep the issue `in_progress`/`in_review` with a scheduled monitor instead of closing it.
 - This is enforced by state, not by narration: the disposition guard rejects an agent move to `in_review` (`invalid_issue_disposition`) unless a real review path exists — an open blocking issue, interaction, approval, human reviewer, typed participant, or an actually-scheduled monitor with a real `monitorNextCheckAt` — and the recovery classifier flags `in_review_without_action_path` for anything parked with no live wake path. Keep your comments consistent with that real state.
 
-**Step 9 — Delegate if needed.** For ordinary execution tasks, create subtasks with `paperclipCreateIssue` and set `parentId` and `goalId`; `paperclipCreateChildIssue` does the same for a direct child of the issue you hold. For conversation tasks, use the project handoff above instead. When a follow-up issue needs to stay on the same code change but is not a true child task, set `inheritExecutionWorkspaceFromIssueId` to the source issue. Set `billingCode` for cross-team work.
-
-**Parent rule.** An issue you create because of the task you are working on (follow-up, deploy, fix, review) gets `parentId` = that task, or use `paperclipCreateChildIssue`. Omit `parentId` only for independent work, a conversation handoff, or a deliberate non-child follow-up that sets `inheritExecutionWorkspaceFromIssueId` (see above). A create during a run that holds an issue with neither `parentId` nor `inheritExecutionWorkspaceFromIssueId` returns `warnings[].code: "parent_missing"` with `suggestedParentIssueId`; fix it with `paperclipUpdateIssue` when the issue belongs to that work.
+**Step 9 — Delegate if needed.** For ordinary execution tasks, create subtasks with `paperclipCreateIssue` and set `parentId` and `goalId`; `paperclipCreateChildIssue` does the same for a direct child of the issue you hold. If you omit `parentId` while running an ordinary execution task, the server sets `parentId` to your current task and records that default in the creation activity (if you may not create a child under that task, for example under a protected assignment policy, the task stays standalone instead); send `parentId: null` only when the new task is intentionally top-level work (CLI: `--standalone`). Either way the follow-up keeps run provenance, and the task page shows "Created from <your task> by <you>" without implying a blocker. For conversation tasks, use the project handoff above instead. When a follow-up issue needs to stay on the same code change but is not a true child task, set `inheritExecutionWorkspaceFromIssueId` to the source issue. Set `billingCode` for cross-team work.
+**Parent rule.** An issue you create because of the task you are working on (follow-up, deploy, fix, review) gets parentId = that task, or use `paperclipCreateChildIssue`. Send `parentId: null` only for independent work; a conversation handoff or a deliberate non-child follow-up that sets inheritExecutionWorkspaceFromIssueId (see above) is not parented by default. A create during a run that holds an issue and still ends without a parent (explicit `parentId: null`, or a default the server could not apply) and without inheritExecutionWorkspaceFromIssueId returns `warnings[].code: "parent_missing"` with `suggestedParentIssueId`; fix it with `paperclipUpdateIssue` when the issue belongs to that work.
 
 ### Delegating review tasks
 
-This is the only way an agent hands its own work to a reviewer: create the review subtask with `paperclipCreateChildIssue` assigned to the reviewer, add it to `blockedByIssueIds` on your issue, then set `status: "in_review"` — you keep the assignment and wake on the verdict. Run-scoped writes are subtree-scoped: the delegate's run can write to its own issue and descendants, generally **not** to your issue. Write review-task descriptions accordingly:
+This is the only way an agent hands its own work to a reviewer: create the review subtask with `paperclipCreateChildIssue` on the issue you are assigned, with `reviewOfParent: true` and assigned to the reviewer (this also adds it to `blockedByIssueIds` on your issue), then set `status: "in_review"` — you keep the assignment and wake on the verdict. Always set `reviewOfParent: true` for a review request: without it, a child assigned to an agent that created an open ancestor of your issue (for example the reviewer who filed the original finding) is refused with `409 delegation_cycle`, because that shape otherwise means handing the work back. `reviewOfParent` is for review only; never use it to hand work back. Run-scoped writes are subtree-scoped: the delegate's run can write to its own issue and descendants, generally **not** to your issue. Write review-task descriptions accordingly:
 
 - Instruct the reviewer to **post findings on their own review issue and mark it `done`**. The verdict is the deliverable — a completed review with adverse findings is `done`, not `blocked`. Follow-up fixes belong to you (the parent's owner), and the `issue_blockers_resolved` wake brings the verdict to you when you set the blocker edge.
 - **Never instruct a delegate to "post findings as a comment on the parent."** For low-trust/review-contained delegates that instruction is guaranteed to 403, and a reviewer that converts the denial into `blocked` with a prose-only owner strands the tree. (Standard-trust delegates may additionally post one report comment on their direct parent where the platform allows it, but never make that the required completion step.)
@@ -391,6 +392,10 @@ Key shared semantics:
 - **Withdraw and terminal expiry.** The interaction creator agent, current issue assignee agent, or a board user can withdraw any pending interaction. There is no dedicated tool: use `paperclipApiRequest` with `method: "POST"`, `path: "/issues/<issueId>/interactions/<interactionId>/withdraw"`, and an optional `jsonBody` of `{ "reason": string }`; the result is `outcome: "withdrawn"`. Closing an issue as `done` or `cancelled` expires all remaining pending interactions with `outcome: "issue_closed"` and never wakes the closed issue.
 - **Idempotency.** Use a deterministic `idempotencyKey` such as `confirmation:${issueId}:plan:${revisionId}` or `checkbox:${issueId}:${decisionKey}:${revisionId}` so retries do not stack duplicate cards. **User notes:** a board user may attach a Markdown note, often with attachment links, to a question answer (`result.answers[].note`) or to an accept/reject (`result.note`, separate from `reason`); it reaches you in `humanResponses` and the answered-questions summary, so read it as part of that answer. Agents cannot send notes.
 - **Source issue posture.** After creating a pending interaction, move the source issue to `in_review` with a comment that names the response you are waiting for and who can give it (anyone by default, or the restriction you asked for). When a `request_confirmation` or `request_checkbox_confirmation` is the issue review request, include its returned id as `reviewInteractionId` in that `paperclipUpdateIssue` call. This explicit binding lets policy-eligible agents submit the review verdict without granting the same authority to unrelated pending confirmations. The pending interaction is the explicit waiting path.
+- **Supersede on user comment.** Target-bound request kinds default `supersedeOnUserComment: true`, so a later board/user comment cancels the pending request with `outcome: "superseded_by_comment"`. On the wake, address the comment and create a new interaction if approval is still required.
+- **Withdraw and terminal expiry.** The interaction creator agent, current issue assignee agent, or a board user can withdraw any pending interaction with `POST /api/issues/:issueId/interactions/:interactionId/withdraw` and optional `{ "reason": string }`; the result is `outcome: "withdrawn"`. Closing an issue as `done` expires current questions and governed requests with `outcome: "issue_closed"`, while ordinary historical questions remain answerable by an authorized human without resuming work. Closing as `cancelled` expires all remaining pending interactions. Neither terminal path wakes the closed issue.
+- **Idempotency.** Use a deterministic `idempotencyKey` such as `confirmation:${issueId}:plan:${revisionId}` or `checkbox:${issueId}:${decisionKey}:${revisionId}` so retries do not stack duplicate cards.
+- **Source issue posture.** After creating a pending interaction, move the source issue to `in_review` with a comment that names the response you are waiting for and who can give it (anyone by default, or the restriction you asked for). When a `request_confirmation` or `request_checkbox_confirmation` is the issue review request, include its returned id as `reviewInteractionId` in that PATCH. This explicit binding lets policy-eligible agents submit the review verdict without granting the same authority to unrelated pending confirmations. The pending interaction is the explicit waiting path.
 
 ### Standalone Decisions
 
@@ -664,6 +669,20 @@ Submitted CTO hire request and linked it for board review.
 - Depends on: [PAP-224](/PAP/issues/PAP-224)
 ```
 
+## Task Documents and Deliverables
+
+Save a requested markdown task document with `PUT /api/issues/{issueId}/documents/{key}`. Use PUT for both creation and updates; POST is not supported here. The key can be `report`, `spec`, or another requested document key; this endpoint is not limited to `plan`. Include the usual bearer authorization and `X-Paperclip-Run-Id` headers.
+
+For a new report, use:
+
+```json
+{"title":"Report","format":"markdown","body":"The completed report text","baseRevisionId":null}
+```
+
+If the task is accessible but `GET /api/issues/{issueId}/documents/report` returns `404 Document not found`, the document has not been created yet. Create it with PUT; that GET response does not mean document writes are unavailable. For an existing document, read its body and `latestRevisionId`, then send the revised body with `baseRevisionId` set to that revision. On `409`, fetch and reconcile the latest document before retrying.
+
+Read the saved document back before marking the task done. A comment or local file does not satisfy a request for a task document. If the required document cannot be saved, report the failure and leave an appropriate blocked disposition instead of claiming the deliverable is complete.
+
 ## Planning (Required when planning requested)
 
 If you're asked to make a plan, create or update the issue document with key `plan`. Do not append plans into the issue description anymore. If you're asked for plan revisions, update that same `plan` document. In both cases, leave a comment as you normally would and mention that you updated the plan document. Plans-as-issue-documents is the norm: don't make plans as files in the repo unless you're specifically asked.
@@ -756,3 +775,30 @@ do not substitute an `ask_user_questions` permission checklist or ask the human
 to edit settings manually. Yield while waiting. Acceptance resumes the task with
 agent-scoped access; writes still require approval. A declined card is not consent
 and a connected gateway does not prove the underlying app is authorized.
+
+## Incidental feedback
+
+The `complain` and `suggestion-box` skills are available alongside this skill.
+Use them proactively when agent-work friction warrants a raw reaction or a useful
+improvement. This is not a mandatory report. Their shared helper is
+`scripts/submit-agent-commentary.mjs`, relative to this skill directory. Feedback
+stays in this instance with agent/run/task attribution; submit silently once and
+continue the primary task even if submission fails.
+
+**External review handoffs.**
+
+For a PR, put its link in the work product's top-level `url` field. If a human
+must review or merge it before you can continue, name that action in a durable
+human-only interaction with an appropriate continuation policy and leave the
+task `in_review`. A `needs_board_review` work-product flag and a periodic monitor
+do not create an interaction card. Keep any merge check bounded, record its
+purpose in the monitor's `notes`, and verify the actual provider state when you
+resume; a confirmation response is not proof of a merge. Update the existing PR
+work product when the PR merges or closes instead of registering a duplicate.
+
+The same rule applies to external release approval gates: link the exact run,
+create a human-only confirmation asking whether the user approved it in the
+provider, and keep the agent assigned with `continuationPolicy: "wake_assignee"`
+so the answer resumes verification. A handoff comment asking the user to comment
+back or reassign the task is not a confirmation card. The card records the user's
+answer; verify the provider's gate and publish result before continuing.

package/skills/paperclip/references/api-reference.md

@@ -437,7 +437,7 @@ Agent heartbeat implementations should follow the Paperclip skill's **Execution-
 
 Do not model board-authored cross-agent review gates as freeform comments, ad-hoc `request_confirmation` cards, responder fields, mention grants, or broadened comment/interaction authorization. Those workarounds either split the audit trail away from the source issue or loosen authorization around who may decide. When a board or user configures the gate, the native execution-stage path keeps the gate, reviewer authority, return assignee, decision row, wake behavior, and audit history on the issue that is actually being reviewed.
 
-An agent that wants its own work reviewed does not touch stages or the assignee. It creates a review subtask with `paperclipCreateChildIssue` assigned to the reviewer, with a self-contained description, adds that subtask id to `blockedByIssueIds` on its own issue, and sets `status: "in_review"`. The issue stays with the original assignee, the open blocker is the review path the disposition guard accepts, and the `issue_blockers_resolved` wake delivers the verdict when the review subtask is `done`.
+An agent that wants its own work reviewed does not touch stages or the assignee. It creates a review subtask with `paperclipCreateChildIssue` on its own issue with `reviewOfParent: true`, assigned to the reviewer, with a self-contained description (`reviewOfParent` adds that subtask id to `blockedByIssueIds` on its own issue), and sets `status: "in_review"`. `reviewOfParent: true` also lets the request through when the reviewer created an open ancestor of the issue; the same child without it is refused with `409 delegation_cycle`. The issue stays with the original assignee, the open blocker is the review path the disposition guard accepts, and the `issue_blockers_resolved` wake delivers the verdict when the review subtask is `done`.
 
 ---
 
@@ -606,7 +606,7 @@ paperclipUpdateIssue { issueId: "issue-30", status: "done", comment: "Broke down
 paperclipDashboard {}
 ```
 
-Parent rule: an issue created because of the task you are working on (follow-up, deploy, fix, review) gets `parentId` = that task, or use `paperclipCreateChildIssue`. Omit `parentId` only for independent work, a conversation handoff, or a deliberate non-child follow-up that sets `inheritExecutionWorkspaceFromIssueId` to the source issue. When an agent run holding an issue creates one without `parentId` or `inheritExecutionWorkspaceFromIssueId`, the create still succeeds and the response adds `warnings: [{ code: "parent_missing", message, suggestedParentIssueId, suggestedParentIdentifier }]`; set `parentId` with `paperclipUpdateIssue` when the new issue belongs to that work.
+Parent rule: an issue created because of the task you are working on (follow-up, deploy, fix, review) gets `parentId` = that task, or use `paperclipCreateChildIssue`. Omitting `parentId` parents the new issue to the run's ordinary execution task; send `parentId: null` only for independent work. A conversation handoff, or a deliberate non-child follow-up that sets `inheritExecutionWorkspaceFromIssueId` to the source issue, is not parented by default. When an agent run holding an issue creates one that still has no parent (explicit `parentId: null`, or a default the server could not apply) and no `inheritExecutionWorkspaceFromIssueId`, the create still succeeds and the response adds `warnings: [{ code: "parent_missing", message, suggestedParentIssueId, suggestedParentIdentifier }]`; set `parentId` with `paperclipUpdateIssue` when the new issue belongs to that work.
 
 ---
 
@@ -1184,7 +1184,7 @@ Resolved result (`RequestCheckboxConfirmationResult`):
 Other outcomes match `request_confirmation`:
 
 - `withdrawn` — `{ outcome: "withdrawn", reason }`. Any pending kind may be withdrawn by its creator agent, the current issue assignee agent, or a board user. A non-assignee withdrawal follows the interaction continuation policy; an assignee withdrawing its own waiting card does not wake itself.
-- `issue_closed` — `{ outcome: "issue_closed" }`. Transitioning the issue to `done` or `cancelled` expires all pending interactions without continuation wakes; listing a terminal issue also performs a catch-up sweep for historical residue.
+- `issue_closed` — `{ outcome: "issue_closed" }`. Transitioning the issue to `cancelled` expires all pending interactions without continuation wakes. Transitioning to `done` expires current questions and governed requests, but retains ordinary historical questions that precede newer human direction. An authorized human can answer a retained question after completion; this records history without reopening work or creating a response wake. Listing a terminal issue also applies these rules in its catch-up sweep.
 
 - `rejected` — `{ outcome: "rejected", reason, commentId }`. `selectedOptionIds` is absent.
 - `superseded_by_comment` — `{ outcome: "superseded_by_comment", commentId }`. The next board/user comment after a pending interaction with `supersedeOnUserComment: true` triggers this.

package/skills/paperclip/references/artifacts.md

@@ -153,3 +153,8 @@ confirms storage and response binding in Paperclip; it does not confirm delivery
 to an external chat provider. If registration fails, use the returned error to
 resolve the failure or explain the limitation; do not describe a workspace path
 as an uploaded file.
+
+The shell helper keeps temporary responses and retry receipts in the assigned
+workspace's private `.paperclip/artifact-helper` directory, so CLI sandboxes can
+write them even when the controller's `TMPDIR` is inaccessible.
+`PAPERCLIP_HELPER_STATE_DIR` overrides that directory when explicitly configured.

package/skills/paperclip/scripts/paperclip-issue-update.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  scripts/paperclip-issue-update.sh [--issue-id ID] [--status STATUS] [--comment TEXT] [--dry-run]
+
+Reads a multiline markdown comment from stdin when stdin is piped. This preserves
+newlines when building the JSON payload for PATCH /api/issues/{issueId}.
+
+Examples:
+  scripts/paperclip-issue-update.sh --issue-id "$PAPERCLIP_TASK_ID" --status in_progress <<'MD'
+  Investigating formatting
+
+  - Pulled the raw comment body
+  - Comparing it with the run transcript
+  MD
+
+  scripts/paperclip-issue-update.sh --issue-id "$PAPERCLIP_TASK_ID" --status done --dry-run <<'MD'
+  Done
+
+  - Fixed the issue update helper
+  MD
+EOF
+}
+
+require_command() {
+  if ! command -v "$1" >/dev/null 2>&1; then
+    printf 'Missing required command: %s\n' "$1" >&2
+    exit 1
+  fi
+}
+
+issue_id="${PAPERCLIP_TASK_ID:-}"
+status=""
+comment_arg=""
+dry_run=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --issue-id)
+      issue_id="${2:-}"
+      shift 2
+      ;;
+    --status)
+      status="${2:-}"
+      shift 2
+      ;;
+    --comment)
+      comment_arg="${2:-}"
+      shift 2
+      ;;
+    --dry-run)
+      dry_run=1
+      shift
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      printf 'Unknown argument: %s\n' "$1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [[ -z "$issue_id" ]]; then
+  printf 'Missing issue id. Pass --issue-id or set PAPERCLIP_TASK_ID.\n' >&2
+  exit 1
+fi
+
+comment=""
+if [[ -n "$comment_arg" ]]; then
+  comment="$comment_arg"
+elif [[ ! -t 0 ]]; then
+  comment="$(cat)"
+fi
+
+require_command jq
+
+payload="$(
+  jq -nc \
+    --arg status "$status" \
+    --arg comment "$comment" \
+    '
+      (if $status == "" then {} else {status: $status} end) +
+      (if $comment == "" then {} else {comment: $comment} end)
+    '
+)"
+
+if [[ "$dry_run" == "1" ]]; then
+  printf '%s\n' "$payload"
+  exit 0
+fi
+
+if [[ -z "${PAPERCLIP_API_URL:-}" || -z "${PAPERCLIP_API_KEY:-}" || -z "${PAPERCLIP_RUN_ID:-}" ]]; then
+  printf 'Missing PAPERCLIP_API_URL, PAPERCLIP_API_KEY, or PAPERCLIP_RUN_ID.\n' >&2
+  exit 1
+fi
+
+# A successful PATCH always returns the updated issue JSON. An empty body or a
+# connection-level failure means the write did NOT land, even when a pipeline
+# exit code says otherwise, so verify the response instead of inferring success.
+# Two attempts total: the shared heartbeat policy stops a control-plane write
+# after two consecutive failures, so the helper must not send a third.
+max_attempts=2
+attempt=1
+while :; do
+  http_code=""
+  body=""
+  set +e
+  response="$(
+    curl -sS -m 30 -X PATCH \
+      "$PAPERCLIP_API_URL/api/issues/$issue_id" \
+      -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+      -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
+      -H 'Content-Type: application/json' \
+      --data-binary "$payload" \
+      -w '\n%{http_code}'
+  )"
+  curl_exit=$?
+  set -e
+
+  if [[ "$curl_exit" -eq 0 ]]; then
+    http_code="${response##*$'\n'}"
+    body="${response%$'\n'*}"
+  fi
+
+  if [[ "$curl_exit" -eq 0 && "$http_code" == 2* ]]; then
+    if [[ -z "$body" ]]; then
+      printf 'Issue update FAILED: HTTP %s with an empty response body. A real update echoes the issue JSON; treat this write as not saved.\n' "$http_code" >&2
+      exit 1
+    fi
+    if [[ -n "$status" ]]; then
+      returned_status="$(jq -r '.status // empty' <<<"$body" 2>/dev/null || true)"
+      if [[ "$returned_status" != "$status" ]]; then
+        printf 'Issue update FAILED: server echoed status %s instead of requested %s.\n' "${returned_status:-<none>}" "$status" >&2
+        printf '%s\n' "$body" >&2
+        exit 1
+      fi
+    fi
+    printf '%s\n' "$body"
+    exit 0
+  fi
+
+  # 4xx (other than 429) is a definitive rejection; retrying cannot change it.
+  if [[ "$curl_exit" -eq 0 && "$http_code" == 4* && "$http_code" != "429" ]]; then
+    printf 'Issue update rejected (HTTP %s).\n' "$http_code" >&2
+    [[ -n "$body" ]] && printf '%s\n' "$body" >&2
+    exit 1
+  fi
+
+  if (( attempt >= max_attempts )); then
+    printf 'Issue update FAILED after %d attempts (curl exit %s, HTTP %s). The status/comment was NOT saved — report this write as failed, do not assume it landed.\n' "$max_attempts" "$curl_exit" "${http_code:-000}" >&2
+    [[ -n "$body" ]] && printf '%s\n' "$body" >&2
+    exit 1
+  fi
+
+  printf 'Issue update attempt %d/%d failed (curl exit %s, HTTP %s); retrying...\n' "$attempt" "$max_attempts" "$curl_exit" "${http_code:-000}" >&2
+  sleep $((attempt * 2))
+  attempt=$((attempt + 1))
+done

package/skills/paperclip/scripts/paperclip-upload-artifact.sh

@@ -113,6 +113,17 @@ sha256_text() {
   fi
 }
 
+helper_state_directory() {
+  printf '%s' "${PAPERCLIP_HELPER_STATE_DIR:-${PAPERCLIP_WORKSPACE_CWD:-$PWD}/.paperclip/artifact-helper}"
+}
+
+helper_response_file() {
+  local directory
+  directory="$(helper_state_directory)"
+  # TMPDIR can name a controller-owned directory outside a CLI sandbox.
+  (umask 077; mkdir -p "$directory" && mktemp "$directory/response.XXXXXX")
+}
+
 request_json() {
   local method="$1"
   local url="$2"
@@ -120,7 +131,7 @@ request_json() {
   local response_file
   local status_code
 
-  response_file="$(mktemp)"
+  response_file="$(helper_response_file)"
   if [[ -n "$body" ]]; then
     status_code="$(
       curl -sS -X "$method" -w '%{http_code}' -o "$response_file" \
@@ -163,7 +174,7 @@ upload_file() {
 
   escaped_path="${path//\\/\\\\}"
   escaped_path="${escaped_path//\"/\\\"}"
-  response_file="$(mktemp)"
+  response_file="$(helper_response_file)"
   status_code="$(
     curl -sS -X POST -w '%{http_code}' -o "$response_file" \
       "$url" \
@@ -223,7 +234,7 @@ acquire_operation_lock() {
   local attempts=0
 
   umask 077
-  operation_state_root="${PAPERCLIP_HELPER_STATE_DIR:-${TMPDIR:-/tmp}/paperclip-upload-artifact}"
+  operation_state_root="$(helper_state_directory)"
   mkdir -p "$operation_state_root"
   operation_lock_path="$operation_state_root/$operation_key.lock"
   operation_lock_owner="$$|$(process_start_identity "$$" || true)"

package/skills/paperclip/scripts/submit-agent-commentary.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// One bounded, nonfatal submission. Feedback comes from stdin, never shell arguments.
+import { randomUUID } from "node:crypto";
+
+const MAX_BODY_LENGTH = 524288;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+async function readBounded(stream, maxBytes) {
+  const chunks = [];
+  let bytes = 0;
+  for await (const chunk of stream) {
+    bytes += chunk.length;
+    if (bytes > maxBytes) throw new Error("Input too large");
+    chunks.push(chunk);
+  }
+  return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(Buffer.concat(chunks));
+}
+
+try {
+  const [kind, idempotencyKey = randomUUID()] = process.argv.slice(2);
+  if (kind !== "complaint" && kind !== "suggestion") throw new Error("Invalid kind");
+  // Bound bytes before decoding; JavaScript string length matches the server's ceiling.
+  const body = await readBounded(process.stdin, 4 * MAX_BODY_LENGTH);
+  if (!body.trim() || body.length > MAX_BODY_LENGTH) throw new Error("Invalid body");
+  const { PAPERCLIP_API_URL, PAPERCLIP_API_KEY, PAPERCLIP_COMPANY_ID, PAPERCLIP_RUN_ID } = process.env;
+  if (!PAPERCLIP_API_URL || !PAPERCLIP_API_KEY || !UUID.test(PAPERCLIP_COMPANY_ID ?? "") || !UUID.test(PAPERCLIP_RUN_ID ?? "")) {
+    throw new Error("Missing run context");
+  }
+  const apiUrl = PAPERCLIP_API_URL.replace(/\/+$/, "").replace(/\/api$/, "");
+  const response = await fetch(`${apiUrl}/api/companies/${PAPERCLIP_COMPANY_ID}/agent-commentary`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${PAPERCLIP_API_KEY}`,
+      "X-Paperclip-Run-Id": PAPERCLIP_RUN_ID,
+    },
+    body: JSON.stringify({ kind, body, idempotencyKey }),
+    // Never forward run credentials through redirects. Bound the entire HTTP attempt.
+    redirect: "error",
+    signal: AbortSignal.timeout(10_000),
+  });
+  if (response.status !== 200 && response.status !== 201) {
+    await response.body?.cancel();
+    throw new Error("Submission failed");
+  }
+  const acknowledgement = JSON.parse(await readBounded(response.body, 4096));
+  if (typeof acknowledgement.id !== "string" || !acknowledgement.id) throw new Error("Invalid acknowledgement");
+  console.log("Feedback stored.");
+} catch {
+  // No exception text: transport errors may contain credentials or submitted text.
+  console.error("Feedback could not be confirmed. Ignore this failure, do not retry, and continue the primary task.");
+}

package/skills/paperclip-converting-plans-to-tasks/SKILL.md

@@ -1,60 +1,27 @@
 ---
 name: paperclip-converting-plans-to-tasks
 description: >
-  Convert Paperclip plans into executable issue graphs. Use when asked to plan,
-  scope, or break down Paperclip company work into assigned tasks with specialty
-  fit, dependencies, blockers, and parallelization.
+  Decide whether Paperclip work needs delegation, and connect justified tasks
+  with owners and real dependencies. Use when turning an authorized plan into work.
 ---
 
-# Paperclip — Converting Plans to Tasks
+# Plans to tasks
 
-A companion skill for turning a plan into executable Paperclip work. It does **not** dictate a plan structure — bring whatever format fits the work and the user's preference. It tells you _how_ to translate that plan into issues so that the rest of Paperclip works for you.
+Keep small, cohesive work on its current ordinary task with one end-to-end owner.
+A plan's steps, files, and phases do not each need a task.
 
-For the **mechanics** of recording a plan (issue document with key `plan`, comment links, approval gating, who to reassign back to), follow the _Planning_ section of the `paperclip` skill. This skill covers planning method, not the API surface.
+Create a separate task only for a useful boundary: another owner or permission,
+independent parallel output, a real prerequisite, independent review, or substantial
+follow-up that needs its own lifecycle. Check the available agents before assigning.
+Give each delegate enough context and a clear deliverable to work independently.
 
-## When you're asked to plan
+Set real dependencies through `blockedByIssueIds` (or the native dependency tool).
+Parent/child nesting and prose do not delay execution. Independent work can start
+now; dependent work must wait for its prerequisite. Verify the saved relationships.
 
-- **Plan deeply.** Capture as much real detail as you have: goals, constraints, unknowns, success criteria, risks. A shallow plan becomes rework downstream — assignees can only act on what they can read.
-- **Minimize the issue graph.** Use as few tasks as possible while still completing and verifying the job. Prefer one end-to-end task with one owner over separate tasks for each step, file, component, or phase. Keep those structural details as checklists or acceptance criteria inside the owning task unless a real execution boundary requires another issue.
-- **Split only for a qualifying boundary.** Create a separate subtask only when at least one of these applies:
-  - A different specialist, owner, permission boundary, or external actor must own the work.
-  - A self-contained deliverable can usefully run in parallel with other work.
-  - A hard dependency or handoff needs its own `blockedByIssueIds` lifecycle.
-  - A review, QA pass, or governed approval gate has an independent owner.
-  - Substantial follow-up work needs independent tracking or retry because it cannot safely be completed and verified in the parent.
-- **Know your team.** Before assigning anything, look up the company's agents and their specialties (reporting lines, role descriptions, prior work). Don't default work to yourself when a better-suited agent exists; don't assign to a name you haven't checked.
-- **Assign for specialty.** Hand each piece of work to the agent most relevant to it. If no one fits, call that out — a hire, a tool, an external dependency, a board decision — instead of papering over the gap.
-- **Take responsibility.** Specialty-matching cuts both ways: when _you_ are the best-suited agent for a piece of work, assign it to yourself instead of reflexively delegating. Don't hand off to avoid load.
-- **Use the dependency tree.** Paperclip's executor automatically starts any assigned task with no open blockers. Parent/child issue nesting is structure, not execution blocking. Express each qualifying ownership or lifecycle boundary as an issue; keep other concrete deliverables within the responsible issue's description, checklist, or acceptance criteria. Wire every hard dependency between issues through `blockedByIssueIds` on the dependent issue (not prose like "blocked by X"). When a blocker reaches `done`, dependents auto-wake.
-- **Order, then parallelize.** Sequence work by real dependencies, not by personal preference. Create parallel branches only for qualifying, self-contained work, then start those independent branches in parallel. Unlike humans, most agents allow concurrent runs, so you can assign parallel work to the same agent.
-- **Write review tasks for the reviewer's boundary.** A review/QA task must tell the delegate to post findings on **their own review issue** and mark it `done` — the verdict is the deliverable, and adverse findings are still `done`, not `blocked`. Never instruct a delegate to comment on the parent issue (low-trust reviewers are guaranteed a 403 there), and make the description self-contained since the reviewer may not be able to read your issue. Wire the dependent issue's `blockedByIssueIds` to the review issue so the verdict wakes the right owner.
-- **Enough is enough.** Plans exist to unblock execution, not replace it. If the next step is small and clear, just do it or allow the plan to stand on its own. Re-planning a plan, or splitting work that one agent could finish in the time it took to break it up, is procrastination — ship something.
+Reviewers publish findings on their own review task and complete it, including an
+adverse verdict. Make its description self-contained. Connect the verdict to the
+owner who must act on it; do not require writes to the parent.
 
-## When converting an accepted plan into tasks
-
-Start from one end-to-end task and add issues only for the qualifying boundaries above. Before creating tasks, write a compact task matrix with each proposed task, owner, initial status, blockers, and the specific qualifying reason it must be separate. Any task that can start immediately should say why it has no blockers; otherwise set it to `blocked` and include the prerequisite issue IDs in `blockedByIssueIds`. Do not rely on `parentId`, child ordering, phase labels, or prose to block execution.
-
-Run a merge-back pass before publishing or creating the graph. Require every proposed subtask to name at least one qualifying reason from this skill. If it cannot, merge it into its parent or an adjacent task and preserve the work as an internal step, checklist item, or acceptance criterion. Repeat until every remaining issue has a real ownership, scheduling, lifecycle, or governance reason to exist.
-
-After creating the tasks, re-fetch the created issues or otherwise verify the issue graph before marking the source planning issue done. Confirm that every separate issue still has its qualifying reason, each dependent task has the expected `blockedByIssueIds`, each independent task has an explicit "can start now" reason, review tasks respect the reviewer's write boundary, and the parent/child hierarchy is only being used for traceability. If the graph contains an unjustified split or expected blockers are missing, correct it or report the mismatch and leave the planning issue in `in_review` or `blocked` until the graph is fixed.
-
-## Quick checklist before you publish a plan
-
-- [ ] Enough detail that assignees can act without re-asking.
-- [ ] The plan uses the fewest tasks that can complete and verify the job, preferring one end-to-end owner over step/file/component/phase splits.
-- [ ] Every concrete deliverable is accounted for inside an issue or, only when a qualifying boundary applies, as its own issue.
-- [ ] Every proposed subtask names a qualifying reason; otherwise it was merged into its parent or an adjacent task.
-- [ ] Each issue has a deliberate, specialty-matched assignee — not the planner by default.
-- [ ] Each issue's real blockers are declared via `blockedByIssueIds`.
-- [ ] Independently owned review, QA, and governed approval tasks respect the reviewer's boundary.
-- [ ] A compact task matrix names planned task, owner, initial status, blockers, and qualifying reason.
-- [ ] Tasks without blockers have an explicit reason they can start immediately.
-- [ ] Created issues were re-fetched or otherwise verified before closing the source planning issue.
-- [ ] Qualifying independent branches can start in parallel.
-- [ ] Gaps (missing skills, hires, decisions, external inputs) are surfaced, not hidden.
-
-## What this skill is not
-
-- Not a plan template. Use any format — prose, outline, table, RACI, Gantt, whatever fits.
-- Not software-development–specific. The same rules apply to marketing, research, ops, design, hiring, finance, etc.
-- Not a replacement for the `paperclip` skill's planning mechanics. Use both.
+Honor existing authorization and approval boundaries. Use Paperclip's planning
+mechanics when approval is required; decomposition does not create new approval gates.

package/skills/slack/SKILL.md

@@ -80,3 +80,13 @@ On a Slack-linked task, human messages sent from Paperclip and your final respon
 are mirrored into its Slack thread. Do not manually send the same final response
 again. Ordinary tasks and routines have no automatic Slack destination: perform the
 requested Slack send explicitly and report whether delivery was confirmed.
+
+On a Slack-linked task, when results are ready, include the outcome and accessible
+deliverable links or supported attachments in your final response to the originating
+Slack conversation.
+Do not leave the result only on the Paperclip task. When the user must review a
+plan, approve an action, or review a result, save the artifact and create the
+required review interaction through the normal Paperclip workflow. Tell the user
+what needs review and what action to take in the same Slack conversation. A saved
+plan or an `in_review` status alone is not a review request. Keep approval gates
+in place and do not claim delivery without a successful receipt.

package/skills/suggestion-box/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 Denver Technologies, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Adapted from Warp's suggestion-box skill:
+https://github.com/warpdotdev/common-skills/blob/main/.agents/skills/suggestion-box/SKILL.md
+
+Paperclip adaptations: local attributed storage, native tools, free-form
+suggestions, and document-sized input limits.