# 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)                                  │
│    └─ p4d :1666  (internal/VPN only)  ← primary p4d         │
│                                                              │
│  ppn.perforce.com  (Ubuntu 20.04, DMZ)                       │
│    ├─ p4broker :1670  (external-facing) ← production broker  │
│    │    └─ DLP rules enforced here (see below)               │
│    ├─ p4broker :1671  (internal only)  ← P4Sudo broker (TBD) │
│    │    └─ no DLP rules; calls P4Sudo scripts                │
│    └─ 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)                      │
│                                                              │
└──────────────────────────────────────────────────────────────┘
         │
         │  DMZ exposes :1670 (broker) and :443 (Swarm) externally
         │  :1671 (P4Sudo broker) stays internal-network only
```

- **ppn-p4d-01:** The production P4D. Internal/VPN access only. Safe to target
  for P4 operations (creating depots, editing text files).
- **ppn.perforce.com:** DMZ machine running the production broker (:1670),
  Swarm, and eventually the P4Sudo broker (:1671). Mission-critical — do not
  risk the production broker.
- **ppn-p4d-02:** Standby replica. Ignore for now. P4Sudo scripts live on the
  broker machine, 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.perforce.com, internal)
      │  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.perforce.com | **Pending** | Needs AWS Security Group change (internal-only) |
| 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 config for :1671 | **Not started** | Draft after port is opened |
| `mkblackbelt.sh` implementation | **Not started** | Next major coding task |
| P4Sudo web app | **Not started** | After CLI path is solid |

---

### 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 |