fix(ci): remove unused staging PR write authority

[simple-agent-manager]

Summary

• Removes the orphaned pull-requests: write authority from the staging deployment caller.
• Declares the actual minimum token contract explicitly: contents: read, deployments: none, and id-token: none.
• Adds a structural, scenario-driven workflow contract that protects caller-to-reusable permission inheritance, dry-run wiring, and known PR-write consumer regressions.
• Preserves all public, API, CLI, data, reusable-deploy, smoke-sequencing, and staging behavior. WP-117 authenticated smoke logic is intentionally excluded.

Release contract: keep this PR open and unmerged. Do not deploy this individual source PR to shared staging; the final integration task owns staging.

Validation

• pnpm lint -- --quiet — 7/7 tasks
• pnpm typecheck — 16/16 tasks
• pnpm test — the local full suite exposed timeout-only API flakes in files identical to the green base SHA; this is not represented as green. Clean-runner GitHub CI is mandatory below.
• Additional validation run:
  • pnpm install --frozen-lockfile
  • focused workflow contracts: 44/44
  • repository quality-script tests: 225/225
  • source-contract tests, dependency governance, stale-binary check
  • actionlint v1.7.12 across every workflow (official release attestation verified)
  • pnpm build — 9/9 tasks
• N/A: no sweep, cron, alarm, or candidate-selection logic changes.

Current main SHA 8eed3b7402d2e036900a67db0232fe6c8623155a has a successful GitHub CI run. The branch was conservatively rebased onto that exact SHA before final validation.

Staging Verification (EXPLICIT USER OVERRIDE — NOT PERFORMED)

The task's release contract expressly prohibits deploying this individual source PR to shared staging. The final integration task owns staging verification. No staging workflow was triggered and shared staging was not mutated.

• Staging deployment green — N/A under the direct no-staging release contract; intentionally not triggered.
• Live app verified via Playwright — N/A; no UI/runtime behavior change and staging access is prohibited for this PR.
• Existing workflows confirmed working — covered by local workflow contracts, actionlint, and required GitHub CI; no shared-staging mutation.
• New feature/fix verified on staging — deferred to the final integration task by explicit instruction.
• Infrastructure verification completed — N/A: permission-only workflow hardening; no VM/cloud/runtime infrastructure path changed.
• Mobile and desktop verification notes added — N/A: no UI change.

Staging Verification Evidence

Explicit no-staging override. Local contracts verify the staging caller/reusable interface and GitHub CI must be completely green. Shared staging remains untouched.

UI Compliance Checklist

• N/A: no UI change.

End-to-End Verification

• Data flow traced from caller token declaration to reusable workflow jobs.
• Capability tests exercise the caller/reusable contract across both real workflow files.
• Existing reusable inputs, inherited secrets, dry-run contract, and smoke sequencing were verified against code.
• The only gap—live staging—is explicitly owned by the final integration task.

Data Flow Trace

1. .github/workflows/deploy-staging.yml declares the exact root token scopes.
2. jobs.deploy.uses invokes .github/workflows/deploy-reusable.yml with the unchanged environment, skip-agent, dry-run, and inherited-secret contract.
3. GitHub passes the caller token scopes into the same-repository reusable workflow; the callee contains no root/job override and cannot elevate.
4. The structural contract reads both actual workflow files and rejects missing minimum scopes, nested overrides, PR authority, explicit token/API consumers, and PR-comment actions.

Untested Gaps

Live staging execution is intentionally omitted under the direct release contract. Clean-runner GitHub CI is required to close the local broad-suite timeout limitation before handoff.

Post-Mortem

What broke

The staging deployment retained repository pull-request write authority after the only PR-comment feature using it was deleted.

Root cause

Commit 3ec20f63b added the permission with the PR-comment step. Commit aaa6e00e6 later removed the step without removing its adjacent permission.

Class of bug

Orphaned security authority after feature removal.

Why it wasn't caught

Existing workflow tests covered deploy behavior and pins but did not connect granted token scopes to active capabilities.

Process fix included in this PR

scripts/quality/deploy-staging-permissions.test.ts structurally enforces the exact caller permission map and rejects historical, relocated, broad, malformed/escaped, inherited-override, token-backed API, and PR-comment-action regressions.

Post-mortem file

tasks/active/2026-08-08-staging-workflow-least-privilege.md

Specialist Review Evidence

• All local reviewers completed and findings addressed before handoff
• N/A: every reviewer completed; no needs-human-review label is required

Reviewer	Status	Outcome
security-auditor	ADDRESSED	Parser and consumer bypass findings fixed; final review approved with no remaining security findings.
independent defensive regression reviewer	ADDRESSED	Quoted/escaped YAML, inheritance, multiline token/API, and third-party comment-action attacks now fail; final re-attack approved.
constitution-validator	PASS	No Principle XI, dependency, or behavior-preservation violations.
test-engineer / test-quality critic	ADDRESSED	Reusable checkout capability fixture and focused dependency diff corrected; final 44/44 suite approved.
task-completion-validator	PASS	Checks A-F passed with no implementation or contract-test gaps.

Exceptions

• Scope: shared staging deployment and PR merge.
• Rationale: direct user release contract assigns staging to the final integration task and requires this source PR to remain open and unmerged.
• Expiration: only a later explicit human instruction may authorize staging or merge.

Agent Preflight (Required)

• Preflight completed before code changes

Classification

• external-api-change
• cross-component-change
• business-logic-change
• public-surface-change
• docs-sync-change
• security-sensitive-change
• ui-change
• infra-change

External References

Official GitHub documentation was consulted before coding: permissions for GITHUB_TOKEN and reusable-workflow access/permission propagation.

• https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication
• https://docs.github.com/en/actions/sharing-automations/reusing-workflows#access-and-permissions-for-nested-workflows

Codebase Impact Analysis

• .github/workflows/deploy-staging.yml: remove PR write authority and declare exact minimum scopes.
• .github/workflows/deploy-reusable.yml: unchanged contract boundary inspected by the new test.
• scripts/quality/deploy-staging-permissions.test.ts: structural cross-workflow capability/permission regression coverage.
• package.json and pnpm-lock.yaml: direct test-only yaml@2.9.0 dependency with a three-line importer-only lock delta.

Documentation & Specs

N/A: no public behavior or documentation surface changes. The operational record is maintained in tasks/active/2026-08-08-staging-workflow-least-privilege.md.

Constitution & Risk Check

Principles II, VI, X, and XI were checked. The change removes authority, preserves all existing behavior, adds scenario-driven contract coverage, pins the structural parser dependency, and introduces no runtime URL, timeout, limit, secret, identifier, or deployment prerequisite. The principal risk was a false sense of coverage from regex parsing; independent defensive review drove the final structural parser and adversarial fixtures.

[codspeed-hq]

Merging this PR will not alter performance

✅ 6 untouched benchmarks

---

_{Comparing sam/wp-121-remove-unused-c1n154 (3b862fa) with main (8c689a6)}

[simple-agent-manager]

Integration in progress — owned by task 01KZMFQJ4VKXEFB9K9Q64QKDDF. PR Shepherd: hands off until this completes.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[simple-agent-manager]

Integration in progress — owned by task 01M03VFVP79GR882BJMPKZV58V (overnight consolidated PR sweep authorized by Raphaël 2026-08-15). PR Shepherd: hands off until this completes. This supersedes the stale claim by failed task 01KZMFQJ4VKXEFB9K9Q64QKDDF where present.