fix(jira): address PR #302 review — signature binding, REST-pivot docs, ADR-015

[flamingquaks]

Summary

Addresses all six blocking issues (and the test-coverage gaps) from krokoko's changes-requested review on aws-samples#302. Merging this into feat/288-jira-integration updates that PR in place.

Blocking issues resolved

1. CI red (test_config.py syntax error) — already fixed at PR HEAD by 1e4a4a0; this branch keeps the agent suite green (1005 passed).
2. Stale Starlight mirrors — regenerated at this HEAD; node docs/scripts/sync-starlight.mjs is clean.
3. Multi-tenant signature binding (security) —
   • bgagent jira setup no longer mirrors the stack-wide secret into per-tenant bundles. Each tenant keeps its own secret; only the first tenant seeds the stack-wide fallback (needed for Settings-UI webhooks, which omit cloudId).
   • The receiver forwards verified_via: 'per-tenant' | 'stack-wide' to the processor. On stack-wide verification the processor refuses a body-supplied cloudId and binds the delivery to the sole active tenant (drops when zero/multiple); a missing verified_via is treated as untrusted.
   • Missing-timestamp deliveries log the skipped replay-window check so the bypass is observable.
4. ADR / docs MCP→REST reconciliation — ADR renumbered to ADR-015 (feat(tasks): workflow-driven tasks — declarative steps + repo-less workflows (#248) aws-samples/sample-autonomous-cloud-coding-agents#296 took ADR-014), status accepted, rewritten for the implemented REST outbound and the actual dedup key ({issueKey}#{webhookEvent}#{timestamp}). JIRA_SETUP_GUIDE, USER_GUIDE ("six ways"), ROADMAP, jira-integration.ts, jira-webhook-processor.ts, config.py, and test_config.py docstrings all brought in line. channel_mcp.py drops the non-functional jira entry from CHANNEL_MCP_BUILDERS (the Atlassian Remote MCP can't authenticate headlessly), with tests pinning the no-op.
5. Non-existent CLI command in user-facing strings — unmapped-project feedback and setup "Next steps" now print bgagent jira map <cloud-id> <project-key> --repo … (setup interpolates the actual cloudId).
6. Dead orchestrator IAM — notifyJiraOnConcurrencyCap implemented in orchestrate-task.ts (parity with Linear), so the registry-read + secret grants in agent.ts now have their consumer.

Test coverage added

• cdk/test/handlers/jira-webhook-multi-tenant.test.ts — 10 cases mirroring the Linear multi-workspace suite (per-tenant verify, cross-tenant mismatch fatal, revoked no-fallback even when stack-wide matches, verified_via tagging, infra-error 500, missing-timestamp dispatch).
• Processor cloudId trust-binding tests (4 cases incl. stack-wide + foreign-cloudId drop).
• cdk/test/handlers/shared/jira-feedback.test.ts — ADF body shape (pinned exactly — REST v3 400s otherwise), timeout/non-2xx/resolver-throw paths.
• cdk/test/constructs/jira-integration.test.ts — key schemas, GSI, dedup TTL, env wiring, and read-only receiver IAM on the OAuth prefix.
• cli/test/jira-oauth.test.ts — 22 cases: JSON (not form-encoded) token exchange, refresh-token rotation persistence, invalid_grant, accessible-resources, PKCE, authorize-URL params incl. audience.
• stored-oauth-token-parity.test.ts parameterized to also cover the Jira StoredOauthToken ↔ StoredJiraOauthToken pair.

Verification

• cdk: 109 suites / 1977 passed
• cli: 26 suites / 325 passed (+ compile + eslint clean)
• agent: 1005 passed, ruff + ty clean
• check-types-sync / check-constants-sync OK; Starlight mirrors regenerated

🤖 Generated with Claude Code