Add task-to-process-doc links

[alexeygrigorev]

Add Task-To-Process-Doc Links

Status: pending
Tags: enhancement, process-docs, work-engine, backend, frontend, data, P0
Depends on: #5
Blocks: first end-to-end workflow issues that need task-to-SOP navigation

Scope

Ship a V1 link between work execution records and process docs using the document registry delivered in #5.

Implement the smallest useful slice:

• Extend work-engine template/task data contracts with optional:
  • sourceDocIds on templates
  • taskDefinitions[].instructionDocId
  • taskDefinitions[].instructionStepId
  • taskDefinitions[].phase
  • taskDefinitions[].systems
  • taskDefinitions[].validation
  • matching task-level fields copied during template instantiation
• Keep instructionsUrl backward compatible, but prefer instructionDocId when both exist.
• Validate shape/type of the new fields in template create/update and task create/update APIs.
• During bundle creation from a template, copy doc-context fields from each task definition onto the created task.
• In the integrated portal task panel, resolve instructionDocId through the Design document registry IDs and resolver #5 docs registry/resolver and show docs-in-context:
  • process doc title
  • doc type/path or summary
  • systems/phase when available
  • action to open the process doc in the portal, not as a raw external URL
• Add a lightweight frontend fallback for unresolved doc IDs: show the stable ID and a clear document-unavailable state without breaking the task panel.
• Seed or update one V1 workflow/template fixture, preferably podcast because Design document registry IDs and resolver #5 seeded podcast stable IDs, so there is a real task with instructionDocId.

Acceptance Criteria

• Template create/update APIs accept and persist sourceDocIds and new task definition doc-context fields.
• Task create/update APIs accept and persist task-level instructionDocId, instructionStepId, phase, systems, and validation.
• Template validation rejects malformed doc-context fields, such as non-string instructionDocId, non-string phase, non-array systems, or non-string/non-object validation payloads.
• Bundle instantiation copies each task definition's doc-context fields onto the created task.
• Existing templates/tasks using only instructionsUrl continue to work unchanged.
• The portal task panel prefers instructionDocId, resolves it through the document registry, and renders a process-doc action that opens the resolved document in the portal.
• If a task has only instructionsUrl, the existing external instructions link remains available.
• If instructionDocId cannot be resolved, the task panel stays usable and clearly shows the unresolved stable ID.
• Automated tests cover API persistence, validation, template-to-task copying, backward compatibility, and task-panel docs-in-context rendering.

Test Scenarios

Scenario: Template task links to a process doc by stable ID

Given: a template task definition has instructionDocId
When: the template is saved
Then: the API response includes the same instructionDocId and does not require a raw instructionsUrl.

Scenario: Bundle instantiation preserves doc context

Given: a template task definition includes instructionDocId, instructionStepId, phase, systems, and validation
When: an operator starts a bundle from that template
Then: each created task includes the same doc-context fields.

Scenario: Operator opens instructions from a task

Given: a task has a resolvable instructionDocId
When: the operator opens the task panel
Then: the panel shows the resolved process doc title and an action to open that doc in the portal.

Scenario: Legacy instruction URL still works

Given: a task has instructionsUrl and no instructionDocId
When: the operator opens the task panel
Then: the current external Open instructions link is still shown.

Scenario: Broken doc ID does not break task execution

Given: a task has instructionDocId: "missing.doc"
When: the operator opens the task panel
Then: the panel shows an unresolved-doc state and still allows normal task actions.

Out of Scope

• Migrating every DataTasks Google Doc URL to registry IDs.
• Cleaning all process-doc frontmatter or adding stable IDs to every doc.
• Building a full template-from-doc importer.
• Creating the complete podcast workflow.
• Deep workflow editor UX for choosing docs from a picker.
• Replacing instructionsUrl entirely.
• Moving work-engine storage into the Python backend.

[alexeygrigorev]

Implemented and shipped in commit 2e87241.

Summary:

• Added task/template doc-context fields: instructionDocId, instructionStepId, phase, systems, validation, and template sourceDocIds.
• Template instantiation now copies doc-context fields onto created tasks.
• The portal task panel now resolves instructionDocId through the document registry, shows the process doc in context, and falls back to legacy instructionsUrl when no doc ID exists.
• Portable export includes and validates the new doc-context fields.
• Seeded the podcast create-document task with a real process-doc link.

Verification:

• npm --prefix work-engine test: 621 passed.
• npm --prefix work-engine run typecheck: passed.
• tests/docs_app/test_frontend_routes_and_links.py: passed.
• docs_app backend metadata tests: passed in tester run.
• git diff --check: passed.
• Deploy DataOps V1 Lambda run 28297991312: passed.
• Manual Validate DataOps Content run 28298080339: passed.

Process note:

• PM accepted the slice and tester passed it. I also tightened _docs/PROCESS.md afterward to make the AI Shipping Labs on-call boundary explicit for future issues.