🐛 (release-rw): Gate docs-build/docs-preview on intent.yaml artifacts.docs != skip

[Chisanan232]

Target

• Task summary:

  Honor artifacts.docs: skip from a consumer project's intent.yaml
  when invoking the Docusaurus operations sub-workflow. Today the
  docs-build / docs-preview jobs in
  rw_release_validation_complete.yaml and
  rw_release_staging_complete.yaml invoke
  rw_docusaurus_operations.yaml unconditionally — which fails for
  consumer projects that use MkDocs (or any non-Docusaurus docs system)
  because there is no docs/package.json for the sub-workflow's
  pnpm install to find.

  The sibling production workflow rw_release_complete.yaml
  (line 465) already has the gate
  if: needs.intent.outputs.do_release == 'true' && needs.intent.outputs.docs != 'skip' && ….
  The validation + staging workflows just missed copying it.

• Task tickets:

  • Task ID: AAASM-2063 (downstream Jira tracking)
  • Relative task IDs:
    • AAASM-2053 — downstream python-sdk PR that surfaced this bug
  • Relative PRs:
    • Surfaced by: AI-agent-assembly/python-sdk PR #66 (draft, blocked on this PR)

• Key point change:

  Three changes across two files:

  #	File	Change
  1	rw_release_validation_complete.yaml line ~165	Added if: needs.intent-parse.outputs.docs != 'skip' to the docs-build job
  2	rw_release_validation_complete.yaml line ~224	DOCS_OK in validation-summary now accepts 'skipped' alongside 'success'
  3	rw_release_staging_complete.yaml lines ~202 + ~256	Added if: needs.config.outputs.docs != 'skip' to docs-preview; DOCS_OK in staging-summary accepts 'skipped'

  After this PR, all three rw_release_*_complete.yaml orchestrators
  consistently honour artifacts.docs: skip from intent.yaml.

Effecting Scope

• Action Types:

  • 🔧 Fixing bug
    • 🟢 No breaking change

• Affected workflows:

  • rw_release_validation_complete.yaml
  • rw_release_staging_complete.yaml

• Downstream consumer impact:

  • Projects with artifacts.docs: skip (string form) in intent.yaml:
    the docs-build / docs-preview jobs are now SKIPPED on
    validation + staging runs instead of FAILING. Summary jobs treat
    skipped as a pass.
  • Projects with artifacts.docs: auto / force, or the enhanced
    multi-section object form: behaviour unchanged — the
    Docusaurus operations run exactly as before.
  • Projects that never set artifacts.docs at all (or set it to
    anything other than the string "skip"): unchanged.

Discovery context

