Route legacy task work to the operational skill and show clickable delivery

Use stock discovery metadata and an actual Markdown document-link example. Clarify the future explicit UI-link fixture and retain the original task request and all measured failures.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

doc/plans/2026-10-02-opencode-skill-routing-link-qualification.md

@@ -0,0 +1,37 @@
+# OpenCode skill routing and clickable delivery — 2026-10-02
+
+**TL;DR: the two matched pairs are pending; the correction has no measured performance result yet.** Prior evidence shows original OpenCode work skipped the operational skill until status recovery, while explicit storage read the skill/reference and saved a document but gave a code-formatted path. The original failures and worse clickable handoff remain recorded in the [prior repair report](2026-10-02-legacy-document-skill-repair.md).
+
+This approved narrow correction expands the operational skill's stock discovery description to include Paperclip task/heartbeat work and document/file delivery. The existing early API recipe asks for a clickable Markdown link, and the reference provides an actual canonical UI link example. The full skill body remains on disk; no default-manual pointer, adapter policy override, full-body injection or native completion tool is added.
+
+| Classic OpenCode case | Pre-correction skill | Corrected skill |
+| --- | --- | --- |
+| Original assigned skill, verbatim request | Pending | Pending |
+| Explicit Paperclip storage with clarified clickable UI link | Pending | Pending |
+
+Both variants use the same original request and a future explicit request naming the clickable company-prefixed Paperclip UI link its oracle already checks. Bare paths and code-formatted paths fail calibration; saved content/revision and correct relative/same-app absolute links remain independent evidence. Historical API-link grades are not retroactively changed. Explicit results from this clarified fixture are not a direct repeat of the earlier usable-link wording.
+
+The tiny manual/shared prompts, native Codex fix #14920, models, effort, auth,
+permissions, tools, fixtures and behavioral graders are fixed in both variants.
+Only the two operational skill source files differ. First-assignment skill
+selection and reference reads will be reported separately from recovery; a model
+can still omit stock skill selection despite the improved metadata.
+
+The bounded comparison selects only these two classic OpenCode cells per
+variant, four expected provider turns total, on separate frozen concurrency
+targets. Exact-source credential-free admission must pass before provider
+credentials. Existing hard stops and cleanup remain intact. No broad matrix or
+native provider rerun is part of this correction.
+
+Discovery delivery is verified for existing classic Codex/Claude/OpenCode and
+ACP Codex skill mounts. ACP Claude's names/root-only advertisement is a separate
+metadata follow-up. Hermes/Pi are not live-qualified here; custom ACP and OpenClaw
+have different delivery contracts. Hiring templates are owned by a separate
+implementation and are unchanged by this qualification.
+
+Local preparation passes 918 E2E support tests and eight canonical inventory
+calibrations. Both capability inventories now use one declared skill-source
+list, including issue-documents.md; their existing heading parsing scopes are
+preserved. Skill validation passes. Final exact-source type/discovery/preflight,
+source freeze and protected runner dispatch remain pending. All prior failures,
+automatic recovery and costs remain retained; both PRs remain draft.

doc/plans/2026-10-02-stock-harness-paperclip-checklist.md

@@ -246,7 +246,25 @@ Starting points: [onboarding assets](../../server/src/onboarding-assets/),
 [hiring skill and references](../../skills/paperclip-create-agent/),
 [teams catalog](../../packages/teams-catalog/catalog/).
 
-Decision: per-template disposition and migration policy pending.
+Dotta approved hiring implementation; it is ongoing in a separate branch from
+master. The hiring work owns its skill/references, CEO/CoS assets and team
+catalog. This qualification branch does not change those files.
+
+The read-only audit found four onboarding CEO files (1,897 words), a 164-word
+CoS manual, four role examples (coder 652, QA 619, UX 1,325, security 1,724 words),
+and eight team-catalog manuals. Hiring step 6, the 60–150-line role guide and
+review checklist would regenerate the removed operating policies.
+
+- [ ] **3.1** Reduce role drafting rules, coder/adapted hire examples and matching
+  catalog coder, preserving metadata, auth, permissions and skill selections.
+- [ ] **3.2** Reduce the CEO bundle/copy, including forced delegation, hiring,
+  memory and repeated API recipes.
+- [ ] **3.3** Review remaining roles/catalog and CoS copy.
+- [ ] **3.4** Review specialized built-in/plugin contracts separately; retain
+  product-required behavior rather than assuming every rule is redundant.
+
+Custom and existing bundles and governance remain deliberate rollout boundaries.
+Separate hiring PR/branch link and prompt diffs are pending.
 
 ## 4. Fix repository context while retaining Paperclip configuration
 
