# 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 ``` 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 `. - 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 ` 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. /// ().` 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 ▼ 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..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 |