DottaandPaperclip
c32e1ba6da
## Thinking Path > - Paperclip manages work through tasks, agent runs, dependencies, and human decisions. > - The first-task workflow asks for approval before it creates an execution task. > - File-producing work must run on a child task before onboarding can finish. > - A child blocked by its onboarding source cannot start while the source waits for that child. > - This change rejects that dependency during task creation and later edits, and gives the agent a correction. > - The shipped recipe shows the dependency direction and requires the actual approved inputs in the child instructions. ## Linked Issues or Issue Description **What happened?** After human approval, an onboarding run could create a child with the onboarding source in `blockedByTaskIds`. Creation saved a blocked child with no wake. The parent could then wait for that child. A handoff could also refer to input from the parent conversation without including the input in the child description. **Expected behavior** The approved child can execute before its waiting parent. Invalid first-task dependency input fails before task creation and leaves the same command key available for a corrected call. The child instructions include the required approved input and constraints. **Steps to reproduce** 1. Accept a proposal on a server-created first task. 2. Call native `create_task` with `status: "todo"` and the onboarding source in `blockedByTaskIds`. 3. Observe a blocked child with no scheduled wake. Block the parent on that child to expose the stalled handoff. **Paperclip version or commit** The regression reproduces on `f8484a9f8d1f68e9534fee4f29e00e716dc680f4`. The repair is based on current master. **Deployment mode** Core native and REST task creation. The same server boundary serves self-hosted and hosted instances. Related: #18080 fixed remote delivery of the selected first-task skill. This change handles the later child handoff boundary. ## What Changed - Reject a task blocked by its authenticated first-task source during creation and later dependency edits. Later agent edits also check the locked target's server-owned onboarding parent, protecting a child running under its own execution. Compare UUID identity in PostgreSQL so alternate supported UUID spellings cannot bypass the check. The error explains the correction. - Add a native child/dependency recipe with self-contained approved input guidance. Clarify the general `create_task` input descriptions and update their generated contracts. - Cover native and REST rejection, corrected retry, preserved valid dependencies and replay, and an executable recipe with exact input bytes read from the child's own context. Thread the authenticated run through native dependency edits. Keep blocker corrections independent of a new proposal decision. - Update execution semantics and the existing onboarding map entries. ## Verification - Red on `f8484a9f`: the new native regression received a created blocked child instead of the expected rejection. - Review regressions were red on the original PR head: uppercase, unhyphenated and braced source UUIDs created blocked children; a later child PATCH returned 200 and saved the reversed blocker. - Review follow-up reproduced both native and REST child-own-run bypasses on `75fa75a6`: the native dependency call applied the reverse edge; the child's own PATCH returned 200. The regression uses the actual authenticated child execution and an already checked-out task. - All 95 tests across first-task admission, assets, and the full native tool-authority suite pass. The shipped recipe is validated against the native schemas and exercised through real task/dependency services with disposable PostgreSQL. Rejected PATCH tests preserve existing authorization and attempt-audit behavior and require no requested task-field, relation or wake change. Compatibility controls retain ordinary manual parent blockers, explicit board edits, other blockers and empty-list corrections. - Runner TypeScript build, generated contracts, capability inventory, protocol manifest, and map checks passed. - Server typecheck and all 95 focused tests pass with the child-run follow-up. All latest checks pass on `f24509ae`: 55 successful checks, one neutral review check, four skipped checks, and a successful legacy security status. Both automated reviews are 5/5 on this exact commit. - Prior-head CI failures are preserved: the Runner close fixture had unconfirmed provider drain while suspension succeeded; its exact fake-provider subprocess row passed locally with unchanged sources. The browser outage test lost its title textarea before any outage write. A bounded local control with a fully loaded composer passed every original outage assertion. The prior failure is an editor-readiness race; its exact asynchronous ordering remains unproved. No UI, browser-test, or timeout change is included. Neither failure is counted as a pass or silently discarded. - The first `f24509ae` CI attempt had two interrupted jobs: Typecheck and General server 9/12. Their logs record runner shutdown signals. The server job also records lost runner communication. The same-head failed-job rerun passed both jobs and the required aggregate. It reused the other successful results. No source, test, or timeout change was made for the rerun. The failed attempt remains preserved. Full repository checks pass in CI; the local full repository typecheck, test, and build commands were not repeated. - No external model or provider calls are used by these checks. Real-provider acceptance at this revision remains separate. ## Risks - The new rejection uses the authenticated run and the server-owned onboarding origin. Ordinary tasks, other blockers, empty-list corrections, and already committed creation replay retain their existing behavior. Blocker edits do not reapply the creation approval gate. - Nonempty blocker edits perform two indexed identity reads; the task lookup covers at most the run source and locked structural parent. Other patches and empty-list corrections add no source lookup. The update guard adds no parent row lock behind a child. Existing REST authorization checkout and attempt auditing remain in place before the domain mutation guard. - The explicit input recipe guides the model. Schema and persistence tests do not prove that a future model follows every instruction. - The tool guidance changes the generated semantic catalog identity. The maintained generated files are synchronized in this change. ## Model Used OpenAI `gpt-6.1-sol` through Codex, with `ultra` reasoning effort, repository tools, code generation, and test execution. The context window is not exposed by the runtime. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used and stated the available runtime detail - [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 described the issue in-PR following the bug issue template - [x] I have not referenced internal or instance-local Paperclip issues or links - [x] My branch name describes the change and contains no internal ticket ID - [x] I have run focused 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 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>
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 implementation spec; 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:
baselineoroperation-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
noneonly 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
When a change adds/removes a capability or changes its behavior, API, permission, tool binding, CLI support, or work mode, update the affected companion and product recipe as appropriate in the same change. 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.