fix(ci): render Pages candidate summary safely (#216)

[miso-develop]

Rework for #216 after post-merge Human Gate finding.

Problem

Manual Pages candidate run 35449129354 deployed the correct exact-main candidate, but .github/workflows/pages.yml rendered Markdown backticks inside double-quoted Bash echo strings. Bash treated those backticks as command substitution, corrupting the required source/build identity summary.

Fix

• move candidate summary rendering to repository-owned scripts/ci_pages_summary.py
• pass source/build values as ordinary CLI arguments; Python writes Markdown directly with no shell interpolation
• escape any embedded Markdown backtick before inline-code rendering
• preserve exact-main authorization, candidate acknowledgement, non-exact identity, production build/deploy, one-day staging retention, and exact artifact-ID deletion
• wire focused regression into the existing required security:scan suite
• pin workflow wiring so unsafe double-quoted backtick echo cannot regress

Regression

tests/ci_pages_summary_test.py verifies:

• exact source ref/SHA/candidate/main summary output
• exact v1.0.0/build-commit/non-exact identity summary output
• backticks and $() supplied as values remain literal text and cannot execute shell commands

tests/ci_change_impact_test.py verifies Pages uses the helper and contains no unsafe double-quoted backtick echo.

Scope boundary

No change to:

• exact-main manual candidate authorization
• candidate_sha 40-hex requirement
• explicit candidate acknowledgement
• tag-triggered Pages release behavior
• M5AUTH_EXACT_RELEASE=false for manual candidate
• Pages/OIDC permissions
• one-day artifact retention
• exact artifact-ID cleanup
• Authorized Release workflow
• Product/Protocol/Storage/Vault behavior

Because this fix changes main after merge, the prior #213 manual candidate becomes stale. After this PR is reviewed and integrated, #213 must rerun the exact-main manual Pages candidate Human Gate on the new main SHA.

Exact-head verification

HEAD: 694241b5956418e55cd0f5b58ce8c4715b9c0d26

• Security #951: SUCCESS
  • required context remains exactly security:scan
  • main Ruleset still binds it to GitHub Actions integration ID 15368
  • tests/ci_change_impact_test.py + tests/ci_pages_summary_test.py: 18 tests passed
  • tracked repository security scan: SUCCESS
• Foundation #948: SUCCESS
  • classify: SUCCESS
  • Web Linux + production-equivalent Chrome smoke: SUCCESS
  • Windows Chrome QR/Argon2: SUCCESS
  • Firmware + isolated ESP-IDF build/package validation: SUCCESS
• branch is behind 0; PR is mergeable
• current main remains 6f008c6864d3b080106f53d51eb7cbe1f2b4c150
• PR fix(ci): render Pages candidate summary safely (#216) #219 is the only open PR
• effective diff is limited to:
  • .github/workflows/pages.yml
  • .github/workflows/security.yml
  • scripts/ci_pages_summary.py
  • tests/ci_change_impact_test.py
  • tests/ci_pages_summary_test.py
• Pages workflow contains no double-quoted echo line with Markdown backticks
• v1.0.0 tag: absent
• v1.0.0 GitHub Release: absent

Post-integration requirement

The previous manual candidate run is stale once this fix reaches main. After independent Review and Integration, #213 must run the exact-main manual Pages candidate Human Gate again against the new current-main SHA and verify the corrected summary identity before protected v1.0.0 creation.

[miso-develop]

Post-merge #216 rework is complete at exact HEAD 694241b5956418e55cd0f5b58ce8c4715b9c0d26.

Blocking Human Gate defect resolved:

• candidate summary rendering no longer uses Bash echo strings containing Markdown backticks;
• repository-owned scripts/ci_pages_summary.py writes source/build identity directly as text;
• embedded backticks are escaped for Markdown;
• regression proves backticks and $() remain literal and cannot execute shell commands;
• Pages workflow contract test requires both summary helper calls and rejects unsafe double-quoted backtick echo.

Preserved:

• exact-main authorization and fresh origin/main equality;
• explicit candidate_sha and candidate acknowledgement;
• manual candidate non-exact release identity;
• tag-triggered Pages behavior;
• one-day staging retention;
• exact artifact-ID deletion;
• Authorized Release boundary and Pages/OIDC authority.

Exact-head evidence:

• Security #951: SUCCESS; Pages/change-impact summary regression suite ran 18 tests and passed.
• Foundation #948: SUCCESS; classify, Web, Windows Chrome, and Firmware all succeeded.
• required main context remains security:scan from GitHub Actions integration 15368.
• current main remains 6f008c6864d3b080106f53d51eb7cbe1f2b4c150; branch behind 0; PR mergeable.
• v1.0.0 tag/Release remain absent.

The previously deployed #213 candidate is stale after this fix. Once reviewed/integrated, the exact-main manual candidate Human Gate must be rerun on the new main SHA before tag creation.

[miso-develop]

HANDOFF
FROM: implementation
TO: review
DOMAIN: infra
ISSUE: #216
PR: #219
HEAD: 694241b
STATE: READY_FOR_REVIEW

[miso-develop]

Review disposition: READY_FOR_INTEGRATION

Reviewed exact PR head 694241b5956418e55cd0f5b58ce8c4715b9c0d26 against reopened Issue #216 and the durable post-merge Human Gate finding from manual Pages candidate run 35449129354.

No blocking finding identified.

Human Gate defect resolution

The observed defect is correctly addressed.

The failed candidate summary path on merged main used Markdown backticks inside double-quoted Bash echo arguments. Bash interpreted those backticks as command substitution, which the durable Human Gate evidence confirmed with errors such as:

• refs/heads/main: No such file or directory;
• v1.0.0: command not found.

PR #219 removes both affected shell-rendered summary blocks and replaces them with repository-owned Python rendering:

• authorization summary:
  python scripts/ci_pages_summary.py candidate-authorization ...
• build identity summary:
  python scripts/ci_pages_summary.py candidate-build-identity ...

The identity values are passed as ordinary quoted CLI arguments. Python writes the Markdown directly to GITHUB_STEP_SUMMARY; no shell evaluates the rendered Markdown contents.

For the actual workflow path, the values are additionally constrained before/at use:

• source ref must equal exactly refs/heads/main;
• candidate SHA must match exact 40-hex syntax;
• workflow source SHA must equal freshly fetched current main;
• candidate SHA must equal that same current main;
• build commit is GitHub's source SHA;
• Product/Firmware version continues through the canonical release validation contract;
• exact-release input is constrained to true|false.

Therefore the required source/build identity no longer passes through a shell command-substitution boundary.

Regression coverage

tests/ci_pages_summary_test.py verifies:

• exact authorization summary identity;
• exact v1.0.0 / build-commit / non-exact candidate identity;
• backticks and $() supplied as CLI values remain inert literal data and cannot execute shell commands.

tests/ci_change_impact_test.py additionally pins workflow wiring:

• Pages must invoke both summary-helper commands;
• the Pages workflow must not contain a double-quoted echo line with Markdown backticks.

The summary tests are wired into the unconditional required security:scan job.

Preserved manual candidate security/release contract

The fix does not weaken or reorder the manual candidate authorization gate:

• workflow_dispatch only for manual candidate;
• GITHUB_REF == refs/heads/main;
• explicit candidate acknowledgement remains mandatory;
• exact 40-character candidate_sha remains mandatory;
• origin/main is freshly fetched;
• workflow source SHA must equal fresh current main;
• candidate SHA must equal fresh current main;
• manual candidate still forces EXACT_RELEASE=false;
• tag-triggered Pages behavior is unchanged;
• production release validation remains;
• immutable ESP-IDF identity remains;
• isolated firmware build/package/image validation remains;
• same-origin firmware assets and production Web build remain;
• Pages staging artifact retains retention-days: 1;
• consumed Pages artifact is still deleted by exact artifact ID;
• Pages/OIDC authority remains confined to the Pages deploy job.

.github/workflows/release-authorized.yml is byte-for-byte unchanged from current main (blob d126d260b05c56556cb2e83017ee21086a362490).

No Product, Protocol, Storage Schema, Vault Format, crypto, Trusted Browser, Recovery, Lock, firmware-runtime, or release-authority behavior changes.

Exact-head CI

Security #951: SUCCESS.

• exact job/check context: security:scan;
• tests/ci_change_impact_test.py + tests/ci_pages_summary_test.py: 18 tests passed;
• existing release authorization, attestation, supply-chain, automatic-lock, snapshot-production-boundary, and repository security checks remain green;
• final repository scan: SUCCESS.

Foundation #948: SUCCESS.

• deterministic classifier: SUCCESS;
• exact PR impact: Web=true, Firmware=true, Pages=true, Shared=true, uncertain=false;
• changed-path set contains exactly the five effective PR files;
• Linux Web + production-equivalent Chrome smoke: SUCCESS;
• Windows Chrome: SUCCESS;
• Firmware: SUCCESS;
• release validation remains M5StickS3 v1.0.0 protocol=2 storage=2 vault=1 security=encrypted-vault-ram-only-vmk/v1 eligibility=production-eligible;
• isolated ESP-IDF/package validation and dependency-lock verification succeeded.

No Pages workflow run was created for this PR, as expected.

Staleness / collision / release state

• handoff HEAD matches current PR HEAD;
• PR #219 is open, non-draft, mergeable;
• current main remains exact PR base 6f008c6864d3b080106f53d51eb7cbe1f2b4c150;
• compare is 5 commits ahead / 0 behind;
• effective diff is exactly:
  • .github/workflows/pages.yml;
  • .github/workflows/security.yml;
  • scripts/ci_pages_summary.py;
  • tests/ci_change_impact_test.py;
  • tests/ci_pages_summary_test.py;
• PR #219 is the only open PR at final Review check;
• v1.0.0 tag is absent;
• GitHub Release v1.0.0 is absent.

Integration / Human Gate boundary

#216 / PR #219 is ready for Integration.

The previously successful manual candidate deployment at main 6f008c6864d3b080106f53d51eb7cbe1f2b4c150 becomes stale once this fix is merged.

After Integration merges #219, control must return to #213 and the explicit Human-approved manual Pages candidate gate must be rerun against the new exact current-main SHA. That rerun must verify, from the actual hosted workflow summary/deployment evidence:

• source ref renders literally as refs/heads/main;
• source SHA, candidate SHA, and current-main SHA render fully and identically;
• Product/Firmware identity renders as v1.0.0;
• build commit renders fully;
• exact release renders false;
• candidate build/deploy succeeds;
• staging artifact is deleted by exact ID;
• hosted candidate remains non-exact/pre-release.

Protected v1.0.0 creation must remain blocked until that fresh exact-main Human Gate passes.

No additional Security-role review is required for this narrow summary-rendering correction; the required Security workflow is green and no security/release authority was expanded.

[miso-develop]

HANDOFF
FROM: review
TO: integration
ISSUE: #216
PR: #219
HEAD: 694241b
STATE: READY_FOR_INTEGRATION

[miso-develop]

READY_TO_MERGE

HEAD: 694241b5956418e55cd0f5b58ce8c4715b9c0d26
Current main / PR base: 6f008c6864d3b080106f53d51eb7cbe1f2b4c150

Integration reconstruction:

• exact PR head matches Review handoff
• Review disposition: READY_FOR_INTEGRATION; no blocking finding remains
• Security #951: SUCCESS
• Foundation #948: SUCCESS
• no unresolved review threads
• PR open, non-draft, mergeable
• PR fix(ci): render Pages candidate summary safely (#216) #219 is the only open PR
• v1.0.0 tag and Release remain absent
• Protect main + SemVer creation/immutability Rulesets remain active
• no additional Security-role review or Human Gate is required for this narrow fix itself
• prior manual candidate is stale after merge and must be rerun on the new exact main before tag creation

STATE: READY_TO_MERGE

[miso-develop]

INTEGRATED

PR: #219
Pre-merge HEAD: 694241b5956418e55cd0f5b58ce8c4715b9c0d26
Squash merge commit / current main: 996378b07d8587c0d11e43362590e5d1062ad8c2

Pre-merge evidence:

• Review: READY_FOR_INTEGRATION
• Security #951: SUCCESS
• Foundation #948: SUCCESS
• no unresolved review threads

Post-merge evidence on exact merged main:

• Security #952: SUCCESS
• Foundation #949: SUCCESS
  • classify: SUCCESS
  • web: SUCCESS
  • web QR Windows Chrome: SUCCESS
  • firmware: SUCCESS
• ordinary main push created no Pages workflow run
• Foundation produced no Actions artifact; no Pages staging artifact path was entered
• canonical Product/Firmware remains 1.0.0
• Protocol / Storage / Vault remain 2 / 2 / 1
• production_release_allowed: true
• Authorized Release workflow remains blob d126d260b05c56556cb2e83017ee21086a362490
• retired Release tombstone remains present
• Protect main / SemVer creation / SemVer immutability Rulesets remain active
• v1.0.0 tag and Release remain absent

The earlier manual candidate on 6f008c... is stale. A fresh exact-main candidate run is still required before tag creation.

STATE: INTEGRATED