0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-10 01:24:44 +02:00

Files

T

DottaandPaperclip bacc0e6a98 docs: remove automatic agent escalation from coordination skill (#14188 )

## Thinking Path

> - Paperclip manages work for AI agents.
> - The coordination skill tells agents how to handle blocked work.
> - The skill directs blocked work to managers and other agents.
> - Those agents may lack the same access or authority.
> - These extra assignments delay the required human action.
> - This pull request removes automatic escalation advice.
> - Agents must identify the missing capability and use the correct
approval or human-input path.

## Linked Issues or Issue Description

**Issue type**

Incorrect information.

**Where is the issue?**

The critical rules in `skills/paperclip/SKILL.md` and blocker guidance
in `skills/paperclip/references/api-reference.md`.

**What's wrong?**

The skill tells agents to escalate through `chainOfCommand`, ask another
agent for help, and avoid human help. A manager title does not grant
permission to fix a connection or complete an administrator action.

**Suggested fix**

Remove blanket escalation and agent-first rules. Keep normal delegation
when the recipient has a concrete capability for a bounded task. Use
saved human-input interactions or existing connection and approval flows
for human-only actions.

Searches for open PRs with “escalation”, “chainOfCommand”, and “ask
another agent” found no duplicate skill change. Recovery-routing PRs
change server behavior, which is outside this change.

## What Changed

- Remove the chain-of-command escalation rule and both repeated
agent-first directives.
- Replace manager handoffs in the API reference with direct blocker
handling.
- Keep reporting fields, normal delegation, approval gates, and the ban
on bypassing permission denials.
- Keep the ban on cancelling cross-team tasks. Request a decision
instead of automatically assigning the task to a manager.

## Verification

- Final head `1483e82cc3fe10a7c910230b3779635d6d54c162`: Greptile 5/5,
no outstanding findings, all CI checks pass (optional Storybook jobs
skipped).

- Created a fresh worktree at `.worktrees/skill-blocker-guidance` from
the current master commit.
- Ran `git diff --check`: passed.
- Ran Node assertions against both documents: passed. Removed directives
are absent. Human-input and capability-based delegation guidance is
present.
- Checked that checkout conflict, approval, dependency, and normal
delegation instructions remain.
- Attempted `pnpm -r typecheck`, `pnpm test:run`, and `pnpm build`. None
could run because this environment has no `pnpm` executable.
- Refreshed both generated capability inventories and their derived
contract after skill heading positions changed. Both generator and
live-inventory checks pass. The eval and MCP baselines remain unchanged.
- Ran `node --test
packages/paperclip-runner/scripts/check-capability-inventory.test.mjs`:
all four tests pass.
- Ran `node
packages/paperclip-runner/scripts/check-capability-inventory.mjs` and
`node packages/paperclip-runner/scripts/generate-capability-contract.mjs
--check`: both pass.
- Added explicit requester routing for agent and human scope questions.
Focused Node assertions pass.

## Risks

- Agents can request human input earlier for actions that require human
authority.
- Existing runs or installed copies can keep old skill text until
refreshed.
- This change does not alter server recovery routing or permission
checks.

## Model Used

OpenAI Codex, with reasoning, tool use, and shell execution. The runtime
does not expose a verifiable exact model ID or context window size.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

2026-09-28 08:37:26 -05:00

29 KiB

Raw Permalink Blame History

Capability Capability Contract

This generated contract is a self-contained derivative of the Paperclip skill, its seven references, the Paperclip Evals corpus, and the legacy MCP tool surface. It does not import or contact the Paperclip control plane.

The skill/reference inventory and eval cases are the only normative behavior sources. Paperclip does not use the legacy MCP calls as a production capability surface; all MCP names below are traceability aliases folded into normative eval rows. Their disposition, grants, assertions, and evidence contract are inherited from the target row rather than classified independently.

Baseline Counts

Skill/reference headings: 155
Eval cases: 106 across 16 groups
Total normative rows: 261
Legacy MCP aliases folded into normative rows: 42

Eval group	Cases
hb	5
co	6
st	8
cm	6
se	4
su	4
bl	5
dp	3
ix	9
ap	6
ar	4
er	9
rf	22
mh	4
rs	3
wk	8

Regeneration

pnpm --dir packages/paperclip-runner generate:capability-inventory imports the canonical baselines and rewrites every generated file.
pnpm --dir packages/paperclip-runner check:capability-inventory validates counts, uniqueness, normative dispositions, one-to-one MCP folds, required fields, and generated-file drift without requiring the external eval repository.

Skill / Reference Rows

Legacy MCP Alias Index

This is a compatibility/traceability index, not a tool catalog. “Inherited disposition” is shown only to make the normative target easy to audit.

Legacy MCP name	Folded into normative row	Inherited disposition	Source anchor
paperclipMe	eval:hb-inbox-lite-01	control_plane_owned	packages/mcp-server/src/tools.ts:290
paperclipInboxLite	eval:hb-inbox-lite-01	control_plane_owned	packages/mcp-server/src/tools.ts:296
paperclipListAgents	eval:rf-api-mgr-heartbeat-01	optional_agent_tool	packages/mcp-server/src/tools.ts:302
paperclipListSkills	eval:rf-cskill-audit-01	optional_agent_tool	packages/mcp-server/src/tools.ts:308
paperclipGetAgent	eval:rf-api-mgr-heartbeat-01	optional_agent_tool	packages/mcp-server/src/tools.ts:314
paperclipListIssues	eval:se-q-filters-01	optional_agent_tool	packages/mcp-server/src/tools.ts:323
paperclipGetIssue	eval:se-get-issue-01	optional_agent_tool	packages/mcp-server/src/tools.ts:338
paperclipGetHeartbeatContext	eval:hb-context-01	control_plane_owned	packages/mcp-server/src/tools.ts:344
paperclipListComments	eval:se-get-issue-01	optional_agent_tool	packages/mcp-server/src/tools.ts:353
paperclipGetComment	eval:hb-wake-comment-01	control_plane_owned	packages/mcp-server/src/tools.ts:366
paperclipListIssueApprovals	eval:ap-board-approval-01	optional_agent_tool	packages/mcp-server/src/tools.ts:373
paperclipListDocuments	eval:dp-base-revision-01	always_agent_tool	packages/mcp-server/src/tools.ts:379
paperclipGetDocument	eval:dp-base-revision-01	always_agent_tool	packages/mcp-server/src/tools.ts:385
paperclipListDocumentRevisions	eval:dp-base-revision-01	always_agent_tool	packages/mcp-server/src/tools.ts:392
paperclipListProjects	eval:rf-wf-project-setup-01	optional_agent_tool	packages/mcp-server/src/tools.ts:402
paperclipGetProject	eval:rf-wf-project-setup-01	optional_agent_tool	packages/mcp-server/src/tools.ts:408
paperclipGetIssueWorkspaceRuntime	eval:rf-iws-start-url-01	optional_agent_tool	packages/mcp-server/src/tools.ts:417
paperclipControlIssueWorkspaceServices	eval:rf-iws-start-url-01	optional_agent_tool	packages/mcp-server/src/tools.ts:423
paperclipWaitForIssueWorkspaceService	eval:rf-iws-target-restart-01	optional_agent_tool	packages/mcp-server/src/tools.ts:440
paperclipListGoals	eval:su-parent-goal-01	optional_agent_tool	packages/mcp-server/src/tools.ts:466
paperclipGetGoal	eval:su-parent-goal-01	optional_agent_tool	packages/mcp-server/src/tools.ts:472
paperclipListApprovals	eval:ap-approval-wake-01	optional_agent_tool	packages/mcp-server/src/tools.ts:478
paperclipCreateApproval	eval:ap-board-approval-01	optional_agent_tool	packages/mcp-server/src/tools.ts:487
paperclipGetApproval	eval:ap-approval-wake-01	optional_agent_tool	packages/mcp-server/src/tools.ts:496
paperclipGetApprovalIssues	eval:ap-approval-wake-01	optional_agent_tool	packages/mcp-server/src/tools.ts:502
paperclipListApprovalComments	eval:ap-approval-deny-01	optional_agent_tool	packages/mcp-server/src/tools.ts:508
paperclipCreateIssue	eval:su-parent-goal-01	optional_agent_tool	packages/mcp-server/src/tools.ts:514
paperclipUpdateIssue	eval:st-done-comment-01	always_agent_tool	packages/mcp-server/src/tools.ts:521
paperclipCheckoutIssue	eval:co-body-contract-01	control_plane_owned	packages/mcp-server/src/tools.ts:528
paperclipReleaseIssue	eval:er-release-01	control_plane_owned	packages/mcp-server/src/tools.ts:540
paperclipAddComment	eval:cm-multiline-01	always_agent_tool	packages/mcp-server/src/tools.ts:546
paperclipSuggestTasks	eval:ix-suggest-tasks-01	always_agent_tool	packages/mcp-server/src/tools.ts:553
paperclipAskUserQuestions	eval:ix-questions-01	always_agent_tool	packages/mcp-server/src/tools.ts:565
paperclipRequestConfirmation	eval:ix-confirmation-plan-01	always_agent_tool	packages/mcp-server/src/tools.ts:577
paperclipRequestCheckboxConfirmation	eval:ix-checkbox-01	always_agent_tool	packages/mcp-server/src/tools.ts:589
paperclipUpsertIssueDocument	eval:dp-plan-doc-01	always_agent_tool	packages/mcp-server/src/tools.ts:601
paperclipRestoreIssueDocumentRevision	eval:dp-base-revision-01	always_agent_tool	packages/mcp-server/src/tools.ts:612
paperclipLinkIssueApproval	eval:ap-board-approval-01	optional_agent_tool	packages/mcp-server/src/tools.ts:627
paperclipUnlinkIssueApproval	eval:ap-board-approval-01	optional_agent_tool	packages/mcp-server/src/tools.ts:636
paperclipApprovalDecision	eval:ap-approval-wake-01	optional_agent_tool	packages/mcp-server/src/tools.ts:646
paperclipAddApprovalComment	eval:ap-approval-deny-01	optional_agent_tool	packages/mcp-server/src/tools.ts:668
paperclipApiRequest	eval:rf-api-404-report-01	optional_agent_tool	packages/mcp-server/src/tools.ts:677

Capability	Primary disposition	Source anchor
skill:skills/paperclip/SKILL.md:paperclip-skill:10	optional_agent_tool	skills/paperclip/SKILL.md:10
skill:skills/paperclip/SKILL.md:terminology:14	optional_agent_tool	skills/paperclip/SKILL.md:14
skill:skills/paperclip/SKILL.md:authentication:18	control_plane_owned	skills/paperclip/SKILL.md:18
skill:skills/paperclip/SKILL.md:conversation-tasks:30	optional_agent_tool	skills/paperclip/SKILL.md:30
skill:skills/paperclip/SKILL.md:server-verified-external-chat-turns:47	control_plane_owned	skills/paperclip/SKILL.md:47
skill:skills/paperclip/SKILL.md:the-heartbeat-procedure:87	optional_agent_tool	skills/paperclip/SKILL.md:87
skill:skills/paperclip/SKILL.md:generated-artifacts-and-work-products:159	always_agent_tool	skills/paperclip/SKILL.md:159
skill:skills/paperclip/SKILL.md:status-quick-guide:207	control_plane_owned	skills/paperclip/SKILL.md:207
skill:skills/paperclip/SKILL.md:monitors-and-watchers-say-only-what-you-actually-scheduled:217	optional_agent_tool	skills/paperclip/SKILL.md:217
skill:skills/paperclip/SKILL.md:delegating-review-tasks:230	always_agent_tool	skills/paperclip/SKILL.md:230
skill:skills/paperclip/SKILL.md:managing-a-user-s-inbox:241	control_plane_owned	skills/paperclip/SKILL.md:241
skill:skills/paperclip/SKILL.md:issue-dependencies-blockers:249	control_plane_owned	skills/paperclip/SKILL.md:249
skill:skills/paperclip/SKILL.md:requesting-board-approval:274	optional_agent_tool	skills/paperclip/SKILL.md:274
skill:skills/paperclip/SKILL.md:issue-thread-interactions:295	optional_agent_tool	skills/paperclip/SKILL.md:295
skill:skills/paperclip/SKILL.md:standalone-decisions:324	optional_agent_tool	skills/paperclip/SKILL.md:324
skill:skills/paperclip/SKILL.md:mcp-tool-approval-gates:428	optional_agent_tool	skills/paperclip/SKILL.md:428
skill:skills/paperclip/SKILL.md:niche-workflow-pointers:470	optional_agent_tool	skills/paperclip/SKILL.md:470
skill:skills/paperclip/SKILL.md:cases:480	optional_agent_tool	skills/paperclip/SKILL.md:480
skill:skills/paperclip/SKILL.md:company-skills-workflow:485	optional_agent_tool	skills/paperclip/SKILL.md:485
skill:skills/paperclip/SKILL.md:routines:496	optional_agent_tool	skills/paperclip/SKILL.md:496
skill:skills/paperclip/SKILL.md:issue-workspace-runtime-controls:507	optional_agent_tool	skills/paperclip/SKILL.md:507
skill:skills/paperclip/SKILL.md:proposing-credentials-safely:514	optional_agent_tool	skills/paperclip/SKILL.md:514
skill:skills/paperclip/SKILL.md:reading-granted-secrets:521	optional_agent_tool	skills/paperclip/SKILL.md:521
skill:skills/paperclip/SKILL.md:critical-rules:547	optional_agent_tool	skills/paperclip/SKILL.md:547
skill:skills/paperclip/SKILL.md:comment-style-required:567	always_agent_tool	skills/paperclip/SKILL.md:567
skill:skills/paperclip/SKILL.md:update:599	optional_agent_tool	skills/paperclip/SKILL.md:599
skill:skills/paperclip/SKILL.md:planning-required-when-planning-requested:609	optional_agent_tool	skills/paperclip/SKILL.md:609
skill:skills/paperclip/SKILL.md:key-endpoints-hot-routes:642	optional_agent_tool	skills/paperclip/SKILL.md:642
skill:skills/paperclip/SKILL.md:searching-issues:671	optional_agent_tool	skills/paperclip/SKILL.md:671
skill:skills/paperclip/SKILL.md:full-reference:681	optional_agent_tool	skills/paperclip/SKILL.md:681
skill:skills/paperclip/references/artifacts.md:generated-artifacts-and-work-products:1	always_agent_tool	skills/paperclip/references/artifacts.md:1
skill:skills/paperclip/references/artifacts.md:workspace-only-file-references:15	optional_agent_tool	skills/paperclip/references/artifacts.md:15
skill:skills/paperclip/references/cases.md:cases:1	optional_agent_tool	skills/paperclip/references/cases.md:1
skill:skills/paperclip/references/cases.md:core-model:12	optional_agent_tool	skills/paperclip/references/cases.md:12
skill:skills/paperclip/references/cases.md:upsert-semantics:29	optional_agent_tool	skills/paperclip/references/cases.md:29
skill:skills/paperclip/references/cases.md:read-and-search:67	optional_agent_tool	skills/paperclip/references/cases.md:67
skill:skills/paperclip/references/cases.md:documents:90	always_agent_tool	skills/paperclip/references/cases.md:90
skill:skills/paperclip/references/cases.md:fields:118	optional_agent_tool	skills/paperclip/references/cases.md:118
skill:skills/paperclip/references/cases.md:issue-links:151	optional_agent_tool	skills/paperclip/references/cases.md:151
skill:skills/paperclip/references/cases.md:child-cases:176	optional_agent_tool	skills/paperclip/references/cases.md:176

29 KiB Raw Permalink Blame History