@@ -424,6 +442,7 @@ will address them. Record intentional behavior explicitly rather than as a bug.
 - F18: Native blocker browser assertion required a marker-only reply despite asking for owner/action/reason. Correct marker-plus-explanation checks symmetrically, calibrate contradictory and future-condition replies, retain original verdicts.
 - F19: Original prompt-removal cohorts loaded Paperclip; OpenCode skill truncation omitted the late API recipe. The early repair fixed Claude in one paired trial. In the repaired original OpenCode assignment, Paperclip was first loaded only during disposition recovery after a local-file write. Shared legacy operational-skill delivery/selection needs review before more recipe expansion.
 - F20: Explicit repaired OpenCode reads the early recipe/reference and saves a public document/revision, but hands off a code-formatted path rather than a clickable anchor. Baseline provides a clickable API URL, rejected by the UI-only oracle. Preserve both grades; clarify future clickable UI-link fixture and review the smallest link example separately.
+- F22: Legacy operational skill mounting is already mandatory, but its discovery description omitted ordinary task/heartbeat work and document delivery. The approved narrow fix expands stock metadata selection and adds a real Markdown link example in the existing reference. Original + clarified-explicit OpenCode paired qualification is pending; no full-body injection or native-tool leakage. ACP Claude names-only metadata, custom ACP unsupported delivery, OpenClaw wrappers and Pi HOME differences remain distinct follow-ups.
 - F21: Skill heading insertion shifted both generated capability inventories. General CI caught stale metadata after the frozen repair campaign’s narrower build admitted providers. Regenerate canonical derived files and require stale-manifest/inventory checks before future provider admission.
 
 For each completed item, add the chosen behavior, changed paths, verification

skills/paperclip/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: paperclip
 description: >
-  Interact with the Paperclip control plane API for task coordination and
-  governance. Use when checking assignments, updating issue status, posting
-  comments, delegating work, managing routines, or calling Paperclip API
-  endpoints.
+  Use for Paperclip-managed tasks and heartbeats: reading task context, delivering
+  task documents or files, updating completion or blockers, coordinating or
+  delegating work, and following company governance. Includes control plane API
+  operations for assignments, comments, approvals, and routines.
 ---
 
 # Paperclip Skill
@@ -15,7 +15,7 @@ You run in **heartbeats** — short execution windows triggered by Paperclip. Ea
 
 In Paperclip, **task** and **issue** refer to the same work item. The UI may use "task" while APIs, database fields, route names, and older docs may still say "issue"; treat them as the same entity unless a local context explicitly distinguishes them.
 
-**Task documents (API runtimes).** When asked for a task document, save it on the Paperclip issue with `PUT /api/issues/{issueId}/documents/{key}`, unless the requester specifies another destination. Confirm the returned document's saved revision and link it before reporting completion; read [references/issue-documents.md](references/issue-documents.md) for the payload and revision-safe updates. Downloadable files follow [Generated Artifacts and Work Products](#generated-artifacts-and-work-products).
+**Task documents (API runtimes).** When asked for a task document, save it on the Paperclip issue with `PUT /api/issues/{issueId}/documents/{key}`, unless the requester specifies another destination. Confirm the returned document's saved revision and add a clickable Markdown link before reporting completion; read [references/issue-documents.md](references/issue-documents.md) for the payload and revision-safe updates. Downloadable files follow [Generated Artifacts and Work Products](#generated-artifacts-and-work-products).
 
 ## Authentication
 

skills/paperclip/references/issue-documents.md

@@ -32,10 +32,10 @@ with the saved document JSON. Check its `key`, `body`, and `latestRevisionId`
 before claiming delivery. This receipt is sufficient; another GET is unnecessary
 when it confirms the intended content and a saved revision.
 
