# P4Sudo Project — Claude Code Governance

## Pleasantries

Greetings, Claude!

---

## Session Startup Checklist

Run these commands at the start of every session. Use `cd` to ensure commands
run from the p4sudo workspace root so the correct `.p4config` is picked up.

```bash
cd /Users/ttyler/pub/ai/p4sudo

p4 -s login -s        # Verify ticket. If expired, stop and ask Tom to refresh.
p4 status             # Should be "No files to reconcile" (see note below).
p4 -s opened          # Should be "File(s) not opened on this client."
p4 switch -l          # Confirm active stream (should be "dev *").
p4 -s sync -q         # Get current. Ensure output ends with "exit: 0".
```

**Note on `p4 status`:** The file `.claude/settings.local.json` may appear as
needing reconciliation. This is expected and intentional — defer the decision
on versioning it to Tom at the start of the session.

If `p4 -s opened` shows any open files, stop and ask Tom before proceeding.

**Always use `cd /Users/ttyler/pub/ai/p4sudo &&` as a prefix on every bash
command** — the shell resets its working directory between tool calls, so the
`.p4config` must be picked up fresh each time.

---

## Current Task

Read the latest session handoff file in `ai/` (highest-numbered
`session-NNN-handoff.md`) to understand current project status, what was
accomplished last session, and what to do next.

---

## Governance

### Working Directory and Workspace

- **Local workspace root:** `/Users/ttyler/pub/ai/p4sudo`
- **P4 workspace name:** `bot_Claude_Anthropic.P4MBPro5.p4sudo`
- **P4CONFIG file:** `/Users/ttyler/pub/ai/p4sudo/.p4config`
- **Active stream:** `//p4sudo/dev`
- **P4 server:** Public Depot (see below)

This is a **Streams workspace**. The client view is generated from the stream
spec and cannot be edited directly in the client spec. To change the view,
the stream spec must be edited. Use `p4 switch -l` to see available streams.

---

### P4 Servers

Two P4 servers are relevant to this project.

#### 1. Public Depot (default for this workspace)

| Property | Value |
|----------|-------|
| P4PORT | `54.241.106.223:1666` |
| Official hostname | `public.perforce.com:1666` |
| P4CONFIG | `.p4config` (default) |
| Access | Public, accessible from anywhere |
| Purpose | Open-source P4Sudo framework code |

The IP address is used instead of the hostname as a workaround for DNS
issues caused by the corporate VPN.

#### 2. PPN (Perforce Partner Network)

| Property | Value |
|----------|-------|
| P4PORT | `ssl:50.18.77.74:1670` |
| Official hostname | `ssl:ppn.perforce.com:1670` |
| P4CONFIG | `.p4config.ppn` |
| Access | Private; accessible from anywhere via broker/Swarm, SSH only from VPN |
| Purpose | Black Belt program customer data; P4Sudo command deployment |

To run a single command against PPN without changing the default P4CONFIG:
```bash
p4 -E P4CONFIG=.p4config.ppn <command>
```

To verify PPN login:
```bash
cd /Users/ttyler/pub/ai/p4sudo && p4 -E P4CONFIG=.p4config.ppn -s login -s
```

---

### PPN Server Topology

The PPN service involves three server machines:

```
INTERNAL AWS NETWORK
┌──────────────────────────────────────────────────────────────┐
│                                                              │
│  ppn-p4d-01  (Ubuntu 20.04, HelixProd VPC)                   │
│    ├─ p4d :1666  (internal/VPN only)  ← primary p4d         │
│    └─ p4broker :1671  (internal/VPN only) ← P4Sudo broker   │
│         └─ no DLP rules; targets local p4d; calls scripts   │
│                                                              │
│  ppn.perforce.com  (Ubuntu 20.04, HelixDMZ VPC)              │
│    ├─ p4broker :1670  (external-facing) ← production broker  │
│    │    └─ DLP rules enforced here (see below)               │
│    └─ Swarm / Apache  (external-facing, P4 Code Review UI)   │
│                                                              │
│  ppn-p4d-02  (Ubuntu 20.04)                                  │
│    └─ standby replica of ppn-p4d-01  ← ignore for now       │
│                                                              │
│  new-app-server  (Ubuntu 24.04, to be provisioned)           │
│    └─ P4Sudo web app  (internal-facing)                      │
│         └─ targets ppn-p4d-01:1671                           │
│                                                              │
└──────────────────────────────────────────────────────────────┘
         │
         │  DMZ exposes :1670 (broker) and :443 (Swarm) externally
         │  :1671 (P4Sudo broker) is HelixProd VPC only — VPN required
```

