Repository navigation
Extend process docs with stable IDs #33
Description
Extend process docs with stable IDs
Status: pending
Tags: enhancement, docs, process-docs, backend, work-engine, testing, data, P0
Depends on: None
Blocks: #34, #36, #37, #38, #39
Scope
Add a stable document identity policy and the first implementation slice for process documents that are used by DataOps workflows.
The current docs conventions already describe frontmatter IDs, and the docs registry can generate fallback IDs from paths. That fallback is not enough for V1 workflow execution because task templates and runtime tasks need process-document references that survive file renames, repo moves, and the future dataops-knowledge split described in docs/decisions/dataops-knowledge-repository.md.
This issue should make stable IDs an explicit contract for workflow-critical process docs and migrate the first priority set. The implementer should inspect and update the relevant documentation and code paths, especially:
.goal-v1.md_docs/PROCESS.md_docs/MERGE_PLAN.mdPROJECT_PLAN.mdPORTAL_ANALYSIS.mddocs/STRUCTURE.mddocs/sop-format.mddocs/local-development.mddocs/decisions/dataops-knowledge-repository.mddocs/v1-workflow-data-model.mdcontent/tasks/templates/*.md- Podcast workflow process docs referenced by
content/tasks/templates/podcast.mdandwork-engine/scripts/seed-templates.ts lambda-functions/src/lambda_functions/doc_registry.pylambda-functions/src/lambda_functions/docs_index.py- docs metadata/search tests under
tests/docs_app/ - work-engine template/task metadata code and tests when
sourceDocIdsorinstructionDocIdmappings are changed
The first migration target is:
- Every Markdown task template in
content/tasks/templates/*.mdhas explicit stable frontmatterid,aliases,doc_type: task-template,schema_version: 1,source,systems,tags, andrelated_docswhere applicable. - Every Podcast process doc referenced by the Podcast task template or Podcast seed-template
instructionDocIdhas an explicit stable frontmatterid, or the reference is corrected to the stable ID already present on the target document. - Workflow template records that already expose
sourceDocIdsand task definitions that exposeinstructionDocIduse these stable document IDs rather than path-derived or Google Docs-only references. - The policy docs explain how IDs, aliases, source metadata, task/workflow references, and repository boundaries work together.
Metadata Format
Use the existing frontmatter style and make it normative for workflow-critical process docs:
---
id: sop.media.podcast.create-podcast-document
aliases:
- sop.media.podcast.create-a-podcast-document
title: "Create a podcast document"
summary: "Short operator-facing summary."
doc_type: sop
schema_version: 1
source: "Processes/Podcast/Create a podcast document.docx"
systems:
- github
tags:
- podcast
related_docs:
- task-template.tasks.podcast
---Rules to preserve or document:
idis the canonical stable identity. It must use lowercase letters, numbers, dots, dashes, and underscores only.- Prefer namespaces by type and domain:
sop.<domain>.<area>.<slug>,template.<domain>.<area>.<slug>,reference.<domain>.<area>.<slug>,playbook.<domain>.<area>.<slug>,prompt.<domain>.<area>.<slug>, andtask-template.tasks.<workflow>. aliasescontains old IDs, old generated IDs, or old repo-relative paths that should still resolve after a rename or migration.related_docs, task-templatesourceDocIds, and task/task-definitioninstructionDocIdshould prefer stable IDs over paths and external Google Docs URLs.sourceremains provenance for imported docs. It is not the runtime identity.instructionsUrlmay remain for external Google Docs links during migration, but it must not be the only process-doc identity when an in-repo process doc exists.
Migration Strategy
Do this as a narrow first batch, not a repo-wide blind rewrite.
- Update the documentation contract first so future agents know when a stable ID is required and how to choose it.
- Audit the current workflow-critical docs and list any generated fallback IDs that are being relied on today.
- Add explicit IDs to all
content/tasks/templates/*.md, preserving existing generated IDs as aliases when the explicit ID differs from the current generated ID. - Add explicit IDs to the Podcast docs referenced by
content/tasks/templates/podcast.mdandwork-engine/scripts/seed-templates.tswhere missing. - Update
related_docs,sourceDocIds, andinstructionDocIdvalues only when needed to point at the canonical stable ID. - Keep source repositories read-only. Do not edit
../dtc-operations,../datatasks, or../podcast-assistant. - Do not split
content/intoDataTalksClub/dataops-knowledgein this issue. The ADR remains a future boundary decision.
Validation And Search Impact
The implementation must keep the docs registry and search behavior deterministic:
- Registry validation must fail loudly for duplicate
idvalues, duplicate aliases, aliases that conflict with another document ID/path, invalid ID syntax, and brokenrelated_docsreferences. - Workflow-critical docs migrated in this issue must report
stable_id: trueandid_source: frontmatterfrom the docs API/registry. - Search index generation must still succeed after the migration and must index the stable
idfield for migrated docs. - Existing path and alias resolution must keep working for migrated docs.
- Generated fallback IDs may remain for legacy docs outside this issue's migration batch, but tests should make clear that workflow-critical docs are not allowed to rely on fallback IDs.
Acceptance Criteria
-
docs/STRUCTURE.md,docs/sop-format.md, and relevant process/development docs explain the stable-ID requirement for workflow-critical process docs, aliases, source provenance,related_docs,sourceDocIds,instructionDocId, and the future knowledge-repo boundary. - All
content/tasks/templates/*.mdfiles have explicit stable frontmatter IDs using thetask-template.tasks.<workflow>namespace and are covered by tests. - Podcast workflow docs referenced by
content/tasks/templates/podcast.mdand Podcast seed-templateinstructionDocIdvalues have explicit stable IDs or references are corrected to existing explicit IDs. -
related_docs,sourceDocIds, andinstructionDocIdvalues for the migrated batch resolve through the document registry by stable ID. - Registry/search behavior preserves aliases and path resolution for migrated docs, and duplicate/conflicting IDs fail with actionable validation errors.
- Search index build succeeds and includes stable IDs for the migrated task templates and Podcast process docs.
- Work-engine template/task tests still prove that
sourceDocIdsandinstructionDocIdpersist, export, and instantiate correctly. - No source repositories outside
DataTalksClub/dataopsare modified.
Test Scenarios
Scenario: Task template has stable identity
Given: each Markdown file under content/tasks/templates/
When: the docs registry indexes the content tree
Then: each template record has id_source: frontmatter, stable_id: true, doc_type: task-template, and a unique task-template.tasks.<workflow> ID.
Scenario: Podcast task opens process doc by ID
Given: a Podcast task definition with instructionDocId: sop.media.podcast.create-podcast-document
When: the frontend or docs API resolves the instruction document
Then: the stable ID resolves to the expected Markdown document even if the file path has an alias or generated fallback ID.
Scenario: Duplicate ID fails loudly
Given: two Markdown docs define the same id
When: registry validation or search-index build runs
Then: validation fails with a message naming both conflicting paths.
Scenario: Alias preserves old references
Given: a migrated doc has an alias for its previous generated/path reference
When: /docs/resolve?ref=<alias> or registry resolution is used
Then: it resolves to the canonical document record and reports the canonical id.
Scenario: Search indexes migrated IDs
Given: migrated task-template and Podcast process docs
When: the search index is built
Then: the index build succeeds, migrated docs include their stable id keyword field, and existing search tests still pass.
Scenario: Work-engine keeps process-doc identity
Given: a template with sourceDocIds and task definitions with instructionDocId
When: templates are created, updated, instantiated into tasks, and exported
Then: the stable process-doc IDs are preserved and no code falls back to Google Docs URLs as the only identity for migrated in-repo docs.
Out of Scope
- Moving
content/or process knowledge into a newDataTalksClub/dataops-knowledgerepository. - Adding stable IDs to every imported SOP/template/reference in
content/**beyond the task-template files and Podcast workflow-critical docs named by this issue. - Implementing the full internal-link validator for every Markdown link. That belongs to Add internal link and related-doc validation #34.
- Mapping Newsletter, Tax Report, Book of the Week, Open-Source Spotlight, or other workflows to process docs beyond ensuring their task-template Markdown files have stable IDs. Those workflow-specific mappings belong to Map Newsletter workflow to operator-ready process docs #36, Map Monthly Tax Report workflow to operator-ready docs and metadata #37, Map Book of the Week workflow to process docs #38, and Map Open-Source Spotlight workflow to operator-ready process docs and executable task metadata #39.
- Building the process quality dashboard. That belongs to Add process quality dashboard for runnable workflows #35.
- Changing production data, DynamoDB records, source repositories, or external Google Docs.
Dependencies
- This issue is foundational for Add internal link and related-doc validation #34 and the workflow mapping issues because they should rely on stable document identities rather than generated path IDs.
- No external credentials or human-only checks are expected.
- If a referenced Podcast process doc does not exist in
content/**, document the missing mapping in the implementation notes and keep the current externalinstructionsUrl; do not invent a document or edit a source repository.
Labels
Use labels: enhancement, docs, process-docs, backend, work-engine, testing, data, P0.
Remove needs grooming after this body is applied.
Verification Commands
Run the relevant focused checks during implementation, and the full relevant workflow before handoff:
uv run --project lambda-functions --extra search --with pytest python -m pytest tests/docs_app/test_backend_docs_metadata.py tests/docs_app/test_frontend_routes_and_links.pyuv run --project lambda-functions --extra search --with pytest python -m pytest tests/docs_appcd lambda-functions
uv run --extra search python -m lambda_functions.build_search_index \
--docs-dir ../content \
--output ../.tmp/dataops-content-search.indexnpm --prefix work-engine test
npm --prefix work-engine run typecheck
npm --prefix work-engine run build
Activity
alexeygrigorev commentedon Jun 27, 2026
Implementation note from #10 workflow-card slice:
The portal now starts workflows from process template cards using a conservative bridge: future explicit template ID fields (
templateId,sourceTemplateId,canonicalTemplateId) match live template IDs; otherwise docslug/typemust match exactly one live templateslug/type. Ambiguous matches leave the workflow selector unselected.This is still a bridge, not the final boundary. When grooming #33, include acceptance criteria for a persisted canonical process-doc/template identity, such as
sourceDocIdorcanonicalTemplateId, in Git frontmatter and runtime templates, with validation that duplicate mappings fail loudly.alexeygrigorev commentedon Jun 27, 2026
PM grooming complete. I rewrote the issue as a scoped P0 implementation spec for stable process-document IDs, including the metadata contract, first migration batch, validation/search impact, workflow/task references, source boundaries, acceptance criteria, out-of-scope items, dependencies, labels, and verification commands. The issue is agent-ready and
needs groominghas been removed.alexeygrigorev commentedon Jun 28, 2026
Process Curator pre-implementation review
I reviewed #33 against
.goal-v1.md, the V1 operator JTBD, SOP format, workflow data model, currentcontent/,doc_registry.py,docs_index.py, task-template content, and the Podcast seed mappings. This issue should stay a narrow identity hardening slice, not a broad content rewrite.Stable ID conventions
Use the existing registry syntax as the hard rule: lowercase letters, numbers, dots, dashes, and underscores only, matching
^[a-z0-9][a-z0-9._-]*$. The ID is the runtime/document identity.sourceis provenance only. File paths and Google Docs URLs are not stable identities.Recommended canonical namespaces:
sop.<domain>.<area>.<operator-action>.Examples:
sop.media.podcast.create-podcast-document,sop.events.luma.creating-events-webinar-workshop-and-podcast-on-luma,sop.finance.tax-reporting.monthly-tax-report,sop.community.book-of-the-week.select-book-of-the-week-winners.template.<domain>.<area>.<slug>.Examples:
template.media.podcast.podcast-remind-the-guest-about-the-event-a-day-before-template,template.newsletter.sponsorship.send-sponsorship-document-2-weeks-before,template.community.book-of-the-week.book-of-the-week-announcement-template.reference.<domain>[.<area>].<slug>.Examples:
reference.overview.schedule,reference.newsletter.newsletter-sponsorship,reference.finance.invoices-receipts-and-statements,reference.social-media.post-podcast-overview-after-the-event.task-template.tasks.<workflow-type>for the current Markdown task-template docs and work-enginesourceDocIds.Examples:
task-template.tasks.podcast,task-template.tasks.newsletter,task-template.tasks.book-of-the-week,task-template.tasks.tax-report,task-template.tasks.oss,task-template.tasks.social-media.Do not introduce a second competing workflow ID namespace in this issue. If future YAML workflow definitions move to
workflow-templates/, either preserve the currenttask-template.tasks.<workflow>identity as the canonical template ID or make that change in a separate schema issue with migration rules.Aliases should be conservative:
aliases: []is fine.content/media/podcast/sops/create-a-podcast-document.mdis the right example: canonicalsop.media.podcast.create-podcast-document, aliassop.media.podcast.create-a-podcast-document.referencesorinstructionsUrlfallback fields.Current state to account for
The registry currently sees 357 Markdown docs. Only 2 have explicit frontmatter IDs:
content/tasks/templates/podcast.mdandcontent/media/podcast/sops/create-a-podcast-document.md. The other task-template docs currently resolve through generated IDs such astask-template.tasks.newsletter,task-template.tasks.tax-report, andtask-template.tasks.oss.Podcast seed data already uses stable-looking
sourceDocIdsandinstructionDocIdvalues, but most resolve only because generated path IDs happen to match. That is the main risk #33 needs to remove.Two Podcast source references do not currently resolve through
content/:assistant.podcast.process.podcasttemplate.media.podcast.podcast-guest-intakeDo not invent replacement content for those in #33. Either keep them as explicitly external/assistant references with clear implementation notes, or point them to real in-repo docs only if the implementation confirms a supported registry type and canonical file exists. The repo does have
assistants/podcast/process/podcast.mdandassistants/podcast/templates/podcast_guest_intake.md, but the current document registry only indexescontent/**/*.md.Also note that
work-engine/src/public/app.jscurrently has a hard-codedPROCESS_DOC_REGISTRY. That can be a display cache, but it must not become the source of truth. Runtime links should ultimately resolve through the document registry or generated registry data, not hand-maintained IDs in the frontend.V1 content priority
For #33 itself, the highest priority is identity coverage for docs already used by V1 task/workflow execution:
content/tasks/templates/*.md, with explicit IDs intask-template.tasks.<workflow>.content/tasks/templates/podcast.mdandwork-engine/scripts/seed-templates.ts.For follow-up workflow mapping issues, prioritize operator-critical content in this order:
The principle is: prioritize docs that unblock dashboard actions, waiting/follow-up states, missing-evidence reminders, and completion proof. Low-risk references can keep generated IDs until later.
Bulk migration risks to avoid
instructionsUrlvalues until the in-repoinstructionDocIdis proven resolvable. During migration,instructionDocIdshould be primary andinstructionsUrlcan remain legacy fallback.template.media.podcast...) with workflow task templates (task-template.tasks.podcast).schema_version: 1to legacy SOPs unless their body actually follows the structured SOP marker contract, or the parser/linter behavior is known to accept the shape. Metadata-only changes should not imply structured-body compliance accidentally.source,related_docs, or references.docs_index.iter_docs()currently emits the frontmatteridfield, so migrated docs will index IDs only if explicit IDs are actually present.How workflow/task references should work
Workflow/template level:
Template.sourceDocIdsshould include the task-template document ID and the small set of process docs needed to understand the whole workflow.task-template.tasks.podcastand make every resolvable PodcastsourceDocIdsentry a frontmatter-backed stable ID. External assistant refs should be marked or documented as external until the registry supports them.related_docsshould point to stable IDs, not paths, for the key SOP/reference docs.Task level:
instructionDocIdfor the canonical in-repo process doc.instructionStepIdwhen the SOP has structured steps and the task maps to a specific step.phase,systems,validation,requiredLinkName,requiresFile, andproofRequirementaligned so the operator sees the SOP in the same context as due date, waiting/follow-up, and proof requirements.instructionsUrlonly as a legacy fallback for external Google Docs or missing in-repo docs.Operator UI expectation:
instructionDocIdresolves, with phase/step/system metadata nearby.Required validation and evidence for the later implementation
The future SWE/Process Curator implementation should provide evidence for all of these:
validate=Trueand no duplicate ID, duplicate alias, alias/path conflict, invalid ID, or brokenrelated_docserrors.content/tasks/templates/*.mddocument reportsstable_id: trueandid_source: frontmatterfrom/docs/registryor direct registry inspection.sourceDocIdsorinstructionDocIdresolves by stable ID throughdoc_registry.resolve_reference()and/docs/resolve?ref=....assistant.podcast.process.podcastandtemplate.media.podcast.podcast-guest-intake, are either resolved through a deliberate registry extension or explicitly reported as external/non-content references. They should not be left as accidental missing content refs.idkeyword fields.related_docs.sourceDocIds,instructionDocId,instructionStepId, andinstructionsUrlfallback persist through template create/update, template instantiation into tasks, and portable export.instructionDocId, resolve canonical docs, and display unresolved IDs visibly.Recommended verification commands from #33 remain appropriate:
A useful additional focused check is a registry audit that compares every migrated
sourceDocIdsandinstructionDocIdagainstdoc_registry.resolve_reference()and fails unless the reference is deliberately marked external.Read-only review only: I did not modify repo files, commit, push, close the issue, or open a PR.
alexeygrigorev commentedon Jun 28, 2026
READY FOR TEST
SWE handoff for issue #33 from worktree
/home/alexey/git/dataops/.tmp/worktrees/issue-33on branchworktree-issue-33.Summary:
content/tasks/templates/*.mdusingtask-template.tasks.<workflow>.sourceDocIdsorinstructionDocIdvalues.work-engine/scripts/seed-templates.ts:template.media.podcast.podcast-guest-intake->assistants/podcast/templates/podcast_guest_intake.mdassistant.podcast.process.podcast->assistants/podcast/process/podcast.mdsourceprovenance,related_docs,sourceDocIds,instructionDocId,instructionsUrlfallback, and future knowledge-repo boundary.Changed files:
PROJECT_PLAN.md_docs/MERGE_PLAN.md_docs/PROCESS.mddocs/STRUCTURE.mddocs/decisions/dataops-knowledge-repository.mddocs/local-development.mddocs/sop-format.mddocs/v1-workflow-data-model.mdtests/docs_app/test_backend_docs_metadata.pywork-engine/scripts/seed-templates.tswork-engine/tests/seed.test.tscontent/tasks/templates/book-of-the-week.mdcontent/tasks/templates/course.mdcontent/tasks/templates/maven-ll.mdcontent/tasks/templates/newsletter.mdcontent/tasks/templates/office-hours.mdcontent/tasks/templates/oss.mdcontent/tasks/templates/podcast.mdwas already explicitly ID-backed and was reviewed; no diff needed there.content/tasks/templates/social-media.mdcontent/tasks/templates/tax-report.mdcontent/tasks/templates/webinar.mdcontent/tasks/templates/workshop.mdcontent/events/calendar/sops/create-a-calender-invite-for-the-guests-speaker-for-an-event.mdcontent/events/calendar/sops/creating-tentative-event-on-google-calendar.mdcontent/events/luma/sops/creating-events-on-google-calendar.mdcontent/events/luma/sops/creating-events-webinar-workshop-and-podcast-on-luma.mdcontent/events/luma/sops/downloading-the-csv-file-on-luma.mdcontent/events/meetup/sops/create-events-in-meetup-com.mdcontent/events/outreach/sops/how-to-find-emails-of-previous-guests.mdcontent/events/planning/sops/create-speaker-profiles-via-airtable-form.mdcontent/events/planning/sops/fill-in-the-event-form-in-airtable-for-adding-events-to-our-website.mdcontent/events/sops/announce-event-in-slack-in-announcements.mdcontent/media/podcast/sops/add-a-guest-bio-to-the-podcast-document.mdcontent/media/podcast/sops/add-a-podcast-episode-via-airtable-form.mdcontent/media/podcast/sops/add-links-to-youtube-after-the-stream-is-over.mdcontent/media/podcast/sops/creating-podcast-transcription-document.mdcontent/media/podcast/sops/generate-timecodes-from-docx-transcriptions.mdcontent/media/podcast/sops/making-event-announcements-when-topic-bio-or-outline-is-missing.mdcontent/media/podcast/sops/managing-podcast-workflow.mdcontent/media/podcast/sops/move-podcast-documents-to-archive-in-google-drive.mdcontent/media/podcast/sops/moving-podcast-audio-in-dropbox.mdcontent/media/podcast/sops/reach-out-to-guests-and-propose-a-date-on-linkedin.mdcontent/media/podcast/sops/removing-the-beginning-from-the-youtube-stream.mdcontent/media/podcast/sops/schedule-podcast-episodes-with-spotify-for-podcaster.mdcontent/media/podcast/sops/select-and-propose-a-date-for-events.mdcontent/media/podcast/sops/sending-a-podcast-scheduled-email-to-pavel-after-the-event.mdcontent/media/podcast/sops/update-the-website-with-the-information-from-forms.mdcontent/media/podcast/sops/updating-the-cover-of-the-youtube-video.mdcontent/media/podcast/templates/podcast-adding-johanna-and-sending-the-podcast-link-to-the-speaker.mdcontent/media/podcast/templates/podcast-links-after-the-event-is-over.mdcontent/media/podcast/templates/podcast-remind-about-the-event-in-a-week-share-registration-link-template.mdcontent/media/podcast/templates/podcast-remind-the-guest-about-the-event-a-day-before-template.mdcontent/media/podcast/templates/podcast-share-the-podcast-page-template.mdcontent/media/podcast/templates/sending-podcast-document-on-slack-the-dtc-podcast-help-channel.mdcontent/media/video-youtube/sops/adding-videos-from-other-channels-to-our-playlist.mdcontent/social-media/reference/post-podcast-overview-after-the-event.mdcontent/social-media/sops/post-podcast-guest-recommendations.mdcontent/social-media/templates/template-new-event-announcements-podcasts-webinars-workshops.mdVerification:
pwd:/home/alexey/git/dataops/.tmp/worktrees/issue-33git status --shortin/home/alexey/git/dataops: clean.git diff --check: passed, no output.PYTHONPATH=lambda-functions/src python - <<'PY' ...checked Podcast/workflow source refs fromwork-engine/scripts/seed-templates.ts:checked=38 external=2 missing=0 generated=0.uv run --project lambda-functions --extra search --with pytest python -m pytest tests/docs_app/test_backend_docs_metadata.py tests/docs_app/test_frontend_routes_and_links.py: 37 passed in 1.82s.uv run --project lambda-functions --extra search --with pytest python -m pytest tests/docs_app: 86 passed, 1 skipped in 5.27s. The skip is the pre-existing local Playwright docs flow skip from that suite, not a skipped Extend process docs with stable IDs #33 verification command.cd lambda-functions && uv run --extra search python -m lambda_functions.build_search_index --docs-dir ../content --output ../.tmp/dataops-content-search.index: Indexed 357 documents into../.tmp/dataops-content-search.index.npm --prefix work-engine test: 647 passed, 0 failed in 6291ms after installing local work-engine dependencies.npm --prefix work-engine run typecheck: passed.npm --prefix work-engine run build: passed.Notes:
npm --prefix work-engine cicould not run becausework-engine/has no package lock. I usednpm --prefix work-engine installto install local verification dependencies, then removed the generated untrackedwork-engine/package-lock.json. No tracked package metadata remains changed.alexeygrigorev commentedon Jun 28, 2026
TEST PASS
Tester verification for issue #33 from worktree
/home/alexey/git/dataops/.tmp/worktrees/issue-33on branchworktree-issue-33.Required command results:
git diff --check: passed with no output.uv run --project lambda-functions --extra search --with pytest python -m pytest tests/docs_app/test_backend_docs_metadata.py tests/docs_app/test_frontend_routes_and_links.py: passed, 37 passed in 1.75s.uv run --project lambda-functions --extra search --with pytest python -m pytest tests/docs_app: passed, 86 passed, 1 skipped in 2.12s. The skipped test istests/docs_app/test_playwright_local_docs_flow.pyfrom the existing suite.cd lambda-functions && uv run --extra search python -m lambda_functions.build_search_index --docs-dir ../content --output ../.tmp/dataops-content-search.index: passed, indexed 357 documents into../.tmp/dataops-content-search.index.npm --prefix work-engine test: passed, 647 tests, 0 failed, 0 skipped. The output includes an intentionalSimulated DB failurelog from a passing error-handling test.npm --prefix work-engine run typecheck: passed (tsc --noEmit, test tsconfig, and script tsconfig all completed).npm --prefix work-engine run build: passed (tscplus public/pages copy completed).Focused registry/reference audit:
content/,work-engine/scripts/seed-templates.ts, andlambda_functions.doc_registry/docs_index.iter_docs.AUDIT PASS.task_templates=11,registry_documents=357,podcast_registry_refs_checked=51,assistant_local_external_refs=2,search_indexed_ids_checked=49.content/tasks/templates/*.mdfile has required stable frontmatter metadata,task-template.tasks.<workflow>ID,doc_type: task-template,id_source: frontmatter, andstable_id: trueregistry behavior.sourceDocIdsandinstructionDocIdrefs from the seed script resolve throughdoc_registryby frontmatter-backed stable ID.template.media.podcast.podcast-guest-intakeandassistant.podcast.process.podcastremain explicitly documented assistant-local references underassistants/podcast/and do not accidentally resolve through the content registry.Acceptance-criteria evidence:
docs/STRUCTURE.md,docs/sop-format.md,docs/local-development.md,docs/v1-workflow-data-model.md,docs/decisions/dataops-knowledge-repository.md,_docs/PROCESS.md,_docs/MERGE_PLAN.md, andPROJECT_PLAN.md. They document stable IDs, aliases,sourceas provenance,related_docs,sourceDocIds,instructionDocId,instructionsUrlfallback, and the future knowledge-repo boundary.tests/docs_app/test_backend_docs_metadata.pynow covers task-template stable IDs, Podcast workflow content IDs, alias resolution, searchidfields, and duplicate/invalid/conflicting registry failures.work-engine/tests/seed.test.tscovers Podcast seedsourceDocIds, documented assistant-local exceptions,instructionDocId, and instantiation semantics.sourceDocIdsandinstructionDocId(api-templates,templates,api-bundles,tasks,api-tasks, andexport-portablewere included in the 647-test run).sourceDocIdsand PodcastinstructionDocIdvalues are stable IDs;instructionsUrlremains a fallback field.Worktree/source-boundary checks:
/home/alexey/git/dataopsmain checkout: clean (## main...origin/main). This resolves the wrong-worktree concern for main.worktree-issue-33; no untracked files shown bygit status --short --branch --untracked-files=all./home/alexey/git/dtc-operations: clean./home/alexey/git/podcast-assistant: the root is not a git checkout, so there is no source-repo status to report there./home/alexey/git/datatasks: has a pre-existing modifiede2e/.auth-state.jsondated2026-06-24 23:21:12 +0200, changing localhost auth state from port 3000 to 3001. This predates Extend process docs with stable IDs #33 testing/handoff and was not touched by the Extend process docs with stable IDs #33 commands; I found no evidence Extend process docs with stable IDs #33 modified source repos outsidedataops.No files were edited, committed, pushed, merged, deployed, or cache-refreshed by this tester run beyond the required local
.tmpsearch-index artifact command.alexeygrigorev commentedon Jun 28, 2026
Tester clarification: the required
npm --prefix work-engine run buildcommand writes ignoredwork-engine/dist/output, and the required search-index command writes the ignored.tmp/dataops-content-search.indexartifact.git status --short --branch --untracked-files=allremains limited to the intended tracked #33 implementation files; no tracked source files were modified by the tester run.alexeygrigorev commentedon Jun 28, 2026
PM ACCEPTED
Acceptance evidence:
No PM acceptance blocker found.
alexeygrigorev commentedon Jun 28, 2026
COMMITTED
Commit:
24f23105969cca0d1009c9395f574149fb55b7dfBranch:
worktree-issue-33Changed files summary:
work-engine/scripts/seed-templates.tsfor documented assistant-local Podcast references.Commit-readiness checks:
git status --short --untracked-files=allbefore commit; only intended tracked Extend process docs with stable IDs #33 changes were present, with no untracked files..tmp/,.pytest_cache/, and Python__pycache__/directories.git status --short --untracked-files=allis clean.No push, merge, PR, deploy, cache refresh, or source-repo modification was performed.
Merge issue #33 stable process doc IDs
Fix content validation diff checkout for #33
alexeygrigorev commentedon Jun 28, 2026
ON-CALL PASS after merge commit
6dda9a9and follow-up on-call workflow fix493565cfor #33.Evidence:
git diff 081fb410aeb2fd7634010b495ede7dc2c4e616b7 6dda9a94d7d7be2cebae57776db8ddd30b60c9fareportfatal: bad object, so the workflow skipped refresh. Fixed onmainin493565cby using full-history checkout for this workflow.DocsFullAppFunctionmodified and stackUPDATE_COMPLETE.493565c: success. https://github.com/DataTalksClub/dataops/actions/runs/283105373186dda9a9to493565cwithout the previous shallow-clone error and correctly skipped refresh because the fix commit changed only the workflow file.No source repos were modified. No manual deploy/cache refresh was run.
Add stable process doc IDs (Closes #33)
Merge issue #33 stable process doc IDs
Fix content validation diff checkout for #33