kandev/docs/plans/pr-walkthrough/task-03-workflow-artifact-generation.md

id, title, status, wave, depends_on, plan, spec

id	title	status	wave	depends_on	plan	spec
03-workflow-artifact-generation	Workflow artifact generation	done	2	01-walkthrough-skill-renderer 02-agent-rendering-contract	plan.md	../../specs/pr-walkthrough/spec.md

Task 03: Workflow artifact generation

Add a dedicated PR walkthrough workflow with a generation job. The job checks out the immutable base commit, fetches the PR head only as a Git object, uses base-commit copies of the skill and helpers, gives OpenCode narrow trusted rendering and PR-file tools, and uploads the agent-generated files and logs for the separate R2 publication job.

• Acceptance: A non-draft authorized pull request event invokes OpenCode, creates distinct docs/pr-walkthrough/pr-<number>.json and .html files, and uploads them as an artifact. The generation job runs on opened, reopened, ready_for_review, and the generate-pr-walkthrough label, but not on synchronize.

• Acceptance: The job cannot execute PR-owned scripts through OpenCode or modify source. OpenCode may invoke only the base-controlled rendering adapter, which writes the fixed walkthrough outputs. The job does not request id-token, hosting credentials, R2 credentials, or GitHub write permissions.

• Acceptance: A contract test covers the trigger, immutable base checkout, head-object fetch, constrained PR-file reads, trusted base assets, read-only agent permissions, output paths, artifact upload, and generation-only boundary. The artifact handoff is explicit for the dependent R2 publication job.

• Acceptance: The workflow uses PR_WALKTHROUGH_ENABLED, the opencode-go/muse-spark-1.2-contributor#high model reference and the model's native high-reasoning variant. The normal review workflow remains independently gated by OPENCODE_REVIEW_ENABLED.

• Verification:

  python3 .github/scripts/pr-walkthrough-workflow-contract_test.py
  python3 .github/scripts/lint-action-pinning_test.py
  python3 .github/scripts/lint-action-pinning.py
  zizmor .github/workflows/pr-walkthrough.yml
  git diff --check
  

• Files likely touched: .github/workflows/pr-walkthrough.yml, .github/workflows/lint-action-pinning.yml, .github/scripts/pr-walkthrough-workflow-contract_test.py, .gitignore.

• Dependencies: Tasks 01 and 02.

• Parallelism: sequential, because it edits the shared OpenCode workflow and consumes both earlier artifacts.

• Inputs: The spec's permissions, failure modes, persistence guarantees, and scenarios; tasks 01 and 02; current OpenCode workflow gates and action pinning conventions.

• Output contract: Report changed files, contract/security check results, artifact paths from any local dry run, and any unavailable external CI dependency. Mark the task done after implementation and verification. This task does not publish to R2; task 04 owns that boundary.

Results

Added the isolated same-repository OpenCode generation job to the dedicated pull_request_target walkthrough workflow. It materializes the skill, renderer, shell, and narrow rendering adapter from the base SHA. OpenCode builds and repairs the JSON/HTML through that adapter while generic edit and Bash remain denied. The job preserves logs and outputs as a uniquely keyed artifact, including on failure.

The three OpenCode jobs now share a base-SHA-materialized setup action with one version and checksum. The walkthrough generation worktree stays on the trusted base commit. A bounded helper reads regular UTF-8 files from the immutable PR head Git object without exposing PR-controlled filesystem entries. Walkthrough artifacts use a visible staging directory and fail when empty. Workflow-level per-PR concurrency serializes generation, publication, and linking, and the walkthrough label no longer runs the normal code-review job.

The walkthrough has its own enable variable and uses the Muse Spark contributor model with its native high-reasoning variant. The pinned OpenCode 1.17.7 CLI catalog reports reasoning support plus built-in high and xhigh variants, and the CLI resolved the default-deny agent permissions.

Verification: workflow contract tests passed; action pinning tests and linter passed; actionlint passed; git diff --check passed. The targeted zizmor audit still reports the workflow's existing pull_request_target warning.