Found while fixing trigger-placeholder bugs in python-sdk (downstream
PR #66).
That repo uses MkDocs (mkdocs.yml at root, docs/ is Markdown only)
and has its own documentation.yaml workflow that deploys docs on
workflow_run: ["release"]: types: [completed]. The release-validate
docs-build was both redundant AND incompatible — but couldn't be
disabled from the consumer side because the gate didn't exist here.

Setting artifacts.docs: skip in the consumer's intent.yaml is
already the documented escape hatch (see the comment block in the
example intent.yaml shipped under
docs/INTENT_YAML_SAMPLE.md
or similar). This PR makes that knob actually do what it claims.

Verification

• 3 small commits, one logical change each (gate-validation,
  summary-accept-skipped-validation, gate-staging + summary).
• actionlint clean on both modified files (pre-existing info-level
  shellcheck findings unchanged).
• No new inputs, no new outputs, no schema changes — purely additive
  if: guards + an OR-clause on existing DOCS_OK shell checks.
• Backwards-compatible: any consumer not using artifacts.docs: skip
  sees no behaviour change.

[Chisanan232]

Claude Code review — 🐛 (release-rw): Gate docs-build/docs-preview on intent.yaml \artifacts.docs != skip``

CI state

mergeable=MERGEABLE, mergeStateStatus=BLOCKED (branch protection — reviewer required), 27 checks total: 7 SUCCESS / 13 SKIPPED / 7 FAILURE.

All 7 failures are pre-existing in this repo's self-test workflows, not regressions introduced by this PR. Cross-verified by pulling the run history of the two affected workflows:

Workflow	Run history (last 5 runs across all branches)
test-release-validate.yml	fix/gate-docusaurus-ops-on-docs-skip 2026-05-26 ❌ • dependabot/sonarqube-scan-8.1.0 2026-05-19 ❌ • dependabot/sonarqube-scan-8.0.0 2026-04-30 ❌ • dependabot/sonarqube-scan-7.2.0 2026-04-29 ❌ • develop 2026-04-24 ❌
test-release-staging.yml	Same pattern — every PR since April 2026 has been red

The failing jobs (docs-build / Docs test, python-build-check / Python Package test, Compute Staging Version, plus the cascading Validation Summary / Staging Release Summary) test the reusable workflows against this repo's own setup (which uses Docusaurus + a sample intent.yaml). They've been broken since long before this PR was opened — independent of the if: gate I'm adding.

For example, the docs-build / Docs test failure on my PR is at pnpm approve-builds exit code 1 — a Docusaurus dev-dependency build-script approval prompt, not anything my if: change touches. With this repo's own intent.yaml set to docs: auto, my new gate (if: needs.intent-parse.outputs.docs != 'skip') evaluates to true and the job runs exactly as before — the existing breakage then surfaces.

Per the user's "ignore acceptance/SonarQube failures" rule, these pre-existing failures are out of scope for this PR. They should be tracked as a separate repo-health issue.

→ No CI failures attributable to this PR.

Scope vs. PR description

Claim	Where verified	Status
rw_release_validation_complete.yaml docs-build gated on needs.intent-parse.outputs.docs != 'skip'	Commit 08faf1d line 166	✅
rw_release_validation_complete.yaml validation-summary DOCS_OK accepts 'skipped'	Commit 744782c line 224	✅
rw_release_staging_complete.yaml docs-preview gated on needs.config.outputs.docs != 'skip'	Commit 9a2a37a line 202	✅
rw_release_staging_complete.yaml staging-summary DOCS_OK accepts 'skipped'	Commit 9a2a37a line 256	✅
Matches the existing gate pattern in rw_release_complete.yaml line 465 (docs != 'skip')	Comparison verified	✅
No breaking change — consumers without artifacts.docs: skip see no behaviour difference	New if: gates are pure additions; existing inputs/outputs unchanged	✅

Commit granularity (3 atomic commits)

1. 08faf1d — 🐛 (validation): Gate docs-build on intent.yaml artifacts.docs != skip
2. 744782c — 🐛 (validation): Accept skipped as a pass for docs-build in validation-summary
3. 9a2a37a — 🐛 (staging): Gate docs-preview + accept skipped in staging-summary

Each commit changes exactly one logical concern and is independently bisectable.

Implementation details worth recording

• The validation workflow uses needs.intent-parse.outputs.docs (intent-parse job); the staging workflow uses needs.config.outputs.docs (no intent-parse step — staging reads docs config directly from rw_parse_project_config.yaml outputs). Both ultimately point at the same intent.yaml artifacts.docs value.
• The summary DOCS_OK="${{ ... == 'success' || ... == 'skipped' }}" pattern mirrors how docker jobs are already treated when a Dockerfile is absent (line 197 in validation: '⏭️ Skipped (no Dockerfile)'). The skipped-as-OK precedent existed; we're applying it to docs as well.
• The production-release workflow rw_release_complete.yaml already had this gate at line 465 (if: needs.intent.outputs.do_release == 'true' && needs.intent.outputs.docs != 'skip' && …). After this PR, all three rw_release_*_complete.yaml orchestrators consistently honour artifacts.docs: skip.

Verdict

Ready for human approval and merge. All scope-AC items satisfied; 7 CI reds are pre-existing in this repo's self-test workflows and predate this PR by ~1 month. Once this merges, the downstream AI-agent-assembly/python-sdk PR #66 (currently draft) can be flipped ready-for-review with green CI.

— Claude Code (Opus 4.7, 1M context)