# Session 004 Handoff — P4Sudo Project

**Date:** 2026-04-24
**Bot user:** bot_Claude_Anthropic
**Workspace:** bot_Claude_Anthropic.P4MBPro5.p4sudo
**Stream:** //p4sudo/dev

---

## Session Summary

A productive session with three main areas of work:

1. **`bin/mkblackbelt.sh`** — Full implementation of the first site-defined
   command script (CL 32599). This is the primary coding deliverable.
2. **Architecture decision** — P4Sudo broker moves to `ppn-p4d-01` (HelixProd
   VPC), not `ppn.perforce.com` (DMZ). Broker is now running (pass-through).
3. **AWS Security Group investigation** — SG created, but port :1671 not yet
   reachable from Tom's machine externally. Investigation deferred.

Also versioned `.claude/settings.local.json` (CL 32598) and updated CLAUDE.md
governance twice to reflect the topology change and broker deployment details
(CLs 32601, this CL).

---

## Changelists This Session

| CL | Description | Status |
|----|-------------|--------|
| 32598 | Add .claude/settings.local.json (Claude Code project permissions) | Submitted |
| 32599 | Add bin/mkblackbelt.sh — site command to bootstrap Black Belt customer | Submitted |
| 32601 | Update CLAUDE.md: P4Sudo broker topology correction | Submitted |
| (this CL) | Update CLAUDE.md: broker deployment details; session-004 handoff | Submitted this session |

---

## What Was Accomplished

### bin/mkblackbelt.sh

Full implementation of the 9-step Black Belt bootstrap workflow documented in
`doc/use-cases.md`. Highlights:

- **All 9 steps implemented:** input validation, template fetch, depot/stream
  provisioning (idempotent), ephemeral workspace, INFO.md instantiation via
  token substitution, submit, ephemeral workspace cleanup, CustomerIndex.md
  update.
- **Submit conflict retry:** CustomerIndex.md step reverts, re-syncs, re-applies
  the row insertion, and retries once on a submit conflict.
- **On-error behavior:** ephemeral workspace is left in place for debugging on
  any step failure (deleted only on full success).
- **Stdout discipline:** only the final result summary goes to stdout (the broker
  protocol channel); all intermediate progress goes to a per-invocation log in
  `$LOGS`.
- **Coding standard:** SDP-compliant (set -u, 3-space indent, UpperCamelCase
  globals, function style, usage/-h/-man/-V, SDP lib sourcing, terminate()
  override). ShellCheck 0.10.0 clean. Syntax-checked with `bash -n`.
- **Deployment path:** `/p4/common/site/p4sudo/commands/mkblackbelt.sh`
  (as registered in `doc/p4sudo.cfg.example`).

### Architecture Decision: Broker on ppn-p4d-01

The P4Sudo broker (:1671) will run on `ppn-p4d-01` (HelixProd VPC, same host as
the p4d), not on `ppn.perforce.com` (DMZ). Rationale:

- P4Sudo is internal-only — no reason to expose it through the DMZ machine.
- Broker-to-p4d connection is loopback (no network hop).
- Simpler AWS networking: stays entirely within HelixProd VPC.

CLAUDE.md has been updated with the corrected topology throughout.

### Broker Deployed (Pass-Through)

Tom deployed a pass-through p4broker config on `ppn-p4d-01`:

- **Config file:** `/p4/common/config/p4_ppn.broker.ppn-p4d-01.cfg`
- **ServerID:** `p4broker.p4sudo`
- **Service:** `p4broker_ppn` systemd service (existing SDP-standard service,
  previously installed but not enabled on this host; now enabled and running).
- **SDP host-specific convention:** The service uses the host-specific config
  automatically by filename convention. No new service needed.

Verified on the server: `p4 -p ssl:1671 trust -y` and `p4 -p ssl:1671 info`
both succeed. The broker is listening and forwarding to local p4d.

**ppn-p4d-01 IP:** `10.252.3.146` (no DNS; use IP or `/etc/hosts`).

### AWS Security Group

`P4SudoBroker` security group created in HelixProd VPC, opening TCP :1671 to
Tom's personal IP for testing. However, port :1671 was not reachable from Tom's
machine. The `p4broker_ppn` broker is confirmed listening on the server itself,
so the blockage is AWS networking. Likely causes (to investigate next session):

1. **Second security group on the instance** — EC2 instances can have multiple
   SGs; another SG may lack a :1671 rule, and all SGs must permit the traffic.
2. **Network ACL (NACL)** — Subnet-level firewall, stateless; may block :1671
   even if SGs allow it. Less common but possible.