- **ppn-p4d-01:** The production P4D (HelixProd VPC, internal/VPN only). Also
  hosts the P4Sudo broker on :1671. The broker targets the local p4d (loopback
  — no network hop). P4Sudo scripts live on this machine. AWS Security Group
  `P4SudoBroker` (HelixProd VPC) controls access to port :1671.
  **IP:** `10.252.3.146` (no DNS resolution; use IP or add `/etc/hosts` entry).
- **ppn.perforce.com:** DMZ machine (HelixDMZ VPC) running the production broker
  (:1670, external-facing with DLP rules) and Swarm. Mission-critical — do not
  risk the production broker. The P4Sudo broker is NOT on this machine.
- **ppn-p4d-02:** Standby replica. Ignore for now. P4Sudo scripts live on
  ppn-p4d-01, so a `p4 failover` of p4d has no impact on script deployment.

**SSH access to ppn.perforce.com** requires being on the corporate VPN
(port 22 is internal-only). The broker port :1671 will also be internal-only.

---

### DLP (Data Leakage Protection) on PPN

DLP rules are enforced **in the production broker config (port :1670)** —
they are a broker policy, not a p4d server feature.

The P4Sudo broker (port :1671) has its own separate config with **no DLP
rules**. Internal users connecting through :1671 get an unrestricted view.

**Known DLP behaviors on :1670 (for reference only — not relevant to :1671):**
- `p4 users` is blocked unless you are a super user (classified as oversharing)
- `p4 clients` is rewritten to show only the requesting user's own workspaces

When running commands against PPN during development, prefer :1671 (once
available) to avoid hitting these restrictions.

---

### Bot User and Ticket Management

- **Bot P4 username:** `bot_Claude_Anthropic`
- Tickets expire regularly (typically 24 hours). Always check at session start.
- If the ticket has expired, **stop and ask Tom to refresh it** — the bot
  cannot refresh its own ticket non-interactively.
- This applies to both the Public Depot and PPN connections independently.
- Tom has noted that generating the ticket before starting the agent is easy
  to forget — a note in Tom's own runbook would help.

---

### Version Control Workflow

- Always create a **numbered pending changelist** for work, not the default CL.
- Use `p4 change -o | sed '...' | p4 change -i` to create CLs programmatically.
- Always associate file edits with the CL: `p4 edit -c <CL> <file>`.
- End each changelist description with `#review @robert_cowham @tom_tyler`.
- Check syntax before submitting scripts (`bash -n script.sh`, `python3 -m py_compile`).
- Do `p4 describe -s <CL>` to verify the CL is on the correct workspace before
  submitting.
- End each session by writing a session handoff file and submitting it.
- Files that are already versioned must be opened with `p4 edit` before writing.

#### Stream Topology and the `ai/` Folder

The `//p4sudo/dev` stream spec contains an **isolate mapping for `ai/...`**:

```
isolate ai/...
```

This means:
- Session handoff files, CLAUDE.md, and other material in `ai/` are versioned
  normally in the `dev` stream. They cannot be promoted to `//p4sudo/main` or
  to any release stream (e.g. a future `//p4sudo/r26.1`) via copy or merge.
- This is intentional: `ai/` is an audit trail and AI session log, not shippable
  project content.
- `isolate` differs from `exclude`: `exclude` would remove `ai/` from the stream
  view entirely (files could not be versioned at all). `isolate` keeps files
  fully versionable in `dev` while preventing them from flowing north.
- When doing end-of-session handoffs, always submit `ai/session-NNN-handoff.md`
  to `//p4sudo/dev` as normal. No special handling is needed — the stream spec
  enforces the boundary automatically.

#### Version File

The project version is tracked in `//p4sudo/dev/Version` (and promoted to
`//p4sudo/main`). The format follows the convention used by other Perforce
software projects:

```
Rev. P4Sudo/MultiArch/2026.1/32549 (2026/04/08).
```

Fields: `Rev. <Project>/<Platform>/<Release>/<CL> (<Date>).`

Update the Version file as part of any release promotion to `main`. Tom manages
this file manually; the bot should not modify it unless explicitly asked.

---

### P4Sudo Project Architecture

P4Sudo gives non-super P4 users access to privileged or site-defined operations
via a controlled, audited mechanism modeled on Unix `sudo`. It is implemented
using the p4broker filter/REWRITE feature.

