Files
PaperClipAI/maps
DottaandClaude Opus 5.5 2eda54162a fix(evals): grade recovery on fresh continuation, accept in-turn queued-comment reads, verify the saved service model (#21210)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The chat eval catalog checks that agents in chat do the right thing,
graded on saved product state and rendered links
> - Full cohort 8 (OpenCode,
`openrouter/deepseek/deepseek-v4.1-flash-1017`, master 7747487ee7)
failed six cases after two deliberate product changes and one harness
race
> - #21135 continues an unfinished run in a fresh run from saved work
instead of leaving an exhausted, board-owned recovery action. Three
recovery cases still waited for that action.
> - #21175 counts a `get_task_history` read of a queued comment's
current revision as delivery. Two steering cases still required a
continuation run.
> - `companies.prompt-injection-guard` read the settings back before its
own save finished
> - This pull request grades the recovery and steering cases on the new
contracts and makes the settings harness verify the saved model before
it continues
> - The benefit is that the evals accept the intended product behavior
and still fail a broken product

## Linked Issues or Issue Description

Refs #21135
Refs #21175

**What happened?**
Cohort 8 failed `recovery.explain-stall`, `recovery.retry-exhausted` and
`recovery.source-action`: the harness waited 30 s for an "exhausted
source recovery action with no automatic wake". #21135 now logs
"Unfinished run continues in a fresh run from saved work" (`trigger:
recovery_refused`, `delivery: recorded`) instead.
`steering.edit-queued-message` and `agent-chat.multiple-handoffs` failed
their run counts: the running worker turn read the queued comment
(current revision) and applied it, so no continuation run was queued.
`companies.prompt-injection-guard` read `openai/gpt-oss-safeguard-20b`:
the server log shows the harness GET finished before the settings PUT.

**Expected behavior**
Infrastructure loss continues automatically in one fresh run, the chat
explains it, and the continuation finishes the task. A queued comment is
consumed once, in the running turn or in one continuation. The settings
harness tests only the model it saved.

**Steps to reproduce**
Run the six `chat-features.runner-opencode.local.*` cases on master
after #21135 and #21175.

## What Changed

- `runtime-infrastructure.ts` (`recovery.explain-stall`,
`recovery.source-action`, oracle `infrastructure-recovery.v6`): after
three real Runner losses, the setup waits for one system-owned
fresh-continuation record of the failed run (`?inspectSourceRunId`),
resolved as `restored`, `replay: "none"`, the failed run marked
superseded, and one run with `retryOfRunId` = the failed run that waits
for its brief in its own workspace. The chat question is asked while it
runs. The harness then releases the brief, and the grade requires the
continuation to succeed, save the brief's reference as the latest
revision and complete the original task. No person-owned hold and no
blocked task at the reply. Three runs: failed 1, succeeded 2. The reply
must still come from a run that read the recovery record (now also the
continuation run) and link the original task. Setup timing is saved to
`runtime-fresh-continuation.json`.
- `runtime-infrastructure-retry.ts` (`recovery.retry-exhausted`, oracle
`retry-exhausted.v6`): an infrastructure loss no longer offers Retry.
The case uses a failure only the person can resolve
(`native_provider_model_rejected`, a `PERSON_OWNED_FAILURE_CODES`
member) and keeps the Retry-under-budget-hold journey unchanged. The
setup proves the task waits blocked with no fresh continuation and no
successor run for 45 s.
- `runtime-busy-worker.ts`: the Retry listener helpers move here; a
listener counts only when its `.waiting` file is newer than the run's
start.
- `runtime-queue.ts`: `historyReadRevisions`, `readCurrentRevision`,
`runHistoryReads` read `task_history.read` events; `settledQueue` needs
a 30 s quiet settled state.
- `runtime-queue-controls.ts` (`steering.edit-queued-message`, oracle
`structural.v5`) and `runtime-multiple-handoffs.ts` (oracle `v5`):
accept in-turn consumption only with a worker `task_history.read` of
every queued comment's current revision, the change saved as the latest
revision (blue; "Launch sooner"), an empty queue, a done task and zero
continuations. The continuation path stays: exactly one continuation
with the unread comments in order, when the turn did not read the
current revision. Run bounds 2–3 and 4–5. The worker brief no longer
tells the agent to leave follow-ups for a continuation.
- `identity-company-models.ts` (`prompt-injection-guard` oracle
`prompt-injection-guard.v2`, `fast-responses` `v4`): before saving,
check the model field holds the requested model; wait for the PUT;
require 200, the sent model, the saved model, then a matching read-back.
- `recovery.yaml`: context and expected outcome for the three recovery
cases. Recorded in `chat-full-catalog-testops-manifest.json`
`changedFields` and pinned in its test. Descriptors and the inventory
digest are updated. `maps/feature-map/recovery.md` exhaustion line
corrected.

## Verification

- `npx vitest run --config tests/runner-e2e/vitest.config.ts
tests/runner-e2e/chat-catalog tests/runner-e2e/chat-catalog-domains`:
283 files, 3895 tests pass. New calibration tests cover valid,
reworded-valid and broken cases: no continuation, a person-owned hold,
two continuation records or runs, a replayed turn, an unfinished
continuation, a missing saved result; an old-revision-only read, a
missing outcome, a double application, two continuations; a model field
that lost the model, a different sent model, a wrong saved model.
- `pnpm test:e2e:runner:typecheck`: pass.
- `node --test
tests/runner-e2e/chat-full-catalog-testops-manifest.test.mjs`: 10/10
pass.
- `node tests/runner-e2e/source-sdk-public-inputs.mjs <head sha>
--check`: `changed: false`.
- `node scripts/check-maps.mjs`: aligned.
- Paid run: Runner Full-Stack E2E 43321773136 at 9de2bd5a6f, six cases:
prompt-injection-guard passed. The two fresh-continuation cases found a
product failure (the continuation never started), fixed in #21217.
retry-exhausted showed that a model-rejected failure offers no Retry
control. multiple-handoffs failed correctly: the turn read the
instruction and did not apply it. edit-queued-message did not reach the
new grade (6-minute CEO turn). Details are in a PR comment.

## Risks

- The recovery cases depend on the fresh continuation starting within 5
minutes. The paid run showed it did not start; #21217 fixes that. Until
#21217 merges, those cases fail on master.
- `recovery.retry-exhausted` expects a Retry control that the product
does not show for a model-rejected failure. It fails until a product
decision is made.
- `recovery.retry-exhausted` no longer covers infrastructure exhaustion;
the two other recovery cases cover the new automatic path.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code with tool use and code execution.

## 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
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 17:26:50 -06:00
..

Paperclip maps

The maps describe the same capabilities from two perspectives:

  • Feature map: what a person can do, where to reach it, and how to verify the user journey. Preserve its Poteto format.
  • Agent access map: the APIs and agent entry points for those capabilities, their permission boundaries, and access verification.

The chat scenario catalog adds natural-language requests, starting context and expected conversational outcomes for the same capability IDs. It lives with Product E2E as planning data; a scenario reference is neither a registered execution nor evidence that a journey passed.

These are sibling directories under maps/. Each feature file has a same-named agent access companion. Reuse the product map's sub-feature IDs, so tasks/create identifies the same capability in both maps. Product behavior remains governed by the code and its tests; a map cannot grant authority or redefine a permission denial as success.

Capability identifiers

The feature ID is the recipe filename without .md, such as onboarding. The full capability ID joins that feature ID and a Sub-features key with /: the company key in feature-map/onboarding.md is onboarding/company. Its agent-access-map/onboarding.md companion uses the same local company key. The feature-map index lists the existing feature and full capability IDs.

Each child page states Feature ID: `onboarding`. after its introduction or product-map link. In feature recipes, show the full ID beside the parsed local key: - `company`: `onboarding/company` — create a company. In access companions and Storybook verification guidance, keep the existing local heading and put Capability ID: `onboarding/company`. beneath it. These labels make the existing identifiers visible without changing keys, anchors, or ID generation.

Use full capability IDs in cross-feature references, Storybook annotations, tests, issues, PRs, and verification evidence. Both segments use lowercase letters, digits, and hyphens. Keep filenames and keys stable when display titles or navigation labels change; renaming either changes the capability ID.

Entry-point IDs describe a surface, such as web-wizard, and are scoped to their recipe. Reference them with a recipe link, such as onboarding.md#web-wizard, and record the capability exercised separately. Navigation section labels are not capability IDs. See IDs and references for examples.

Access contract

Every business operation needs both an API and a usable agent entry point for an actor authorized to perform it. A dedicated tool is optional when REST, the CLI, an assigned MCP client, or native search_api / call_api already provides the operation. Record which agent surfaces actually have that path; an installed CLI or optional MCP package cannot be assumed available to every native/remote run.

Track these independently:

Dimension Values and meaning
API present, missing, not-applicable, or unreviewed. Use exact methods/paths; distinguish protocols from REST.
Agent access available, partial, missing, restricted, operator-only, not-applicable, or unreviewed. Name the supported surface and actual entry point.
Policy Actor, action/grant, company/resource/ownership scope, responsible-user intersection, run requirements, work modes, and gates relevant to the operation.
Evidence source-only, verified, failed, blocked, or not-run. Source presence and successful board calls are not agent verification.
Review depth baseline records representative operations and known gaps; operation-reviewed enumerates the capability's meaningful operations and their individual access contracts.

Broad capabilities such as task properties must be split into operations before they count as operation-reviewed: renaming, metadata edits, assignment, dependencies, and lifecycle changes can use different tools and permission rules. An available read path cannot certify a write path. List/get/create/update/delete, execution/control, credential handling, and resolution are separate where their authority or transport differs. Do not duplicate request schemas from OpenAPI.

Exceptions and restrictions

Presentation-only state, static developer fixtures, and pre-start/local operator work may use not-applicable for a domain API, with a concrete reason and the existing local path. When a capability combines shared data with presentation, split the operations: browser recents do not exempt resource lookup from API coverage. Promoting local state to a shared feature requires revisiting the entry.

A board-only endpoint is restricted for agent identity, not an automatic exception or a missing API. Cite the enforced policy and record whether the agent can request the authorized human's action and observe its result. An unresolved delegation question remains in Gaps. Company access, a job title, a personal assistant's OAuth grant, or an accepted interaction does not grant board identity. Keep budget, approval, secret and execution authority intact.

Check actual route/service authorization and production tool admission. OpenAPI actor labels and scenario/evaluation tool declarations are supporting metadata; record disagreements rather than using them as proof of access. Native API fallback restrictions, tool field/scope limits, and rollout settings are part of the agent path, even when a legacy agent can call the REST endpoint directly.

Companion file format

Each agent-access-map/<area>.md has an H1, a relative link to its product file, and its feature ID, followed by one H2 backticked local key per product sub-feature. Each capability starts with its full capability ID and contains these fields:

  • Review: baseline or operation-reviewed.
  • API: presence state and exact operation IDs, or a reasoned exception.
  • Agent access: availability state and concrete entry points by surface.
  • Policy: relevant permission and runtime boundaries, with source references.
  • Evidence: evidence state, reviewed commit and sources or executed proof.
  • Verification: allowed/denied assertions and observable result; record what has actually run separately from the proposed recipe.
  • Gaps: missing APIs/paths, discovery drift, unreviewed operations or policy decisions; use none only for the enumerated scope that was reviewed.

For an operation-reviewed capability, use H3 backticked operation IDs and repeat API, Agent access, Policy, Evidence, Verification and Gaps for each operation. Use small operation names such as create, update, read, or run-now. The enclosing capability has Review: operation-reviewed only after its meaningful operations have been enumerated. The following excerpt shows one operation; include the others before using that review label:

## `definition`

Review: `operation-reviewed`.

### `create`

API: `present` — POST /api/companies/{companyId}/routines.
Agent access: `available` — agent REST, CLI routine create and native call_api
under the enabled rollout and active-run/mode gates.
Policy: same company; assigneeAgentId must be the calling agent; cite the
routine authorization and native API policy sources.
Evidence: `source-only` — reviewed commit and source links; no live proof.
Verification: `not-run` — create an owned routine; reject assignment to another
agent; inspect saved configuration, attribution and retry behavior.
Gaps: verify ownership and responsible-user resolution with a permitted agent
context; source presence alone does not qualify this operation.

Keeping the maps synchronized

Add entries only for substantial new features under the feature-map scope rule. Routine fixes, polish, refactors, performance work, and test changes do not require map updates. Correct or remove existing text only when behavior or access changes make it materially inaccurate; keep the correction local to the affected recipe or companion. Preserve IDs across renames where the capability is unchanged; update the affected cross-links together. Indexes discover recipes automatically. An API-only change may update the companion without rewriting unchanged user instructions. Update the corresponding chat scenarios when their request, assumptions or expected outcome changes; use multiple cases for meaningfully different starting conditions rather than treating an API path as conversational coverage.

maintain-verification-skill owns reconciliation of both maps. It follows changed source and authorization, checks real agent reachability, and records product gaps without implementing them during a maintenance pass. The creation skill uses this structure. verify-paperclip consumes the relevant recipes and reports evidence/drift; map editing belongs to maintenance.

Run the structural check after map changes:

node scripts/check-maps.mjs

It checks paired areas/IDs, navigation metadata, required fields, and local references. It does not certify endpoint authorization, production bindings, operation completeness, or live behavior. Source audits must check those against the existing API and tool contracts; avoid a second schema catalog or runtime.

For live access proof, use Paperclip's existing API/runner/MCP fixtures or an owned isolated instance. Use the actual agent identity, target and work mode. Assert the allowed result and relevant denial (another company/private resource, wrong owner, missing grant, invalid run, restricted mode or resolver). Mutations also need persisted state/attribution and retry behavior. Capture evidence using the existing artifact workflow; keep executed run results separate from generated maps/generated/coverage.json, which lists page references.

Local authorship and generated indexes

Change only the recipes, access contracts and stories whose behavior or intent changed. Feature recipes own navigation metadata; stories own small parameters.paperclip annotations. Keep the feature-map README's readable ID index aligned with those sources; it does not register entries for generation. Do not refresh counts in shared READMEs, inventories, fingerprints or review journals.

node scripts/storybook-catalog.mjs validates and generates aggregate navigation, Storybook data, verification routes and the page inventory. All outputs live in ignored maps/generated/, ui/storybook/generated/, and the ignored Storybook preview.tsx wrapper. Start/build and UI typechecking generate their own inputs. A clean merged checkout therefore assembles both branches' changes automatically.

Git provides history and diffs. PRs, issues and CI artifacts retain review/run evidence for the named revision. Capability associations do not create whole-file review dependencies. Keep durable scenario limits in the affected recipe or story.