3. **VPN egress rules** — Tom's VPN might restrict outbound ports or NAT to a
   different IP than what's in the SG rule.

---

## Tom's Action Items (Carried Forward + New)

1. **Debug port :1671 connectivity** — Check all SGs attached to the ppn-p4d-01
   instance (not just P4SudoBroker); check subnet NACL for port :1671; verify
   which IP the VPN presents to AWS (run `curl ifconfig.me` with VPN on).
2. **AWS CLI access for helixdmz account** — File IT ticket if CLI access is
   needed. (Not blocking anything currently — console is sufficient for SG work.)
3. **Promote `README.md` to `//p4sudo/main`** — Carried from session 003.
4. **`ai/...` isolate on `//p4sudo/dev` stream spec** — Verify done (or do it).
5. **Provision Ubuntu 24.04 EC2** — New app server in HelixProd VPC for P4Sudo
   web app. Not blocking current work.
6. **`p4sudo-svc` service account on PPN** — Create when broker is reachable.
7. **`p4sudo-svc.blackbelt` persistent workspace on PPN** — Create after svc
   account exists. See Admin Guide notes.

---

## Next Session: Where to Pick Up

### Immediate: Debug the Security Group

Before any integration testing can happen, port :1671 must be reachable. Start
with:

```bash
# On ppn-p4d-01 — confirm the broker is still listening
p4 -p ssl:1671 info

# From Tom's machine (VPN on) — check effective public IP
curl ifconfig.me

# In AWS console — check which SGs are attached to the ppn-p4d-01 instance
# (EC2 → Instances → ppn-p4d-01 → Security tab)
# Verify ALL attached SGs allow TCP :1671 from the VPN IP.

# Also check: VPC → Subnets → [ppn-p4d-01 subnet] → Network ACL → Inbound rules
```

### After Connectivity Is Established: Write the Real Broker Config

The current broker on ppn-p4d-01 is a pass-through. It needs to be updated with
the P4Sudo filter rules. The config file to modify:

```
/p4/common/config/p4_ppn.broker.ppn-p4d-01.cfg
```

Required filter rules (two):
1. `command: ^(sudo)$` → `action = filter; execute = /p4/common/site/p4sudo/p4sudo.sh`
2. `command: ^(help)$` → `action = filter; execute = /p4/common/site/p4sudo/p4sudo-help.sh`

See `doc/broker-rewrite-reference/README.md` for the exact config syntax.

### After Broker Config: Deploy Scripts and Config to ppn-p4d-01

Files to deploy (not yet on the server):

| Source (Public Depot) | Deployment path on ppn-p4d-01 |
|-----------------------|-------------------------------|
| `bin/p4sudo.sh` | `/p4/common/site/p4sudo/p4sudo.sh` |
| `bin/p4sudo-help.sh` | `/p4/common/site/p4sudo/p4sudo-help.sh` |
| `bin/mkblackbelt.sh` | `/p4/common/site/p4sudo/commands/mkblackbelt.sh` |
| `doc/p4sudo.cfg.example` | basis for `/p4/common/site/config/p4sudo.cfg` |

All scripts need `chmod +x`. The `p4sudo.cfg` needs to be customized for PPN
(correct `p4sudo_user`, log paths, etc.) and is not a direct copy of the example.

### After Scripts Are Deployed: Service Account and First End-to-End Test

1. Create `p4sudo-svc` P4 user on PPN (super user, non-expiring ticket via broker).
2. Create `p4sudo-svc.blackbelt` workspace on PPN (mapped to `//BlackBelt/main`).
3. Add `mkblackbelt` authorization rule to `p4sudo.cfg` for Tom's user.
4. Run `p4 -p ssl:10.252.3.146:1671 sudo mkblackbelt TestCo --salesforce-link=...`
   and watch the log.

---

## Files of Interest

| Path | Notes |
|------|-------|
| `ai/CLAUDE.md` | Full governance — read at session start |
| `bin/p4sudo.sh` | Core dispatcher — complete |
| `bin/p4sudo-help.sh` | Help interception — complete |
| `bin/mkblackbelt.sh` | Black Belt bootstrap command — complete, needs integration test |
| `README.md` | Project overview (Swarm landing page) |
| `doc/use-cases.md` | UC-001 mkblackbelt — fully documented |
| `doc/mkblackbelt.ui.yaml` | Web form definition for mkblackbelt |
| `doc/p4sudo.cfg.example` | Annotated config reference |
| `doc/broker-rewrite-reference/README.md` | Broker filter protocol reference |
| `doc/admin-guide.md` | Pre-implementation admin guide — needs updating |