```
User (CLI or web)
      │  p4 sudo <subcmd> <args>
      ▼
p4broker :1671  (ppn-p4d-01, HelixProd VPC, VPN only)
      │  action = filter; execute = p4sudo.sh
      ▼
p4sudo.sh  (dispatcher)
      ├─ reads broker stdin (user, workspace, args)
      ├─ checkauth (verify valid ticket)
      ├─ reads p4sudo.cfg (authorization rules)
      └─ dispatches to command script OR rejects
            │
            ▼
      mkblackbelt.sh / mkproj.sh / etc.
            │  runs as p4sudo-svc (service account)
            └─ operates against ppn-p4d-01
```

**Key files (deployment on ppn.perforce.com):**

| Path | Purpose |
|------|---------|
| `/p4/common/site/p4sudo/p4sudo.sh` | Core dispatcher (called by broker) |
| `/p4/common/site/config/p4sudo.cfg` | Authorization rules |
| `/p4/common/site/p4sudo/commands/` | Site-defined command scripts |
| `/p4/common/site/p4sudo/commands/*.ui.yaml` | Web form definitions |
| `/p4/common/site/p4sudo/logs/` | Operational and audit logs |
| `/p4/1/broker/p4broker-p4sudo.conf` | P4Sudo broker config (:1671) |

**Service account:** `p4sudo-svc` — holds minimum necessary P4 permissions,
must not appear in `p4sudo.cfg` rules, needs a non-expiring broker-side ticket.

**Persistent workspace:** `p4sudo-svc.blackbelt` — pre-created on PPN, mapped
to `//BlackBelt/main`, used by `mkblackbelt.sh` to update `CustomerIndex.md`.
Root directory must exist on `ppn.perforce.com`. To be set up manually as
part of P4Sudo deployment; document in Admin Guide.

For the p4broker REWRITE feature, see `doc/broker-rewrite-reference/README.md`.

---

### Development Infrastructure Status

| Component | Status | Notes |
|-----------|--------|-------|
| P4Sudo broker :1671 on ppn-p4d-01 | **Partial** | Pass-through broker running; P4Sudo filter config not yet written; AWS SG connectivity issue under investigation |
| New Ubuntu 24.04 app server (AWS) | **Pending** | New EC2 in same account as PPN fleet |
| `p4sudo-svc.blackbelt` workspace on PPN | **Pending** | Manual setup; document in Admin Guide |
| p4broker P4Sudo filter config | **Not started** | Write `/p4/common/config/p4_ppn.broker.ppn-p4d-01.cfg` with real filter rules |
| `mkblackbelt.sh` implementation | **Complete** | CL 32599; needs integration test once broker is reachable |
| P4Sudo web app | **Not started** | After CLI path is solid |

---

### P4Sudo Broker Deployment on ppn-p4d-01

**Broker config file:** `/p4/common/config/p4_ppn.broker.ppn-p4d-01.cfg`

**ServerID:** `p4broker.p4sudo`

**SDP host-specific config convention:** The existing `p4broker_ppn` systemd
service (SDP-standard, was installed but not enabled on ppn-p4d-01) looks for a
host-specific config file before falling back to the instance default:

1. `/p4/common/config/p4_ppn.broker.<ShortHostname>.cfg` — **used if present**
2. `/p4/common/config/p4_ppn.broker.cfg` — default (production broker on ppn.perforce.com)

By naming the config with the short hostname (`ppn-p4d-01`), the P4Sudo broker
config is picked up only on that machine. The production broker config on
`ppn.perforce.com` is unaffected. No new systemd service or custom procedures
are needed — start/stop/status use the standard `p4broker_ppn` service on each
host.

**Current state:** A pass-through broker config is deployed and the broker is
running on ppn-p4d-01:1671. Verified locally on the server:
- `p4 -p ssl:1671 trust -y` succeeded
- `p4 -p ssl:1671 info` succeeded

The broker needs to be updated with the real P4Sudo filter rules (see
`doc/broker-rewrite-reference/README.md` and the existing `p4broker-p4sudo.conf`
path noted in Project Architecture above).

**AWS Security Group:** `P4SudoBroker` created in HelixProd VPC, opening port
:1671 to Tom's personal IP for testing. External connectivity from Tom's machine
has not yet succeeded — the instance may have an additional SG blocking the port,
or a NACL may be in play. Investigation pending.

---

### Project File Locations (Public Depot)

All P4Sudo framework code is versioned in `//p4sudo/dev/` on the Public Depot.

| Depot path | Local path | Description |
|------------|------------|-------------|
| `//p4sudo/dev/ai/` | `ai/` | Session logs, CLAUDE.md, handoffs |
| `//p4sudo/dev/doc/` | `doc/` | Design documents, examples |
| `//p4sudo/dev/doc/broker-rewrite-reference/` | `doc/broker-rewrite-reference/` | CBD example files + REWRITE protocol README |