-Link the returned document key in the completion comment or response:
-`/<prefix>/issues/<issue-identifier>#document-<returned-key>`.
-Use the returned key because a locked document can redirect an agent's write
-to a new document.
+Add a clickable Markdown link in the completion comment or response:
+Saved [Task report](/PAP/issues/PAP-123#document-report).
+Use the prefix from the current issue identifier and the key from the write receipt;
+a locked document can redirect an agent's write to a new document.
 
 ## Update or resolve an unclear write
 

tests/runner-e2e/context-integrity-cases.ts

@@ -28,7 +28,7 @@ export function contextIntegrityScenario(id: string, nonce: string) {
       id === "ordered-comment-continuation"
         ? `Maintain a packing list report document. Start with the initial scope: passport and charger. Save the initial report and leave this task waiting for follow-up comments. When follow-up comments arrive, copy each user's exact wording verbatim into one ordered ledger, including identical wording repeated more than once. After the follow-up batch, save one report containing both initial items and every verbatim request in arrival order. Add a separate section headed "## Final scope" outside the quoted ledger. Put only the final requested scope name as plain text in that section. Then finish. Do not invent extra comments, child tasks, or deliverables.`
         : id === PAPERCLIP_DOCUMENT_CASE
-          ? "Use the assigned Context integrity output skill. Save its requested document as a Paperclip document on this task, check the saved revision and content, and post a completion comment linking the saved document. A workspace file alone does not deliver this requested Paperclip document. Finish after delivery. Do not create child tasks or unrelated deliverables."
+          ? "Use the assigned Context integrity output skill. Save its requested document as a Paperclip document on this task, check the saved revision and content, and post a completion comment with a clickable Markdown link to the saved document in the Paperclip task UI, including the company prefix. A workspace file alone does not deliver this requested Paperclip document. Finish after delivery. Do not create child tasks or unrelated deliverables."
           : "Use the assigned Context integrity output skill for this task, then follow its instructions and finish the task. Do not create child tasks or unrelated deliverables.",
     comments: [repeated, repeated, changed] as const,
   };

tests/runner-e2e/paperclip-document.test.ts

@@ -24,6 +24,8 @@ describe("explicit Paperclip document delivery", () => {
     const { scenario, initial, final } = recording();
     expect(gradeContextIntegrity({ ...scenario, checkpoints: [initial, final] }).every(row => row.passed)).toBe(true);
     expect(scenario.prompt).toContain("Paperclip document");
+    expect(scenario.prompt).toContain("clickable Markdown link");
+    expect(scenario.prompt).toContain("Paperclip task UI");
     expect(scenario.prompt).not.toContain(scenario.marker);
   });
   it.each(["https://paperclip.example/DOC/issues/DOC-1#document-report", "<https://paperclip.example/DOC/issues/DOC-1#document-report>"])("accepts the same-app document link %s", target => {
@@ -31,12 +33,14 @@ describe("explicit Paperclip document delivery", () => {
     final.comments[0]!.body = `Saved [report](${target}).`;
     expect(gradeContextIntegrity({ ...scenario, checkpoints: [initial, final] }).every(row => row.passed)).toBe(true);
   });
-  it.each(["local-only", "missing-revision", "wrong-content", "local-link", "wrong-document-link", "other-app-link", "user-link-only"])(
+  it.each(["local-only", "missing-revision", "wrong-content", "local-link", "wrong-document-link", "other-app-link", "user-link-only", "bare-path", "code-formatted-path"])(
     "rejects plausible %s delivery", variant => {
       const { scenario, initial, final } = recording();
       if (variant === "local-only") { final.documents = []; final.comments[0]!.body = "Saved report.md in the workspace."; }
       if (variant === "missing-revision") final.documents[0]!.latestRevisionId = null;
       if (variant === "wrong-content") final.documents[0]!.body = "A different report";
+      if (variant === "bare-path") final.comments[0]!.body = "Saved /DOC/issues/DOC-1#document-report.";
+      if (variant === "code-formatted-path") final.comments[0]!.body = "Saved `/DOC/issues/DOC-1#document-report`.";
       if (variant === "local-link") final.comments[0]!.body = "Saved [report](./report.md).";
       if (variant === "wrong-document-link") final.comments[0]!.body = "Saved [report](/DOC/issues/DOC-1#document-other).";
       if (variant === "other-app-link") final.comments[0]!.body = "Saved [report](https://other.example/DOC/issues/DOC-1#document-report).";