Create CI workflow for planning and docs checks

[alexeygrigorev]

Create CI workflow for planning and docs checks

Status: pending
Tags: docs, process-docs, infra, testing, P1
Depends on: None
Blocks: None

Scope

Add a GitHub Actions workflow and the repo-local validation it needs to protect DataOps planning docs, process docs, templates, metadata, and V1 goal/JTBD references before source-system imports and unified-platform changes land on main.

The workflow should be stronger than a docs-only prose check. It should validate the planning/process contract that keeps DataOps aligned with the AI Shipping Labs-style lifecycle, plus the technical references that connect docs, templates, work-engine tasks, search, and the V1 operator goal.

Expected implementation areas:

• Add a planning/docs CI workflow, likely .github/workflows/validate-planning-docs.yml, with read-only permissions and workflow_dispatch.
• Trigger it for changes to planning/process/metadata surfaces, including _docs/**, docs/**, templates/**, content/tasks/templates/**, .goal-v1.md, PROJECT_PLAN.md, PORTAL_ANALYSIS.md, README.md, related tests/scripts, and the workflow itself.
• Add or extend automated validation under tests/, scripts/, or the existing docs-app test suite as appropriate. Prefer normal repo test commands over one-off shell assertions embedded only in YAML.
• Validate internal Markdown links and repo-relative references for the protected docs set. External URLs should not make CI flaky unless the implementation uses a deliberate, bounded checker.
• Validate stable metadata needed by the unified operations platform: document IDs/aliases, related_docs, task-template frontmatter, template references, and docs registry/search behavior where those surfaces are touched.
• Protect _docs/PROCESS.md from weaker process drift by checking for the required lifecycle gates and role ownership: orchestrator intake, PM grooming, SWE implementation without commit, Tester verification with real tests/screenshots where relevant, PM acceptance, local merge to main, push, and On-Call CI/CD monitoring.
• Protect .goal-v1.md and docs/operations-manager-platform-jtbd.md references so the V1 goal, JTBD, and referenced files remain present and linkable.
• Keep this CI path separate from deployment and deployed cache refresh. It should not require AWS credentials, mutate production state, or depend on GitHub PRs as the process source of truth.
• Do not use stylint or user-facing prose tooling for these internal process docs unless Alexey explicitly asks for prose polish.

Affected areas:

• .github/workflows/**
• _docs/PROCESS.md, _docs/MERGE_PLAN.md, _docs/import-log.md
• .goal-v1.md, PROJECT_PLAN.md, PORTAL_ANALYSIS.md, README.md
• docs/**, especially docs/local-development.md, docs/operations-manager-platform-jtbd.md, runtime/data-model docs, and repository-structure docs
• templates/**
• content/tasks/templates/**
• lambda-functions/src/lambda_functions/doc_registry.py, search-index tooling, docs-app tests, or new planning-doc validation tests if needed
• work-engine/docs/** and work-engine template contracts where referenced by the checks

Acceptance Criteria

• A GitHub Actions workflow exists for planning/process/docs validation with read-only permissions, workflow_dispatch, and path filters that cover the protected planning docs, process docs, templates, metadata, goal/JTBD references, and the workflow itself.
• The workflow runs concrete repo validation, not prose-only linting. At minimum it runs the new planning/docs validation command, docs metadata/registry coverage, and a search-index build or equivalent search smoke check for template/doc metadata surfaces.
• Internal Markdown links and repo-relative references in the protected docs set fail CI when they point at missing files or missing required reference targets. External links are either ignored or checked only with a deliberate non-flaky policy documented in the implementation.
• _docs/PROCESS.md has automated guardrails for the AI Shipping Labs-strength lifecycle controls listed in Scope. The guard must fail if the process drops or weakens the required gates/roles, even though the original sibling repo is not available in GitHub Actions.
• .goal-v1.md reference files and the Operations Manager JTBD reference remain present and linkable; CI fails if a referenced repo-local file or directory is removed without updating the goal/JTBD contract.
• Task-template and process-doc metadata that feeds the unified operations platform is covered: stable IDs/aliases, related_docs, task-template frontmatter, and template/doc registry behavior are validated by tests or a script with test coverage.
• The workflow does not deploy, refresh the deployed docs cache, assume AWS credentials, require production secrets, or mutate GitHub/content/runtime state.
• The implementation explicitly avoids stylint/user-facing prose tooling for internal process docs.
• Local documentation is updated only if needed to name the new command/workflow in the existing local-development command matrix. Do not rewrite process docs or planning docs beyond what is necessary for the CI contract.
• The issue checkboxes are updated by SWE/Tester as the work passes implementation and verification, following _docs/PROCESS.md.

Test Scenarios

Scenario: Planning-doc workflow catches broken internal references

Given: a change edits _docs/**, docs/**, .goal-v1.md, PROJECT_PLAN.md, PORTAL_ANALYSIS.md, README.md, templates/**, or content/tasks/templates/**
When: the planning/docs validation workflow runs
Then: missing repo-local Markdown links, missing referenced files/directories, and broken goal/JTBD references fail the job with actionable output.

Scenario: Process lifecycle controls cannot be weakened silently

Given: _docs/PROCESS.md is changed
When: the planning/docs validation command runs
Then: it fails if required lifecycle controls are removed or materially weakened: PM grooming, SWE no-commit-before-review, Tester real verification, PM acceptance, local merge to main, push, On-Call CI/CD monitoring, no PR merge workflow, and no stylint requirement for internal process docs.

Scenario: Unified-platform metadata remains executable

Given: task templates, process docs, or metadata used by the portal/work-engine/search contract are changed
When: the planning/docs validation workflow runs
Then: stable document IDs/aliases, related_docs, task-template frontmatter, and docs registry/search behavior are validated so task-to-doc and template-to-doc references do not drift.

Scenario: CI is safe for internal process changes

Given: a process-doc-only or planning-doc-only change lands on main
When: GitHub Actions runs the new workflow
Then: the job uses read-only repository access, does not assume AWS OIDC credentials, does not deploy, and does not refresh the deployed docs cache.

Scenario: Local verification matches CI

Given: a SWE has implemented the workflow and validation command
When: Tester runs the required verification commands locally
Then: the same checks that protect planning/docs CI pass locally, and any intentionally skipped broader command is explained against _docs/PROCESS.md and docs/local-development.md.

Out of Scope

• Rewriting _docs/PROCESS.md or weakening the AI Shipping Labs parity contract.
• Broad content cleanup across all content/** process docs.
• Migrating source repos or modifying ../dtc-operations, ../datatasks, or ../podcast-assistant.
• Adding a PR-based development process or requiring gh pr create / gh pr merge.
• Live AWS deployment, deployed cache refresh, production Lambda invocation, GitHub content writes, or any check requiring secrets.
• Stylint, prose-polish, or user-facing content-style enforcement for internal process docs.
• Building a full external-link crawler unless separately scoped.

Dependencies

• Existing docs/process expectations in _docs/PROCESS.md and docs/local-development.md.
• Existing CI workflows:
  • .github/workflows/deploy-dataops-v1.yml
  • .github/workflows/validate-dataops-content.yml
  • .github/workflows/assistant-ci.yml
• Existing validation commands for docs app, search index, and work-engine checks.
• GitHub Actions cannot access ../ai-shipping-labs/_docs/PROCESS.md, so parity automation must use repo-local required-control guardrails. Local reviewer parity inspection against the sibling source process remains a manual verification step only if _docs/PROCESS.md itself is changed.

Required Verification Commands

Run from the repo root unless noted:

git diff --check

uv run --project lambda-functions --extra search --with pytest python -m pytest tests/docs_app

uv run --with pytest python -m pytest tests/planning_docs

If the implementation uses a different path/name for the new planning-doc validation tests, update this issue before handoff and use that exact command in Tester evidence.

Build the content/search index because this issue protects template/doc metadata and search references:

cd lambda-functions
uv run --extra search python -m lambda_functions.build_search_index \
  --docs-dir ../content \
  --output ../.tmp/dataops-content-search.index

Run work-engine contract checks if the implementation touches work-engine/**, content/tasks/templates/**, root work-engine package wrappers, or template/task metadata behavior:

npm --prefix work-engine test
npm --prefix work-engine run typecheck
npm --prefix work-engine run build

For workflow YAML changes, inspect the changed workflow paths and confirm the local commands above match the workflow steps. Do not run live AWS deploy/cache-refresh checks for this issue.

Blockers

• None known.
• Do not block on live GitHub Actions completion before implementation handoff; On-Call monitoring happens after approved work is committed, locally merged to main, and pushed.
• If the implementation discovers that a required check needs production credentials, external accounts, or live GitHub/AWS writes, stop and re-scope that check as [HUMAN] or out of scope before continuing.

[alexeygrigorev]

PM grooming complete. The issue is now scoped as a CI implementation task for planning/process/docs validation with AI Shipping Labs-strength guardrails, concrete acceptance criteria, test scenarios, required local verification commands, and explicit no-stylint/no-live-deploy boundaries. Removed needs grooming and added process-docs.

[alexeygrigorev]

SWE handoff for issue #25: READY FOR TEST

Worktree: /home/alexey/git/dataops/.tmp/worktrees/issue-25
Branch: worktree-issue-25

Changed files:

• .github/workflows/validate-planning-docs.yml - new read-only planning/process/docs workflow with workflow_dispatch, push/pull_request path filters for protected planning docs/templates/metadata surfaces, and no AWS/GitHub write/deploy/cache-refresh steps.
• scripts/validate_planning_docs.py - repo-local validator for protected internal Markdown links, frontmatter related_docs, V1 goal references, Operations Manager JTBD source references, PROCESS lifecycle controls, content doc registry/task-template metadata, and workflow safety.
• tests/planning_docs/test_validate_planning_docs.py - pytest coverage for current repo validation and representative failure cases.
• Makefile - added make validate-planning-docs.
• docs/local-development.md - documented the new local command/workflow scope and external-link/stylint policy.
• .goal-v1.md - corrected the podcast assistant reference from the old source-style path to assistants/podcast/README.md.

Verification run:

• PASS: git diff --check
• PASS: uv run --with pytest python -m pytest tests/planning_docs (6 passed)
• PASS: uv run --project lambda-functions --extra search --with pytest python -m pytest tests/docs_app (84 passed, 1 skipped)
• PASS: 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)
• PASS: uv run python scripts/validate_planning_docs.py

Acceptance criteria status:

• Implemented and locally verified: read-only workflow, concrete repo validation, internal link/reference checks, PROCESS lifecycle guardrails, V1 goal/JTBD references, doc registry/task-template metadata coverage, search-index build coverage, no deploy/AWS/cache-refresh/GitHub-write workflow steps, no stylint/prose tooling for internal docs, and local-development command docs.
• Issue checkboxes were updated after SWE verification.

Skipped checks / notes:

• Work-engine checks were not run because this change does not modify work-engine/**, content/tasks/templates/**, root work-engine wrappers, or template/task runtime behavior. The new validator only reads existing task-template metadata.
• gh workflow view was not run because .github/workflows/validate-planning-docs.yml does not exist on the remote default branch until this work is committed, merged locally to main, and pushed.
• No stylint/prose polishing was used.

No commit, push, PR, source-repo edits, AWS credentials, deploys, or cache refreshes were performed.

[alexeygrigorev]

TEST PASS

Tester verification for issue #25 in /home/alexey/git/dataops/.tmp/worktrees/issue-25 on branch worktree-issue-25.

Commands run:

git diff --check

Result: PASS, exit 0, no output.

uv run --project lambda-functions --extra search --with pytest python -m pytest tests/docs_app

Result: PASS, exit 0. Pytest collected 85 items: 84 passed, 1 skipped.

uv run --with pytest python -m pytest tests/planning_docs

Result: PASS, exit 0. Pytest collected 6 items: 6 passed.

uv run python scripts/validate_planning_docs.py

Result: PASS, exit 0. Output: Planning docs validation passed.

cd lambda-functions && uv run --extra search python -m lambda_functions.build_search_index --docs-dir ../content --output ../.tmp/dataops-content-search.index

Result: PASS, exit 0. Output: Indexed 357 documents into ../.tmp/dataops-content-search.index.

Work-engine checks: skipped. The implementation did not modify work-engine/**, content/tasks/templates/**, root work-engine wrappers, or runtime template/task metadata behavior. The new validator reads existing task-template metadata and is covered by tests/planning_docs, tests/docs_app, and the search-index build above.

Acceptance coverage:

• Planning/docs workflow exists at .github/workflows/validate-planning-docs.yml with permissions: contents: read, workflow_dispatch, and path filters for _docs/**, docs/**, templates/**, content/tasks/templates/**, .goal-v1.md, planning docs, validation scripts/tests, docs-app tests, and workflow/self-related metadata files.
• Workflow runs concrete repo checks: planning-doc validator tests, docs metadata/registry tests, and content search-index build. It is not prose-only linting/stylint.
• scripts/validate_planning_docs.py checks protected internal Markdown links, anchors, repo-local related_docs, .goal-v1.md references, JTBD source references, doc registry state, task-template metadata, and workflow safety. External Markdown URLs are ignored by the validator and documented in docs/local-development.md as non-flaky policy.
• _docs/PROCESS.md retains AI Shipping Labs-strength lifecycle controls. The validator guards orchestrator intake/needs grooming, PM grooming, SWE no-commit-before-review, Tester real verification/screenshots, PM acceptance, local merge to main, push, On-Call CI/CD monitoring, no PR workflow, and no stylint requirement for internal process docs.
• .goal-v1.md still references docs/operations-manager-platform-jtbd.md and content/tasks/templates/; its podcast assistant reference was corrected to the in-repo assistants/podcast/README.md. JTBD source references remain present/linkable.
• Task-template/process-doc metadata and docs registry/search behavior are covered by the validator, planning-doc tests, docs-app tests, and search-index build.
• Workflow safety checked: no deploy, no cache refresh, no AWS credential/OIDC permission, no production secrets, no git push, no PR mutation, no GitHub/content/runtime mutation steps.
• docs/local-development.md and Makefile updates are scoped to documenting/exposing the new planning-docs validation command; _docs/PROCESS.md and planning docs were not rewritten by this implementation.
• Issue checkboxes were already marked complete in the issue body before Tester handoff; no checkbox edit was needed from Tester.

Generated/cache artifacts observed after verification:

• .tmp/dataops-content-search.index (about 2.0M), produced by the required search-index command.
• Existing .tmp/issue25-body.md.
• Ignored local environments/caches: .venv/, lambda-functions/.venv/, .pytest_cache/, lambda-functions/src/lambda_functions/__pycache__/, scripts/__pycache__/, tests/docs_app/__pycache__/, tests/planning_docs/__pycache__/.

No files were edited by Tester. No commit, push, PR, AWS credentials, deploy, cache refresh, or source-repo modifications were performed.

[alexeygrigorev]

PM ACCEPTED

Evidence:

• Implementation protects the DataOps V1 and operations-manager JTBD contract, not just docs prose: scripts/validate_planning_docs.py validates .goal-v1.md, docs/operations-manager-platform-jtbd.md, task-template metadata, doc registry references, internal links, and workflow safety.
• AI Shipping Labs-strength process guardrails are preserved: _docs/PROCESS.md lifecycle gates are checked for orchestrator intake/needs grooming, PM grooming, SWE no-commit-before-review, Tester real verification/screenshots, PM acceptance, local merge to main, push, On-Call CI/CD monitoring, and no gh pr create / gh pr merge workflow.
• The planning-docs workflow is read-only (permissions: contents: read) and contains no AWS/OIDC deploy, cache refresh, production secret, git push, or GitHub mutation step.
• Internal process docs explicitly avoid stylint/user-facing prose tooling unless Alexey asks for prose polish.
• .goal-v1.md only corrects the podcast assistant reference from missing podcast-assistant/README.md to existing assistants/podcast/README.md; the V1 objective and reference set are not weakened.
• Makefile and docs/local-development.md changes are scoped to exposing/documenting the new planning-docs validation command.
• Tester passed with git diff --check, docs-app tests, planning-doc tests, the validator, and search-index build in Create CI workflow for planning and docs checks #25 (comment).

Accepted for the next pipeline step: SWE commit with Closes #25, then local merge to main, push, and On-Call CI/CD monitoring per _docs/PROCESS.md.

[alexeygrigorev]

SWE commit complete for issue #25.

Commit: b13576623a34e20fa2781e8a8833aab98231a90c

Changed files:

• .github/workflows/validate-planning-docs.yml
• .goal-v1.md
• Makefile
• docs/local-development.md
• scripts/validate_planning_docs.py
• tests/planning_docs/test_validate_planning_docs.py

No push, merge, PR, AWS/deploy, cache refresh, or source-repo edits were performed.